remarque-tokens 0.15.0 → 0.17.0

package/AGENT_RULES.md

@@ -62,12 +62,14 @@ These are not guidelines. Agents must follow them literally.
 - Within the centered column, use `.content-reading` for prose-width sections (46rem, auto-centered within the 72rem column)
 - Do NOT use Tailwind's `max-w-reading` or `max-w-standard` on page sections — these only set max-width without centering. Use the CSS classes `.content-reading` / `.content-standard` instead, which include `margin-inline: auto`
 - Code blocks (`<pre>`) inherit the width of their parent container — no special wrapping needed when the parent is already constrained
+- Stacking order is structural, not personalization: never author a bare `z-index` number — reference `tokens-core.css`'s `--z-*` scale (`--z-base`/`--z-sticky`/`--z-dropdown`/`--z-overlay`/`--z-modal`/`--z-toast`/`--z-skip-link`). Tailwind v4 has no `--z-index-*` theme namespace, so use arbitrary values (`z-[var(--z-modal)]`) rather than bare Tailwind numbers. See REMARQUE.md "Stacking."
 
 ### Color
 
 - Accent color is used for exactly two things: inline links and one interactive element per viewport
 - Dark mode is not an inverted light mode — it must be independently tuned for readability
 - Background colors use `--color-bg`, never pure white (#fff) or pure black (#000)
+- State colors (`--color-error`/`--color-success`/`--color-warning`/`--color-disabled`, plus the `-subtle` banner-background companions on the first three) are for feedback moments only — form validation, status banners, disabled controls — never for decoration. The one-accent rule above still governs everything else. See REMARQUE.md "State Colors."
 
 ### Components
 
@@ -142,6 +144,7 @@ project/
 ├── 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)
+├── broadsheet.css            # Optional Broadsheet pattern: masthead, lead, entry list, post kicker (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
@@ -203,6 +206,7 @@ Before considering any implementation complete, verify:
 - [ ] 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)
+- [ ] If a Landing/archive page uses the Broadsheet pattern (`remarque-tokens/broadsheet`): entry numerals are generated from `data-entry-number` via `attr()` (not `counter()`), the entry list stays a `<ul>` (not `<ol>` — the numeral is `aria-hidden` and decorative), and every kicker/dateline row uses `font-variant-caps: all-small-caps`, never `text-transform: uppercase`
 - [ ] Mobile version is roomy — not a compressed desktop layout
 - [ ] Mobile nav links have ≥44px touch targets
 - [ ] No pure white or pure black backgrounds
@@ -210,6 +214,8 @@ Before considering any implementation complete, verify:
 - [ ] Muted text placed on `--color-surface` still meets 4.5:1 (check the surface pairing, not just bg)
 - [ ] All transitions use the motion duration tokens (reduced-motion support depends on it)
 - [ ] Skip-to-content link present and functional
+- [ ] If state colors are used (error/success/warning/disabled): only for feedback moments (validation, banners, disabled controls), never decoration; every state text color and `-subtle` companion passes `npm run audit`
+- [ ] No bare `z-index` numbers anywhere in the page's CSS — every stacking layer references `tokens-core.css`'s `--z-*` scale
 - [ ] OG meta tags present (og:title, og:description, og:image)
 - [ ] `<html lang="en">` attribute set
 - [ ] The site looks more like a book than a web app

package/CHANGELOG.md

@@ -4,6 +4,127 @@ 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.17.0 — 2026-07-23
+
+Semantic state colors + z-index scale (closes #26, closes #29).
+
+### Added
+- **State colors (`tokens-palette.css`, PALETTE tier)** — four semantic slots for feedback
+  moments (form validation, status banners, disabled controls), never decoration; the
+  one-accent rule still governs everything else. Hand-authored from the house ANSI hue
+  conventions, both themes, all three dark-mode conventions (`@media
+  prefers-color-scheme: dark`, `[data-theme="dark"]`, `:root.dark`):
+  - `--color-error` (hue 25, ANSI red) — light `oklch(0.52 0.12 25)` 5.44:1 bg / 5.28:1
+    surface; dark `oklch(0.62 0.11 26)` 5.07:1 bg / 4.82:1 surface.
+  - `--color-success` (hue 145, ANSI green) — light `oklch(0.51 0.12 145)` 5.08:1 bg /
+    4.93:1 surface; dark `oklch(0.61 0.11 145)` 5.36:1 bg / 5.10:1 surface.
+  - `--color-warning` (hue 85, ANSI yellow) — light `oklch(0.52 0.105 85)` 5.17:1 bg /
+    5.02:1 surface; dark `oklch(0.62 0.11 85)` 5.29:1 bg / 5.03:1 surface. The hard case:
+    yellow's low luminance-contrast means this slot solves noticeably darker in light
+    mode than error/success, the same shape as `--color-syntax-constant`'s solve.
+  - `--color-disabled` — aliased to `var(--color-muted)` in both themes: neutral
+    hue-80 muted family, deliberately **not** ANSI-derived.
+  - `-subtle` banner-background companions on the first three (`--color-error-subtle`/
+    `--color-success-subtle`/`--color-warning-subtle`, modeled on `--color-accent-subtle`
+    — near-bg lightness, state hue, low chroma) verified so `--color-fg` stays ≥4.5:1 on
+    them (the pairing that matters for callout/banner body text). No `-subtle` for
+    `--color-disabled` — a disabled control is quieter, not tinted.
+  - Every state text color ≥4.5:1 against `--color-bg` **and** `--color-surface`, both
+    themes; `scripts/audit.mjs` gains the 11 new pairings, `scripts/test-audit.mjs`'s
+    fixtures cover all seven tokens plus a must-fail case (`state-color-fails.css`).
+  - `scripts/theme.mjs` (`remarque-theme`) derives error/success/warning from a source
+    theme's red/green/yellow ANSI slots — keep-if-passing lightness checked against the
+    **stricter** of `--color-bg`/`--color-surface` at once (a new dual-target solver,
+    `keepOrSolveDual`/`solveDual`), not just one target like every other slot. Disabled
+    aliases the already-derived `--color-muted`. `-subtle` companions derive like
+    `--color-accent-subtle` (fixed 0.95 / bg+0.06 starting lightness — not the theme's
+    own solved bg lightness, which can exceed 0.95), nudged toward the extreme only if a
+    pathological theme doesn't already clear 4.5:1 against `--color-fg`. Self-verify
+    `CHECKS` mirrors `audit.mjs`'s new pairings exactly.
+  - `scripts/palette-golden.mjs` golden-gates all seven new tokens for free (it already
+    iterates whatever the bridge emits) — ΔE2000 ≤ 2.0 against `remarque-light`/
+    `remarque-dark`'s ANSI derivation, same identity/serialization contract as the rest
+    of the default palette. All new tokens land at ΔE ≤ 0.5 (see the PR description for
+    the full per-token table).
+  - REMARQUE.md "State Colors" — semantics, usage table, derivation note; Enforcement
+    Checklist gains the state-color pairing line.
+- **Z-index scale (`tokens-core.css`, CORE tier)** — stacking is structural, not
+  personalization. A small ordinal scale, sparse gaps of 10: `--z-base` (0), `--z-sticky`
+  (10), `--z-dropdown` (20), `--z-overlay` (30), `--z-modal` (40), `--z-toast` (50),
+  `--z-skip-link` (60, tops everything). Wired into `essay.css`'s sticky TOC rail
+  (`z-index: var(--z-sticky)`) and the demo site's skip-to-content link
+  (`focus:z-[var(--z-skip-link)]`, replacing a hardcoded Tailwind `focus:z-50`).
+  `theme.css`'s header comment documents the Tailwind v4 workaround — v4 has no
+  `--z-index-*` theme namespace, so `z-*` utilities can't map to these directly; use
+  arbitrary values (`z-[var(--z-modal)]`) instead, same pattern as the motion durations.
+  REMARQUE.md "Stacking" — the scale, and the rule that consumer CSS must never author a
+  bare `z-index` number. AGENT_RULES.md's Layout/Quality Checklist sections gain matching
+  lines.
+
+### Changed
+- **`scripts/tokens-json.mjs`** — `typeOf()` now types `--z-*` tokens as `number`
+  (unitless stacking-order integers), matching the existing `--leading-*` treatment,
+  instead of falling through to the generic `string` type.
+
+## 0.16.0 — 2026-07-23
+
+Broadsheet pattern — masthead, lead article, numbered entry list, post-header kicker, graduated from the flagship (closes #36).
+
+### Added
+- **`broadsheet.css`** (new subpath: `remarque-tokens/broadsheet`, `remarque-tokens/broadsheet.css`) —
+  optional editorial Landing/archive pattern, not aggregated into `tokens.css` or `prose.css`.
+  Validated downstream on williamzujkowski.github.io (landing PR #213, archive/tag/post-header
+  PR #214) before upstreaming. Adds four primitives:
+  - `.remarque-masthead` — centered nameplate: mono small-caps kicker, oversized mixed
+    roman + italic `--font-display` title, mono dateline with hairline-rule separators.
+    **Fluid-type decision:** the flagship's `clamp(3.5rem, 9vw, 7.5rem)` title exceeds
+    `--text-display` (tokens-core.css's largest rung, `clamp(2.75rem, 5.5vw, 5rem)`) — no
+    existing token reaches it, so `.remarque-masthead` declares a file-scoped
+    `--remarque-masthead-size` whose min/max bounds are arithmetic on existing core spacing
+    tokens (`--space-7 + --space-2` = 3.5rem, `--space-10 - --space-2` = 7.5rem) rather than
+    new literals or a new core token — both resolve to the exact flagship values already
+    validated (contrast/gamut/font-floor audits + axe).
+  - `.remarque-lead` — mono kicker, large `--font-display` title (reuses `--text-display`
+    as-is — its range covers the flagship's closely enough that no exception was needed
+    here), underline-grow hover (`--motion-normal`/`--motion-easing`, reduced-motion-safe
+    for free via tokens-core.css's existing zeroing), italic lede with an italic drop cap
+    (same 3.5em/`initial-letter` mechanics as `.remarque-prose--dropcap` — one drop-cap
+    voice, not a second bespoke number).
+  - `.remarque-entry-list` / `.remarque-entry` — numbered entries via `data-entry-number`
+    + `attr()`, NOT `counter()` (counter-generated content doesn't reliably receive the
+    OpenType oldstyle-figure treatment across Newsreader's weights — a graduation finding
+    worth keeping). Numeral column sized in `ch` units (intrinsic to the glyphs) rather
+    than an asserted rem literal. `<ul>`, not `<ol>` — the numeral is `aria-hidden` and
+    decorative, an `<ol>` would double-announce the position. Collapses to one column via
+    a container query at `40rem` (exactly `--space-10` x 5, matching the flagship's `640px`
+    — container-query conditions can't reference custom properties/`calc()`, so this is
+    the literal the multiple resolves to).
+  - `.remarque-post-kicker` — the same mono kicker voice, scaled to sit above an
+    individual post's own title.
+  - `font-variant-caps: all-small-caps` on every kicker/dateline row, not
+    `text-transform: uppercase` — the flagship predates the Small Caps rule and used
+    uppercase throughout this pattern; corrected on the way upstream, same as the Essay
+    Module's TOC summary.
+- **`print.css`** — caps the masthead/lead title point sizes for print (28pt/18pt, matching
+  this file's existing `body { font-size: 11pt; }` convention) instead of printing the
+  on-screen fluid nameplate size; adds `.remarque-masthead`/`.remarque-lead`/
+  `.remarque-entry-list` to the existing full-width-on-print selector list.
+- **REMARQUE.md "Patterns"** — new top-level section (Broadsheet is its first entry),
+  markup contract, the fluid-type decision writeup, and when-to-use guidance. Landing
+  archetype's "Optionally includes" list now references it.
+- **AGENT_RULES.md** — File Structure Convention lists `broadsheet.css`; Quality Checklist
+  gains a Broadsheet-pattern line (`attr()` not `counter()`, `<ul>` not `<ol>`, small caps
+  not uppercase).
+- **Demo site (`site/`)** — `site/src/components/BroadsheetEntry.astro` (reference
+  lead/entry component); `writing/index` restyled as a broadsheet archive (masthead + lead
+  + entry list); `writing/against-decoration` gains the post-header kicker. New VR baseline:
+  `broadsheet-{light,dark}-{desktop,mobile}.png` (4 files, `writing` path added to `PAGES`).
+
+### Documentation
+- **README.md "Graduation"** — adds this release to the "Historical examples" list; the
+  "optional module" destination list now names the Broadsheet pattern alongside sidenotes/
+  TOC rail/palette deck.
+
 ## 0.15.0 — 2026-07-23
 
 Essay module — sidenotes + sticky TOC rail, graduated from the flagship (closes #52).

package/README.md

@@ -133,9 +133,10 @@ margin and should stay there. A local invention is upstreamable when **all four*
    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.
+argument); optional module (sidenotes, TOC rail, palette deck, the Broadsheet pattern); 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
@@ -143,7 +144,10 @@ 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.
+the Broadsheet editorial pattern (masthead, lead article, numbered entry list, post-header
+kicker) graduated as an optional pattern module
+([#36](https://github.com/williamzujkowski/remarque/issues/36)); the zine layer
+deliberately stayed local.
 
 **Standing rulings** (ratified 3-0, 2026-07-23) on patterns the reviews kept re-flagging:
 

package/REMARQUE.md

@@ -90,6 +90,23 @@ The audit remains the gate regardless of provenance — `remarque-theme` self-ve
 
 ---
 
+## State Colors
+
+Four semantic slots — `--color-error`, `--color-success`, `--color-warning`, `--color-disabled` — for feedback moments: form validation, status banners, disabled controls. **These are for feedback, not decoration.** The one-accent rule ("Visual Rules" / "Changing the Accent Hue") still governs expressive color everywhere else — a state color says "this specific thing failed/succeeded/needs attention/can't be used right now," not "this section is important." Don't recolor headings, borders, or chrome with a state color; reserve it for the actual feedback element (an inline error message, a success toast, a disabled button's text).
+
+Three of the four carry a `-subtle` companion — `--color-error-subtle`, `--color-success-subtle`, `--color-warning-subtle` — a faint tinted background for callout/banner-style feedback (an error banner, a success toast), sized the same way `--color-accent-subtle` is: near-`--color-bg` lightness, the state's hue, low chroma. `--color-disabled` has no `-subtle` companion — a disabled control is quieter than its enabled state, not tinted; use `--color-surface`/`--color-bg-subtle` for a disabled control's background if it needs one.
+
+| Slot | Use for | `-subtle` companion |
+|---|---|---|
+| `--color-error` | Validation errors, failure states, destructive-action confirmation text | `--color-error-subtle` (banner/callout background) |
+| `--color-success` | Confirmation messages, completed states | `--color-success-subtle` |
+| `--color-warning` | Caution messages, states needing attention before proceeding | `--color-warning-subtle` |
+| `--color-disabled` | Text/icon color for a disabled control | — (no subtle background; see above) |
+
+**Derivation:** hand-authored in `tokens-palette.css` from the house ANSI hue conventions — error hue 25 (red), success hue 145 (green), warning hue 85 (yellow) — the same conventions `--color-syntax-string`/`--color-syntax-constant` already use for green/yellow. `scripts/remarque-theme` derives all three from a source theme's `red`/`green`/`yellow` ANSI slots (keep-if-passing lightness, checked against the **stricter** of `--color-bg` and `--color-surface` at once, not just one), exactly like every other slot in "Color Providers." `--color-disabled` is deliberately **not** ANSI-derived — it aliases the already-derived neutral `--color-muted` family, since a disabled state is a muted/quiet register, not a hue. Warning (hue 85, yellow) is the hard case in light mode — yellow has low luminance-contrast against a light background, so its solved lightness sits noticeably darker than the other two states, the same shape as `--color-syntax-constant`'s solve. Every state text color holds ≥ 4.5:1 against `--color-bg` **and** `--color-surface` in both themes; every `-subtle` background holds `--color-fg` ≥ 4.5:1 on it (the pairing that matters for a callout's body text) — both enforced by `scripts/audit.mjs` and golden-gated (ΔE2000 ≤ 2.0) against the upstream themes like the rest of the default palette.
+
+---
+
 ## Font Slots
 
 Remarque uses a three-slot font system. Each slot has a strict role, and each slot accepts a small set of approved faces — swap the face, keep the role.
@@ -365,6 +382,26 @@ Motion in Remarque is nearly invisible. The only permitted motion:
 
 ---
 
+## Stacking
+
+Stacking order is structural, not personalization — `tokens-core.css` (CORE tier, never overridden) carries a small ordinal `--z-*` scale:
+
+| Token | Value | Use for |
+|---|---:|---|
+| `--z-base` | 0 | Default stacking context — the implicit baseline |
+| `--z-sticky` | 10 | Sticky headers/rails (essay.css's TOC rail) |
+| `--z-dropdown` | 20 | Dropdown/select menus |
+| `--z-overlay` | 30 | Overlays/backdrops |
+| `--z-modal` | 40 | Modal dialogs |
+| `--z-toast` | 50 | Toast/notification stacks |
+| `--z-skip-link` | 60 | The skip-to-content link — tops everything; it must never be obscured when focused |
+
+**The rule: never a bare `z-index` number in consumer CSS.** Reference one of these seven tokens instead — an unnamed `z-index: 999` (or any other asserted integer) can't be reasoned about against the rest of the page's stacking contexts, and it's the same "hardcoded value bypasses the token system" problem as a literal hex color or a bare font-size. The scale is deliberately sparse (gaps of 10) so a future layer can be inserted between two existing rungs without renumbering everything above it.
+
+Tailwind v4 ships `z-*` as a static, non-themable utility scale — there's no `--z-index-*` entry in its default `@theme` to map these into. `theme.css` (the Tailwind v4 adapter) documents the workaround in its header comment: use arbitrary values with the tokens, `z-[var(--z-modal)]` / `focus:z-[var(--z-skip-link)]`, the same pattern already used for motion durations (`duration-[var(--motion-fast)]`).
+
+---
+
 ## USWDS Accessibility Compliance
 
 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/):
@@ -419,6 +456,8 @@ Every PR that ships Remarque pages MUST pass (`npm run audit` automates the colo
 - [ ] No hardcoded hex/rgb colors — only `var(--color-*)` tokens.
 - [ ] Body line-height ≥ 1.5 (Remarque target: 1.75).
 - [ ] Every `--color-syntax-*` slot ≥ 4.5:1 against `--color-code-bg` in both themes (see "Syntax Highlighting").
+- [ ] Every `--color-error`/`--color-success`/`--color-warning`/`--color-disabled` ≥ 4.5:1 against `--color-bg` **and** `--color-surface` in both themes; every `-subtle` background keeps `--color-fg` ≥ 4.5:1 on it (see "State Colors"). State colors used only for feedback moments, never decoration.
+- [ ] No bare `z-index` number in consumer CSS — reference `tokens-core.css`'s `--z-*` scale (see "Stacking").
 
 Agents reviewing PRs should reject changes that violate any line above without explicit rationale.
 
@@ -556,6 +595,7 @@ The homepage or entry point. Sets the tone.
 - Recent entries or updates (3–5 max)
 - A brief "about" line
 - **CLI-tool landing only:** a single mono install command block (styled as prose `<pre>`, copy button allowed) — the one sanctioned interactive element on an otherwise CTA-free page — and an optional `--help`-output figure (follows the Plate convention, see Image Treatment)
+- **Editorial/archive landing:** the Broadsheet pattern's masthead + lead article + numbered entry list (own module, `remarque-tokens/broadsheet`) — see "Patterns" below
 
 **Never includes:**
 - Hero images or banners
@@ -774,6 +814,170 @@ applied so the next consumer doesn't rediscover it.
 
 ---
 
+## Patterns
+
+Optional, opt-in composition patterns for specific contexts — unlike the
+Essay Module above (one archetype, two related features), a "pattern" in
+this section is a small family of primitives meant to be composed
+together, shipped as its own subpath rather than aggregated.
+
+### Broadsheet
+
+The editorial Landing/archive pattern: a newspaper-broadsheet voice for
+the typography-maximalist end of the system. Own subpath,
+`remarque-tokens/broadsheet` (`broadsheet.css`) — not aggregated into
+`tokens.css` or `prose.css`.
+
+**Provenance.** Graduated from williamzujkowski.github.io's landing
+masthead and archive/tag/post-header implementation, validated in
+[PR #213](https://github.com/williamzujkowski/williamzujkowski.github.io/pull/213)
+(landing) and [PR #214](https://github.com/williamzujkowski/williamzujkowski.github.io/pull/214)
+(archive/tag/post-header) — all Remarque tokens, all audits + axe passing
+downstream before upstreaming — ratified in
+[issue #36](https://github.com/williamzujkowski/remarque/issues/36) per
+the "Graduation" checklist in the package README. No site-specific
+literal was copied; every dimension is re-derived from tokens this
+package already ships (see `broadsheet.css`'s header comment for the
+value-by-value mapping and the fluid-type decision below).
+
+Four primitives, composed independently — a page can use any subset:
+
+1. **Masthead** (`.remarque-masthead`) — centered nameplate: mono
+   small-caps kicker, an oversized mixed roman + italic `--font-display`
+   title, mono dateline with hairline-rule separators.
+2. **Lead article** (`.remarque-lead`) — a featured story: mono kicker
+   (`Section · N min read · Date`), a large `--font-display` title with
+   underline-grow hover, an italic lede paragraph with an italic drop cap.
+3. **Numbered entry list** (`.remarque-entry-list` / `.remarque-entry`) —
+   italic oldstyle-figure numerals in the outer margin (via
+   `data-entry-number`), a two-column grid (numeral / kicker+title+excerpt),
+   a hairline between entries, collapsing to one column in a narrow
+   container.
+4. **Post-header kicker** (`.remarque-post-kicker`) — the same mono
+   `Section · Reading time · Date` line, scaled down to sit above an
+   individual post's own title.
+
+### Markup contract
+
+```html
+<header class="remarque-masthead">
+  <p class="remarque-masthead-kicker"><span>Field Notes</span></p>
+  <h1 class="remarque-masthead-title">Quiet <em>Signals</em></h1>
+  <p class="remarque-masthead-dateline">
+    <span class="remarque-rule" aria-hidden="true"></span>
+    <span>July 23, 2026</span>
+    <span class="remarque-rule" aria-hidden="true"></span>
+  </p>
+</header>
+
+<article class="remarque-lead">
+  <p class="remarque-lead-kicker">
+    <span class="remarque-lead-section">Essay</span>
+    <span class="remarque-dot" aria-hidden="true">&middot;</span>
+    <span>8 min read</span>
+    <span class="remarque-dot" aria-hidden="true">&middot;</span>
+    <time datetime="2026-04-08">Apr 8, 2026</time>
+  </p>
+  <h2 class="remarque-lead-title"><a href="/writing/x">Title</a></h2>
+  <p class="remarque-lead-lede">Lede paragraph…</p>
+</article>
+
+<ul class="remarque-entry-list">
+  <li class="remarque-entry">
+    <span class="remarque-entry-numeral" data-entry-number="2" aria-hidden="true"></span>
+    <div class="remarque-entry-body">
+      <p class="remarque-entry-kicker">
+        <span class="remarque-entry-section">Essay</span>
+        <span class="remarque-dot" aria-hidden="true">&middot;</span>
+        <span>6 min read</span>
+        <span class="remarque-dot" aria-hidden="true">&middot;</span>
+        <time datetime="2026-03-29">Mar 29, 2026</time>
+      </p>
+      <h3 class="remarque-entry-title"><a href="/writing/y">Title</a></h3>
+      <p class="remarque-entry-excerpt">Excerpt…</p>
+    </div>
+  </li>
+</ul>
+
+<header class="remarque-post-header">
+  <p class="remarque-post-kicker">
+    <span class="remarque-post-kicker-section">Essay</span>
+    <span class="remarque-dot" aria-hidden="true">&middot;</span>
+    <span>8 min read</span>
+    <span class="remarque-dot" aria-hidden="true">&middot;</span>
+    <time datetime="2026-04-08">Apr 8, 2026</time>
+  </p>
+  <h1 class="text-display font-display">Post Title</h1>
+</header>
+```
+
+Requirements the CSS depends on:
+
+- `.remarque-entry-list` uses `<ul>`, not `<ol>` — the visual numeral is
+  decorative (`aria-hidden`) and generated from `data-entry-number`; an
+  `<ol>` would have a screen reader announce "1 of 2" alongside it, a
+  second voice for the same information.
+- Entry numerals are generated via `content: attr(data-entry-number)` on
+  `.remarque-entry-numeral::before`, NOT CSS `counter()`. `attr()` reads
+  the attribute of the element the pseudo-content is generated on, so
+  `data-entry-number` goes on `.remarque-entry-numeral` itself, not the
+  parent `<li>`.
+- Every kicker/dateline row (`.remarque-masthead-kicker`,
+  `.remarque-masthead-dateline`, `.remarque-lead-kicker`,
+  `.remarque-entry-kicker`, `.remarque-post-kicker`) uses
+  `font-variant-caps: all-small-caps` — never `text-transform: uppercase`
+  (the flagship predates the Small Caps rule and used uppercase
+  throughout this pattern; corrected on the way upstream, same as the
+  Essay Module's TOC summary).
+
+### Fluid-type decision: the masthead title
+
+The flagship's masthead title is `clamp(3.5rem, 9vw, 7.5rem)` — bigger
+than `--text-display` (tokens-core.css's largest type-scale rung,
+`clamp(2.75rem, 5.5vw, 5rem)`) ever reaches. Per issue #36's required
+call: express via an existing type token if the scale reaches that size,
+else a documented fluid exception using core tokens as bounds — never a
+new core token.
+
+The scale does not reach it, so `.remarque-masthead` declares a
+file-scoped custom property whose min/max bounds are arithmetic on
+tokens already in `tokens-core.css`, not new literals:
+
+```css
+--remarque-masthead-size: clamp(
+  calc(var(--space-7) + var(--space-2)),   /* 3rem + 0.5rem = 3.5rem */
+  9vw,
+  calc(var(--space-10) - var(--space-2))   /* 8rem - 0.5rem = 7.5rem */
+);
+```
+
+Both bounds resolve to the exact flagship values already validated
+downstream (contrast/gamut/font-floor audits + axe). The `9vw` rate is
+unchanged from the flagship — it continues the same escalating per-tier
+vw progression `tokens-core.css`'s own scale already uses (2.25vw
+section → 3.5vw title → 5.5vw display), one step further for a register
+one step past display. This property is declared inside `broadsheet.css`
+only, never added to `tokens-core.css` — it is local arithmetic on
+existing core tokens, not a new one.
+
+Everywhere else in the pattern, an existing token already covers the
+register: `.remarque-lead-title` uses `--text-display` as-is (its
+2.75–5rem range covers the flagship's 2.25–3.75rem closely enough that
+no exception is warranted), and `.remarque-entry-title` uses
+`--text-section` as-is (1.375–2rem vs. the flagship's 1.5–1.875rem).
+
+### When to use
+
+Landing/archive contexts only — a Landing page's masthead, or an
+archive/tag-listing page's lead-plus-entry-list. Typography-maximalist:
+this is the one pattern in Remarque where a title is allowed to outgrow
+`--text-display`, and it is deliberately reserved for exactly one
+register, not a general-purpose "big heading" utility. The post-header
+kicker is the one primitive meant for individual post pages rather than
+the archive itself.
+
+---
+
 ## Signature Moves
 
 These are the repeatable visual tells that make a Remarque site recognizable: