# Marginalia
> Print-derived page furniture for genuinely long-form pages — a scroll-linked running folio (current-section head), a marginal read-o-meter (reading time + percent as small-caps type, never a progress bar), a sticky scrollspy section rail, Tufte-style footnote/sidenote gutters in a reserved margin column, and marginal pull-quotes — all set in layout-grid's outer column and degrading to inline superscript + native popover below the gutter breakpoint. Invoke in the Build phase for essays, case studies, docs, reports, or annual-report pages (never a landing page), or when the user says "running header", "reading progress", "table of contents rail", "scrollspy", "sidenotes", "footnotes in the margin", "Tufte sidenotes", "pull quote", or "margin notes".
- Skill: `blyatiful1/marginalia` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add blyatiful1/marginalia`
- Raw SKILL.md: https://api.skillmd.com/api/skills/blyatiful1/marginalia/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: blyatiful1 (https://skillmd.com/u/blyatiful1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/blyatiful1/marginalia
---
# marginalia — the page furniture of long-form
**Stage:** Phase 6 — Build (long-form pages only) - **Reads:** design/SYSTEM.md §type + §layout, design/SITEMAP.md, page content - **Writes:** components/marginalia/* (folio, read-meter, section-rail, sidenote styles) applied on long-form page templates
## Standard
Print magazines carry meaning in their furniture — folios, running heads, footnotes, marginalia — as much as in the body. A page number in Bloomberg Businessweek small-caps, a Tufte sidenote riding the margin, gwern.net's section rail, The Pudding's live act markers: none is body copy, all are typographic identity. Porting that furniture to long-form web gives an essay a printed conviction the article alone can't carry — and adds zero UI chrome. First-grade here means the furniture reads as *set*, not bolted on: it lives in real margin space, it's quiet, and it degrades honestly.
- **Fires on long-form only.** ≥ ~1,200 words / ≥ a 6-minute read, or an explicitly long-form page type in SITEMAP (essay, case study, docs, report, changelog entry). Never on a landing, marketing, product, or pricing page — furniture on a short page is affectation. If SITEMAP doesn't mark the page long-form, this skill does not run.
- **Steal the principle, not the surface** (`award-canon`): the *idea* of a running head, not a scanned page. All furniture is set in SYSTEM.md tokens — small-caps labels at 11–13px / +0.10–0.14em (typography's uppercase rule), notes at the caption step, the site accent for links.
- **The margin is layout-grid's, and it has one tenant.** The gutter is the **Margin Note 3/9** column layout-grid already reserves — marginalia *claims* it, never mints a second grid. Expose its width as `--gutter-w` so every piece aligns to the same column. A page runs **either** a Section Rail **or** a Sidenote Gutter as the column's primary tenant — never both fighting for it. The folio and read-o-meter are small enough to share the thin top-outer edge.
- **Degrades down, not off.** At ≥1440px the gutter is real. Below it, sidenotes collapse to a numbered superscript + native popover (zero-JS, Baseline 2024). At 375px there is **no gutter** — footnotes become an endnotes list with two-way anchor links. Nothing horizontally scrolls, ever.
- **Reduced motion:** the folio swaps instantly (no fade), the read-o-meter percent still reads (it's information, not animation) but drops the spring, and no scroll is ever hijacked — native scroll stays authoritative.
## Variants
### 1. Running Folio — the current-section head
A sticky small-caps label echoing the section you're in, like a print running head. Driven by scrollspy, not a scroll listener. Because it *echoes* the visible H2, it's `aria-hidden` — screen readers already have the heading.
```tsx
"use client";
import { useEffect, useState } from "react";
export function useActiveSection(ids: string[]) { // shared by folio + rail
const [active, setActive] = useState(ids[0]);
useEffect(() => {
const obs = new IntersectionObserver(
(entries) => { const seen = entries.find((e) => e.isIntersecting); if (seen) setActive(seen.target.id); },
{ rootMargin: "0px 0px -70% 0px" }, // active once the heading crosses the top 30%
);
ids.forEach((id) => { const el = document.getElementById(id); if (el) obs.observe(el); });
return () => obs.disconnect();
}, [ids]);
return active;
}
//
{label}
```
**When:** essays and case studies with named H2 sections a reader loses their place in. IntersectionObserver, never a per-frame `scroll` handler.
### 2. Read-o-meter — progress as type, not a bar
Reading time + percent set as marginal small-caps — deliberately **not** a fixed progress bar (that's scroll-motion's `ReadingProgress`, banned here as un-print). Reading time is computed at build by content-cms (words ÷ 200 wpm); percent reuses scroll-motion's `scrollYProgress` rendered into text.
```tsx
"use client";
import { useScroll, useMotionValueEvent } from "motion/react";
import { useState } from "react";
export function ReadMeter({ minutes }: { minutes: number }) {
const { scrollYProgress } = useScroll();
const [pct, setPct] = useState(0);
useMotionValueEvent(scrollYProgress, "change", (v) => setPct(Math.round(v * 100)));
return
{minutes} min · {pct}%
;
}
```
`tabular-nums` so the percent doesn't jitter the label width. **When:** any long read where "how much is left" reassures — reports, deep docs.
### 3. Section Rail — sticky scrollspy TOC
A sticky in-page contents list in the margin, current item lit via the shared `useActiveSection`. Unlike the folio this is a **real `