remarque-tokens 0.10.0 → 0.11.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,76 @@ 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.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/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.11.0",
   "engines": {
     "node": ">=18"
   },
@@ -31,7 +31,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"

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