remarque-tokens 0.13.0 → 0.15.0

package/AGENT_RULES.md

@@ -141,6 +141,8 @@ project/
 ├── tokens-core.css           # CORE tier: type scale, spacing, widths, radius, motion, prose machinery. NEVER override
 ├── tokens-palette.css        # PALETTE tier: font slots, colors, accent, reading measure. Override freely, then run the audit
 ├── prose.css                 # .remarque-prose long-form styling (aggregated by tokens.css; own subpath for opt-out)
+├── essay.css                 # Optional Essay module: sidenotes + sticky TOC rail (own subpath, NOT aggregated — import explicitly)
+├── print.css                 # Print stylesheet (own subpath, NOT aggregated — import explicitly)
 ├── theme.css                 # Tailwind v4 adapter (@theme inline) — import after tailwindcss + tokens
 ├── tailwind.config.js        # Tailwind v3 ONLY — v4 projects use theme.css instead
 ├── public/
@@ -200,6 +202,7 @@ Before considering any implementation complete, verify:
 - [ ] No scroll-triggered or entrance animations exist
 - [ ] Every image has a 1px border and mono caption
 - [ ] Every page maps to an archetype (Essay, Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery)
+- [ ] If the Essay uses sidenotes/a TOC rail (`remarque-tokens/essay`): `.remarque-sidenote-ref`/`.remarque-sidenote` alternate in strict DOM order, the rail never intrudes into `.remarque-prose`'s own measure, and the page renders correctly with `essay.css`'s `@media` block deleted (the narrow-viewport/no-JS fallback)
 - [ ] Mobile version is roomy — not a compressed desktop layout
 - [ ] Mobile nav links have ≥44px touch targets
 - [ ] No pure white or pure black backgrounds

package/CHANGELOG.md

@@ -4,6 +4,69 @@ All notable changes to `remarque-tokens` are documented here. Token value
 changes always state the design rationale — downstream sites pin against
 these entries when syncing.
 
+## 0.15.0 — 2026-07-23
+
+Essay module — sidenotes + sticky TOC rail, graduated from the flagship (closes #52).
+
+### Added
+- **`essay.css`** (new subpath: `remarque-tokens/essay`, `remarque-tokens/essay.css`) —
+  optional Essay-archetype module, not aggregated into `tokens.css` or `prose.css`. Adds:
+  - `.remarque-sidenote-ref` / `.remarque-sidenote` — footnotes as in-flow margin notes.
+    Small-print inline block below `80rem` (`--color-border-bold`, the note's only visual
+    separator at that width); floats into the left gutter above it via a Tufte-style
+    negative-margin technique (`clear: left` stacks consecutive notes, no JS). Numbered
+    with CSS counters (`counter-reset` on `.remarque-prose`) rather than an authored number
+    — this package ships no build step, unlike the flagship's rehype transform. A repeat
+    citation of an already-noted footnote uses `.remarque-sidenote-ref--repeat` (styled
+    identically, doesn't advance the shared counter).
+  - `.remarque-footnotes` — a same-voice fallback for consumers without a DOM-reordering
+    build step: styles GFM's default end-of-document footnotes section instead of relocating
+    notes inline.
+  - `.remarque-toc-rail` — `position: sticky` right rail at `>= 80rem`, plain inline
+    collapsible `<details>` below it, same markup at every width (mono meta voice, small
+    caps rather than `text-transform: uppercase` — the flagship predates that rule).
+  - `.remarque-essay` — the opt-in 3-column grid shell (gutter / reading column / TOC
+    rail) that places the above two. Center track is `minmax(0, var(--content-reading))`,
+    identical to plain `.content-reading` centering; the grid never sets `max-width` or
+    `margin-inline` on its children, so the reading-column measure is unaffected with or
+    without this module.
+  - Single breakpoint, `>= 80rem` (1280px) — re-derived from `--content-standard` /
+    `--content-reading` / the core spacing scale rather than asserting the flagship's
+    literal rem measurements. Deleting the `@media` block leaves the correct
+    narrow-viewport/no-JS presentation, not a degraded one.
+  - `grid-row: 1 / span 999` on the rail, not `1 / -1` — ships with the flagship's
+    same-day grid-inflation fix already applied (`-1` resolves to row 1 with no explicit
+    `grid-template-rows`, inflating it to the rail's own height).
+- **`print.css`** — forces `.remarque-sidenote` back to inline mode and `.remarque-essay`
+  back to block flow under `@media print`, making good on this file's existing "when a
+  sidenotes module lands" comment. (`.remarque-toc-rail` was already caught by the
+  existing `nav` / `[class*="toc-"]` print-hiding rules — no change needed there.)
+- **REMARQUE.md "Essay Module"** — markup contract, when-to-use guidance, the
+  breakpoint-behavior table, and the grid-inflation provenance note.
+- **AGENT_RULES.md** — File Structure Convention lists `essay.css` (and, newly, `print.css`,
+  which the convention had never mentioned); Quality Checklist gains an Essay-module line.
+- **Demo site (`site/`)** — `writing/typography-as-interface` (the Essay archetype's VR
+  reference page) now exercises both sidenotes and the TOC rail. VR baselines updated:
+  `essay-{light,dark}-{desktop,mobile}.png` (4 files). New computed-style assertion:
+  the TOC rail's bounding box never overlaps `.remarque-prose`'s reading column at the
+  `1280px` desktop viewport.
+
+### Documentation
+- **README.md "Graduation"** — adds this release to the "Historical examples" list as
+  the worked example of the "optional module" destination.
+
+
+
+Triage bundle — prose/`.content-reading` pairing documented, `--motion-easing` bridged into the Tailwind v4 utility layer, USWDS/WCAG source citations added to the accessibility section (closes #23, closes #31, closes #32).
+
+### Added
+- **`ease-remarque` Tailwind v4 utility** — `theme.css`'s `@theme inline` block now maps `--ease-remarque: var(--motion-easing)`, mirroring the `transitionTimingFunction.remarque` mapping the v3 `tailwind.config.js` already carried. Utility-class users of `duration-[var(--motion-fast)]` previously fell back to Tailwind's default `ease` timing function instead of the token (#31).
+- **Demo site** — every `duration-[var(--motion-fast)]` call site (22, across `site/src/pages/*`, `layouts/BaseLayout.astro`, `components/Meta.astro`) now pairs with `ease-remarque` so the rendered CSS carries `var(--motion-easing)` instead of Tailwind's default.
+
+### Documentation
+- **REMARQUE.md "Editorial Microtypography"** — states that `.remarque-prose` is typography-only (font, line height, numeral register, optical wrapping) and does not center the column; pair it with `.content-reading`, with a minimal code sample (#23).
+- **REMARQUE.md "USWDS Accessibility Compliance"** — every cited WCAG 2.1 success criterion (1.4.3 Contrast Minimum, 1.4.11 Non-text Contrast, 2.5.5 Target Size, 2.3.3 Animation from Interactions, the last in the adjacent "Motion Rules" section) and USWDS claim (16px font-size floor, the overall accessibility approach) now links to its source (`w3.org/WAI/WCAG21/Understanding/*`, `designsystem.digital.gov`) (#32).
+
 ## 0.13.0 — 2026-07-23
 
 Syntax-highlighting palette — 9 `--color-syntax-*` slots, ANSI-derived, golden-gated (closes #53; consensus-ratified 3-0 with a binding taxonomy design record, 2026-07-23).

package/README.md

@@ -119,6 +119,41 @@ See the [live demo](https://williamzujkowski.github.io/remarque/) for the origin
 | Border radius | 0.5rem max | Restrained. No "friendly SaaS" over-rounding |
 | Motion | 120ms/180ms | Hover and theme transitions only. No scroll-triggered, entrance, or staggered animations |
 
+## Graduation — when a site invention becomes system vocabulary
+
+Consumer sites invent things (the flagship's sidenotes and theme deck, tsundoku's gallery
+grid). Some of those inventions belong upstream; most are the site's own remarque in the
+margin and should stay there. A local invention is upstreamable when **all four** hold:
+
+1. **Wanted by 2+ sites** (or one site plus a ratified case that it generalizes).
+2. **Consumes only tokens** — no hardcoded colors, sizes, or faces.
+3. **Passes the audit tooling** (`remarque-audit`, and `remarque-drift` reports it as
+   palette-tier INFO, not a core FAIL).
+4. **Violates no Never-list entry** in the spec — or arrives together with an explicit
+   spec amendment arguing the change.
+
+**Three destinations.** Core spec (rare — core is identity, the bar is a fork-level
+argument); optional module (sidenotes, TOC rail, palette deck); or *documented site-local
+pattern* — explicitly not shared. The zine layer that inspired this checklist is the
+exemplar of the third: sanctioned personality that would be diluted by generalizing it.
+
+**Process (single-maintainer scale, no ceremony):** open an issue with before/after
+screenshots and the token-purity check; record the decision in the changelog. Historical
+examples: measure compensation and the Gallery archetype graduated; the essay
+sidenotes/sticky-TOC-rail pair graduated as an optional module
+([#52](https://github.com/williamzujkowski/remarque/issues/52)); the theme deck was
+re-scoped on the way up ([#56](https://github.com/williamzujkowski/remarque/issues/56));
+the zine layer deliberately stayed local.
+
+**Standing rulings** (ratified 3-0, 2026-07-23) on patterns the reviews kept re-flagging:
+
+| Pattern | Ruling |
+|---------|--------|
+| Share links in post footers | Site-local, never a system module. If you build one: URL-encode every interpolated value and reject non-`https` schemes — title/frontmatter injection into share-intent URLs is the classic mistake. |
+| Cross-hue hover accents | Not sanctioned anywhere. The hover move is a lightness/chroma shift within the accent hue (`--color-accent-hover` models it). A cross-hue hover is a documented deviation, not personalization. |
+| Ambient/decorative animation | Site-local only, never in system modules — and the `prefers-reduced-motion` guard is mandatory, not advisory. A future audit scan may flag unguarded infinite animations (as a heuristic check, not a soundness proof). |
+| Landing-page entry counts | Permitted as meta-voice data in the Landing archetype **only when computed from real inventory at build time**. A hardcoded count is a violation — counts drift (see the upstream count-drift bug class this system just fixed in its own theme provider). |
+
 ## Named For
 
 In fine art printmaking, a *remarque* is a small original drawing made by the artist in the margin of a proof print. Found only in limited editions, it is the mark that says: this was made by someone specific, with intention.

package/REMARQUE.md

@@ -124,6 +124,14 @@ This is why the measure is palette-tier: it is a property of the font choice, no
 
 The book-craft layer: numerals, small caps, drop caps, pull quotes, and optical wrapping. These are the details that separate typeset prose from a web page that merely uses nice fonts.
 
+`.remarque-prose` supplies typography only — font, line height, numeral register, optical wrapping — and stops short of centering the column, so pair it with `.content-reading` wherever the reading column needs to sit centered on the page:
+
+```html
+<div class="remarque-prose content-reading">
+  <!-- article body -->
+</div>
+```
+
 ### Numerals
 
 Two numeral registers, chosen by context:
@@ -353,19 +361,19 @@ Motion in Remarque is nearly invisible. The only permitted motion:
 - Parallax effects
 - Any animation on non-interactive elements
 
-**Reduced motion:** all motion must respect `prefers-reduced-motion` (WCAG 2.3.3). Because every sanctioned transition uses the two duration tokens, tokens.css zeroes `--motion-fast`/`--motion-normal` under `prefers-reduced-motion: reduce` — motion authored with the tokens is automatically safe. Never hardcode durations; any future opt-in animation must live inside a `(prefers-reduced-motion: no-preference)` query.
+**Reduced motion:** all motion must respect `prefers-reduced-motion` ([WCAG 2.3.3](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html)). Because every sanctioned transition uses the two duration tokens, tokens.css zeroes `--motion-fast`/`--motion-normal` under `prefers-reduced-motion: reduce` — motion authored with the tokens is automatically safe. Never hardcode durations; any future opt-in animation must live inside a `(prefers-reduced-motion: no-preference)` query.
 
 ---
 
 ## USWDS Accessibility Compliance
 
-Remarque adopts typography and accessibility standards from the US Web Design System (USWDS) and WCAG 2.1:
+Remarque adopts typography and accessibility standards from the [US Web Design System (USWDS)](https://designsystem.digital.gov/documentation/accessibility/) and [WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/):
 
 ### Font Size Floors
 
 | Token | Value | USWDS Rationale |
 |-------|-------|-----------------|
-| `--text-body` | 17px (1.0625rem) | Exceeds USWDS 16px minimum. Non-negotiable floor. |
+| `--text-body` | 17px (1.0625rem) | Exceeds [USWDS 16px minimum](https://designsystem.digital.gov/components/typography/). Non-negotiable floor. |
 | `--text-meta` | 14px (0.875rem) | USWDS minimum for small text. Used sparingly for metadata, labels, captions. |
 | `--text-micro` | 13px (0.8125rem) | USWDS floor for timestamps and fine print only. Never for body content. |
 
@@ -373,13 +381,13 @@ Remarque adopts typography and accessibility standards from the US Web Design Sy
 
 | Pairing | Requirement | Notes |
 |---------|-------------|-------|
-| Normal text on background | 4.5:1 minimum | All text below 24px regular / 18.5px bold. Applies on `--color-surface` too, not just `--color-bg` |
-| Large text on background | 3:1 minimum | Display and title text (24px+) |
-| Functional non-text elements | 3:1 minimum | WCAG 1.4.11 — use `--color-border-bold` (meets 3:1). `--color-border` is decorative-only by design and exempt; never the sole boundary of an interactive element |
+| Normal text on background | 4.5:1 minimum | [WCAG 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) — all text below 24px regular / 18.5px bold. Applies on `--color-surface` too, not just `--color-bg` |
+| Large text on background | 3:1 minimum | [WCAG 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) — display and title text (24px+) |
+| Functional non-text elements | 3:1 minimum | [WCAG 1.4.11](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html) — use `--color-border-bold` (meets 3:1). `--color-border` is decorative-only by design and exempt; never the sole boundary of an interactive element |
 
 ### Touch Targets
 
-All interactive elements (links, buttons, inputs) must have a minimum touch target of **44x44px** (WCAG 2.5.5 AAA). This applies to nav links, theme toggles, footer links, chips, and any clickable element.
+All interactive elements (links, buttons, inputs) must have a minimum touch target of **44x44px** ([WCAG 2.5.5](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html) AAA). This applies to nav links, theme toggles, footer links, chips, and any clickable element.
 
 ### Line Height
 
@@ -488,7 +496,8 @@ Long-form writing. The core content type.
 - Low-noise footer navigation (previous/next)
 
 **Optionally includes:**
-- Side table of contents on desktop (outside reading column)
+- Side table of contents on desktop (outside reading column) — see "Essay Module" below for the sanctioned sticky-rail implementation
+- Sidenotes/footnotes as in-flow margin notes — same module, same rail-vs-gutter layout
 
 **Never includes:**
 - Sidebar content within the reading column
@@ -618,6 +627,153 @@ Cover-grid and catalog pages — a page whose primary content unit is a grid of
 
 ---
 
+## Essay Module
+
+An optional pair of Essay-archetype features — margin notes and a sticky
+table of contents — shipped as their own subpath, `remarque-tokens/essay`
+(`essay.css`), rather than aggregated into `tokens.css` or `prose.css`.
+Not every Essay wants either; both are opt-in.
+
+**Provenance.** Graduated from williamzujkowski.github.io's
+`rehype-sidenotes.mjs` + `global.css` sidenote/sticky-TOC implementation,
+ratified for upstreaming in [issue #52](https://github.com/williamzujkowski/remarque/issues/52)
+per the "Graduation" checklist in the package README — a footnote
+vocabulary Remarque otherwise entirely lacked (this spec, until now,
+permitted a side TOC at line ~499 without specifying anything about it).
+No site-specific value was copied; every dimension below is re-derived
+from tokens this package already ships (see `essay.css`'s header comment
+for the value-by-value mapping).
+
+### Markup contract
+
+```html
+<article class="remarque-essay">
+  <header class="content-reading">
+    <h1 class="text-display font-display">Essay Title</h1>
+  </header>
+
+  <nav class="remarque-toc-rail" aria-label="Table of contents">
+    <details open>
+      <summary>On this page</summary>
+      <ul>
+        <li><a href="#section-one">Section One</a></li>
+        <li><a href="#section-two">Section Two</a></li>
+      </ul>
+    </details>
+  </nav>
+
+  <div class="remarque-prose content-reading">
+    <h2 id="section-one">Section One</h2>
+    <p>
+      A claim worth a citation<a href="#note-1" id="note-1-ref"
+        class="remarque-sidenote-ref" aria-describedby="note-1"></a>.
+    </p>
+    <aside class="remarque-sidenote" id="note-1" role="note">
+      The note text, in real DOM order right after the paragraph that
+      cites it — not collected into an end-of-document section.
+    </aside>
+  </div>
+
+  <footer class="content-reading">...</footer>
+</article>
+```
+
+Requirements the CSS depends on:
+
+- `.remarque-sidenote-ref` and its matching `.remarque-sidenote` MUST
+  alternate in strict DOM order (ref, then note, then the next ref, then
+  its note...) — the module numbers them with CSS counters
+  (`counter-reset` on `.remarque-prose`), not an authored number, so an
+  out-of-order pair mislabels every note after it.
+- A footnote cited more than once: only the FIRST reference gets a
+  `.remarque-sidenote` after it; later citations of the same note use
+  `.remarque-sidenote-ref--repeat` (styled identically, does not advance
+  the counter) so the shared numbering doesn't skip.
+- `role="note"` on every `.remarque-sidenote` — `<aside>`'s implicit role
+  is `complementary`, a landmark; an essay with several notes would
+  otherwise scatter that many unlabeled landmark regions through the
+  page. `aria-describedby` on the reference (pointing at the note's `id`)
+  is optional but recommended.
+- `.remarque-toc-rail` wraps a plain `<details open>` — the SAME markup
+  at every viewport width, no JS breakpoint listener. `open` by default
+  is deliberate (see "Breakpoint behavior" below).
+
+**No build step required, and none shipped.** This module doesn't ship or
+depend on a rehype/remark transform — the contract above is satisfied by
+hand-authored HTML exactly as well as by a build-time relocation step. If
+your pipeline doesn't relocate GFM footnote definitions into DOM order
+(most don't, out of the box), style the default end-of-document
+`<section data-footnotes>` output with `.remarque-footnotes` instead —
+same mono/meta voice, without the DOM-reordering accessibility upgrade:
+
+```html
+<section class="remarque-footnotes">
+  <h2>Notes</h2>
+  <ol>
+    <li id="note-1">The note text. <a href="#note-1-ref">&#8617;</a></li>
+  </ol>
+</section>
+```
+
+Use `.remarque-sidenote` whenever you can relocate notes into reading
+order — that relocation is the actual accessibility win this module
+exists for. `.remarque-footnotes` is a same-voice fallback, not a lesser
+tier of support, for the common case where you can't (yet).
+
+### When to use
+
+Essay archetype only (sidenotes/a TOC rail are meaningless outside
+long-form prose). Reach for sidenotes on essays with real citations,
+asides, or sourcing that would otherwise interrupt the sentence; reach
+for the TOC rail on any essay long enough that "where am I" becomes a
+real question — roughly the same length threshold Reference/Docs pages
+already assume. Both are independent opt-ins: an essay can use one, the
+other, both, or neither without violating the archetype.
+
+### Breakpoint behavior
+
+Gated on a single `>= 80rem` (1280px) `@media` query — no other
+breakpoint, no JS:
+
+| Viewport | Sidenotes | TOC |
+|---|---|---|
+| `< 80rem` (narrow) | Small-print block, in-flow, right after the citing paragraph — bordered with `--color-border-bold` (a 3:1 functional border, since it's the note's only visual separator at this width) | Inline collapsible `<details>` in the reading column, native disclosure triangle |
+| `>= 80rem` (wide) | Floats into the LEFT margin gutter via a Tufte-style negative-margin technique, `clear: left` stacks consecutive notes, border relaxes to decorative `--color-border` (whitespace is now the real separator) | `position: sticky` in the RIGHT rail, `.remarque-essay` becomes a 3-column grid (gutter / reading column / rail) |
+
+The rail and margin notes always live OUTSIDE `--content-reading` — that
+is the entire point of the module. The center grid track is
+`minmax(0, var(--content-reading))`, identical to the plain
+`max-width: content-reading; margin-inline: auto` centering used
+everywhere else in Remarque; a TOC rail or a floated sidenote can widen
+the page shell, never the reading column itself. `.remarque-essay`'s grid
+placement rule only ever sets `grid-column` on its children — it never
+touches `max-width`/`margin-inline`, so the reading-column assertion
+this spec's Enforcement Checklist already covers holds unmodified with
+or without this module.
+
+Delete `essay.css`'s single `@media (min-width: 80rem)` block and the
+page still renders correctly — that IS the narrow-viewport presentation,
+not a degraded one. No JavaScript is required at either width. (The
+flagship implementation runs a small script to force `<details>` open on
+every breakpoint crossing; this module holds to "no JS required" and
+instead specifies `open` by default in the markup — a reader who
+manually collapses the TOC below the breakpoint and then widens their
+window keeps it collapsed until clicked again, a fully static cost this
+module accepts in exchange for not requiring a script tag.)
+
+### Provenance note: the grid-inflation lesson
+
+`.remarque-essay`'s TOC rail spans `grid-row: 1 / span 999`, not
+`1 / -1`. With no explicit `grid-template-rows` (as here), `-1` resolves
+to "the last explicit row line" — which, with zero explicit rows, is
+row 1. The flagship implementation shipped exactly that bug: the rail's
+own height inflated row 1, pushing the whole essay down and leaving a
+visible gap between the header and the first paragraph on wide
+viewports, fixed same-day. This module ships with the fix already
+applied so the next consumer doesn't rediscover it.
+
+---
+
 ## Signature Moves
 
 These are the repeatable visual tells that make a Remarque site recognizable:

package/essay.css

@@ -0,0 +1,429 @@
+/*
+ * Remarque — Essay Module (sidenotes + sticky TOC rail)
+ * ───────────────────────────────────────────────────────
+ * Optional Essay-archetype module: footnotes become in-flow margin notes
+ * (Tufte/gwern-style), and an "on this page" table of contents pins to a
+ * sticky rail alongside the reading column. Both are progressive
+ * enhancements over a plain Essay page — CSS-only, no JavaScript required
+ * at either breakpoint.
+ *
+ * PROVENANCE — graduated, not invented here. This module re-expresses, in
+ * Remarque's own token vocabulary, a design first built and shipped on
+ * williamzujkowski.github.io (`astro-site/src/lib/rehype-sidenotes.mjs` +
+ * `global.css`'s "Sidenotes"/"Sticky TOC side rail" blocks). Ratified for
+ * upstreaming in issue #52. No site-specific value (the flagship's literal
+ * `11.5rem`/`13rem`/`14rem`/`1280px` measurements) was copied — every
+ * dimension below is re-derived from tokens already in tokens-core.css /
+ * tokens-palette.css. See REMARQUE.md's "Essay Module" section for the
+ * full markup contract, and this file's inline comments for exactly which
+ * site value maps to which token and why a few mechanics changed shape
+ * (CSS counters instead of a build-time numbering step; `<details open>`
+ * by default instead of a JS breakpoint listener) on the way upstream.
+ *
+ * Own subpath (remarque-tokens/essay, remarque-tokens/essay.css) — NOT
+ * included by the tokens.css aggregator, and not required by prose.css:
+ * plenty of Essay pages want neither sidenotes nor a TOC rail. Import
+ * explicitly, after prose.css:
+ *   @import 'remarque-tokens/prose.css';
+ *   @import 'remarque-tokens/essay.css';
+ * (string form — see AGENT_RULES.md Pitfall #6.)
+ *
+ * ─── MARKUP CONTRACT (summary — full version in REMARQUE.md) ──────────
+ *
+ *   <article class="remarque-essay">
+ *     <header class="content-reading">...</header>
+ *
+ *     <nav class="remarque-toc-rail" aria-label="Table of contents">
+ *       <details open>
+ *         <summary>On this page</summary>
+ *         <ul>
+ *           <li><a href="#section-one">Section One</a></li>
+ *         </ul>
+ *       </details>
+ *     </nav>
+ *
+ *     <div class="remarque-prose content-reading">
+ *       <p>
+ *         A claim worth a citation<a href="#note-1" id="note-1-ref"
+ *           class="remarque-sidenote-ref" aria-describedby="note-1"></a>.
+ *       </p>
+ *       <aside class="remarque-sidenote" id="note-1" role="note">
+ *         The note text, in real DOM order right after the paragraph that
+ *         cites it — not collected into an end-of-document section.
+ *       </aside>
+ *     </div>
+ *
+ *     <footer class="content-reading">...</footer>
+ *   </article>
+ *
+ * DOM order is the accessibility requirement, not a presentational nicety:
+ * a screen reader hits a sidenote's content exactly where its reference
+ * occurs. `.remarque-sidenote-ref` and its matching `.remarque-sidenote`
+ * MUST alternate in strict DOM order (ref, then note, then the next ref,
+ * then its note...) — the counter mechanics below depend on it. `role=
+ * "note"` keeps a page with several sidenotes from scattering that many
+ * unlabeled `complementary` landmarks through the document (`<aside>`'s
+ * implicit role) — the same fix the flagship's rehype plugin documents.
+ *
+ * This module is deliberately silent on HOW that markup gets produced. A
+ * build-time transform (the flagship's rehype-sidenotes.mjs is one worked
+ * example, not a dependency of this package) or hand-authored HTML both
+ * satisfy the contract equally — see REMARQUE.md for the no-build-step
+ * fallback (`.remarque-footnotes`) if you don't have one.
+ *
+ * ─── BREAKPOINT ─────────────────────────────────────────────────────────
+ * Gated on >= 80rem (1280px, at the platform default 16px root) viewport
+ * width — the same threshold the flagship ratified, re-derived here from
+ * this package's own tokens instead of asserted as a bare magic number:
+ * `--content-standard` (72rem) is the widest a Remarque page's content
+ * ever grows, and the rail/gutter tracks below need `--space-11`+
+ * `--space-12` (10-12rem) and `--space-10` (8rem) of clearance on top of
+ * `--content-reading` (46rem default) plus two `--space-6` gaps — call it
+ * roughly 70-76rem of content width before both tracks have their
+ * documented minimum room, plus headroom for a scrollbar and window
+ * chrome. 80rem clears that with margin to spare across every approved
+ * body-face/measure pairing (see REMARQUE.md's Measure Compensation
+ * table) without needing a `--breakpoint-*` token this package doesn't
+ * otherwise have. Below it: sidenotes render as small-print inline blocks
+ * exactly where the plain document flow already places them, and the TOC
+ * is a collapsible `<details>` in the reading column — this is also the
+ * ONLY rendering a consumer who skips this module's `@media` block ever
+ * sees, so nothing here is required for the page to work.
+ */
+
+/* ─── Sidenotes — default / narrow-viewport mode ────────────────────────
+ * `.remarque-sidenote` renders as a bordered small-print block right in
+ * the text flow by default. This IS the narrow-viewport fallback the
+ * spec calls for — zero extra markup, zero JS: the note just isn't
+ * floated into a margin yet.
+ *
+ * Numbering is generated, not authored: `counter-reset` on
+ * `.remarque-prose`, `counter-increment` on `.remarque-sidenote-ref` only,
+ * and `.remarque-sidenote` simply READING that same counter (no increment
+ * of its own — see the comment on that rule) keep the visible number in
+ * sync across the reference and its note with no number typed into
+ * either element — the flagship's rehype plugin injects a literal
+ * `<span class="sidenote-number">1</span>`/text node at build time; this
+ * package ships no build step, so CSS counters do the same job for a
+ * pure-CSS module. A repeat citation of an already-noted footnote should
+ * use `.remarque-sidenote-ref--repeat` (no `.remarque-sidenote` follows
+ * it) so the shared counter isn't advanced for a note that was already
+ * printed — mirrors the flagship's "only the first reference gets a
+ * sidenote" rule.
+ */
+.remarque-prose {
+  counter-reset: remarque-sidenote;
+}
+
+.remarque-sidenote-ref {
+  counter-increment: remarque-sidenote;
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  /* USWDS floor rationale: --text-micro is reserved for timestamps/fine
+     print only (tokens-core.css, REMARQUE.md "Font Size Floors") — the
+     flagship's own marker used that size, but this module holds to
+     Remarque's stricter 14px floor for anything read as content. */
+  line-height: 0;
+  vertical-align: super;
+  color: var(--color-accent);
+  text-decoration: none;
+}
+
+.remarque-sidenote-ref::after {
+  content: counter(remarque-sidenote);
+}
+
+.remarque-sidenote-ref:hover {
+  color: var(--color-accent-hover);
+  text-decoration: underline;
+}
+
+.remarque-sidenote-ref--repeat {
+  counter-increment: none;
+}
+
+.remarque-sidenote {
+  /* No counter-increment here: `.remarque-sidenote-ref` already advanced
+     `remarque-sidenote` immediately before this element in DOM order —
+     incrementing again would double-count every pair (ref shows N, the
+     note that follows it would show N+1 instead of N). This element only
+     READS the counter its ref just set. */
+  display: block;
+  margin-block: var(--space-3);
+  padding-inline-start: var(--space-3);
+  /* border-bold: this is the note's ONLY visual separator from running
+     prose at narrow widths, so it must clear the 3:1 functional-border
+     minimum (WCAG 1.4.11) — same reasoning as .remarque-prose blockquote. */
+  border-inline-start: var(--border-width) var(--border-style) var(--color-border-bold);
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  line-height: var(--leading-meta);
+  color: var(--color-fg-muted);
+}
+
+/* The generated number precedes whatever content the note holds. If that
+   content is a single run of inline text (no wrapping <p>), the number
+   sits inline with the opening words — the flagship's "1 Note text..."
+   pairing. A `<p>`-wrapped note (multi-paragraph notes need it) instead
+   reads as a small label above the paragraph — a pure-CSS module can't
+   reach inside an arbitrary child the way a build-time transform can, so
+   this is the honest degradation: prefer bare text for single-line notes. */
+.remarque-sidenote::before {
+  content: counter(remarque-sidenote) "\2002";
+  color: var(--color-accent);
+  font-weight: var(--weight-semibold);
+}
+
+.remarque-sidenote :where(p) {
+  margin: 0;
+}
+
+.remarque-sidenote :where(p) + :where(p) {
+  margin-top: var(--space-2);
+}
+
+/* ─── Sidenotes — wide-viewport mode: float into the left margin ────────
+ * Classic Tufte CSS technique: `.remarque-sidenote` isn't a grid child
+ * itself (it's nested inside `.remarque-prose`, which IS grid-column 2 —
+ * see `.remarque-essay` below) so grid placement doesn't apply to it
+ * directly. Instead it floats left with a negative inline-start margin
+ * exactly wide enough to clear its own box plus one column-gap unit,
+ * landing in the grid's column-1 gutter. `clear: left` stacks consecutive
+ * notes without any JS-computed offset.
+ *
+ * Width (`--space-10`, 8rem) and pull-out distance (that width plus
+ * `--space-6`, the same gap the grid below uses between tracks) are both
+ * drawn from the core spacing scale rather than asserting a bespoke
+ * sidebar-width value — this is the token-vocabulary re-expression of the
+ * flagship's hand-measured `11.5rem`/`13rem` pair.
+ */
+@media (min-width: 80rem) {
+  .remarque-sidenote {
+    float: left;
+    clear: left;
+    width: var(--space-10);
+    margin-inline-start: calc(-1 * (var(--space-10) + var(--space-6)));
+    margin-block: var(--space-1) var(--space-4);
+    padding-inline-start: 0;
+    padding-inline-end: var(--space-2);
+    border-inline-start: none;
+    /* Decorative-only at this width (the gutter's own whitespace is the
+       real separator now) — `--color-border`, not `-bold`, matching the
+       flagship's own choice to relax the border once it's no longer the
+       sole boundary cue. */
+    border-inline-end: var(--border-width) var(--border-style) var(--color-border);
+    text-align: start;
+  }
+}
+
+/* ─── Footnotes fallback (no relocation build step) ─────────────────────
+ * `.remarque-footnotes` styles a traditional end-of-document footnotes
+ * section — e.g. GFM/mdast-util-to-hast's default
+ * `<section data-footnotes><h2>Footnotes</h2><ol>...</ol></section>`
+ * output — in the same meta voice as `.remarque-sidenote`, for a consumer
+ * who hasn't built (or doesn't want) a DOM-reordering transform. It is a
+ * same-voice fallback, not a lesser feature: use `.remarque-sidenote`
+ * whenever you can relocate notes into DOM reading order (the real a11y
+ * upgrade this module exists for); reach for `.remarque-footnotes` only
+ * when that isn't available yet.
+ *
+ *   <section class="remarque-footnotes">
+ *     <h2>Notes</h2>
+ *     <ol>
+ *       <li id="note-1">The note text. <a href="#note-1-ref">&#8617;</a></li>
+ *     </ol>
+ *   </section>
+ */
+.remarque-footnotes {
+  margin-top: var(--space-7);
+  padding-top: var(--space-3);
+  border-top: var(--border-width) var(--border-style) var(--color-border);
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  line-height: var(--leading-meta);
+  color: var(--color-fg-muted);
+}
+
+.remarque-footnotes h2 {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  letter-spacing: var(--tracking-caps);
+  font-variant-caps: all-small-caps;
+  color: var(--color-muted);
+  margin: 0 0 var(--space-3);
+}
+
+.remarque-footnotes ol {
+  padding-inline-start: var(--space-5);
+  margin: 0;
+}
+
+.remarque-footnotes li + li {
+  margin-top: var(--space-2);
+}
+
+.remarque-footnotes a {
+  color: var(--color-accent);
+  text-decoration: none;
+}
+
+.remarque-footnotes a:hover {
+  color: var(--color-accent-hover);
+  text-decoration: underline;
+}
+
+/* ─── Sticky TOC rail ────────────────────────────────────────────────────
+ * `.remarque-toc-rail` wraps a plain collapsible `<details>` — the SAME
+ * markup at every viewport, no JS breakpoint listener. Author it
+ * `<details open>` by default: below the rail breakpoint this is an
+ * inline collapsible block a reader can close to save space (native
+ * disclosure behavior, unchanged); at/above it, it reads as an
+ * already-expanded sticky rail. The flagship instead runs a small inline
+ * script that force-opens the native `open` attribute on every breakpoint
+ * crossing — this module holds to "no JS required," so it authors the
+ * open state up front instead of syncing it at runtime. The one
+ * degradation this trades away: a reader who manually collapses the TOC
+ * below the breakpoint and then widens their window keeps it collapsed
+ * until they click it again — a fully static, CSS-only cost worth paying
+ * for not requiring a script tag.
+ *
+ * Marker: reuses the same quiet mono disclosure triangle as
+ * `.remarque-prose details summary::before` (prose.css) rather than
+ * asking consumers to embed an inline SVG chevron, as the flagship's
+ * TableOfContents.astro does.
+ */
+.remarque-toc-rail {
+  margin-block: var(--space-5);
+}
+
+.remarque-toc-rail details {
+  border: none;
+  padding: 0;
+}
+
+.remarque-toc-rail summary {
+  cursor: pointer;
+  list-style: none;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-2);
+  padding-block: var(--space-2);
+  border-bottom: var(--border-width) var(--border-style) var(--color-border);
+  /* Mono meta voice — same declarations as .text-label (tokens-core.css),
+     repeated rather than shared because .text-label isn't a mixin: true
+     small caps, never text-transform: uppercase (REMARQUE.md "Small
+     Caps"). The flagship predates that rule and used `text-transform:
+     uppercase`; this is the one place the re-expression corrects the
+     source rather than just relocating it. */
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  font-variant-caps: all-small-caps;
+  letter-spacing: var(--tracking-caps);
+  color: var(--color-muted);
+  transition: color var(--motion-fast) var(--motion-easing);
+}
+
+.remarque-toc-rail summary::-webkit-details-marker {
+  display: none;
+}
+
+.remarque-toc-rail summary::before {
+  content: "\25B8";
+  display: inline-block;
+  color: var(--color-muted);
+  transition: transform var(--motion-fast) var(--motion-easing);
+}
+
+.remarque-toc-rail details[open] summary::before {
+  transform: rotate(90deg);
+}
+
+.remarque-toc-rail summary:hover {
+  color: var(--color-fg);
+}
+
+.remarque-toc-rail ul {
+  list-style: none;
+  padding: 0;
+  margin: var(--space-3) 0 0;
+}
+
+.remarque-toc-rail li + li {
+  margin-top: var(--space-1);
+}
+
+.remarque-toc-rail a {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  color: var(--color-fg-muted);
+  text-decoration: none;
+  transition: color var(--motion-fast) var(--motion-easing);
+}
+
+.remarque-toc-rail a:hover {
+  color: var(--color-fg);
+}
+
+/* ─── Essay grid shell — wide-viewport rail layout ───────────────────────
+ * `.remarque-essay` is the opt-in grid container an Essay page's <article>
+ * adds to place a sticky TOC rail beside the reading column, mirroring
+ * this module's sidenote gutter on the OTHER side (right rail = TOC, left
+ * gutter = sidenotes — never the same side, so the two mechanisms never
+ * fight over space). Below the breakpoint it is a no-op: every child
+ * keeps whatever block-flow centering it already had from `.content-
+ * reading` / `.remarque-prose` — this rule only exists inside the
+ * `@media` block.
+ *
+ * Track widths: the center track is `minmax(0, var(--content-reading))` —
+ * IDENTICAL to the plain `max-width: content-reading; margin-inline:
+ * auto` centering used everywhere else (same visual column, just a grid
+ * track instead of block flow), so nothing here changes the reading
+ * measure the "prose measure" computed-style check already covers. The
+ * right track (`minmax(--space-11, --space-12)`, 10-12rem) is this
+ * module's re-expression of the flagship's bespoke `minmax(12rem, 14rem)`
+ * rail — same shape (a comfortable range, not a fixed width), core
+ * spacing tokens instead of asserted rem literals.
+ *
+ * Children are placed by exclusion (`:not(.remarque-toc-rail)` -> column
+ * 2) rather than an explicit tag list, deliberately: nothing about this
+ * rule touches `max-width` or `margin-inline` on any child, so each
+ * element's own `.content-reading` / `.remarque-prose` centering keeps
+ * working exactly as it does outside a grid — the grid track is already
+ * sized to match it.
+ */
+@media (min-width: 80rem) {
+  .remarque-essay {
+    display: grid;
+    grid-template-columns:
+      minmax(0, 1fr)
+      minmax(0, var(--content-reading))
+      minmax(var(--space-11), var(--space-12));
+    column-gap: var(--space-6);
+  }
+
+  .remarque-essay > :not(.remarque-toc-rail) {
+    grid-column: 2;
+  }
+
+  .remarque-essay > .remarque-toc-rail {
+    grid-column: 3;
+    /* `1 / -1` resolves to row 1 ONLY when the grid has no explicit
+       `grid-template-rows` (as here) — `-1` means "the last explicit
+       row line," which with zero explicit rows IS row 1. That inflates
+       row 1 to the rail's own height instead of spanning the real
+       content rows, shoving everything after it down a gap the height
+       of the TOC. (Exactly the bug the flagship shipped and fixed,
+       2026-07-20 — captured here so this module doesn't reintroduce
+       it.) A generous explicit span covers any Essay's block count;
+       empty implicit rows stay 0-height. */
+    grid-row: 1 / span 999;
+    align-self: start;
+    justify-self: start;
+    position: sticky;
+    top: var(--space-6);
+    width: 100%;
+    max-height: calc(100vh - var(--space-8));
+    overflow-y: auto;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "engines": {
     "node": ">=18"
   },
@@ -68,6 +68,8 @@
     "./prose.css": "./prose.css",
     "./print": "./print.css",
     "./print.css": "./print.css",
+    "./essay": "./essay.css",
+    "./essay.css": "./essay.css",
     "./agent-rules": "./AGENT_RULES.md",
     "./spec": "./REMARQUE.md",
     "./package.json": "./package.json"
@@ -92,6 +94,7 @@
     "scripts/tokens-json.mjs",
     "prose.css",
     "print.css",
+    "essay.css",
     "scripts/lib/css-tokens.mjs"
   ]
 }

package/print.css

@@ -18,10 +18,11 @@
  * markup — a site with different class names should add its own
  * @media print rule for anything this file doesn't catch.
  *
- * Sidenotes: this package does not yet ship a sidenotes module. When
- * one lands, its narrow-viewport "inline" mode is exactly the right
- * print behavior — print should never attempt the wide-margin
- * side-rail layout a sidenotes module might use on desktop screens.
+ * Sidenotes/TOC rail (remarque-tokens/essay.css, issue #52): the "Force
+ * the narrow-viewport mode" rule below is this file making good on the
+ * promise above — the essay module's own default (non-`@media`) CSS
+ * already IS the narrow-viewport inline mode, so this rule only needs to
+ * cancel the `>= 80rem` float, not author a print-specific layout.
  */
 
 @page {
@@ -84,17 +85,43 @@
     display: none !important;
   }
 
+  /* ─── Sidenotes: force the narrow-viewport (inline) mode ───
+   * essay.css's `>= 80rem` float/negative-margin rule has no viewport to
+   * key off of on paper, and some print engines DO evaluate desktop-width
+   * `@media (min-width)` queries against the page box. Cancel it
+   * explicitly rather than relying on that not happening — a floated
+   * margin note next to a 2cm-margin page is exactly the layout the
+   * comment at the top of this file promises never to attempt. */
+  .remarque-sidenote {
+    float: none !important;
+    width: auto !important;
+    margin-inline-start: 0 !important;
+    margin-block: var(--space-3) !important;
+    padding-inline-start: var(--space-3) !important;
+    padding-inline-end: 0 !important;
+    border-inline-start: var(--border-width) var(--border-style) var(--color-border-bold) !important;
+    border-inline-end: none !important;
+  }
+
   /* ─── Full-width reading column ────────────────────────────
    * The page itself is already narrow at 2cm margins — don't also
-   * constrain content to the on-screen reading measure. */
+   * constrain content to the on-screen reading measure. Also collapses
+   * `.remarque-essay` back to plain block flow — same defensive reasoning
+   * as the sidenote float-cancel above, for the grid rather than the
+   * float half of essay.css's wide-viewport rule. */
   .content-reading,
   .content-standard,
   .content-wide,
+  .remarque-essay,
   main {
     max-width: 100% !important;
     margin-inline: 0 !important;
   }
 
+  .remarque-essay {
+    display: block !important;
+  }
+
   body {
     font-size: 11pt;
     line-height: 1.5;

package/theme.css

@@ -24,6 +24,9 @@
  * is never overridden (mt-12 stays 3rem; use mt-remarque-9 for 6rem).
  * Motion utilities: use arbitrary values with the tokens —
  * duration-[var(--motion-fast)] — so reduced-motion zeroing applies.
+ * Pair every duration-[var(--motion-*)] utility with ease-remarque
+ * (mapped below from --motion-easing) — without it Tailwind falls back
+ * to its default `ease` timing function instead of the token (issue #31).
  */
 
 @theme inline {
@@ -74,4 +77,8 @@
   /* Radius (rounded-sm / rounded-md — the system's ceiling) */
   --radius-sm: var(--radius-sm);
   --radius-md: var(--radius-md);
+
+  /* Easing (ease-remarque) — pair with duration-[var(--motion-*)] so
+     transitions use the token instead of Tailwind's default `ease` */
+  --ease-remarque: var(--motion-easing);
 }

package/tokens.d.ts

@@ -1,6 +1,6 @@
 /*
  * Remarque design tokens — GENERATED from tokens.json by
- * scripts/tokens-json.mjs (v0.13.0). Do not edit — the CSS
+ * scripts/tokens-json.mjs (v0.15.0). Do not edit — the CSS
  * (tokens-core.css + tokens-palette.css) is the source of truth;
  * tokens.json is the intermediate machine-readable form this file is
  * generated from. Regenerate with: node scripts/tokens-json.mjs

package/tokens.json

@@ -2,7 +2,7 @@
   "$description": "Remarque design tokens — GENERATED from tokens-core.css + tokens-palette.css by scripts/tokens-json.mjs. Do not edit; the CSS is the source of truth.",
   "$extensions": {
     "remarque": {
-      "version": "0.13.0",
+      "version": "0.15.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"