remarque-tokens 0.10.0 → 0.12.0

package/AGENT_RULES.md

@@ -42,6 +42,7 @@ These are not guidelines. Agents must follow them literally.
 - Site personalization happens ONLY by overriding `tokens-palette.css` tokens (font slots from the approved pairings, colors, accent, `--content-reading` per the measure table) in a stylesheet loaded after the tokens
 - After ANY palette change, run the audit and fix every failure before shipping — `npm run audit` inside this repo; `npx remarque-audit --palette <file> --src <dir>` in a consumer project (the npm script only exists here)
 - A generated palette override (from `npx remarque-theme <light> --dark <dark>`, see REMARQUE.md "Color Providers") is regenerated, never hand-edited — if it needs to change, change the source theme slugs and re-run `remarque-theme`, don't patch the emitted CSS directly
+- The DEFAULT palette in `tokens-palette.css` is bound to the upstream `remarque-light`/`remarque-dark` themes (REMARQUE.md "Color Providers" identity/serialization contract) — `node scripts/palette-golden.mjs` must stay green. Changing a default color means changing the upstream themes first (or in lockstep with the hand file), never editing `tokens-palette.css` alone to chase a design change; a value edited only on this side is drift, not personalization, and the golden gate exists to catch it
 
 ### Typography
 

package/CHANGELOG.md

@@ -4,6 +4,105 @@ 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.12.0 — 2026-07-23
+
+TypeScript types and a README "Used By" section (closes #34, closes #35).
+
+### Added
+- **`tokens.d.ts`** — generated from `tokens.json` by `scripts/tokens-json.mjs`
+  (regenerates in the same run as `tokens.json`; `--check` verifies both are
+  fresh, wired into the same `deploy.yml` CI step). Ships literal-union types
+  for every token name (`RemarqueCoreToken`, `RemarquePaletteToken`,
+  `RemarqueToken`), a `RemarqueCssVar` template-literal type
+  (`` `--${RemarqueToken}` ``), structural interfaces matching tokens.json's
+  actual shape (`RemarqueTokensFile`, `RemarqueCoreTokenEntry`,
+  `RemarquePaletteTokenEntry`), a `RemarqueTokenValues` interface with the
+  live value of every token as a literal type, and an ambient
+  `declare module 'remarque-tokens/tokens.json'` so
+  `import tokens from 'remarque-tokens/tokens.json'` is precisely typed
+  without depending on the consumer's `resolveJsonModule`. This package has
+  no JS entry point — the types exist for editors/TS consumers who author
+  Remarque token names or read `tokens.json` programmatically.
+  `package.json` wires `types`, an `./tokens.d.ts` export, and a `types`
+  condition on the existing `./tokens.json` export; `scripts/test-types.mjs`
+  gates token-name coverage, the exported type surface, and the
+  `package.json` wiring (string assertions, no `typescript` dependency
+  added).
+- **README "Used By" section** — the demo site, `williamzujkowski.github.io`
+  (core-tier npm consumer), `tsundoku` (full-palette npm consumer, custom
+  accent hue), and `remarque-starter` (template repo), one line each on how
+  they consume the package.
+
+## 0.11.0 — 2026-07-23
+
+Palette golden gate: the default palette is now bound, by CI, to the
+upstream `remarque-light`/`remarque-dark` themes (Phase 3 of the
+color-provider integration, closes #76; consensus-ratified 3-0,
+2026-07-23).
+
+### Changed
+- **`remarque-theme`: lightness is now KEEP-IF-PASSING, not always
+  solved.** For `fg`, `accent`, `accent-hover`, and (in dark)
+  `selection-fg`/`code-fg`, the bridge now keeps the theme's own
+  authored lightness when it already clears the slot's contrast target,
+  and only solves (binary search) when it doesn't. Previously every one
+  of these slots was solved unconditionally — e.g. `fg` always landed
+  exactly on the 10:1 threshold, flattening a well-designed theme's own
+  ~13:1+ contrast down to the floor. The `fg` target itself also drops
+  from 10:1 to 7:1 (the actual AAA line this slot exists to clear) when
+  a solve is needed at all. **This changes derived output for every
+  existing theme pairing** — most of the 61-pair corpus shifts at least
+  one slot (see the PR for the full before/after) — hence the minor
+  bump rather than a patch. Every pair still passes `remarque-audit`;
+  the corpus property test (`test-theme.mjs`) stays green.
+- **`fg-muted` and `border-bold` gain contrast headroom over their solved
+  minimums** (−0.01 L and −0.02 L further from the background,
+  respectively; mirrored in dark). Slots that exist to clear a legal line
+  shouldn't sit exactly on it: borders at 3.0:1 are fragile against
+  antialiasing, AAA text at 7.0:1 has no margin for rendering variance.
+  This encodes the same headroom the hand-authored default has always
+  carried (border-bold at 3.39:1, fg-muted at 7.55:1) into the
+  derivation itself — it's what reconciled the golden gate's last two
+  outliers without loosening the ΔE threshold.
+- All other slots (`muted`, the bg ladder, `selection-bg`,
+  `accent-subtle`) are unaffected — solved/derived unconditionally, same
+  as before.
+- **Accent selection now prefers the dataset's `accent` field** (dataset
+  0.3.0+, upstream #133) — the same cursor-else-most-chromatic-ANSI
+  heuristic, computed upstream where it can be curated per theme. The
+  local heuristic remains as fallback for older datasets. Dev pin bumped
+  `0.2.0` → `0.3.0`, whose native themes are OKLCH-authored (upstream
+  #132): the Remarque themes now carry the design palette's exact
+  values, which is what lets the golden gate below hold at ΔE ≤ 2.0
+  with most tokens exactly 0.
+
+### Added
+- **`scripts/palette-golden.mjs`** (new CI gate, wired into
+  `deploy.yml` right after the `remarque-theme` corpus test): derives
+  the reference palette from the pinned `remarque-light`/`remarque-dark`
+  themes and compares every `--color-*` token in both themes against
+  the hand-authored `tokens-palette.css`, resolving `var()` chains,
+  via CIEDE2000 (`culori`'s `differenceCiede2000` — not hand-rolled ΔE
+  math). Asserts ΔE2000 ≤ 2.0 per token and an exact `weight-display`
+  match; the full per-token table prints unconditionally (not just on
+  failure) so drift stays visible before it reaches the threshold. A
+  breach means the upstream themes and the hand file have diverged —
+  reconcile one against the other, the gate does not loosen.
+- **Site mirror check**, same script: asserts every `--color-*` value in
+  `site/src/styles/globals.css`'s `[data-theme="light"]` block is
+  string-identical (whitespace-normalized) to `tokens-palette.css`'s
+  `:root` light value — the known drift trap called out in #76.
+- `culori` added as a devDependency (already present transitively via
+  `@williamzujkowski/oklch-terminal-themes`; now pinned directly since
+  `palette-golden.mjs` imports it).
+- REMARQUE.md "Color Providers": documents the identity/serialization
+  contract — the upstream themes are the source of truth for the
+  default palette's identity, `tokens-palette.css` is its human-authored
+  serialization, and the golden gate is what keeps them from drifting
+  apart. AGENT_RULES.md: palette color changes must keep the golden
+  gate green; changing a default color means changing the upstream
+  themes first (or in lockstep), not hand-editing the CSS alone.
+
 ## 0.10.0 — 2026-07-23
 
 Color-provider Phase 2 groundwork: the upstream dataset now pairs its own

package/README.md

@@ -19,6 +19,13 @@ Most developer sites inherit the visual language of SaaS dashboards or component
 - **Self-hosted fonts** — no Google CDN dependency. Strict CSP. GDPR-compliant.
 - **AI-native** — designed to be consumed by Claude Code, Cursor, Copilot, and other AI coding tools with zero aesthetic drift.
 
+## Used By
+
+- **[Remarque demo site](https://williamzujkowski.github.io/remarque/)** — the `site/` directory in this repo; reference implementation of all four demoed archetypes, deployed to GitHub Pages.
+- **[williamzujkowski.github.io](https://github.com/williamzujkowski/williamzujkowski.github.io)** — flagship personal site; core-tier npm consumer (`remarque-tokens/core` from npm, hand-authored palette layer on top).
+- **[tsundoku](https://github.com/williamzujkowski/tsundoku)** — bookshelf/reading-log site; full-palette npm consumer, custom terracotta "book cloth" accent hue over the default palette for its card-catalog identity.
+- **[remarque-starter](https://github.com/williamzujkowski/remarque-starter)** — template repo; Astro scaffold pulling `remarque-tokens` from npm with the audit wired into CI, meant to be forked.
+
 ## Install
 
 ```bash

package/REMARQUE.md

@@ -80,12 +80,14 @@ The palette tier (all `--color-*` tokens) can be *supplied* rather than hand-aut
 npx remarque-theme <light-slug> [--dark <dark-slug>] [-o palette-override.css]
 ```
 
-Terminal themes carry only `background/foreground/cursor/selection` + 16 ANSI slots — a few of Remarque's 15 semantic slots map directly, and most themes fail the AAA `fg-muted` 7:1 line as authored. So `remarque-theme` *derives* rather than maps: **hue and chroma carry the theme's personality; lightness is solved per slot** (binary search against the same contrast targets as the Enforcement Checklist below, with in-gamut chroma clamping) so the output passes `remarque-audit` by construction. The accent hue comes from the theme's cursor color if it's chromatic, otherwise the most saturated classic ANSI color, and is kept consistent between the light and dark half of a pair.
+Terminal themes carry only `background/foreground/cursor/selection` + 16 ANSI slots — a few of Remarque's 15 semantic slots map directly, and most themes fail the AAA `fg-muted` 7:1 line as authored. So `remarque-theme` *derives* rather than maps: **hue and chroma carry the theme's personality; lightness is KEEP-IF-PASSING**. For the slots that have a meaningful "theme's own value" — `fg`, `accent`, `accent-hover`, and (in dark) `selection-fg`/`code-fg` — the theme's own authored lightness is kept as-is when it already clears the slot's contrast target; lightness is solved (binary search, same targets as the Enforcement Checklist below, with in-gamut chroma clamping) *only* when it doesn't. Every other slot (`fg-muted`, `muted`, `border-bold`, the bg ladder, `selection-bg`, `accent-subtle`) is solved/derived unconditionally, as it always was — those don't carry an independent authored value to preserve. This means a well-designed input theme comes through close to its own feel instead of being flattened to the exact threshold; a theme that fails a target still gets a value that passes, exactly as before. The accent hue comes from the theme's cursor color if it's chromatic, otherwise the most saturated classic ANSI color, and is kept consistent between the light and dark half of a pair.
 
 The audit remains the gate regardless of provenance — `remarque-theme` self-verifies its own output against the same checks before it will emit anything, but a site that hand-edits a generated palette (or points at a provider with pathological input colors) still runs through `remarque-audit` in CI like any other palette.
 
 **Pairing contract:** dataset 0.2.0+ carries a `counterpart` field linking each paired theme to its canonical opposite-polarity variant ([`oklch-terminal-themes#128`](https://github.com/williamzujkowski/oklch-terminal-themes/issues/128)), and `--dark` defaults to it — `npx remarque-theme rose-pine-dawn` alone derives the rosé-pine pair. For a light theme without a counterpart (or an older dataset), `--dark <slug>` remains required; nothing is ever guessed from names. `remarque-theme` also rejects a light slug that isn't tagged `isDark: false` and a dark slug that isn't tagged `isDark: true`.
 
+**Identity/serialization contract (#76):** the default palette shipped in `tokens-palette.css` is not an independent hand-design — its **identity** is bound to the upstream `remarque-light`/`remarque-dark` native themes in `@williamzujkowski/oklch-terminal-themes` (pinned exact devDependency), derived through the same `remarque-theme` bridge as any other consumer's palette. `tokens-palette.css` itself is that identity's **serialization**: a stable, human-authored file with designed round numbers and hand comments, kept perceptually identical to what the bridge derives. `scripts/palette-golden.mjs` is the CI gate that proves this — it derives the reference palette from the pinned themes, compares every `--color-*` token in both files via CIEDE2000 (ΔE2000 ≤ 2.0, reported per token, always printed so drift stays visible before it reaches the threshold), and separately asserts that `site/src/styles/globals.css`'s `[data-theme="light"]` mirror block stays string-identical to `tokens-palette.css`'s `:root` light value (a known drift trap). A breach means the upstream themes and the hand file have diverged — reconcile one against the other; the gate does not loosen.
+
 ---
 
 ## Font Slots

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "engines": {
     "node": ">=18"
   },
@@ -21,6 +21,7 @@
   },
   "homepage": "https://williamzujkowski.github.io/remarque/",
   "main": "tokens.css",
+  "types": "./tokens.d.ts",
   "bin": {
     "remarque-audit": "scripts/audit.mjs",
     "remarque-drift": "scripts/drift-check.mjs",
@@ -31,7 +32,8 @@
     "drift": "node scripts/drift-check.mjs"
   },
   "devDependencies": {
-    "@williamzujkowski/oklch-terminal-themes": "0.2.0"
+    "@williamzujkowski/oklch-terminal-themes": "0.3.0",
+    "culori": "^4.0.2"
   },
   "peerDependencies": {
     "@williamzujkowski/oklch-terminal-themes": ">=0.1.0 <0.3.0"
@@ -42,7 +44,10 @@
     }
   },
   "exports": {
-    ".": "./tokens.css",
+    ".": {
+      "types": "./tokens.d.ts",
+      "default": "./tokens.css"
+    },
     "./tokens": "./tokens.css",
     "./tokens.css": "./tokens.css",
     "./core": "./tokens-core.css",
@@ -54,7 +59,11 @@
     "./tailwind": "./tailwind.config.js",
     "./theme.css": "./theme.css",
     "./theme": "./theme.css",
-    "./tokens.json": "./tokens.json",
+    "./tokens.json": {
+      "types": "./tokens.d.ts",
+      "default": "./tokens.json"
+    },
+    "./tokens.d.ts": "./tokens.d.ts",
     "./prose": "./prose.css",
     "./prose.css": "./prose.css",
     "./print": "./print.css",
@@ -79,6 +88,7 @@
     "CHANGELOG.md",
     "theme.css",
     "tokens.json",
+    "tokens.d.ts",
     "scripts/tokens-json.mjs",
     "prose.css",
     "print.css",

package/scripts/theme.mjs

@@ -10,9 +10,16 @@
  * ANSI slots — most of Remarque's 15 semantic slots don't map directly,
  * and most themes fail the AAA fg-muted 7:1 line as authored. So this
  * DERIVES rather than maps: hue + chroma come from the theme (its
- * personality), lightness is solved per slot to hit the exact ratio
- * targets from REMARQUE.md's Enforcement Checklist (binary search over
- * L, with in-gamut chroma clamping inside the solver). Output passes
+ * personality); lightness is KEEP-IF-PASSING — a few load-bearing slots
+ * (fg, accent, accent-hover, and dark's selection-fg/code-fg) keep the
+ * theme's own authored lightness when it already clears the slot's
+ * ratio target, and are solved by binary search ONLY when it doesn't.
+ * A well-designed input theme comes through close to its own feel
+ * instead of being flattened to the exact threshold; a theme that fails
+ * still gets a value that passes, same as before (#76). Every other
+ * slot (fg-muted, muted, border-bold, the bg ladder, selection-bg,
+ * accent-subtle) is solved/derived as before — those don't have a
+ * meaningful "theme's own value" to preserve. Output passes
  * remarque-audit BY CONSTRUCTION — this script self-verifies the same
  * pairings before it will emit anything.
  *
@@ -254,24 +261,51 @@ function solveL(C, H, bg, target, dir) {
   );
 }
 
-/* Accent hue: cursor if it's chromatic, else the most-chromatic classic ANSI. */
+/* Accent source: cursor if it's chromatic, else the most-chromatic classic
+ * ANSI. Carries l too (not just h/c) — keep-if-passing needs the source's
+ * own lightness as the candidate to test before falling back to solveL. */
 function accentHue(theme, label) {
+  // Dataset 0.3.0+ publishes a curated/computed accent per theme — prefer
+  // it (it's this same heuristic, computed upstream where it can be
+  // curated per-theme). Validated like any other theme color; the local
+  // heuristic below stays as the fallback for older datasets.
+  if (theme.accent && theme.accent.oklch) {
+    const [l, c, h] = validateOklch(theme.accent.oklch, `${label} accent`);
+    return { l, c, h, from: `accent:${String(theme.accent.source)}` };
+  }
   const cursor = theme.colors && theme.colors.cursor && theme.colors.cursor.oklch;
   if (cursor) {
-    const [, c, h] = validateOklch(cursor, `${label} colors.cursor`);
-    if (c >= 0.05) return { h, c, from: 'cursor' };
+    const [l, c, h] = validateOklch(cursor, `${label} colors.cursor`);
+    if (c >= 0.05) return { l, h, c, from: 'cursor' };
   }
   const names = ['blue', 'purple', 'red', 'green', 'cyan', 'yellow'];
   const cands = [];
   for (const name of names) {
     const o = theme.colors && theme.colors[name] && theme.colors[name].oklch;
     if (!o) continue;
-    const [, c, h] = validateOklch(o, `${label} colors.${name}`);
-    cands.push({ name, c, h });
+    const [l, c, h] = validateOklch(o, `${label} colors.${name}`);
+    cands.push({ name, l, c, h });
   }
   if (!cands.length) die(`${label}: no classic ANSI colors available to derive an accent hue`);
   cands.sort((a, b) => b.c - a.c);
-  return { h: cands[0].h, c: cands[0].c, from: cands[0].name };
+  return { l: cands[0].l, h: cands[0].h, c: cands[0].c, from: cands[0].name };
+}
+
+/* Keep-if-passing: if the theme's own (quantized) lightness at this slot
+ * already clears `target` against `bg`, keep it (chroma gamut-clamped,
+ * hue rounded) — no margin, this is the theme's own value, not a solve.
+ * Only when it fails do we fall back to solveL, which keeps its existing
+ * ×1.03 search margin. `dir` only matters for that fallback path. */
+function keepOrSolve(L0, C, H, bg, target, dir) {
+  // Clamp into the valid domain first — an offset candidate (accent-hover,
+  // dark selection-fg/code-fg) can walk L past 0/1 for a theme whose own
+  // slot already sits near an extreme; ratio()'s luminance clip() would
+  // otherwise let an out-of-[0,1] L "pass" here only to fail the raw
+  // gamut check downstream in selfVerify.
+  const L = Math.min(1, Math.max(0, r3(L0)));
+  const c = fitChroma(L, C, H);
+  if (ratio([L, c, H], bg) >= target) return [L, c, r1(H)];
+  return solveL(C, H, bg, target, dir);
 }
 
 function fmt(triple) {
@@ -280,6 +314,17 @@ function fmt(triple) {
   return `oklch(${L} ${C} ${H})`;
 }
 
+/* Push a solved triple further from the background by delta L — headroom
+ * over the legal minimum for slots that shouldn't sit at it (functional
+ * borders at exactly 3:1 are fragile against antialiasing; AAA text at
+ * exactly 7:1 has no margin for rendering variance). Direction is always
+ * away from bg, so the ratio only increases — never re-verified against
+ * the target, only re-clamped for gamut. */
+function withHeadroom([L0, , H], delta, dir, C) {
+  const L = r3(Math.min(1, Math.max(0, dir === 'darker' ? L0 - delta : L0 + delta)));
+  return [L, fitChroma(L, C, H), r1(H)];
+}
+
 /* ── LIGHT derivation ─────────────────────────────────────────────── */
 
 function deriveLight(t) {
@@ -289,16 +334,23 @@ function deriveLight(t) {
   const bgC = fitChroma(bgL, Math.min(bgC0, 0.02), bgH);
   const bg = [bgL, bgC, bgH];
   const surface = [r3(bgL - 0.01), bgC, bgH];
-  const [, fgC0, fgH] = slotLch(t, 'foreground', 'light');
+  const [fgL0, fgC0, fgH] = slotLch(t, 'foreground', 'light');
   const fgC = Math.min(fgC0, 0.03);
-  const fg = solveL(fgC, fgH, surface, 10, 'darker');
-  const fgMuted = solveL(fgC, fgH, bg, 7.0, 'darker');
+  // fg: keep the theme's own foreground lightness if it already clears the
+  // AAA floor (7:1) against surface; solve only if it doesn't (#76 — this
+  // used to always solve to 10:1, flattening well-designed themes).
+  const fg = keepOrSolve(fgL0, fgC, fgH, surface, 7.0, 'darker');
+  const fgMuted = withHeadroom(solveL(fgC, fgH, bg, 7.0, 'darker'), 0.01, 'darker', fgC);
   const muted = solveL(Math.min(fgC0, 0.02), fgH, surface, 4.5, 'darker');
-  const borderBold = solveL(0.01, bgH, bg, 3.0, 'darker');
+  const borderBold = withHeadroom(solveL(0.01, bgH, bg, 3.0, 'darker'), 0.02, 'darker', 0.01);
   const ac = accentHue(t, 'light');
   const acC = Math.min(ac.c, 0.14);
-  const accent = solveL(acC, ac.h, bg, 4.5, 'darker');
-  const accentHover = [r3(accent[0] - 0.08), fitChroma(r3(accent[0] - 0.08), acC * 0.8, ac.h), r1(ac.h)];
+  // accent: keep the accent-source's own lightness (cursor or chosen ANSI
+  // color) if it already clears 4.5:1 on bg; solve only if it doesn't.
+  const accent = keepOrSolve(ac.l, acC, ac.h, bg, 4.5, 'darker');
+  // accent-hover: still the designed -0.08 offset from accent, but that
+  // offset is verified against 4.5:1 on bg and solve-adjusted if it breaks.
+  const accentHover = keepOrSolve(accent[0] - 0.08, acC * 0.8, ac.h, bg, 4.5, 'darker');
   const raw = {
     'color-bg': bg,
     'color-bg-subtle': [r3(bg[0] - 0.02), bg[1], bg[2]],
@@ -330,21 +382,33 @@ function deriveDark(t, accentHueLight) {
   const bgC = fitChroma(bgL, Math.min(bgC0, 0.03), bgH);
   const bg = [bgL, bgC, bgH];
   const surface = [r3(bg[0] + 0.03), bgC, bgH];
-  const [, fgC0, fgH] = slotLch(t, 'foreground', 'dark');
+  const [fgL0, fgC0, fgH] = slotLch(t, 'foreground', 'dark');
   const fgC = Math.min(fgC0, 0.02);
-  const fg = solveL(fgC, fgH, surface, 10, 'lighter');
-  const fgMuted = solveL(fgC, fgH, bg, 7.0, 'lighter');
+  // fg: keep the theme's own foreground lightness if it already clears the
+  // AAA floor (7:1) against surface; solve only if it doesn't (mirrors
+  // light — direction flipped, see #76).
+  const fg = keepOrSolve(fgL0, fgC, fgH, surface, 7.0, 'lighter');
+  const fgMuted = withHeadroom(solveL(fgC, fgH, bg, 7.0, 'lighter'), 0.01, 'lighter', fgC);
   const muted = solveL(fgC, fgH, surface, 4.5, 'lighter');
-  const borderBold = solveL(0.01, bgH, bg, 3.0, 'lighter');
+  const borderBold = withHeadroom(solveL(0.01, bgH, bg, 3.0, 'lighter'), 0.02, 'lighter', 0.01);
   const ac = accentHue(t, 'dark');
   const h = accentHueLight ?? ac.h; // keep hue consistent across the pair
   const acC = Math.min(ac.c, 0.12);
-  const accent = solveL(acC, h, bg, 4.5, 'lighter');
-  const accentHover = [r3(accent[0] + 0.07), fitChroma(r3(accent[0] + 0.07), acC, h), r1(h)];
+  // accent: keep the accent-source's own lightness if it already clears
+  // 4.5:1 on bg; solve only if it doesn't.
+  const accent = keepOrSolve(ac.l, acC, h, bg, 4.5, 'lighter');
+  // accent-hover: still the designed +0.07 offset from accent, verified
+  // against 4.5:1 on bg and solve-adjusted if the offset breaks it.
+  const accentHover = keepOrSolve(accent[0] + 0.07, acC, h, bg, 4.5, 'lighter');
   const selBg = [r3(bg[0] + 0.14), fitChroma(r3(bg[0] + 0.14), 0.06, h), r1(h)];
-  const selFg = solveL(0.005, fgH, selBg, 4.5, 'lighter');
+  // selection-fg: "slightly brighter than fg on selection" — derived from
+  // the (kept-or-solved) dark fg's own L/C/H, +0.02 lightness, verified
+  // against 4.5:1 on selection-bg and solved only if that breaks it.
+  const selFg = keepOrSolve(fg[0] + 0.02, fg[1], fg[2], selBg, 4.5, 'lighter');
   const codeBg = [r3(bg[0] + 0.04), bgC, bgH];
-  const codeFg = solveL(0.005, fgH, codeBg, 7, 'lighter');
+  // code-fg: "slightly dimmer than fg" — same pattern, -0.02, verified
+  // against the AAA 7:1 line on code-bg.
+  const codeFg = keepOrSolve(fg[0] - 0.02, fg[1], fg[2], codeBg, 7.0, 'lighter');
   const raw = {
     'color-bg': bg,
     'color-bg-subtle': surface,

package/scripts/tokens-json.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 /*
- * Generates tokens.json (W3C design-tokens flavored) FROM the CSS —
- * tokens-core.css and tokens-palette.css remain the single source of
- * truth; this file is derived output for tooling and AI agents.
+ * Generates tokens.json (W3C design-tokens flavored) and tokens.d.ts
+ * (TypeScript literal-union types) FROM the CSS — tokens-core.css and
+ * tokens-palette.css remain the single source of truth; both files
+ * here are derived output for tooling, AI agents, and TS editors.
  *
- *   node scripts/tokens-json.mjs           # (re)write tokens.json
- *   node scripts/tokens-json.mjs --check   # exit 1 if tokens.json is stale (CI)
+ *   node scripts/tokens-json.mjs           # (re)write tokens.json + tokens.d.ts
+ *   node scripts/tokens-json.mjs --check   # exit 1 if either is stale (CI)
  *
  * Multi-theme values use per-token light/dark groups with $value on each
  * (the W3C spec has no native theming; this follows its $extensions
@@ -70,14 +71,159 @@ for (const [name, value] of Object.entries(lightDecls)) {
 
 const json = JSON.stringify(out, null, 2) + '\n';
 
+/* ── tokens.d.ts ──────────────────────────────────────────────────────
+ * Literal-union types + a typed shape for tokens.json, generated from
+ * the same in-memory `out` object that produces tokens.json — so the
+ * two derived files can never disagree with each other, only (briefly,
+ * until regenerated) with the CSS. The package ships no JS entry point;
+ * this file exists purely for editors/TS consumers that either author
+ * Remarque token names (`RemarqueToken`, `RemarqueCssVar`) or read
+ * tokens.json programmatically (`RemarqueTokensFile`, wired via the
+ * ambient `declare module 'remarque-tokens/tokens.json'` below).
+ */
+function tsLiteral(value) {
+  return typeof value === 'number' ? String(value) : JSON.stringify(value);
+}
+
+function renderDts(tokens, pkgVersion) {
+  const coreNames = Object.keys(tokens.core);
+  const paletteNames = Object.keys(tokens.palette);
+
+  const coreUnion = coreNames.map((n) => `  | '${n}'`).join('\n');
+  const paletteUnion = paletteNames.map((n) => `  | '${n}'`).join('\n');
+
+  const coreValues = coreNames
+    .map((n) => `    readonly '${n}': ${tsLiteral(tokens.core[n].$value)};`)
+    .join('\n');
+  const paletteValues = paletteNames
+    .map((n) => {
+      const t = tokens.palette[n];
+      return `    readonly '${n}': {\n      readonly light: ${tsLiteral(t.light.$value)};\n      readonly dark: ${tsLiteral(t.dark.$value)};\n    };`;
+    })
+    .join('\n');
+
+  return `/*
+ * Remarque design tokens — GENERATED from tokens.json by
+ * scripts/tokens-json.mjs (v${pkgVersion}). Do not edit — the CSS
+ * (tokens-core.css + tokens-palette.css) is the source of truth;
+ * tokens.json is the intermediate machine-readable form this file is
+ * generated from. Regenerate with: node scripts/tokens-json.mjs
+ *
+ * This package has no JS entry point — these types exist for editors
+ * and TypeScript consumers that either author Remarque token names
+ * (RemarqueToken, RemarqueCssVar) or read tokens.json programmatically
+ * (RemarqueTokensFile / RemarqueTokenValues, and the ambient module
+ * declaration below for \`import tokens from 'remarque-tokens/tokens.json'\`).
+ */
+
+/** All core-tier token names (tokens-core.css). Never overridden. */
+export type RemarqueCoreToken =
+${coreUnion};
+
+/** All palette-tier token names (tokens-palette.css). The sanctioned personalization surface. */
+export type RemarquePaletteToken =
+${paletteUnion};
+
+/** Every Remarque token name, core + palette. */
+export type RemarqueToken = RemarqueCoreToken | RemarquePaletteToken;
+
+/** A Remarque token name as its CSS custom-property form, e.g. \`--text-body\`. */
+export type RemarqueCssVar = \`--${'$'}{RemarqueToken}\`;
+
+/** W3C design-tokens \`$type\` values used across tokens.json. */
+export type RemarqueTokenType =
+  | 'color'
+  | 'dimension'
+  | 'number'
+  | 'fontFamily'
+  | 'fontWeight'
+  | 'duration'
+  | 'string';
+
+/** Shape of a single core-tier entry in tokens.json's \`core\` map. */
+export interface RemarqueCoreTokenEntry {
+  readonly $value: string | number;
+  readonly $type: RemarqueTokenType;
+}
+
+/** Shape of one theme side (\`light\`/\`dark\`) of a palette-tier entry. */
+export interface RemarquePaletteTokenSideValue {
+  readonly $value: string | number;
+  readonly $extensions?: {
+    readonly remarque?: {
+      readonly inheritedFromLight?: boolean;
+    };
+  };
+}
+
+/** Shape of a single palette-tier entry in tokens.json's \`palette\` map. */
+export interface RemarquePaletteTokenEntry {
+  readonly $type: RemarqueTokenType;
+  readonly light: RemarquePaletteTokenSideValue;
+  readonly dark: RemarquePaletteTokenSideValue;
+}
+
+/**
+ * Typed shape of tokens.json's default export — the whole generated
+ * file, structurally. Use this when reading tokens.json dynamically
+ * (\`JSON.parse\`, a bundler JSON import without the ambient module
+ * below applying, etc).
+ */
+export interface RemarqueTokensFile {
+  readonly $description: string;
+  readonly $extensions: {
+    readonly remarque: {
+      readonly version: string;
+      readonly tiers: {
+        readonly core: string;
+        readonly palette: string;
+      };
+    };
+  };
+  readonly core: { readonly [K in RemarqueCoreToken]: RemarqueCoreTokenEntry };
+  readonly palette: { readonly [K in RemarquePaletteToken]: RemarquePaletteTokenEntry };
+}
+
+/**
+ * The actual current value of every token, as literal types — precise
+ * autocomplete for "what is \`--text-body\` right now", not just "what
+ * are its shape and type". Regenerated alongside tokens.json, so these
+ * literals track the live CSS across releases.
+ */
+export interface RemarqueTokenValues {
+  readonly core: {
+${coreValues}
+  };
+  readonly palette: {
+${paletteValues}
+  };
+}
+
+// Precise types for \`import tokens from 'remarque-tokens/tokens.json'\`
+// (and any other bundler-JSON-import path resolving through this
+// subpath) without depending on the consumer's \`resolveJsonModule\`.
+declare module 'remarque-tokens/tokens.json' {
+  const tokens: RemarqueTokensFile;
+  export default tokens;
+}
+`;
+}
+
+const dts = renderDts(out, version);
+
 if (process.argv.includes('--check')) {
-  const current = existsSync('tokens.json') ? readFileSync('tokens.json', 'utf8') : '';
-  if (current !== json) {
-    console.error('tokens.json is stale — run: node scripts/tokens-json.mjs');
+  const currentJson = existsSync('tokens.json') ? readFileSync('tokens.json', 'utf8') : '';
+  const currentDts = existsSync('tokens.d.ts') ? readFileSync('tokens.d.ts', 'utf8') : '';
+  const staleJson = currentJson !== json;
+  const staleDts = currentDts !== dts;
+  if (staleJson || staleDts) {
+    if (staleJson) console.error('tokens.json is stale — run: node scripts/tokens-json.mjs');
+    if (staleDts) console.error('tokens.d.ts is stale — run: node scripts/tokens-json.mjs');
     process.exit(1);
   }
-  console.log('tokens.json is fresh ✓');
+  console.log('tokens.json and tokens.d.ts are fresh ✓');
 } else {
   writeFileSync('tokens.json', json);
-  console.log(`tokens.json written — ${Object.keys(out.core).length} core + ${Object.keys(out.palette).length} palette tokens (v${version})`);
+  writeFileSync('tokens.d.ts', dts);
+  console.log(`tokens.json + tokens.d.ts written — ${Object.keys(out.core).length} core + ${Object.keys(out.palette).length} palette tokens (v${version})`);
 }

package/tokens.d.ts

@@ -0,0 +1,299 @@
+/*
+ * Remarque design tokens — GENERATED from tokens.json by
+ * scripts/tokens-json.mjs (v0.12.0). Do not edit — the CSS
+ * (tokens-core.css + tokens-palette.css) is the source of truth;
+ * tokens.json is the intermediate machine-readable form this file is
+ * generated from. Regenerate with: node scripts/tokens-json.mjs
+ *
+ * This package has no JS entry point — these types exist for editors
+ * and TypeScript consumers that either author Remarque token names
+ * (RemarqueToken, RemarqueCssVar) or read tokens.json programmatically
+ * (RemarqueTokensFile / RemarqueTokenValues, and the ambient module
+ * declaration below for `import tokens from 'remarque-tokens/tokens.json'`).
+ */
+
+/** All core-tier token names (tokens-core.css). Never overridden. */
+export type RemarqueCoreToken =
+  | 'text-display'
+  | 'text-title'
+  | 'text-section'
+  | 'text-body-lg'
+  | 'text-body'
+  | 'text-meta'
+  | 'text-micro'
+  | 'leading-display'
+  | 'leading-title'
+  | 'leading-section'
+  | 'leading-body'
+  | 'leading-meta'
+  | 'tracking-display'
+  | 'tracking-title'
+  | 'tracking-body'
+  | 'tracking-meta'
+  | 'tracking-caps'
+  | 'weight-regular'
+  | 'weight-medium'
+  | 'weight-semibold'
+  | 'space-1'
+  | 'space-2'
+  | 'space-3'
+  | 'space-4'
+  | 'space-5'
+  | 'space-6'
+  | 'space-7'
+  | 'space-8'
+  | 'space-9'
+  | 'space-10'
+  | 'space-11'
+  | 'space-12'
+  | 'content-standard'
+  | 'content-wide'
+  | 'radius-sm'
+  | 'radius-md'
+  | 'radius-none'
+  | 'border-width'
+  | 'border-style'
+  | 'motion-fast'
+  | 'motion-normal'
+  | 'motion-easing';
+
+/** All palette-tier token names (tokens-palette.css). The sanctioned personalization surface. */
+export type RemarquePaletteToken =
+  | 'font-display'
+  | 'font-body'
+  | 'font-mono'
+  | 'content-reading'
+  | 'weight-display'
+  | 'color-bg'
+  | 'color-bg-subtle'
+  | 'color-fg'
+  | 'color-fg-muted'
+  | 'color-muted'
+  | 'color-border'
+  | 'color-border-bold'
+  | 'color-surface'
+  | 'color-accent'
+  | 'color-accent-hover'
+  | 'color-accent-subtle'
+  | 'color-link'
+  | 'color-link-hover'
+  | 'color-focus-ring'
+  | 'color-selection-bg'
+  | 'color-selection-fg'
+  | 'color-code-bg'
+  | 'color-code-fg';
+
+/** Every Remarque token name, core + palette. */
+export type RemarqueToken = RemarqueCoreToken | RemarquePaletteToken;
+
+/** A Remarque token name as its CSS custom-property form, e.g. `--text-body`. */
+export type RemarqueCssVar = `--${RemarqueToken}`;
+
+/** W3C design-tokens `$type` values used across tokens.json. */
+export type RemarqueTokenType =
+  | 'color'
+  | 'dimension'
+  | 'number'
+  | 'fontFamily'
+  | 'fontWeight'
+  | 'duration'
+  | 'string';
+
+/** Shape of a single core-tier entry in tokens.json's `core` map. */
+export interface RemarqueCoreTokenEntry {
+  readonly $value: string | number;
+  readonly $type: RemarqueTokenType;
+}
+
+/** Shape of one theme side (`light`/`dark`) of a palette-tier entry. */
+export interface RemarquePaletteTokenSideValue {
+  readonly $value: string | number;
+  readonly $extensions?: {
+    readonly remarque?: {
+      readonly inheritedFromLight?: boolean;
+    };
+  };
+}
+
+/** Shape of a single palette-tier entry in tokens.json's `palette` map. */
+export interface RemarquePaletteTokenEntry {
+  readonly $type: RemarqueTokenType;
+  readonly light: RemarquePaletteTokenSideValue;
+  readonly dark: RemarquePaletteTokenSideValue;
+}
+
+/**
+ * Typed shape of tokens.json's default export — the whole generated
+ * file, structurally. Use this when reading tokens.json dynamically
+ * (`JSON.parse`, a bundler JSON import without the ambient module
+ * below applying, etc).
+ */
+export interface RemarqueTokensFile {
+  readonly $description: string;
+  readonly $extensions: {
+    readonly remarque: {
+      readonly version: string;
+      readonly tiers: {
+        readonly core: string;
+        readonly palette: string;
+      };
+    };
+  };
+  readonly core: { readonly [K in RemarqueCoreToken]: RemarqueCoreTokenEntry };
+  readonly palette: { readonly [K in RemarquePaletteToken]: RemarquePaletteTokenEntry };
+}
+
+/**
+ * The actual current value of every token, as literal types — precise
+ * autocomplete for "what is `--text-body` right now", not just "what
+ * are its shape and type". Regenerated alongside tokens.json, so these
+ * literals track the live CSS across releases.
+ */
+export interface RemarqueTokenValues {
+  readonly core: {
+    readonly 'text-display': "clamp(2.75rem, 5.5vw, 5rem)";
+    readonly 'text-title': "clamp(1.875rem, 3.5vw, 3rem)";
+    readonly 'text-section': "clamp(1.375rem, 2.25vw, 2rem)";
+    readonly 'text-body-lg': "1.1875rem";
+    readonly 'text-body': "1.0625rem";
+    readonly 'text-meta': "0.875rem";
+    readonly 'text-micro': "0.8125rem";
+    readonly 'leading-display': 1.05;
+    readonly 'leading-title': 1.15;
+    readonly 'leading-section': 1.2;
+    readonly 'leading-body': 1.75;
+    readonly 'leading-meta': 1.5;
+    readonly 'tracking-display': "-0.02em";
+    readonly 'tracking-title': "-0.015em";
+    readonly 'tracking-body': "0em";
+    readonly 'tracking-meta': "0.02em";
+    readonly 'tracking-caps': "0.06em";
+    readonly 'weight-regular': 400;
+    readonly 'weight-medium': 500;
+    readonly 'weight-semibold': 600;
+    readonly 'space-1': "0.25rem";
+    readonly 'space-2': "0.5rem";
+    readonly 'space-3': "0.75rem";
+    readonly 'space-4': "1rem";
+    readonly 'space-5': "1.5rem";
+    readonly 'space-6': "2rem";
+    readonly 'space-7': "3rem";
+    readonly 'space-8': "4rem";
+    readonly 'space-9': "6rem";
+    readonly 'space-10': "8rem";
+    readonly 'space-11': "10rem";
+    readonly 'space-12': "12rem";
+    readonly 'content-standard': "72rem";
+    readonly 'content-wide': "88rem";
+    readonly 'radius-sm': "0.25rem";
+    readonly 'radius-md': "0.5rem";
+    readonly 'radius-none': "0";
+    readonly 'border-width': "1px";
+    readonly 'border-style': "solid";
+    readonly 'motion-fast': "120ms";
+    readonly 'motion-normal': "180ms";
+    readonly 'motion-easing': "ease-out";
+  };
+  readonly palette: {
+    readonly 'font-display': {
+      readonly light: "\"Newsreader\", Georgia, \"Times New Roman\", serif";
+      readonly dark: "\"Newsreader\", Georgia, \"Times New Roman\", serif";
+    };
+    readonly 'font-body': {
+      readonly light: "\"Inter\", ui-sans-serif, system-ui, -apple-system, sans-serif";
+      readonly dark: "\"Inter\", ui-sans-serif, system-ui, -apple-system, sans-serif";
+    };
+    readonly 'font-mono': {
+      readonly light: "\"JetBrains Mono\", ui-monospace, \"Cascadia Code\", \"Fira Code\", monospace";
+      readonly dark: "\"JetBrains Mono\", ui-monospace, \"Cascadia Code\", \"Fira Code\", monospace";
+    };
+    readonly 'content-reading': {
+      readonly light: "46rem";
+      readonly dark: "46rem";
+    };
+    readonly 'weight-display': {
+      readonly light: 400;
+      readonly dark: 500;
+    };
+    readonly 'color-bg': {
+      readonly light: "oklch(0.975 0.005 80)";
+      readonly dark: "oklch(0.16 0.01 80)";
+    };
+    readonly 'color-bg-subtle': {
+      readonly light: "oklch(0.955 0.005 80)";
+      readonly dark: "oklch(0.19 0.01 80)";
+    };
+    readonly 'color-fg': {
+      readonly light: "oklch(0.18 0.01 80)";
+      readonly dark: "oklch(0.90 0.005 80)";
+    };
+    readonly 'color-fg-muted': {
+      readonly light: "oklch(0.43 0.015 80)";
+      readonly dark: "oklch(0.70 0.01 80)";
+    };
+    readonly 'color-muted': {
+      readonly light: "oklch(0.54 0.01 80)";
+      readonly dark: "oklch(0.60 0.01 80)";
+    };
+    readonly 'color-border': {
+      readonly light: "oklch(0.88 0.005 80)";
+      readonly dark: "oklch(0.25 0.005 80)";
+    };
+    readonly 'color-border-bold': {
+      readonly light: "oklch(0.62 0.01 80)";
+      readonly dark: "oklch(0.50 0.01 80)";
+    };
+    readonly 'color-surface': {
+      readonly light: "oklch(0.965 0.005 80)";
+      readonly dark: "oklch(0.19 0.01 80)";
+    };
+    readonly 'color-accent': {
+      readonly light: "oklch(0.50 0.14 250)";
+      readonly dark: "oklch(0.68 0.12 250)";
+    };
+    readonly 'color-accent-hover': {
+      readonly light: "oklch(0.42 0.11 250)";
+      readonly dark: "oklch(0.75 0.12 250)";
+    };
+    readonly 'color-accent-subtle': {
+      readonly light: "oklch(0.95 0.02 250)";
+      readonly dark: "oklch(0.22 0.04 250)";
+    };
+    readonly 'color-link': {
+      readonly light: "var(--color-accent)";
+      readonly dark: "var(--color-accent)";
+    };
+    readonly 'color-link-hover': {
+      readonly light: "var(--color-accent-hover)";
+      readonly dark: "var(--color-accent-hover)";
+    };
+    readonly 'color-focus-ring': {
+      readonly light: "var(--color-accent)";
+      readonly dark: "var(--color-accent)";
+    };
+    readonly 'color-selection-bg': {
+      readonly light: "oklch(0.92 0.04 250)";
+      readonly dark: "oklch(0.30 0.06 250)";
+    };
+    readonly 'color-selection-fg': {
+      readonly light: "var(--color-fg)";
+      readonly dark: "oklch(0.92 0.005 80)";
+    };
+    readonly 'color-code-bg': {
+      readonly light: "oklch(0.945 0.005 80)";
+      readonly dark: "oklch(0.20 0.005 80)";
+    };
+    readonly 'color-code-fg': {
+      readonly light: "var(--color-fg)";
+      readonly dark: "oklch(0.88 0.005 80)";
+    };
+  };
+}
+
+// Precise types for `import tokens from 'remarque-tokens/tokens.json'`
+// (and any other bundler-JSON-import path resolving through this
+// subpath) without depending on the consumer's `resolveJsonModule`.
+declare module 'remarque-tokens/tokens.json' {
+  const tokens: RemarqueTokensFile;
+  export default tokens;
+}

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