remarque-tokens 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,87 @@ 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.13.0 — 2026-07-23
+
+Syntax-highlighting palette — 9 `--color-syntax-*` slots, ANSI-derived, golden-gated (closes #53; consensus-ratified 3-0 with a binding taxonomy design record, 2026-07-23).
+
+### Added
+- **`--color-syntax-keyword/string/constant/comment/function/type/punctuation/variable/link`** —
+  9 new palette-tier slots in `tokens-palette.css`, hand-authored in both
+  themes, quiet/low-chroma (chroma capped at 0.14, the same ceiling as
+  `--color-accent`). Every slot is ≥ 4.5:1 against `--color-code-bg`
+  (not `--color-bg`) in both themes — a new dimension the audit didn't
+  cover before this release.
+- **`scripts/audit.mjs`** — 9 new `CHECKS` pairings (each syntax slot vs.
+  `color-code-bg`, 4.5:1, both themes). `scripts/test-audit.mjs`'s
+  fixture palettes carry the 9 slots and a new must-fail case proves
+  they're actually wired into `CHECKS`, not just parsed.
+- **`scripts/theme.mjs` (`remarque-theme`)** — derives all 9 slots from a
+  source theme's 16 ANSI colors (`keyword`←blue, `string`←green,
+  `constant`←yellow, `function`←purple, `type`←cyan, `comment`←`brightBlack`
+  in dark themes / a solved muted neutral in light themes,
+  `punctuation`←a derived neutral, `variable`←fg-adjacent,
+  `link`←the derived accent, aliased when it clears 4.5:1 on `code-bg`),
+  same keep-if-passing-else-solve pattern and in-gamut chroma clamping as
+  every other slot. `scripts/test-theme.mjs`'s 61-pair corpus (every
+  counterpart-paired theme in the installed `oklch-terminal-themes`
+  dataset) now runs the extended audit — 61/61 pass.
+- **`scripts/palette-golden.mjs`** — extends the ΔE2000 ≤ 2.0 golden gate
+  to the 9 syntax slots (now 24 `--color-*` tokens × 2 themes). The
+  hand-authored defaults are the cleaned round-number serialization of
+  values derived from `remarque-light`/`remarque-dark`'s ANSI colors,
+  same identity/serialization contract as the rest of the default
+  palette (#76).
+- **REMARQUE.md "Syntax Highlighting"** — the slot table with Shiki
+  `createCssVariablesTheme` and Prism class mappings, the exact Astro
+  wiring snippet (pass the theme *object*, never the `'css-variables'`
+  string — Astro renames its prefix), the CSS variable bridge required
+  to make that wiring actually render (Shiki's `variablePrefix` prepends
+  rather than renames its internal `token-*` names), a full Prism CSS
+  mapping block, the three documented divergences (`type` ≡ `function`
+  under Shiki, plain operators inherit foreground, diff markers out of
+  scope), and the comment-contrast policy (4.5:1 held; GitHub
+  light/dark-default and VS Code Dark+ all clear it).
+- **Demo site (`site/`)** — wired `astro.config.mjs`'s `markdown.shikiConfig`
+  and the Type Specimen page's new "Syntax Highlighting" section with
+  the `createCssVariablesTheme` recipe and its CSS bridge
+  (`site/src/styles/globals.css`), so at least one built page exercises
+  every slot in both themes. `shiki` added as an explicit `site`
+  devDependency (Astro already carries it transitively; pinned
+  explicitly so the resolution is intentional, not an accident of
+  hoisting). Playwright baselines updated for the 4 `specimen-*`
+  screenshots (the only page with a highlighted code block); the other
+  16 baselines are unchanged.
+
+## 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

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,7 +80,7 @@ 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 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.
+Terminal themes carry only `background/foreground/cursor/selection` + 16 ANSI slots — a few of Remarque's 24 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.
 
@@ -231,6 +231,113 @@ Charts are not yet a first-class Remarque surface, but tools built with the syst
 
 ---
 
+## Syntax Highlighting
+
+Code blocks are a first-class Remarque surface, not a place to reach for a vendor Shiki/Prism theme: `tokens-palette.css` defines 9 `--color-syntax-*` slots, hand-authored in both themes and golden-gated against the upstream `remarque-light`/`remarque-dark` themes' ANSI colors the same way the rest of the default palette is (issue #53). Because they are ordinary palette-tier tokens, they inherit palette swaps and theme-deck runtime switches for free — a vendor theme never does.
+
+### Slots
+
+| Slot | Shiki (`createCssVariablesTheme`) | Prism |
+|---|---|---|
+| `--color-syntax-keyword` | `token-keyword` | `.keyword`, `.atrule` |
+| `--color-syntax-string` | `token-string` + `token-string-expression` (aliased — regex/template/interpolated are string-like) | `.string`, `.char`, `.attr-value` |
+| `--color-syntax-constant` | `token-constant` | `.number`, `.boolean`, `.constant`, `.symbol` |
+| `--color-syntax-comment` | `token-comment` | `.comment`, `.prolog`, `.doctype`, `.cdata` |
+| `--color-syntax-function` | `token-function` | `.function` |
+| `--color-syntax-type` | (same Shiki variable as `function` — see divergence below) | `.class-name` |
+| `--color-syntax-punctuation` | `token-punctuation` | `.operator`, `.punctuation` |
+| `--color-syntax-variable` | `token-parameter` | `.variable`, `.property`, `.tag`, `.attr-name` |
+| `--color-syntax-link` | `token-link` | `.url` |
+
+Slot names were validated against Shiki's `theme-css-variables.ts` and Prism's reference-theme token vocabulary before being frozen (panel condition on #53) — every name above maps to a real token both highlighters actually emit.
+
+### Derivation
+
+`remarque-theme` derives all 9 slots from the source theme's 16 ANSI colors — the same keep-if-passing-else-solve pattern as every other slot, targeted at `--color-code-bg` (not `--color-bg`) at 4.5:1: `keyword`←blue, `string`←green, `constant`←yellow (the terminal convention for numbers/booleans), `function`←purple, `type`←cyan, `comment`←`brightBlack` in dark themes (solved to a muted neutral on the theme's own fg hue in light themes, where `brightBlack` is often too pale to clear 4.5:1 on `code-bg`), `punctuation`←a derived neutral in the muted family, `variable`←the theme's own fg hue/chroma with a slight lightness offset, and `link`←the already-derived accent triple, aliased with `var(--color-accent)` when it clears 4.5:1 on `code-bg` (solved standalone when it doesn't — accent's guarantee is against `--color-bg`, and `code-bg` sits close enough to drift below the line on some corpus themes). Chroma is capped at 0.14, the same ceiling as `--color-accent`, so syntax colors stay in the system's quiet, one-accent register. `scripts/palette-golden.mjs` extends its ΔE2000 ≤ 2.0 gate to all 9 slots, exactly like the rest of the default palette.
+
+### Astro / Shiki wiring
+
+Shiki v1+ ships `createCssVariablesTheme` — pass it as an object, not the `'css-variables'` string (Astro renames the string form's variable prefix to `--astro-code-*`, which silently breaks the mapping):
+
+```js
+import { createCssVariablesTheme } from 'shiki'; // or '@shikijs/core'
+
+const theme = createCssVariablesTheme({
+  name: 'remarque',
+  variablePrefix: '--color-syntax-',
+  fontStyle: true,
+});
+
+// markdown/MDX: { shikiConfig: { theme } }
+// <Code> component: <Code code={...} lang="..." theme={theme} />
+```
+
+**The CSS bridge (required, not optional):** `createCssVariablesTheme`'s `variablePrefix` is a plain string prepend, not a rename — Shiki's own internal slot names already start with `token-` (`token-keyword`, `token-string-expression`, `token-constant`, …) plus a bare `foreground`/`background`, so `variablePrefix: '--color-syntax-'` makes Shiki bake `color:var(--color-syntax-token-keyword)` into every span, not `var(--color-syntax-keyword)`. Left undefined, that variable resolves to nothing and the span silently inherits its parent's color — the highlighting looks like it's missing, not broken. One small bridge block closes the gap (Astro's Shiki integration puts an `.astro-code` class on the `<pre>`; scope to it so these implementation-detail names don't leak into the page's global custom-property namespace):
+
+```css
+.astro-code {
+  --color-syntax-foreground: var(--color-code-fg);
+  --color-syntax-background: var(--color-code-bg);
+  --color-syntax-token-keyword: var(--color-syntax-keyword);
+  --color-syntax-token-string: var(--color-syntax-string);
+  --color-syntax-token-string-expression: var(--color-syntax-string);
+  --color-syntax-token-constant: var(--color-syntax-constant);
+  --color-syntax-token-comment: var(--color-syntax-comment);
+  --color-syntax-token-function: var(--color-syntax-function);
+  --color-syntax-token-parameter: var(--color-syntax-variable);
+  --color-syntax-token-punctuation: var(--color-syntax-punctuation);
+  --color-syntax-token-link: var(--color-syntax-link);
+  /* token-inserted/-deleted/-changed intentionally left undefined —
+     diff markers, out of scope (see "Documented divergences" below);
+     they fall back to inherited foreground, which is a safe default. */
+}
+```
+
+There is no separate `token-type` — see the `type` ≡ `function` divergence below; `--color-syntax-type` is real for Prism but never appears as a Shiki variable.
+
+### Prism CSS mapping
+
+Prism ships no CSS-variables mode — wire the classes directly:
+
+```css
+.token.keyword,
+.token.atrule            { color: var(--color-syntax-keyword); }
+.token.string,
+.token.char,
+.token.attr-value        { color: var(--color-syntax-string); }
+.token.number,
+.token.boolean,
+.token.constant,
+.token.symbol            { color: var(--color-syntax-constant); }
+.token.comment,
+.token.prolog,
+.token.doctype,
+.token.cdata             { color: var(--color-syntax-comment); }
+.token.function          { color: var(--color-syntax-function); }
+.token.class-name        { color: var(--color-syntax-type); }
+.token.operator,
+.token.punctuation       { color: var(--color-syntax-punctuation); }
+.token.variable,
+.token.property,
+.token.tag,
+.token.attr-name         { color: var(--color-syntax-variable); }
+.token.url               { color: var(--color-syntax-link); }
+```
+
+### Documented divergences
+
+These are deliberate, not bugs:
+
+- **`type` ≡ `function` under Shiki.** Shiki's css-variables mode folds `entity.name.type` into the function-scoped variable, so the two slots render identically in Shiki output even though Prism (`.class-name` vs. `.function`) distinguishes them. The tokens stay separate because Prism needs them separate.
+- **Plain operators inherit the foreground.** Shiki has no scope for a bare operator token; it renders in `--color-fg` like surrounding text rather than `--color-syntax-punctuation`. Prism's `.operator` class does map to punctuation.
+- **Diff markers are out of scope.** `token-inserted`/`token-deleted`/`token-changed` (Shiki) and equivalent Prism diff classes are not covered by this token set — a future `--color-diff-*` family would own them if a concrete consumer needs one.
+
+### Comment-contrast policy
+
+The 4.5:1 floor is held, not relaxed, for `--color-syntax-comment` — muted comments are an editorial convention, not a license to fail AA. Survey of shipping syntax themes: GitHub's light-default theme holds 4.55:1, GitHub's dark-default holds 6.15:1, and VS Code's Dark+ holds 5.0:1 — all pass. Only legacy/neglected themes fail (Prism's own default theme sits at 3.64:1; the legacy `github-dark` theme sits at 3.05:1). A muted-comment convention is achievable within AA; Remarque does not carry a documented exception for this slot.
+
+---
+
 ## Motion Rules
 
 Motion in Remarque is nearly invisible. The only permitted motion:
@@ -303,6 +410,7 @@ Every PR that ships Remarque pages MUST pass (`npm run audit` automates the colo
 - [ ] `font-variant-numeric: tabular-nums lining-nums` on all metadata that mixes with dates/counts.
 - [ ] No hardcoded hex/rgb colors — only `var(--color-*)` tokens.
 - [ ] Body line-height ≥ 1.5 (Remarque target: 1.75).
+- [ ] Every `--color-syntax-*` slot ≥ 4.5:1 against `--color-code-bg` in both themes (see "Syntax Highlighting").
 
 Agents reviewing PRs should reject changes that violate any line above without explicit rationale.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.11.0",
+  "version": "0.13.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",
@@ -43,7 +44,10 @@
     }
   },
   "exports": {
-    ".": "./tokens.css",
+    ".": {
+      "types": "./tokens.d.ts",
+      "default": "./tokens.css"
+    },
     "./tokens": "./tokens.css",
     "./tokens.css": "./tokens.css",
     "./core": "./tokens-core.css",
@@ -55,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",
@@ -80,6 +88,7 @@
     "CHANGELOG.md",
     "theme.css",
     "tokens.json",
+    "tokens.d.ts",
     "scripts/tokens-json.mjs",
     "prose.css",
     "print.css",

package/scripts/audit.mjs

@@ -113,6 +113,15 @@ const CHECKS = [
   ['color-code-fg', 'color-code-bg', 4.5, 'code text'],
   ['color-border-bold', 'color-bg', 3.0, 'functional borders (WCAG 1.4.11)'],
   ['color-selection-fg', 'color-selection-bg', 4.5, 'selected text'],
+  ['color-syntax-keyword', 'color-code-bg', 4.5, 'syntax: keyword'],
+  ['color-syntax-string', 'color-code-bg', 4.5, 'syntax: string'],
+  ['color-syntax-constant', 'color-code-bg', 4.5, 'syntax: constant'],
+  ['color-syntax-comment', 'color-code-bg', 4.5, 'syntax: comment'],
+  ['color-syntax-function', 'color-code-bg', 4.5, 'syntax: function'],
+  ['color-syntax-type', 'color-code-bg', 4.5, 'syntax: type'],
+  ['color-syntax-punctuation', 'color-code-bg', 4.5, 'syntax: punctuation'],
+  ['color-syntax-variable', 'color-code-bg', 4.5, 'syntax: variable'],
+  ['color-syntax-link', 'color-code-bg', 4.5, 'syntax: link'],
 ];
 
 for (const [themeName, decls] of [['light', lightDecls], ['dark', darkDecls]]) {

package/scripts/theme.mjs

@@ -7,7 +7,7 @@
  *   npx remarque-theme <light-slug> --dark <dark-slug> [-o out.css]
  *
  * Terminal themes carry only background/foreground/cursor/selection + 16
- * ANSI slots — most of Remarque's 15 semantic slots don't map directly,
+ * ANSI slots — most of Remarque's 24 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 KEEP-IF-PASSING — a few load-bearing slots
@@ -19,9 +19,11 @@
  * 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.
+ * meaningful "theme's own value" to preserve. The 9 --color-syntax-*
+ * slots (issue #53) are derived straight from the theme's 16 ANSI
+ * colors instead — see the "Syntax-highlighting slots" section below.
+ * Output passes remarque-audit BY CONSTRUCTION — this script
+ * self-verifies the same pairings before it will emit anything.
  *
  * Security (non-negotiable, per the panel security review on #75):
  *   - Both slugs are checked against the package's own index.json BEFORE
@@ -325,6 +327,66 @@ function withHeadroom([L0, , H], delta, dir, C) {
   return [L, fitChroma(L, C, H), r1(H)];
 }
 
+/* ── Syntax-highlighting slots (issue #53) ───────────────────────────
+ * Terminal ANSI colors ARE syntax colors in their native domain, so the
+ * 9 --color-syntax-* slots are derived straight from a theme's 16 ANSI
+ * colors rather than invented fresh — zero new upstream schema work.
+ * Every slot targets --color-code-bg (not --color-bg) at 4.5:1, same
+ * keep-if-passing-else-solve pattern as every other slot above: the
+ * ANSI color's own lightness is kept when it already clears the ratio,
+ * solved (same binary search, same in-gamut chroma clamping) only when
+ * it doesn't. Chroma is capped at 0.14 — the same ceiling already used
+ * for --color-accent — so syntax colors stay in the system's "quiet,
+ * one-accent" register rather than turning carnival-bright. */
+
+const SYNTAX_CHROMA_CAP = 0.14;
+
+/* keyword/string/constant/function/type: a direct ANSI slot, kept if it
+ * already passes vs code-bg, solved (same hue) if it doesn't. */
+function deriveSyntaxAnsi(t, ansiName, label, codeBg, dir) {
+  const [L0, C0, H0] = slotLch(t, ansiName, label);
+  const C = Math.min(C0, SYNTAX_CHROMA_CAP);
+  return keepOrSolve(L0, C, H0, codeBg, 4.5, dir);
+}
+
+/* comment: brightBlack in dark themes (the ANSI convention); in light
+ * themes brightBlack is often too pale to hold 4.5:1 on code-bg, so the
+ * fallback solves a muted neutral on the theme's own fg hue instead of
+ * brightBlack's hue. */
+function deriveSyntaxComment(t, label, codeBg, dir, fallbackC, fallbackH) {
+  const [L0, C0, H0] = slotLch(t, 'brightBlack', label);
+  const C = Math.min(C0, SYNTAX_CHROMA_CAP);
+  const L = r3(Math.min(1, Math.max(0, L0)));
+  const c = fitChroma(L, C, H0);
+  if (ratio([L, c, H0], codeBg) >= 4.5) return [L, c, r1(H0)];
+  return solveL(fallbackC, fallbackH, codeBg, 4.5, dir);
+}
+
+/* punctuation: a derived neutral in the muted family (fg hue, low
+ * chroma), targeted at code-bg rather than surface. */
+function deriveSyntaxPunctuation(fgC, fgH, codeBg, dir) {
+  return solveL(Math.min(fgC, 0.02), fgH, codeBg, 4.5, dir);
+}
+
+/* variable: fg-adjacent — the theme's own fg hue/chroma, offset a little
+ * so it reads as "quieter than plain text," verified (and solved if
+ * needed) against code-bg rather than assumed from the fg/surface pass. */
+function deriveSyntaxVariable(fg, codeBg, dir, offset) {
+  return keepOrSolve(fg[0] + offset, fg[1], fg[2], codeBg, 4.5, dir);
+}
+
+/* link: alias the already-derived accent triple when it clears 4.5:1 on
+ * code-bg (accent is only guaranteed against --color-bg, and code-bg
+ * sits a little off from bg, so this isn't automatic) — solve a
+ * standalone value at the accent's own hue/chroma only when it doesn't,
+ * same as every other slot. Aliasing means a site's accent-hue swap
+ * (REMARQUE.md "Changing the Accent Hue") carries the link color with
+ * it for free whenever the alias holds. */
+function deriveSyntaxLink(accent, codeBg, dir) {
+  if (ratio(accent, codeBg) >= 4.5) return { ref: 'color-accent' };
+  return keepOrSolve(accent[0], accent[1], accent[2], codeBg, 4.5, dir);
+}
+
 /* ── LIGHT derivation ─────────────────────────────────────────────── */
 
 function deriveLight(t) {
@@ -351,6 +413,18 @@ function deriveLight(t) {
   // 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 codeBg = [r3(bg[0] - 0.03), bg[1], bg[2]];
+  // Syntax-highlighting slots (issue #53) — see the derivation helpers
+  // above. All verified against code-bg (not bg) at 4.5:1.
+  const synKeyword = deriveSyntaxAnsi(t, 'blue', 'light', codeBg, 'darker');
+  const synString = deriveSyntaxAnsi(t, 'green', 'light', codeBg, 'darker');
+  const synConstant = deriveSyntaxAnsi(t, 'yellow', 'light', codeBg, 'darker');
+  const synFunction = deriveSyntaxAnsi(t, 'purple', 'light', codeBg, 'darker');
+  const synType = deriveSyntaxAnsi(t, 'cyan', 'light', codeBg, 'darker');
+  const synComment = deriveSyntaxComment(t, 'light', codeBg, 'darker', fgC, fgH);
+  const synPunctuation = deriveSyntaxPunctuation(fgC, fgH, codeBg, 'darker');
+  const synVariable = deriveSyntaxVariable(fg, codeBg, 'darker', 0.08);
+  const synLink = deriveSyntaxLink(accent, codeBg, 'darker');
   const raw = {
     'color-bg': bg,
     'color-bg-subtle': [r3(bg[0] - 0.02), bg[1], bg[2]],
@@ -365,8 +439,17 @@ function deriveLight(t) {
     'color-accent-subtle': [0.95, fitChroma(0.95, 0.02, ac.h), r1(ac.h)],
     'color-selection-bg': [0.92, fitChroma(0.92, 0.04, ac.h), r1(ac.h)],
     'color-selection-fg': { ref: 'color-fg' },
-    'color-code-bg': [r3(bg[0] - 0.03), bg[1], bg[2]],
+    'color-code-bg': codeBg,
     'color-code-fg': { ref: 'color-fg' },
+    'color-syntax-keyword': synKeyword,
+    'color-syntax-string': synString,
+    'color-syntax-constant': synConstant,
+    'color-syntax-comment': synComment,
+    'color-syntax-function': synFunction,
+    'color-syntax-type': synType,
+    'color-syntax-punctuation': synPunctuation,
+    'color-syntax-variable': synVariable,
+    'color-syntax-link': synLink,
   };
   const tokens = {};
   for (const [name, v] of Object.entries(raw)) tokens[name] = v.ref ? `var(--${v.ref})` : fmt(v);
@@ -409,6 +492,17 @@ function deriveDark(t, accentHueLight) {
   // 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');
+  // Syntax-highlighting slots (issue #53) — mirrors the light derivation,
+  // direction flipped ('lighter': text on a dark code-bg).
+  const synKeyword = deriveSyntaxAnsi(t, 'blue', 'dark', codeBg, 'lighter');
+  const synString = deriveSyntaxAnsi(t, 'green', 'dark', codeBg, 'lighter');
+  const synConstant = deriveSyntaxAnsi(t, 'yellow', 'dark', codeBg, 'lighter');
+  const synFunction = deriveSyntaxAnsi(t, 'purple', 'dark', codeBg, 'lighter');
+  const synType = deriveSyntaxAnsi(t, 'cyan', 'dark', codeBg, 'lighter');
+  const synComment = deriveSyntaxComment(t, 'dark', codeBg, 'lighter', fgC, fgH);
+  const synPunctuation = deriveSyntaxPunctuation(fgC, fgH, codeBg, 'lighter');
+  const synVariable = deriveSyntaxVariable(fg, codeBg, 'lighter', -0.08);
+  const synLink = deriveSyntaxLink(accent, codeBg, 'lighter');
   const raw = {
     'color-bg': bg,
     'color-bg-subtle': surface,
@@ -425,9 +519,18 @@ function deriveDark(t, accentHueLight) {
     'color-selection-fg': selFg,
     'color-code-bg': codeBg,
     'color-code-fg': codeFg,
+    'color-syntax-keyword': synKeyword,
+    'color-syntax-string': synString,
+    'color-syntax-constant': synConstant,
+    'color-syntax-comment': synComment,
+    'color-syntax-function': synFunction,
+    'color-syntax-type': synType,
+    'color-syntax-punctuation': synPunctuation,
+    'color-syntax-variable': synVariable,
+    'color-syntax-link': synLink,
   };
   const tokens = {};
-  for (const [name, v] of Object.entries(raw)) tokens[name] = fmt(v);
+  for (const [name, v] of Object.entries(raw)) tokens[name] = v.ref ? `var(--${v.ref})` : fmt(v);
   tokens['weight-display'] = '500';
   return { raw, tokens };
 }
@@ -452,6 +555,15 @@ const CHECKS = [
   ['color-code-fg', 'color-code-bg', 4.5, 'code text'],
   ['color-border-bold', 'color-bg', 3.0, 'functional borders (WCAG 1.4.11)'],
   ['color-selection-fg', 'color-selection-bg', 4.5, 'selected text'],
+  ['color-syntax-keyword', 'color-code-bg', 4.5, 'syntax: keyword'],
+  ['color-syntax-string', 'color-code-bg', 4.5, 'syntax: string'],
+  ['color-syntax-constant', 'color-code-bg', 4.5, 'syntax: constant'],
+  ['color-syntax-comment', 'color-code-bg', 4.5, 'syntax: comment'],
+  ['color-syntax-function', 'color-code-bg', 4.5, 'syntax: function'],
+  ['color-syntax-type', 'color-code-bg', 4.5, 'syntax: type'],
+  ['color-syntax-punctuation', 'color-code-bg', 4.5, 'syntax: punctuation'],
+  ['color-syntax-variable', 'color-code-bg', 4.5, 'syntax: variable'],
+  ['color-syntax-link', 'color-code-bg', 4.5, 'syntax: link'],
 ];
 
 function resolveRaw(raw, name, seen = new Set()) {

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-palette.css

@@ -16,6 +16,7 @@
  *   - Colors: every replacement palette must pass the contrast audit
  *     (npm run audit) — fg-muted ≥ 7:1, muted ≥ 4.5:1 on bg AND
  *     surface, accent + accent-hover ≥ 4.5:1, border-bold ≥ 3:1,
+ *     every --color-syntax-* slot ≥ 4.5:1 on --color-code-bg,
  *     in BOTH themes.
  *   - Accent: change the hue by re-deriving accent/accent-hover/
  *     accent-subtle/selection at the SAME lightness values used here,
@@ -77,6 +78,22 @@
   --color-selection-fg: var(--color-fg);
   --color-code-bg:     oklch(0.945 0.005 80);     /* inline code background */
   --color-code-fg:     var(--color-fg);
+
+  /* Syntax highlighting (issue #53) — quiet, low-chroma slots derived
+     from remarque-light's ANSI colors (scripts/theme.mjs), serialized
+     as round numbers (golden-gated: scripts/palette-golden.mjs). Every
+     slot ≥ 4.5:1 on --color-code-bg. Mapping recipe (Shiki css-variables
+     + Prism) is documented in REMARQUE.md's "Syntax Highlighting"
+     section. */
+  --color-syntax-keyword:     oklch(0.51 0.12 250);   /* ANSI blue — 4.88:1 on code-bg */
+  --color-syntax-string:      oklch(0.50 0.12 145);   /* ANSI green — 4.85:1 */
+  --color-syntax-constant:    oklch(0.51 0.105 85);   /* ANSI yellow (numbers/booleans convention) — 4.94:1 */
+  --color-syntax-comment:     oklch(0.52 0.01 80);    /* solved muted neutral (fg hue) — brightBlack is too pale on code-bg here — 4.69:1 */
+  --color-syntax-function:    oklch(0.52 0.12 310);   /* ANSI purple — 4.96:1 */
+  --color-syntax-type:        oklch(0.50 0.085 196);  /* ANSI cyan — 4.90:1 */
+  --color-syntax-punctuation: oklch(0.52 0.01 80);    /* derived neutral, muted family — 4.69:1 */
+  --color-syntax-variable:    oklch(0.26 0.01 80);    /* fg-adjacent (slight L offset) — 13.23:1 */
+  --color-syntax-link:        var(--color-accent);    /* accent already clears code-bg — 4.5:1+ */
 }
 
 /* ─── Color: Dark theme ─────────────────────────────────── */
@@ -110,6 +127,18 @@
     --color-selection-fg: oklch(0.92 0.005 80);
     --color-code-bg:     oklch(0.20 0.005 80);
     --color-code-fg:     oklch(0.88 0.005 80);
+
+    /* Syntax highlighting (issue #53) — derived from remarque-dark's
+       ANSI colors; see the light block above for the full rationale. */
+    --color-syntax-keyword:     oklch(0.61 0.11 250);   /* ANSI blue — 4.80:1 on code-bg */
+    --color-syntax-string:      oklch(0.60 0.11 145);   /* ANSI green — 4.80:1 */
+    --color-syntax-constant:    oklch(0.61 0.11 84);    /* ANSI yellow — 4.73:1 */
+    --color-syntax-comment:     oklch(0.60 0.005 80);   /* ANSI brightBlack — 4.59:1 */
+    --color-syntax-function:    oklch(0.62 0.11 310);   /* ANSI purple — 4.75:1 */
+    --color-syntax-type:        oklch(0.60 0.10 195);   /* ANSI cyan — 4.81:1 */
+    --color-syntax-punctuation: oklch(0.60 0.005 80);   /* derived neutral, muted family — 4.59:1 */
+    --color-syntax-variable:    oklch(0.82 0.005 80);   /* fg-adjacent (slight L offset) — 10.37:1 */
+    --color-syntax-link:        var(--color-accent);    /* accent already clears code-bg */
   }
 }
 
@@ -141,4 +170,16 @@
   --color-selection-fg: oklch(0.92 0.005 80);
   --color-code-bg:     oklch(0.20 0.005 80);
   --color-code-fg:     oklch(0.88 0.005 80);
+
+  /* Syntax highlighting (issue #53) — derived from remarque-dark's
+     ANSI colors; see the light block above for the full rationale. */
+  --color-syntax-keyword:     oklch(0.61 0.11 250);
+  --color-syntax-string:      oklch(0.60 0.11 145);
+  --color-syntax-constant:    oklch(0.61 0.11 84);
+  --color-syntax-comment:     oklch(0.60 0.005 80);
+  --color-syntax-function:    oklch(0.62 0.11 310);
+  --color-syntax-type:        oklch(0.60 0.10 195);
+  --color-syntax-punctuation: oklch(0.60 0.005 80);
+  --color-syntax-variable:    oklch(0.82 0.005 80);
+  --color-syntax-link:        var(--color-accent);
 }

package/tokens.d.ts

@@ -0,0 +1,344 @@
+/*
+ * Remarque design tokens — GENERATED from tokens.json by
+ * scripts/tokens-json.mjs (v0.13.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'
+  | 'color-syntax-keyword'
+  | 'color-syntax-string'
+  | 'color-syntax-constant'
+  | 'color-syntax-comment'
+  | 'color-syntax-function'
+  | 'color-syntax-type'
+  | 'color-syntax-punctuation'
+  | 'color-syntax-variable'
+  | 'color-syntax-link';
+
+/** 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)";
+    };
+    readonly 'color-syntax-keyword': {
+      readonly light: "oklch(0.51 0.12 250)";
+      readonly dark: "oklch(0.61 0.11 250)";
+    };
+    readonly 'color-syntax-string': {
+      readonly light: "oklch(0.50 0.12 145)";
+      readonly dark: "oklch(0.60 0.11 145)";
+    };
+    readonly 'color-syntax-constant': {
+      readonly light: "oklch(0.51 0.105 85)";
+      readonly dark: "oklch(0.61 0.11 84)";
+    };
+    readonly 'color-syntax-comment': {
+      readonly light: "oklch(0.52 0.01 80)";
+      readonly dark: "oklch(0.60 0.005 80)";
+    };
+    readonly 'color-syntax-function': {
+      readonly light: "oklch(0.52 0.12 310)";
+      readonly dark: "oklch(0.62 0.11 310)";
+    };
+    readonly 'color-syntax-type': {
+      readonly light: "oklch(0.50 0.085 196)";
+      readonly dark: "oklch(0.60 0.10 195)";
+    };
+    readonly 'color-syntax-punctuation': {
+      readonly light: "oklch(0.52 0.01 80)";
+      readonly dark: "oklch(0.60 0.005 80)";
+    };
+    readonly 'color-syntax-variable': {
+      readonly light: "oklch(0.26 0.01 80)";
+      readonly dark: "oklch(0.82 0.005 80)";
+    };
+    readonly 'color-syntax-link': {
+      readonly light: "var(--color-accent)";
+      readonly dark: "var(--color-accent)";
+    };
+  };
+}
+
+// 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.11.0",
+      "version": "0.13.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"
@@ -421,6 +421,87 @@
       "dark": {
         "$value": "oklch(0.88 0.005 80)"
       }
+    },
+    "color-syntax-keyword": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.51 0.12 250)"
+      },
+      "dark": {
+        "$value": "oklch(0.61 0.11 250)"
+      }
+    },
+    "color-syntax-string": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.50 0.12 145)"
+      },
+      "dark": {
+        "$value": "oklch(0.60 0.11 145)"
+      }
+    },
+    "color-syntax-constant": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.51 0.105 85)"
+      },
+      "dark": {
+        "$value": "oklch(0.61 0.11 84)"
+      }
+    },
+    "color-syntax-comment": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.52 0.01 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.60 0.005 80)"
+      }
+    },
+    "color-syntax-function": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.52 0.12 310)"
+      },
+      "dark": {
+        "$value": "oklch(0.62 0.11 310)"
+      }
+    },
+    "color-syntax-type": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.50 0.085 196)"
+      },
+      "dark": {
+        "$value": "oklch(0.60 0.10 195)"
+      }
+    },
+    "color-syntax-punctuation": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.52 0.01 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.60 0.005 80)"
+      }
+    },
+    "color-syntax-variable": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.26 0.01 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.82 0.005 80)"
+      }
+    },
+    "color-syntax-link": {
+      "$type": "color",
+      "light": {
+        "$value": "var(--color-accent)"
+      },
+      "dark": {
+        "$value": "var(--color-accent)"
+      }
     }
   }
 }