remarque-tokens 0.6.1 → 0.8.0

package/AGENT_RULES.md

@@ -26,7 +26,7 @@ Execute in this exact order. Do not skip steps. Do not reorder.
 
 8. **Validate readability on mobile** before adding any visual polish.
 
-9. **Verify every page conforms** to one of the four archetypes (Essay, Project Dossier, Notebook, Landing).
+9. **Verify every page conforms** to one of the seven archetypes (Essay, Project Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery).
 
 **Why this order matters:** Most agents build polished components first and bolt on typography later. That produces the exact aesthetic Remarque exists to prevent. Typography and prose are the foundation. Everything else is furniture.
 
@@ -160,6 +160,8 @@ project/
     └── notes                 # Notebook archetype
 ```
 
+Three further archetypes — Reference/Docs, Changelog, Gallery — are specified in REMARQUE.md but have no reference page in this repo's demo site yet; build them per spec, they follow the same file-structure conventions as the four above (e.g. `docs/[slug]`, `changelog`, `gallery` or `browse`).
+
 ### Implementation Pitfalls (learned from reference implementation)
 
 1. **Tailwind spacing collision:** Never map Remarque's `--space-N` values onto Tailwind's default numeric spacing keys — in v4 `@theme` that means no `--spacing-9`…`--spacing-12`, and in the v3 config no `spacing: { "5"…"12" }` overrides — or `mt-12` produces 192px instead of 48px. Both shipped artifacts namespace instead: the v3 config exposes `mt-remarque-9` etc., the reference v4 `@theme` uses `--spacing-remarque-N`. Use those, or `var(--space-N)` in arbitrary values.
@@ -195,7 +197,7 @@ Before considering any implementation complete, verify:
 - [ ] Accent color appears in ≤2 roles per viewport
 - [ ] 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)
+- [ ] Every page maps to an archetype (Essay, Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery)
 - [ ] 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,120 @@ 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.8.0 — 2026-07-21
+
+Archetype-vocabulary and AI-agent-packaging release (design review; closes
+#55, closes #57).
+
+### Added
+- **Three new page archetypes** (#55): Reference/Docs (persistent nav
+  rail, breadcrumb kicker, prev/next footer — reuses Essay's three-column
+  shape), Changelog (mono version/date headline, grouped Added/Changed/
+  Fixed lists — built from Notebook's entry structure), and Gallery
+  (content-wide cover grids, covers exempt from the reading-width cap,
+  border-only hover — formalized from tsundoku's documented reference
+  implementation, cited directly in REMARQUE.md). Seven archetypes total;
+  agents must not invent an eighth.
+- **Plate** (#55): a screenshot-heavy-page subsection of Image Treatment —
+  numbered mono captions, a narrow 2-up exception for terminal captures.
+- **CLI-tool landing guidance** (#55): a scoped, rationale-argued exception
+  to Landing's no-CTA rule for a single mono install command block.
+- **Dataviz Tokens** (#55): chart grid/axis/categorical-ramp mapped onto
+  existing tokens and required to pass the audit — citing tsundoku's
+  orthogonal category-color system as precedent and naming the one gap
+  (never run through `remarque-audit`'s `CHECKS` array) this guidance
+  closes.
+- **`remarque-tokens/agent-rules` and `remarque-tokens/spec` exports**
+  (#57): both files were already in `files`; this ships them as named
+  subpaths so a consumer can `require.resolve('remarque-tokens/agent-rules')`
+  instead of hardcoding a `node_modules` path.
+- **`.claude/skills/remarque/SKILL.md`** (#57): a Claude Code skill
+  triggering on "remarque" / "design system" / new-page work. Loads
+  `AGENT_RULES.md` + `REMARQUE.md` + `tokens.json`, states the token-tier
+  rules, the audit command, and Pitfalls #6/#7 (string-form `@import`;
+  unlayered token import under Tailwind v4) inline — both pass a green
+  build while silently breaking, so they're worth surfacing without a
+  file round-trip.
+- **`/tokens.json` on the demo site** (#57): `site/scripts/copy-tokens-json.mjs`
+  runs as a prebuild step (`npm run build` in `site/`), copying the
+  installed package's `tokens.json` into `public/` so it ships at
+  `https://williamzujkowski.github.io/remarque/tokens.json` — a remote
+  agent can fetch current token values instead of trusting training data.
+  The copy is generated, not a source file (`site/public/tokens.json` is
+  gitignored).
+- Root README's "For AI Agents" section documents all three packaging
+  additions above.
+
+No core-tier token values changed in this release.
+
+## 0.7.0 — 2026-07-21
+
+Typographic-completeness release (design review, #50/#51/#54): the
+prose element vocabulary, the editorial microtypography layer, and a
+print stylesheet — three gaps the review found between what Remarque
+claims to be ("rooted in book typography") and what it shipped.
+
+### Added
+- **Prose vocabulary completion** (#50): `.remarque-prose` now styles
+  every remaining Markdown element — table/th/td/caption (+
+  `.scroll-wrap` overflow container, mono th with a 2px bottom rule,
+  1px row rules, no zebra, `.num` opt-in for tabular-lining numeric
+  cells), dl/dt/dd (serif-italic term over a muted description, the
+  "specimen list" pattern), h4–h6 (a descent through the three font
+  slots), kbd (mono, 1px border), mark (`--color-accent-subtle`'s first
+  sanctioned use), abbr[title] (dotted underline), sup/sub (footnote-
+  marker-safe sizing), and details/summary (quiet mono triangle
+  marker). No Markdown element renders unstyled after this release.
+- **Editorial microtypography** (#51): the numerals policy
+  (`--text-meta` → tabular-nums lining-nums; `.remarque-prose` →
+  oldstyle-nums proportional-nums — REMARQUE.md:179 mandated this but
+  no CSS ever implemented it); `.text-label` (true small caps via
+  `font-variant-caps`, replacing `text-transform: uppercase`);
+  `.remarque-prose--dropcap` (opt-in Essay first-paragraph drop cap);
+  `.pullquote` (display italic, hairline rules, distinct from
+  blockquote); wrapping/optical defaults (`text-wrap: balance` on
+  headings, `text-wrap: pretty` + `hanging-punctuation` on prose,
+  `font-synthesis: none`, `font-optical-sizing: auto`). New "Editorial
+  Microtypography" spec section in REMARQUE.md.
+- **`remarque-tokens/print.css`** (#54): a print layer scoped entirely
+  inside `@page`/`@media print` — forces the light palette with true
+  black-on-white (ink economy), hides nav/footer/TOC/theme-toggle/skip-
+  link, expands content to full page width at 2cm margins, sets body
+  to 11pt, appends `(url)` after external links, and applies
+  orphans/widows/break-inside discipline to figures/tables/pre. Own
+  subpath — not included by the `tokens.css` aggregator; import
+  explicitly.
+- **Drift-detection CI** (#47/#48, consensus-armed now that 2+ sites
+  consume the package — williamzujkowski.github.io and tsundoku both pull
+  `remarque-tokens` from npm): `scripts/drift-check.mjs` (shipped in the
+  package; `files` + a `remarque-drift` bin entry) compares a consumer's
+  stylesheet against the INSTALLED package's `tokens.json`. Reuses
+  `scripts/lib/css-tokens.mjs` rather than a third CSS parser.
+  - CORE-tier token redefined with a different value → **FAIL** (exit 1),
+    unless the consumer's `DESIGN-DEVIATIONS.md` or `DESIGN-NOTES.md`
+    names the token — then **WARN** with a pointer to that doc.
+  - PALETTE-tier divergence → **INFO** (sanctioned personalization,
+    listed, never blocking).
+  - CORE-tier token consumed only via `var()`, never redeclared → no-op
+    (it resolves from the package import).
+  - Also prints the installed `remarque-tokens` version.
+  - `.github/workflows/token-drift.yml`: reusable `workflow_call` wrapper
+    consumers can call cross-repo (`css-file`, `package-dir` inputs).
+  - `scripts/test-drift.mjs`: fixture tests for the classification rules
+    (9 cases), wired into `deploy.yml` alongside `test-audit.mjs`.
+
+### Changed
+- `scripts/audit.mjs`'s token-file classification now recognizes
+  `print.css` (it carries literal `oklch()` values for the forced
+  print palette, same as a palette file).
+- Demo site (`site/`): specimen page exercises the new table/dl/kbd/
+  mark/abbr/sup-sub/details vocabulary; the five faux-uppercase eyebrow
+  labels (`index.astro` x3, `tokens.astro`, `projects/remarque.astro`)
+  now use `.text-label`; `against-decoration.astro` demonstrates the
+  opt-in drop cap (`<Prose dropcap>`) and a `.pullquote`.
+
+No core-tier token values changed in this release.
+
 ## 0.6.1 — 2026-07-21
 
 ### Fixed

package/README.md

@@ -58,6 +58,11 @@ See: REMARQUE.md for specification, AGENT_RULES.md for implementation contract,
 
 The agent rules define build order, non-negotiable rules, disallowed patterns, and a quality checklist. Every decision is specified — agents don't need to guess.
 
+Packaging for agent tooling:
+- **npm exports:** `remarque-tokens/agent-rules` (→ `AGENT_RULES.md`) and `remarque-tokens/spec` (→ `REMARQUE.md`), alongside the existing `remarque-tokens/tokens.json`, so a project can point an agent at `node_modules/remarque-tokens/AGENT_RULES.md` without hardcoding a filename.
+- **Claude Code skill:** [`.claude/skills/remarque/SKILL.md`](.claude/skills/remarque/SKILL.md) — triggers on "remarque" / "design system" / new-page work, loads all three files, and states the tier rules, the audit command, and the two build-time pitfalls (unlayered-token-import, string-form `@import`) that pass a green build while silently breaking.
+- **Live tokens endpoint:** the demo site serves the current `tokens.json` at **https://williamzujkowski.github.io/remarque/tokens.json** — a remote agent can fetch current token values directly instead of trusting training data.
+
 ## Files
 
 | File | Purpose |
@@ -83,14 +88,17 @@ The agent rules define build order, non-negotiable rules, disallowed patterns, a
 
 ## Page Archetypes
 
-Every page conforms to one of four archetypes:
+Every page conforms to one of seven archetypes:
 
 - **Essay** — long-form writing with serif title, mono metadata, narrow reading column
 - **Project Dossier** — structured project page with metadata block and architecture section
 - **Notebook** — short-form notes with mono timestamps, no cards
 - **Landing** — identity statement, content navigation, generous whitespace
+- **Reference/Docs** — persistent nav rail, breadcrumb kicker, prev/next footer (reuses Essay's three-column shape)
+- **Changelog** — mono version/date headlines, grouped Added/Changed/Fixed lists (built from Notebook's entry structure)
+- **Gallery** — cover-grid pages at `--content-wide`, covers exempt from the reading-width cap (formalized from tsundoku's reference implementation)
 
-See the [live demo](https://williamzujkowski.github.io/remarque/) for all four archetypes in action.
+See the [live demo](https://williamzujkowski.github.io/remarque/) for the original four archetypes in action — Reference/Docs, Changelog, and Gallery are specified in REMARQUE.md but don't yet have a demo page in this repo.
 
 ## Design Decisions
 

package/REMARQUE.md

@@ -100,6 +100,50 @@ This is why the measure is palette-tier: it is a property of the font choice, no
 
 ---
 
+## Editorial Microtypography
+
+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.
+
+### Numerals
+
+Two numeral registers, chosen by context:
+
+- **`.remarque-prose`** uses `font-variant-numeric: oldstyle-nums proportional-nums` — text figures that sit quietly inside a sentence, the way numerals behave in well-set book prose.
+- **`.text-meta`** (and anything sharing its role — dates, counts, table cells, timestamps) uses `font-variant-numeric: tabular-nums lining-nums` — full-height, fixed-width digits that align in columns and don't jitter as they change.
+
+Never mix the two: a numeral inside running prose should never be tabular, and a numeral in a metadata row or table should never be oldstyle. Apply `.num` to any `<td>`/`<th>` holding numeric data to opt that cell into the tabular-lining register (see prose.css's table rules).
+
+### Small Caps
+
+`font-variant-caps: all-small-caps` — not `text-transform: uppercase` — for any label that wants a caps-like treatment. Faux uppercase renders letters at cap-height with no optical correction and reads louder than intended; true small caps render at x-height with corrected weight and spacing. `.text-label` (mono, `--text-meta`, all-small-caps, `--tracking-caps`, `--color-muted`) is the sanctioned utility. `text-transform: uppercase` is disallowed anywhere a label could use `.text-label` instead.
+
+### Drop Caps (opt-in)
+
+`.remarque-prose--dropcap`, applied alongside `.remarque-prose`, floats a large italic display-face initial letter on the first paragraph only — the way a printed essay opens its first page. Rules:
+
+- Essay first paragraph only — never mid-article, never in Dossier/Notebook/Landing content.
+- Uses `initial-letter` where supported, with a `float` + font-size fallback for browsers that lack it.
+- Inherits `--color-fg` — the drop cap is not a place for accent color.
+- Skipped automatically when the paragraph opens with a quote or inline code (the ornament assumes a plain capital letter).
+- Opt-in only. Most pages should not use it; it is reserved for essays that want a printed, literary register.
+
+### Pull Quotes
+
+`.pullquote` is not `.remarque-prose blockquote`. A blockquote cites someone else; a pullquote re-states the article's own words as a visual accent — a magazine convention. Rules:
+
+- Display italic at `--text-section` size, not blockquote's body-italic.
+- Hairline rules above and below (`--color-border`), no background, no accent color.
+- If the pulled text duplicates body copy verbatim, mark the element `<aside aria-hidden="true">` so screen readers don't hear it twice.
+- At most one per screen — it is a rare accent, not a recurring motif.
+
+### Wrapping & Optical Defaults
+
+- Headings: `text-wrap: balance`, `font-optical-sizing: auto`, `font-synthesis: none` — headings never wrap ragged, optical sizing lets variable fonts pick the right grade, and browsers never fake bold/italic for faces that don't have them.
+- Prose: `text-wrap: pretty` (avoids single-word orphan lines) and `hanging-punctuation: first last` (quotes and punctuation hang outside the measure rather than indenting the line).
+- All four properties degrade safely — unsupported browsers silently ignore them and fall back to normal wrapping. Invisible when absent, unmistakable when present.
+
+---
+
 ## Visual Rules
 
 ### Do
@@ -128,7 +172,7 @@ This is why the measure is palette-tier: it is a property of the font choice, no
 
 ## Content Density Rule
 
-No page should show more than three distinct content sections above the fold. The first screen of any page contains only: title, metadata, and the opening of content. Hero sections with CTAs, feature grids, and social proof are not part of Remarque's vocabulary.
+No page should show more than three distinct content sections above the fold. The first screen of any page contains only: title, metadata, and the opening of content. Hero sections with CTAs, feature grids, and social proof are not part of Remarque's vocabulary. (The CLI-tool landing install block, see the Landing archetype, is a single command — not a CTA — and does not count against this rule.)
 
 ---
 
@@ -143,6 +187,28 @@ Remarque is typography-first, but projects include screenshots, architecture dia
 - No rounded corners on images beyond `--radius-sm`
 - Images are never decorative — every image must serve the content
 
+### Plate (screenshot-heavy pages)
+
+Reference/Docs and Project Dossier pages often need to show several screenshots — six or more UI captures walking through a workflow — where "one image at a time" doesn't scale. Plate is the sanctioned pattern; everything above still applies, it only adds:
+
+- Default to single-column figures at `--content-reading` width, one screenshot per figure
+- Every figure gets a numbered mono caption in the form `Fig. 01 — description` (`--font-mono`, `--text-meta`) — the number is mandatory once a page has more than one figure, so prose can cross-reference a specific plate
+- A 2-up grid is permitted only for terminal/CLI captures, and only at `--content-standard` width — the one sanctioned exception to "images never wider than `--content-reading`," reserved for this narrow case
+- A page with six or more plates gets prev/next figure navigation (mono, matching Reference/Docs' footer convention) rather than an unbroken scroll
+
+---
+
+## Dataviz Tokens
+
+Charts are not yet a first-class Remarque surface, but tools built with the system inevitably need them. Rather than inventing chart-specific tokens, map dataviz elements onto vocabulary that already exists, so a chart survives a palette swap the same way prose and chrome do:
+
+- **Grid lines** use `--color-border` — never a separate "chart gray." Grid lines are structural, not decorative, and already have a sanctioned quiet role.
+- **Axis text and tick labels** use `--font-mono` at `--text-meta`, `--color-muted` — the same register as metadata rows and captions, never the body or display face.
+- **Categorical color ramp** is derived, not hand-picked: rotate hue at the accent's lightness/chroma steps — the same discipline "Changing the Accent Hue" already prescribes (fix lightness, vary hue, reduce chroma until every value clears the gamut) — producing a small hue family distinct from `--color-accent` itself, so chart color is never mistaken for the system's one interactive signal.
+- That ramp must be **audit-validated**, exactly like a palette override: every ramp color needs to clear gamut and 4.5:1 contrast against `--color-bg`/`--color-surface` in both themes before it ships.
+
+**Precedent:** [tsundoku](https://github.com/williamzujkowski/tsundoku) built the underlying pattern already — its `DESIGN-NOTES.md` documents an 8-hue "orthogonal category system" (`--pop-pink`/`--pop-blue`/`--pop-green`/etc.), kept deliberately separate from `--color-accent` and used for content taxonomy (book categories, reading status) rather than interactivity. It held those hues to roughly the same lightness/contrast discipline as its audited palette, but by its own admission the hues were **never run through `remarque-audit`'s `CHECKS` array** — that is the one gap this guidance closes. A dataviz ramp should follow tsundoku's separation-from-accent instinct, but unlike its precedent, it must pass the audit before it ships.
+
 ---
 
 ## Motion Rules
@@ -280,7 +346,7 @@ This order is not a suggestion. It is the tiebreaker for every design decision.
 
 ## Page Archetypes
 
-Every page built with Remarque must conform to one of these four archetypes. Agents and implementers should not invent new page structures.
+Every page built with Remarque must conform to one of these seven archetypes: Essay, Project Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery. Agents and implementers should not invent new page structures — the last three exist precisely because real downstream projects (tsundoku, and the multi-site review that produced this revision) needed shapes the first four actively fought, and inventing an unsanctioned workaround is worse than extending the vocabulary here.
 
 ### Essay
 
@@ -352,6 +418,7 @@ The homepage or entry point. Sets the tone.
 **Optionally includes:**
 - 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)
 
 **Never includes:**
 - Hero images or banners
@@ -360,6 +427,67 @@ The homepage or entry point. Sets the tone.
 - Testimonial carousels
 - Newsletter signup forms above the fold
 
+The CLI install block is not a CTA exception in disguise — it is the single piece of information a CLI tool's landing page cannot omit (how do I get this), same status as a book's title. One block, one command, no surrounding marketing copy. A page with an install block *and* a separate "Sign up now" button has smuggled in a second CTA and fails this archetype.
+
+### Reference/Docs
+
+Persistent technical documentation: API references, config guides, multi-page manuals. Reuses the Essay archetype's existing three-column shape (nav rail outside the reading column · reading column · optional desktop ToC outside the reading column) — this is not a new layout engine, only a different left rail.
+
+**Always includes:**
+- A persistent left nav rail listing every doc page (mono, quiet, `--text-meta` — a list of links, not a component), sitting outside the reading column exactly like Essay's optional ToC sits outside it on the other side
+- A breadcrumb kicker above the title (mono, `--text-meta`, e.g. `Reference / Configuration`)
+- Content constrained to `--content-reading`, matching Essay's prose column
+- A low-noise prev/next footer nav between adjacent doc pages (mono, matching Essay's footer nav)
+
+**Optionally includes:**
+- Tables and code blocks widening past the reading column to `--content-standard` when the content genuinely needs the room (a config reference table, a wide code sample) — the surrounding prose stays at `--content-reading`
+- A desktop-only "on this page" ToC, reusing Essay's optional side-ToC convention, on the side opposite the nav rail
+
+**Never includes:**
+- Sidebar content mixed *into* the reading column itself (the nav rail is a fourth structural region, not reading-column content — same rule Essay already enforces for its own ToC)
+- Card grids for the page listing (the nav rail is a list, not a grid of cards)
+- More than one accent color
+- CTAs, feature grids, or any Landing-archetype vocabulary
+
+### Changelog
+
+A tool or project's primary log of released changes. Built from the Notebook archetype's entry structure, not a new component: compact, mono-timestamped, content-forward entries, applied to version history instead of notes.
+
+**Always includes:**
+- A mono version + date headline per entry (e.g. `0.7.0 — 2026-07-21`) — semver renders as plain mono text, never a colored pill or badge
+- Grouped category lists per entry (Added / Changed / Fixed, or whatever categories the project uses), reusing Notebook's compact entry rhythm
+- Reverse-chronological order, most recent release first
+
+**Optionally includes:**
+- An inline mono link to the relevant issue/PR per line item
+- A "compare" or diff link per version, mono, in the entry headline row
+
+**Never includes:**
+- Semver rendered as a pill/badge (`.rounded-full` chips, colored status pills) — plain mono text only, same rule as tags elsewhere in the system
+- Card-based per-version layout
+- Marketing framing of a change ("Exciting new feature!") — changelog prose stays as flat and factual as commit messages
+
+A changelog embedded as an optional subsection of a Project Dossier (already sanctioned) remains valid for short update logs. Promote to the standalone Changelog archetype once the log is long enough, or important enough, to be the page rather than a section of one — typically once a tool ships its own versioned releases.
+
+### Gallery
+
+Cover-grid and catalog pages — a page whose primary content unit is a grid of images with a caption, not prose. None of the other archetypes are shaped for this: they are all fundamentally text/document-shaped. **Reference implementation: [tsundoku](https://github.com/williamzujkowski/tsundoku)**, which needed this shape immediately for its book-catalog `/browse` grid and documented it as an informal fifth archetype in its `DESIGN-NOTES.md` before this spec existed; Gallery formalizes that implementation rather than inventing a new one.
+
+**Always includes:**
+- A grid container widened beyond `--content-standard` (72rem) to `--content-wide` (88rem) — Gallery is the only archetype permitted to exceed `--content-standard`, because a grid of cover-aspect thumbnails needs more horizontal room before it feels cramped than an essay or a dossier ever would
+- Cover/thumbnail images exempt from the `--content-reading` width cap that Image Treatment otherwise mandates — cover art *is* the content here, not illustrative decoration of prose. Every other Image Treatment rule still applies without exception: 1px `--color-border`, no drop shadow, mono captions
+- Grid item hover restricted to a border-color shift only (`--motion-fast`) — no scale, no lift, no shadow growth, matching Motion Rules' general prohibition on attention-seeking animation
+- Grid density driven by content (`repeat(auto-fill, minmax(...))` or breakpoint-based column counts), never a fixed card size that fights the image's native aspect ratio
+
+**Optionally includes:**
+- Prose-bearing sections within a Gallery page (an "about" blurb, an item description) narrowed back down to `--content-reading` — the widened container serves the grid only, not every element on the page
+- Mono captions under each cover (title, author, or other item metadata)
+
+**Never includes:**
+- Card shadows or scale/lift-on-hover
+- Masonry layouts (Notebook's existing prohibition applies here too — a fixed-ratio grid only)
+- The `--content-wide` container used for anything other than the grid itself
+
 ---
 
 ## Signature Moves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "engines": {
     "node": ">=18"
   },
@@ -22,10 +22,12 @@
   "homepage": "https://williamzujkowski.github.io/remarque/",
   "main": "tokens.css",
   "bin": {
-    "remarque-audit": "scripts/audit.mjs"
+    "remarque-audit": "scripts/audit.mjs",
+    "remarque-drift": "scripts/drift-check.mjs"
   },
   "scripts": {
-    "audit": "node scripts/audit.mjs"
+    "audit": "node scripts/audit.mjs",
+    "drift": "node scripts/drift-check.mjs"
   },
   "exports": {
     ".": "./tokens.css",
@@ -43,6 +45,10 @@
     "./tokens.json": "./tokens.json",
     "./prose": "./prose.css",
     "./prose.css": "./prose.css",
+    "./print": "./print.css",
+    "./print.css": "./print.css",
+    "./agent-rules": "./AGENT_RULES.md",
+    "./spec": "./REMARQUE.md",
     "./package.json": "./package.json"
   },
   "files": [
@@ -52,6 +58,7 @@
     "fonts.css",
     "fonts/",
     "scripts/audit.mjs",
+    "scripts/drift-check.mjs",
     "tailwind.config.js",
     "REMARQUE.md",
     "AGENT_RULES.md",
@@ -61,6 +68,7 @@
     "tokens.json",
     "scripts/tokens-json.mjs",
     "prose.css",
+    "print.css",
     "scripts/lib/css-tokens.mjs"
   ]
 }

package/print.css

@@ -0,0 +1,140 @@
+/*
+ * Remarque — Print Stylesheet
+ * ────────────────────────────
+ * A "rooted in book typography" system that prints screen chrome and
+ * dead links has not earned the claim. This file is scoped entirely
+ * inside @page/@media print — it has zero effect on screen rendering,
+ * so it is safe to import unconditionally alongside tokens.css.
+ *
+ * Own subpath (remarque-tokens/print, remarque-tokens/print.css) —
+ * NOT included by the tokens.css aggregator, since not every consumer
+ * wants it wired in automatically. Import explicitly:
+ *   @import 'remarque-tokens/print.css';
+ * (string form — see AGENT_RULES.md Pitfall #6.)
+ *
+ * Selectors for screen chrome (nav/footer/TOC/theme toggle/skip link)
+ * target common conventions (<nav>, <footer>, #theme-toggle, the
+ * "Skip to content" anchor) rather than any one consumer's exact
+ * 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.
+ */
+
+@page {
+  margin: 2cm;
+}
+
+@media print {
+  /* ─── Force the light palette (ink economy) ───────────────
+   * True black on white, not the screen theme's warm near-black/
+   * off-white — printed pages are read in ambient light with no theme
+   * toggle available, and a warm off-white background prints as a
+   * visible ink wash on many printers. Overrides regardless of which
+   * dark-mode convention put the site in dark mode. */
+  :root,
+  [data-theme="light"],
+  [data-theme="dark"],
+  :root.dark {
+    --color-bg: oklch(1 0 0);
+    --color-bg-subtle: oklch(1 0 0);
+    --color-fg: oklch(0 0 0);
+    --color-fg-muted: oklch(0.25 0 0);
+    --color-muted: oklch(0.35 0 0);
+    --color-border: oklch(0.7 0 0);
+    --color-border-bold: oklch(0.4 0 0);
+    --color-surface: oklch(1 0 0);
+    --color-accent: oklch(0 0 0);
+    --color-accent-hover: oklch(0 0 0);
+    --color-accent-subtle: oklch(1 0 0);
+    --color-code-bg: oklch(0.96 0 0);
+    --color-code-fg: oklch(0 0 0);
+    --color-selection-bg: oklch(1 0 0);
+    --color-selection-fg: oklch(0 0 0);
+    --weight-display: 400;
+  }
+
+  html,
+  body {
+    background: oklch(1 0 0) !important;
+    color: oklch(0 0 0) !important;
+  }
+
+  * {
+    box-shadow: none !important;
+    text-shadow: none !important;
+  }
+
+  /* ─── Hide screen-only chrome ──────────────────────────────
+   * Navigation, footer, table of contents, theme toggle, skip link. */
+  nav,
+  footer,
+  .toc,
+  [class*="toc-"],
+  #theme-toggle,
+  [data-theme-toggle],
+  .theme-toggle,
+  a[href="#main-content"],
+  a[href^="#main"],
+  .skip-link,
+  .copy-btn {
+    display: 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. */
+  .content-reading,
+  .content-standard,
+  .content-wide,
+  main {
+    max-width: 100% !important;
+    margin-inline: 0 !important;
+  }
+
+  body {
+    font-size: 11pt;
+    line-height: 1.5;
+  }
+
+  /* ─── External links keep their URL on paper ─────────────── */
+  a[href^="http"]::after {
+    content: " (" attr(href) ")";
+    font-family: var(--font-mono);
+    font-size: 0.75em;
+    color: oklch(0 0 0);
+    word-break: break-all;
+  }
+
+  /* ─── Orphans, widows, and page-break discipline ──────────── */
+  p,
+  li,
+  dd,
+  blockquote {
+    orphans: 2;
+    widows: 2;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    break-after: avoid;
+    orphans: 3;
+    widows: 3;
+  }
+
+  figure,
+  table,
+  pre,
+  .remarque-prose pre,
+  .remarque-prose table,
+  .remarque-prose details {
+    break-inside: avoid;
+  }
+}

package/prose.css

@@ -20,6 +20,14 @@
   line-height: var(--leading-body);
   color: var(--color-fg);
   max-width: var(--content-reading);
+  /* Oldstyle proportional numerals — text figures that sit quietly
+     inside a sentence, the way numerals behave in well-set book prose.
+     Never mixed with .text-meta's tabular lining register (issue #51). */
+  font-variant-numeric: oldstyle-nums proportional-nums;
+  /* Optical defaults: avoid single-word orphan lines, let quotes and
+     punctuation hang outside the measure. Both degrade safely. */
+  text-wrap: pretty;
+  hanging-punctuation: first last;
 }
 
 .remarque-prose > * + * {
@@ -137,6 +145,300 @@
   margin-top: var(--space-2);
 }
 
+/* ─── Headings, continued (h4–h6) ───────────────────────── */
+/*
+ * h2/h3 are defined above. h4–h6 complete the vocabulary with a
+ * deliberate descent through the three font slots — h4 stays in the
+ * body voice (still prose), h5 borrows the display face's italic for a
+ * quieter sub-heading, h6 drops into the mono "technical label" voice
+ * used everywhere else for the deepest level of metadata. No
+ * text-transform: uppercase — see .text-label (tokens-core.css) for
+ * the true small-caps alternative.
+ */
+
+.remarque-prose h4 {
+  font-family: var(--font-body);
+  font-size: var(--text-body);
+  font-weight: var(--weight-semibold);
+  line-height: var(--leading-title);
+  margin-top: var(--space-5);
+  margin-bottom: var(--space-2);
+  color: var(--color-fg);
+}
+
+.remarque-prose h5 {
+  font-family: var(--font-display);
+  font-style: italic;
+  font-size: var(--text-body);
+  font-weight: var(--weight-medium);
+  line-height: var(--leading-title);
+  margin-top: var(--space-4);
+  margin-bottom: var(--space-2);
+  color: var(--color-fg);
+}
+
+.remarque-prose h6 {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  letter-spacing: var(--tracking-meta);
+  font-weight: var(--weight-semibold);
+  line-height: var(--leading-meta);
+  margin-top: var(--space-4);
+  margin-bottom: var(--space-2);
+  color: var(--color-muted);
+}
+
+/* Optical/wrapping defaults for prose headings (issue #51) — see the
+   matching rule on .text-display/.text-title/.text-section in
+   tokens-core.css. */
+.remarque-prose h2,
+.remarque-prose h3,
+.remarque-prose h4,
+.remarque-prose h5,
+.remarque-prose h6 {
+  text-wrap: balance;
+  font-optical-sizing: auto;
+  font-synthesis: none;
+}
+
+/* ─── Tables ─────────────────────────────────────────────── */
+/*
+ * Reading-width tables: mono th voice (metadata surface, matching
+ * figcaption/code/pre), a 2px rule under the header row, 1px row rules
+ * only (no vertical rules, no zebra striping — quiet by rule). Numeric
+ * columns opt in to tabular lining figures with the `.num` class on the
+ * relevant <th>/<td> (keeps digits from jittering as they change,
+ * matches the .text-meta numerals policy).
+ *
+ * Wide tables should not force the reading column wider than
+ * --content-reading — wrap them:
+ *   <div class="scroll-wrap"><table>...</table></div>
+ */
+
+.remarque-prose .scroll-wrap {
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  margin-top: var(--space-5);
+}
+
+.remarque-prose .scroll-wrap > table {
+  margin-top: 0;
+}
+
+.remarque-prose table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: var(--text-body);
+}
+
+.remarque-prose caption {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  letter-spacing: var(--tracking-meta);
+  color: var(--color-muted);
+  text-align: left;
+  caption-side: top;
+  margin-bottom: var(--space-2);
+}
+
+.remarque-prose th {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  letter-spacing: var(--tracking-meta);
+  font-weight: var(--weight-semibold);
+  text-align: left;
+  padding: var(--space-2) var(--space-3);
+  border-bottom: 2px solid var(--color-border-bold);
+  color: var(--color-fg);
+}
+
+.remarque-prose td {
+  padding: var(--space-2) var(--space-3);
+  border-bottom: var(--border-width) var(--border-style) var(--color-border);
+  color: var(--color-fg);
+}
+
+.remarque-prose th.num,
+.remarque-prose td.num {
+  font-variant-numeric: tabular-nums lining-nums;
+  text-align: right;
+}
+
+/* ─── Definition Lists ───────────────────────────────────── */
+/*
+ * The "specimen list" pattern: a serif-italic term (dt) over a muted
+ * body-face description (dd), row rules like a table. Nest a
+ * `.text-label`/`.text-meta` span inside dt for a metadata line under
+ * the term — the utility already renders it in the mono voice, no
+ * extra CSS needed.
+ */
+
+.remarque-prose dl {
+  border-top: var(--border-width) var(--border-style) var(--color-border);
+}
+
+.remarque-prose dt {
+  font-family: var(--font-display);
+  font-style: italic;
+  font-size: var(--text-body-lg);
+  line-height: var(--leading-title);
+  color: var(--color-fg);
+  margin-top: var(--space-4);
+}
+
+.remarque-prose dt:first-child {
+  margin-top: var(--space-4);
+}
+
+.remarque-prose dd {
+  margin-left: 0;
+  margin-top: var(--space-1);
+  padding-bottom: var(--space-4);
+  color: var(--color-fg-muted);
+  border-bottom: var(--border-width) var(--border-style) var(--color-border);
+}
+
+/* ─── kbd, mark, abbr, sup/sub ───────────────────────────── */
+
+.remarque-prose kbd {
+  font-family: var(--font-mono);
+  font-size: 0.85em;
+  padding: 0.1em 0.4em;
+  border: var(--border-width) var(--border-style) var(--color-border);
+  border-radius: var(--radius-sm);
+  background-color: var(--color-surface);
+  color: var(--color-fg);
+}
+
+/* --color-accent-subtle's first sanctioned use (issue #50) — a quiet
+   highlight, not a callout background. */
+.remarque-prose mark {
+  background-color: var(--color-accent-subtle);
+  color: var(--color-fg);
+  padding: 0.05em 0.2em;
+  border-radius: var(--radius-sm);
+}
+
+.remarque-prose abbr[title] {
+  text-decoration: underline dotted;
+  text-underline-offset: 0.2em;
+  cursor: help;
+}
+
+.remarque-prose sup,
+.remarque-prose sub {
+  font-size: 0.75em;
+  line-height: 0;
+  position: relative;
+  vertical-align: baseline;
+}
+
+.remarque-prose sup {
+  top: -0.5em;
+}
+
+.remarque-prose sub {
+  bottom: -0.25em;
+}
+
+/* ─── Details / Summary ──────────────────────────────────── */
+/*
+ * Collapsible asides. Quiet marker: a small triangle in the mono
+ * metadata voice, no default browser disclosure widget.
+ */
+
+.remarque-prose details {
+  border-top: var(--border-width) var(--border-style) var(--color-border);
+  padding-top: var(--space-3);
+  padding-bottom: var(--space-1);
+}
+
+.remarque-prose summary {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  letter-spacing: var(--tracking-meta);
+  color: var(--color-muted);
+  cursor: pointer;
+  list-style: none;
+}
+
+.remarque-prose summary::-webkit-details-marker {
+  display: none;
+}
+
+.remarque-prose summary::before {
+  content: "\25B8";
+  display: inline-block;
+  margin-right: var(--space-2);
+  color: var(--color-muted);
+  transition: transform var(--motion-fast) var(--motion-easing);
+}
+
+.remarque-prose details[open] summary::before {
+  transform: rotate(90deg);
+}
+
+.remarque-prose details > :not(summary) {
+  margin-top: var(--space-3);
+}
+
+
+/* ─── Drop Cap (opt-in) ──────────────────────────────────── */
+/*
+ * Essay first paragraph only. Add alongside .remarque-prose:
+ *   <div class="remarque-prose remarque-prose--dropcap">
+ * `initial-letter` is used where supported, with a float + font-size
+ * fallback for browsers that lack it. Inherits --color-fg — the drop
+ * cap is not a place for accent color. Automatically skipped when the
+ * paragraph opens with a quote or inline code, since the ornament
+ * assumes a plain capital letter.
+ */
+
+.remarque-prose--dropcap > p:first-of-type:not(:has(> q:first-child)):not(:has(> code:first-child))::first-letter {
+  font-family: var(--font-display);
+  font-style: italic;
+  font-size: 3.5em;
+  line-height: 0.85;
+  float: left;
+  padding: 0.08em 0.12em 0 0;
+  color: var(--color-fg);
+}
+
+@supports (initial-letter: 4) or (-webkit-initial-letter: 4) {
+  .remarque-prose--dropcap > p:first-of-type:not(:has(> q:first-child)):not(:has(> code:first-child))::first-letter {
+    initial-letter: 3.5;
+    -webkit-initial-letter: 3.5;
+    float: none;
+    padding: 0 0.08em 0 0;
+  }
+}
+
+/* ─── Pull Quote ─────────────────────────────────────────── */
+/*
+ * Not .remarque-prose blockquote — a blockquote cites someone else; a
+ * pullquote re-states the article's own words as a visual accent (a
+ * magazine convention). Display italic at section size, hairline rules
+ * above/below, no background, no accent color. If the pulled text
+ * duplicates body copy verbatim, mark the element aria-hidden so
+ * screen readers don't hear it twice:
+ *   <aside class="pullquote" aria-hidden="true">...</aside>
+ * At most one per screen.
+ */
+
+.pullquote {
+  font-family: var(--font-display);
+  font-style: italic;
+  font-size: var(--text-section);
+  line-height: var(--leading-section);
+  color: var(--color-fg);
+  text-align: center;
+  max-width: var(--content-reading);
+  margin: var(--space-7) auto;
+  padding: var(--space-4) 0;
+  border-top: var(--border-width) var(--border-style) var(--color-border);
+  border-bottom: var(--border-width) var(--border-style) var(--color-border);
+}
+
 
 /* ─── The Remarque Mark ─────────────────────────────────── */
 /*

package/scripts/audit.mjs

@@ -157,7 +157,7 @@ const FONT_FLOOR_REM = 0.8125, FONT_FLOOR_PX = 13;
 const paletteRel = relative('.', PALETTE);
 const isTokenFile = (p) =>
   p === paletteRel ||
-  /tokens(-core|-palette)?\.css$|fonts\.css$|globals?\.css$|theme-deck\.css$|pages[\/\\]tokens\.astro$/.test(p);
+  /tokens(-core|-palette)?\.css$|fonts\.css$|globals?\.css$|theme-deck\.css$|print\.css$|pages[\/\\]tokens\.astro$/.test(p);
 
 for (const file of walk(SRC)) {
   const rel = relative('.', file);

package/scripts/drift-check.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/*
+ * remarque-drift — token drift check for consumers of remarque-tokens.
+ *
+ *   node scripts/drift-check.mjs --css-file <path> --package-dir <dir>
+ *   npx remarque-drift --css-file src/styles/global.css --package-dir .
+ *
+ * Compares a consumer's stylesheet against the INSTALLED remarque-tokens
+ * package (node_modules/remarque-tokens under --package-dir), using the
+ * package's own generated tokens.json as the source of truth. Reuses
+ * scripts/lib/css-tokens.mjs (same brace-aware parser as audit.mjs /
+ * tokens-json.mjs) rather than a third CSS parser.
+ *
+ * Classification (see REMARQUE.md "Token Tiers"):
+ *
+ *   (a) CORE-tier token redeclared with a DIFFERENT value:
+ *         - FAIL (exit 1) — undocumented core-tier override. The site has
+ *           forked, by definition.
+ *         - WARN — if a DESIGN-DEVIATIONS.md or DESIGN-NOTES.md in the
+ *           consumer mentions the token name, the fork is a ratified,
+ *           documented deviation; still surfaced, not a build failure.
+ *   (b) PALETTE-tier token redeclared with a different value:
+ *         - INFO — sanctioned personalization. Listed, not warned.
+ *   (c) CORE-tier token used via var(--x) but never declared anywhere in
+ *       the consumer's stylesheet: no-op. It resolves from the package
+ *       import at build time; there is nothing to compare.
+ *
+ * Exit code: 1 iff there is at least one undocumented (FAIL) core-tier
+ * mismatch. WARN and INFO never fail the build.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { extractBlocks, declsOf, isLightRoot, isDarkBlock } from './lib/css-tokens.mjs';
+
+const args = process.argv.slice(2);
+function argOf(flag, dflt) {
+  const i = args.indexOf(flag);
+  return i !== -1 && args[i + 1] ? args[i + 1] : dflt;
+}
+
+const CSS_FILE = argOf('--css-file', null);
+const PACKAGE_DIR = resolve(argOf('--package-dir', '.'));
+
+if (!CSS_FILE) {
+  console.error('usage: drift-check.mjs --css-file <path> --package-dir <dir>');
+  process.exit(2);
+}
+if (!existsSync(CSS_FILE)) {
+  console.error(`consumer stylesheet not found: ${CSS_FILE}`);
+  process.exit(2);
+}
+
+const PKG_ROOT = join(PACKAGE_DIR, 'node_modules', 'remarque-tokens');
+const PKG_JSON = join(PKG_ROOT, 'package.json');
+const TOKENS_JSON = join(PKG_ROOT, 'tokens.json');
+
+if (!existsSync(PKG_JSON) || !existsSync(TOKENS_JSON)) {
+  console.error(
+    `remarque-tokens not found under ${PACKAGE_DIR}/node_modules — ` +
+      `pass --package-dir pointing at the directory containing node_modules/remarque-tokens`
+  );
+  process.exit(2);
+}
+
+const installedVersion = JSON.parse(readFileSync(PKG_JSON, 'utf8')).version;
+const tokens = JSON.parse(readFileSync(TOKENS_JSON, 'utf8'));
+
+/* ── Deviation-doc lookup ──────────────────────────────────────────
+ * Accepts either filename (flagship uses DESIGN-DEVIATIONS.md; tsundoku
+ * uses DESIGN-NOTES.md — both are "this site's documented departures"
+ * docs, just named differently by each consumer). Searched in
+ * --package-dir, the consumer's cwd, and every directory between the
+ * stylesheet and the filesystem/git root, so it's found regardless of
+ * which directory happens to hold node_modules vs the doc. */
+const DEVIATION_DOC_NAMES = ['DESIGN-DEVIATIONS.md', 'DESIGN-NOTES.md'];
+
+function candidateDirs(cssFile, packageDir) {
+  const dirs = [packageDir, resolve('.')];
+  let dir = resolve(dirname(cssFile));
+  for (let i = 0; i < 8; i++) {
+    dirs.push(dir);
+    if (existsSync(join(dir, '.git'))) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return [...new Set(dirs)];
+}
+
+function findDeviationDoc(cssFile, packageDir) {
+  for (const dir of candidateDirs(cssFile, packageDir)) {
+    for (const name of DEVIATION_DOC_NAMES) {
+      const p = join(dir, name);
+      if (existsSync(p)) return p;
+    }
+  }
+  return null;
+}
+
+const deviationDocPath = findDeviationDoc(CSS_FILE, PACKAGE_DIR);
+const deviationDocText = deviationDocPath ? readFileSync(deviationDocPath, 'utf8') : '';
+
+function isDocumented(tokenName) {
+  if (!deviationDocPath) return false;
+  return deviationDocText.includes(`--${tokenName}`) || deviationDocText.includes(tokenName);
+}
+
+/* ── Parse the consumer stylesheet ─────────────────────────────────── */
+
+const blocks = extractBlocks(readFileSync(CSS_FILE, 'utf8'));
+const lightDecls = declsOf(blocks, isLightRoot);
+const darkOverrides = declsOf(blocks, isDarkBlock);
+
+const norm = (v) => String(v).trim().replace(/\s+/g, ' ');
+
+/* ── Classify ───────────────────────────────────────────────────────── */
+
+const fails = [];
+const warns = [];
+const infos = [];
+
+for (const [name, tok] of Object.entries(tokens.core || {})) {
+  const canonical = norm(tok.$value);
+  const declaredLight = Object.prototype.hasOwnProperty.call(lightDecls, name) ? lightDecls[name] : undefined;
+  const declaredDark = Object.prototype.hasOwnProperty.call(darkOverrides, name) ? darkOverrides[name] : undefined;
+  if (declaredLight === undefined && declaredDark === undefined) continue; // (c) no-op — resolves from the package import
+
+  const mismatches = [];
+  if (declaredLight !== undefined && norm(declaredLight) !== canonical) mismatches.push({ theme: 'light', value: declaredLight });
+  if (declaredDark !== undefined && norm(declaredDark) !== canonical) mismatches.push({ theme: 'dark', value: declaredDark });
+  if (mismatches.length === 0) continue; // declared but byte-identical to core — harmless duplicate, not a fork
+
+  const diffText = mismatches.map((m) => `${m.theme}: consumer defines "${m.value}"`).join('; ');
+  const entry = { name, canonical: tok.$value, mismatches };
+  if (isDocumented(name)) {
+    entry.doc = deviationDocPath;
+    warns.push(entry);
+  } else {
+    fails.push(entry);
+  }
+  void diffText;
+}
+
+for (const [name, tok] of Object.entries(tokens.palette || {})) {
+  const canonicalLight = norm(tok.light?.$value);
+  const canonicalDark = norm(tok.dark?.$value ?? tok.light?.$value);
+  const declaredLight = Object.prototype.hasOwnProperty.call(lightDecls, name) ? lightDecls[name] : undefined;
+  const declaredDarkRaw = Object.prototype.hasOwnProperty.call(darkOverrides, name) ? darkOverrides[name] : undefined;
+  if (declaredLight === undefined && declaredDarkRaw === undefined) continue; // not touched by the consumer at all
+
+  // CSS cascade: an undeclared dark value inherits the consumer's own light value.
+  const effectiveDark = declaredDarkRaw !== undefined ? declaredDarkRaw : declaredLight;
+
+  const diffs = [];
+  if (declaredLight !== undefined && norm(declaredLight) !== canonicalLight) diffs.push({ theme: 'light', value: declaredLight });
+  if (effectiveDark !== undefined && norm(effectiveDark) !== canonicalDark) diffs.push({ theme: 'dark', value: effectiveDark });
+  if (diffs.length === 0) continue; // declared, but matches the package default — no divergence to report
+
+  infos.push({ name, canonicalLight: tok.light?.$value, canonicalDark: tok.dark?.$value ?? tok.light?.$value, diffs });
+}
+
+/* ── Report ─────────────────────────────────────────────────────────── */
+
+console.log('remarque-drift — token drift check');
+console.log(`  consumer stylesheet: ${CSS_FILE}`);
+console.log(`  installed remarque-tokens: ${installedVersion} (${PKG_ROOT})`);
+console.log(`  deviation doc: ${deviationDocPath || '(none found — DESIGN-DEVIATIONS.md / DESIGN-NOTES.md)'}`);
+
+if (fails.length) {
+  console.log('\nFAIL — undocumented core-tier override(s) (this consumer has forked Remarque):');
+  for (const f of fails) {
+    for (const m of f.mismatches) {
+      console.log(`  ✗ --${f.name} (${m.theme}): core ships "${f.canonical}", consumer defines "${m.value}"`);
+    }
+    console.log(`      fix: revert to the core value, or document the deviation in DESIGN-DEVIATIONS.md / DESIGN-NOTES.md and mention "--${f.name}"`);
+  }
+}
+
+if (warns.length) {
+  console.log('\nWARN — documented core-tier deviation(s) (ratified, not a build failure):');
+  for (const w of warns) {
+    for (const m of w.mismatches) {
+      console.log(`  ⚠ --${w.name} (${m.theme}): core ships "${w.canonical}", consumer defines "${m.value}" — see ${w.doc}`);
+    }
+  }
+}
+
+if (infos.length) {
+  console.log('\nINFO — palette-tier divergence(s) (sanctioned personalization):');
+  for (const i of infos) {
+    for (const d of i.diffs) {
+      const canonical = d.theme === 'light' ? i.canonicalLight : i.canonicalDark;
+      console.log(`  ℹ --${i.name} (${d.theme}): package default "${canonical}", consumer defines "${d.value}"`);
+    }
+  }
+}
+
+console.log(`\nSummary: ${fails.length} FAIL, ${warns.length} WARN, ${infos.length} INFO\n`);
+
+process.exit(fails.length ? 1 : 0);

package/tokens-core.css

@@ -38,7 +38,7 @@
   --tracking-title: -0.015em;
   --tracking-body: 0em;
   --tracking-meta: 0.02em;      /* mono metadata gets slight tracking */
-  --tracking-caps: 0.06em;      /* for any rare uppercase labels */
+  --tracking-caps: 0.06em;      /* letter-spacing for .text-label (true small caps, issue #51) */
 
   /* Font weights */
   --weight-regular: 400;
@@ -149,6 +149,19 @@ html {
   font-weight: var(--weight-medium);
 }
 
+/* Optical/wrapping defaults for display-scale headings (issue #51):
+   balanced line breaks, optical sizing on variable display faces, and
+   no synthesized bold/italic for faces that lack a real one. All three
+   degrade safely — unsupported browsers silently fall back to normal
+   wrapping and the font's default rendering. */
+.text-display,
+.text-title,
+.text-section {
+  text-wrap: balance;
+  font-optical-sizing: auto;
+  font-synthesis: none;
+}
+
 .text-body {
   font-family: var(--font-body);
   font-size: var(--text-body);
@@ -172,6 +185,25 @@ html {
   letter-spacing: var(--tracking-meta);
   font-weight: var(--weight-regular);
   color: var(--color-muted);
+  /* Tabular lining numerals — dates/counts/timestamps align in a
+     column and don't jitter as digits change. Mirrored by
+     .remarque-prose's oldstyle proportional register below; the two
+     never mix (issue #51). */
+  font-variant-numeric: tabular-nums lining-nums;
+}
+
+/* True small caps for labels (issue #51) — font-variant-caps renders at
+   x-height with corrected weight/spacing; text-transform: uppercase
+   renders letters at cap-height with no optical correction and reads
+   louder than intended. Prefer .text-label over uppercase text
+   anywhere a label needs a caps-like treatment. */
+.text-label {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  line-height: var(--leading-meta);
+  font-variant-caps: all-small-caps;
+  letter-spacing: var(--tracking-caps);
+  color: var(--color-muted);
 }
 
 /* ─── Content Width Utilities ───────────────────────────── */

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.6.1",
+      "version": "0.8.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"