remarque-tokens 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,70 @@ 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.14.0 — 2026-07-23
+
+Triage bundle — prose/`.content-reading` pairing documented, `--motion-easing` bridged into the Tailwind v4 utility layer, USWDS/WCAG source citations added to the accessibility section (closes #23, closes #31, closes #32).
+
+### Added
+- **`ease-remarque` Tailwind v4 utility** — `theme.css`'s `@theme inline` block now maps `--ease-remarque: var(--motion-easing)`, mirroring the `transitionTimingFunction.remarque` mapping the v3 `tailwind.config.js` already carried. Utility-class users of `duration-[var(--motion-fast)]` previously fell back to Tailwind's default `ease` timing function instead of the token (#31).
+- **Demo site** — every `duration-[var(--motion-fast)]` call site (22, across `site/src/pages/*`, `layouts/BaseLayout.astro`, `components/Meta.astro`) now pairs with `ease-remarque` so the rendered CSS carries `var(--motion-easing)` instead of Tailwind's default.
+
+### Documentation
+- **REMARQUE.md "Editorial Microtypography"** — states that `.remarque-prose` is typography-only (font, line height, numeral register, optical wrapping) and does not center the column; pair it with `.content-reading`, with a minimal code sample (#23).
+- **REMARQUE.md "USWDS Accessibility Compliance"** — every cited WCAG 2.1 success criterion (1.4.3 Contrast Minimum, 1.4.11 Non-text Contrast, 2.5.5 Target Size, 2.3.3 Animation from Interactions, the last in the adjacent "Motion Rules" section) and USWDS claim (16px font-size floor, the overall accessibility approach) now links to its source (`w3.org/WAI/WCAG21/Understanding/*`, `designsystem.digital.gov`) (#32).
+
+## 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).

package/README.md

@@ -119,6 +119,39 @@ See the [live demo](https://williamzujkowski.github.io/remarque/) for the origin
 | Border radius | 0.5rem max | Restrained. No "friendly SaaS" over-rounding |
 | Motion | 120ms/180ms | Hover and theme transitions only. No scroll-triggered, entrance, or staggered animations |
 
+## Graduation — when a site invention becomes system vocabulary
+
+Consumer sites invent things (the flagship's sidenotes and theme deck, tsundoku's gallery
+grid). Some of those inventions belong upstream; most are the site's own remarque in the
+margin and should stay there. A local invention is upstreamable when **all four** hold:
+
+1. **Wanted by 2+ sites** (or one site plus a ratified case that it generalizes).
+2. **Consumes only tokens** — no hardcoded colors, sizes, or faces.
+3. **Passes the audit tooling** (`remarque-audit`, and `remarque-drift` reports it as
+   palette-tier INFO, not a core FAIL).
+4. **Violates no Never-list entry** in the spec — or arrives together with an explicit
+   spec amendment arguing the change.
+
+**Three destinations.** Core spec (rare — core is identity, the bar is a fork-level
+argument); optional module (sidenotes, TOC rail, palette deck); or *documented site-local
+pattern* — explicitly not shared. The zine layer that inspired this checklist is the
+exemplar of the third: sanctioned personality that would be diluted by generalizing it.
+
+**Process (single-maintainer scale, no ceremony):** open an issue with before/after
+screenshots and the token-purity check; record the decision in the changelog. Historical
+examples: measure compensation and the Gallery archetype graduated; the theme deck was
+re-scoped on the way up ([#56](https://github.com/williamzujkowski/remarque/issues/56));
+the zine layer deliberately stayed local.
+
+**Standing rulings** (ratified 3-0, 2026-07-23) on patterns the reviews kept re-flagging:
+
+| Pattern | Ruling |
+|---------|--------|
+| Share links in post footers | Site-local, never a system module. If you build one: URL-encode every interpolated value and reject non-`https` schemes — title/frontmatter injection into share-intent URLs is the classic mistake. |
+| Cross-hue hover accents | Not sanctioned anywhere. The hover move is a lightness/chroma shift within the accent hue (`--color-accent-hover` models it). A cross-hue hover is a documented deviation, not personalization. |
+| Ambient/decorative animation | Site-local only, never in system modules — and the `prefers-reduced-motion` guard is mandatory, not advisory. A future audit scan may flag unguarded infinite animations (as a heuristic check, not a soundness proof). |
+| Landing-page entry counts | Permitted as meta-voice data in the Landing archetype **only when computed from real inventory at build time**. A hardcoded count is a violation — counts drift (see the upstream count-drift bug class this system just fixed in its own theme provider). |
+
 ## Named For
 
 In fine art printmaking, a *remarque* is a small original drawing made by the artist in the margin of a proof print. Found only in limited editions, it is the mark that says: this was made by someone specific, with intention.

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.
 
@@ -124,6 +124,14 @@ This is why the measure is palette-tier: it is a property of the font choice, no
 
 The book-craft layer: numerals, small caps, drop caps, pull quotes, and optical wrapping. These are the details that separate typeset prose from a web page that merely uses nice fonts.
 
+`.remarque-prose` supplies typography only — font, line height, numeral register, optical wrapping — and stops short of centering the column, so pair it with `.content-reading` wherever the reading column needs to sit centered on the page:
+
+```html
+<div class="remarque-prose content-reading">
+  <!-- article body -->
+</div>
+```
+
 ### Numerals
 
 Two numeral registers, chosen by context:
@@ -231,6 +239,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:
@@ -246,19 +361,19 @@ Motion in Remarque is nearly invisible. The only permitted motion:
 - Parallax effects
 - Any animation on non-interactive elements
 
-**Reduced motion:** all motion must respect `prefers-reduced-motion` (WCAG 2.3.3). Because every sanctioned transition uses the two duration tokens, tokens.css zeroes `--motion-fast`/`--motion-normal` under `prefers-reduced-motion: reduce` — motion authored with the tokens is automatically safe. Never hardcode durations; any future opt-in animation must live inside a `(prefers-reduced-motion: no-preference)` query.
+**Reduced motion:** all motion must respect `prefers-reduced-motion` ([WCAG 2.3.3](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html)). Because every sanctioned transition uses the two duration tokens, tokens.css zeroes `--motion-fast`/`--motion-normal` under `prefers-reduced-motion: reduce` — motion authored with the tokens is automatically safe. Never hardcode durations; any future opt-in animation must live inside a `(prefers-reduced-motion: no-preference)` query.
 
 ---
 
 ## USWDS Accessibility Compliance
 
-Remarque adopts typography and accessibility standards from the US Web Design System (USWDS) and WCAG 2.1:
+Remarque adopts typography and accessibility standards from the [US Web Design System (USWDS)](https://designsystem.digital.gov/documentation/accessibility/) and [WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/):
 
 ### Font Size Floors
 
 | Token | Value | USWDS Rationale |
 |-------|-------|-----------------|
-| `--text-body` | 17px (1.0625rem) | Exceeds USWDS 16px minimum. Non-negotiable floor. |
+| `--text-body` | 17px (1.0625rem) | Exceeds [USWDS 16px minimum](https://designsystem.digital.gov/components/typography/). Non-negotiable floor. |
 | `--text-meta` | 14px (0.875rem) | USWDS minimum for small text. Used sparingly for metadata, labels, captions. |
 | `--text-micro` | 13px (0.8125rem) | USWDS floor for timestamps and fine print only. Never for body content. |
 
@@ -266,13 +381,13 @@ Remarque adopts typography and accessibility standards from the US Web Design Sy
 
 | Pairing | Requirement | Notes |
 |---------|-------------|-------|
-| Normal text on background | 4.5:1 minimum | All text below 24px regular / 18.5px bold. Applies on `--color-surface` too, not just `--color-bg` |
-| Large text on background | 3:1 minimum | Display and title text (24px+) |
-| Functional non-text elements | 3:1 minimum | WCAG 1.4.11 — use `--color-border-bold` (meets 3:1). `--color-border` is decorative-only by design and exempt; never the sole boundary of an interactive element |
+| Normal text on background | 4.5:1 minimum | [WCAG 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) — all text below 24px regular / 18.5px bold. Applies on `--color-surface` too, not just `--color-bg` |
+| Large text on background | 3:1 minimum | [WCAG 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) — display and title text (24px+) |
+| Functional non-text elements | 3:1 minimum | [WCAG 1.4.11](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html) — use `--color-border-bold` (meets 3:1). `--color-border` is decorative-only by design and exempt; never the sole boundary of an interactive element |
 
 ### Touch Targets
 
-All interactive elements (links, buttons, inputs) must have a minimum touch target of **44x44px** (WCAG 2.5.5 AAA). This applies to nav links, theme toggles, footer links, chips, and any clickable element.
+All interactive elements (links, buttons, inputs) must have a minimum touch target of **44x44px** ([WCAG 2.5.5](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html) AAA). This applies to nav links, theme toggles, footer links, chips, and any clickable element.
 
 ### Line Height
 
@@ -303,6 +418,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.12.0",
+  "version": "0.14.0",
   "engines": {
     "node": ">=18"
   },

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/theme.css

@@ -24,6 +24,9 @@
  * is never overridden (mt-12 stays 3rem; use mt-remarque-9 for 6rem).
  * Motion utilities: use arbitrary values with the tokens —
  * duration-[var(--motion-fast)] — so reduced-motion zeroing applies.
+ * Pair every duration-[var(--motion-*)] utility with ease-remarque
+ * (mapped below from --motion-easing) — without it Tailwind falls back
+ * to its default `ease` timing function instead of the token (issue #31).
  */
 
 @theme inline {
@@ -74,4 +77,8 @@
   /* Radius (rounded-sm / rounded-md — the system's ceiling) */
   --radius-sm: var(--radius-sm);
   --radius-md: var(--radius-md);
+
+  /* Easing (ease-remarque) — pair with duration-[var(--motion-*)] so
+     transitions use the token instead of Tailwind's default `ease` */
+  --ease-remarque: var(--motion-easing);
 }

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

@@ -1,6 +1,6 @@
 /*
  * Remarque design tokens — GENERATED from tokens.json by
- * scripts/tokens-json.mjs (v0.12.0). Do not edit — the CSS
+ * scripts/tokens-json.mjs (v0.14.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
@@ -81,7 +81,16 @@ export type RemarquePaletteToken =
   | 'color-selection-bg'
   | 'color-selection-fg'
   | 'color-code-bg'
-  | 'color-code-fg';
+  | '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;
@@ -287,6 +296,42 @@ export interface RemarqueTokenValues {
       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)";
+    };
   };
 }
 

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.12.0",
+      "version": "0.14.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)"
+      }
     }
   }
 }