remarque-tokens 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,74 @@ 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.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/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.6.1",
+  "version": "0.7.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,8 @@
     "./tokens.json": "./tokens.json",
     "./prose": "./prose.css",
     "./prose.css": "./prose.css",
+    "./print": "./print.css",
+    "./print.css": "./print.css",
     "./package.json": "./package.json"
   },
   "files": [
@@ -52,6 +56,7 @@
     "fonts.css",
     "fonts/",
     "scripts/audit.mjs",
+    "scripts/drift-check.mjs",
     "tailwind.config.js",
     "REMARQUE.md",
     "AGENT_RULES.md",
@@ -61,6 +66,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.7.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"