remarque-tokens 0.19.0 → 0.21.0

package/AGENT_RULES.md

@@ -227,6 +227,91 @@ Before considering any implementation complete, verify:
 
 ---
 
+## Machine-Readable Output
+
+Two tools emit structured JSON for agents/tooling instead of colored
+stdout — pass `--json` and parse stdout as a single JSON document. Exit
+codes are unchanged in both cases; `--json` only changes what stdout
+contains (all human progress lines, including error lines normally on
+stderr, are suppressed — nothing but the JSON document is written).
+
+### `remarque-audit --json`
+
+```
+node scripts/audit.mjs --palette <file> --src <dir> --json
+npx remarque-audit --palette <file> --src <dir> --json
+```
+
+```ts
+{
+  version: string;       // the remarque-tokens package version running the audit
+  palette: string;       // the --palette path as given
+  src: string;            // the --src path as given
+  passed: boolean;       // true iff failures.length === 0
+  contrast: Array<{
+    theme: 'light' | 'dark';
+    fg: string;            // fg token name, no leading --
+    bg: string;            // bg token name, no leading --
+    label: string;         // human label from the CHECKS table (e.g. "primary text")
+    required: number;      // minimum ratio (e.g. 4.5, 7.0, 3.0)
+    actual: number | null; // computed ratio rounded to 2dp, or null if fg/bg was unresolvable
+    ok: boolean;
+    error?: string;        // present only when actual is null (unresolved var()/missing token)
+  }>;
+  gamut: Array<{
+    theme: 'light' | 'dark';
+    token: string;          // token name, no leading --
+    value: string;          // e.g. "oklch(0.5 0.14 250)"
+    ok: boolean;            // false = outside sRGB gamut (browsers will clip it)
+  }>;
+  srcScans: {
+    fontFloor: Array<{ file: string; line: number; size: number; unit: 'rem' | 'px' }>;
+    unverifiableFontSize: Array<{ file: string; line: number; snippet: string }>;
+    hardcodedColors: Array<{ file: string; line: number; snippet: string }>;
+    oklchLiteral: Array<{ file: string; line: number; snippet: string }>;
+  };
+  failures: string[];      // every failure as a human-readable message, same text the non-JSON run prints
+}
+```
+
+`contrast` and `gamut` list EVERY check performed (passing and failing);
+only `srcScans` and `failures` are violation-only lists, since a source
+scan that finds nothing has nothing to report per line.
+
+### `remarque-drift --json`
+
+```
+node scripts/drift-check.mjs --css-file <path> --package-dir <dir> --json
+npx remarque-drift --css-file <path> --package-dir <dir> --json
+```
+
+```ts
+{
+  cssFile: string;
+  packageDir: string;          // resolved node_modules/remarque-tokens path
+  installedVersion: string;    // version of the INSTALLED remarque-tokens being checked against
+  deviationDoc: string | null; // path to DESIGN-DEVIATIONS.md / DESIGN-NOTES.md, or null if none found
+  passed: boolean;             // true iff fail.length === 0
+  fail: Array<{ name: string; theme: 'light' | 'dark'; canonical: string; value: string }>;
+  warn: Array<{ name: string; theme: 'light' | 'dark'; canonical: string; value: string; doc: string }>;
+  info: Array<{ name: string; theme: 'light' | 'dark'; canonical: string; value: string }>;
+  summary: { fail: number; warn: number; info: number }; // counts of distinct TOKENS with an entry, not records (one token can produce two records — light + dark)
+}
+```
+
+`fail`/`warn`/`info` are one record per (token, theme) mismatch — see
+`scripts/drift-check.mjs`'s doc comment and REMARQUE.md's "Token Tiers"
+for the FAIL/WARN/INFO classification these mirror.
+
+### `tokens.json` / `tokens.schema.json`
+
+`remarque-tokens/tokens.json` is always machine-readable (no flag
+needed) and now ships with a published JSON Schema — see REMARQUE.md
+"DTCG Conformance" for the schema's location, the `$schema` pointer, and
+the documented DTCG divergences.
+
+---
+
 ## How to Reference This System
 
 In prompts, issues, or agent instructions, use:

package/CHANGELOG.md

@@ -4,6 +4,33 @@ 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.21.0 — 2026-07-23
+
+Forced-colors (Windows High Contrast Mode) + `prefers-contrast: more` support (closes #93) — the ratified program's highest-value accessibility item.
+
+### Added
+- **`@media (forced-colors: active)` audit and fixes** across `tokens-core.css`, `prose.css`, `essay.css`, `broadsheet.css`, `forms.css`, and the demo's `globals.css`/`tokens.astro`. Every color-bearing declaration was classified as fine-as-is (the overwhelming majority — `border-color` on a real, non-transparent border is forced to a visible system color regardless of the authored value, so `--color-border`'s documented sub-3:1 hairlines, prose table rules, sidenote/TOC borders, etc. already survive with zero code changes), affordance-loss (fixed), or must-survive custom painting (`forced-color-adjust: none`, justified). See REMARQUE.md's new "Forced Colors & Contrast Preferences" section for the full inventory.
+  - **Broadsheet title-link hover/focus** (`broadsheet.css`): the underline-grow effect is a `background-image` gradient, which forced-colors mode forces to `none` — added a `text-decoration: underline` fallback under `@media (forced-colors: active)`.
+  - **`.remarque-rule`** (`broadsheet.css`, masthead dateline divider): converted from a `background` fill on a bare `<span>` (at risk of being forced to `Canvas` and disappearing) to a real `border-top` — an unconditional fix, not media-gated, since a border is simply the correct way to author a hairline.
+  - **Form validation states** (`forms.css`): error/success/warning were distinguished entirely by `border-color`/`color`, both forced under forced-colors — added `border-style`/`border-width` differentiation (double/dashed/solid) plus a small glyph (✕/⚠/✓) prefixed to the message line, scoped to `@media (forced-colors: active)`.
+  - **Focus** (`tokens-core.css`): `:focus-visible` was already forced-colors-safe (`outline`, not `box-shadow` — `box-shadow` is unconditionally forced to `none`); added an explicit `outline-color: Highlight` under forced-colors so the ring keys to the same system color as the rest of the OS, and so the CI gate has something explicit to assert against.
+  - **Demo chrome**: `.nav-link`/`.footer-link`/TOC-rail hover (color-only affordances) get the same `text-decoration: underline` forced-colors fallback; `tokens.astro`'s color-token reference swatches get `forced-color-adjust: none` (the one "must-survive custom painting" case — the swatch's entire purpose is showing the real color).
+- **`prefers-contrast: more`** (`tokens-palette.css`). Bumps `--color-border-bold` (light 3.39:1 → 4.52:1, dark 3.23:1 → 4.53:1) and `--color-fg-muted` (light 7.55:1 → 10.11:1, dark 7.26:1 → 9.70:1) one step toward `--color-fg`, for users who want more contrast without forced-colors' system-color override. Lives in the palette tier (same mechanism as the existing `prefers-color-scheme: dark` override) — version-only change to `tokens.json`/`tokens.d.ts` since no new token names were introduced.
+- **`scripts/lib/css-tokens.mjs` context-exactness fix.** `isDarkBlock`'s two recognition paths (the `prefers-color-scheme: dark` media convention and the `[data-theme="dark"]`/`:root.dark` selector convention) were previously matched by unguarded substring checks — a `[data-theme="dark"]` selector or a `prefers-color-scheme: dark` feature nested inside an unrelated or compounded media query (exactly the shape the new `prefers-contrast: more` block uses) would have been misread as an unconditional dark override, silently clobbering the real dark values in generated output (`tokens.json`/`tokens.d.ts`) and audit results. Both paths are now context-exact (top-level, or the plain non-compounded `@media (prefers-color-scheme: dark)` query only). Two regression fixtures added to `scripts/test-audit.mjs` (`nested-media-not-dark.css`, `compound-media-not-dark.css`) proving a nested/compounded dark-selector block no longer overrides the real one.
+- **`site/tests/forced-colors.spec.ts`** — the issue's blocking CI condition. Computed-style assertions (no pixel diffing) under `page.emulateMedia({ forcedColors: 'active' })`: a nav link's keyboard focus renders a visible, non-zero outline; `.remarque-table` borders resolve to a non-transparent `border-color`; the essay module's TOC rail and (narrow-viewport) sidenote borders stay visible; a form's error/success states render `border-style` distinct from the default and from each other. Wired into the existing `visual-regression.yml` workflow (`npx playwright test` already runs the whole `site/tests/` directory). Three forced-colors screenshot baselines (landing/essay/components) added as a secondary, non-blocking supplement — forced-colors rendering is deterministic in headless Chromium.
+
+## 0.20.0 — 2026-07-23
+
+Machine-readable surface: `--json` for `remarque-audit`/`remarque-drift`, and a published JSON Schema for `tokens.json` (closes #98, closes #99).
+
+### Added
+- **`--json` on `remarque-audit`** (issue #98). Suppresses all human console output (both the progress lines and the error lines normally on stderr) and emits ONE JSON document to stdout instead — exit codes unchanged. Shape: `{ version, palette, src, passed, contrast: [{theme,fg,bg,label,required,actual,ok,error?}], gamut: [{theme,token,value,ok}], srcScans: {fontFloor,unverifiableFontSize,hardcodedColors,oklchLiteral}, failures: [] }`. `contrast`/`gamut` list every check performed (pass and fail); `srcScans`/`failures` are violation-only. Documented in `AGENT_RULES.md` ("Machine-Readable Output") — agents are the intended audience, parsing structure instead of scraping colored stdout.
+- **`--json` on `remarque-drift`** (issue #98). Same suppression contract; emits `{ cssFile, packageDir, installedVersion, deviationDoc, passed, fail: [], warn: [], info: [], summary: {fail,warn,info} }` — one record per (token, theme) mismatch, mirroring the FAIL/WARN/INFO classification the human report already prints.
+- **`tokens.schema.json`** (issue #99). JSON Schema (draft 2020-12) describing `tokens.json`'s actual shape, generated by `scripts/tokens-json.mjs` in the same pass as `tokens.json`/`tokens.d.ts`, same `--check` freshness gate. Token *names* are open (`patternProperties` on the kebab-case grammar); the `$value`/`$type`/light-dark VALUE shapes are fixed. Published as the `remarque-tokens/tokens.schema.json` export, shipped in `files`, and served by the demo site at `/tokens.schema.json` (alongside the existing `/tokens.json`) via an extended `site/scripts/copy-tokens-json.mjs` — shadcn's schema-URL precedent. `tokens.json` now carries a `"$schema"` pointer to that URL.
+- **DTCG conformance note** (issue #99, ratified option ii). `tokens.json`'s `$extensions.remarque.dtcg` documents that the file is conformant in spirit with the Design Tokens Community Group format (`$value`/`$type` on every token) with two **deliberate** divergences — color values as `oklch()` CSS strings (not DTCG's structured color object) and per-token `light`/`dark` nesting (DTCG has no ratified multi-mode/resolver mechanism yet) — each with a named ratification trigger, so a future agent can't "fix" `tokens.json` toward an unratified target. Same argument restated for humans in REMARQUE.md's new "DTCG Conformance" section (under "Token Tiers").
+- **Schema validation in CI** (`scripts/test-types.mjs`). Real JSON-Schema validation of `tokens.json` against `tokens.schema.json` via `ajv` (new devDependency, pinned to a version with zero known advisories; the `$data` option that the one applicable ajv CVE requires is never used) — plus three negative fixtures (unknown `$extensions` key, invalid `$type` enum value, missing required `dark` side) proving the schema actually rejects malformed input rather than accepting anything.
+- **`--json` fixture coverage** (`scripts/test-audit.mjs`, `scripts/test-drift.mjs`). Parses the JSON output of a passing and a must-fail fixture for each tool; asserts the documented shape and that the must-fail fixture's offending pairing/token is actually present with `ok`/`passed: false`.
+
 ## 0.19.0 — 2026-07-23
 
 Palette Deck module (closes #56).

package/README.md

@@ -44,6 +44,8 @@ Copy the `fonts/` woff2 files from `node_modules/remarque-tokens/fonts/` into yo
 npx remarque-audit --palette src/styles/my-palette.css --src src
 ```
 
+Add `--json` to either `remarque-audit` or `remarque-drift` for a single structured JSON document on stdout instead of colored console output (exit codes unchanged) — for agents and CI tooling to parse rather than scrape. Shape documented in `AGENT_RULES.md` ("Machine-Readable Output").
+
 **Tailwind v4** projects add the shipped adapter — utilities that track the tokens through every theme switch, no value duplication:
 
 ```css
@@ -52,7 +54,7 @@ npx remarque-audit --palette src/styles/my-palette.css --src src
 @import "remarque-tokens/theme.css";
 ```
 
-**Tailwind v3** projects use the shipped config (`remarque-tokens/tailwind`) instead. A machine-readable token inventory ships as `remarque-tokens/tokens.json` (generated from the CSS — core/palette tiers, light+dark values) for tooling and AI agents. Prefer copy-paste? Grab `fonts.css`, `tokens.css`, `tokens-core.css`, `tokens-palette.css`, and `fonts/` directly — `tokens.css` aggregates the two tier files, so all three CSS files travel together. Use string-form `@import './tokens.css'` only (some bundlers silently drop `@import url(...)` for local files).
+**Tailwind v3** projects use the shipped config (`remarque-tokens/tailwind`) instead. A machine-readable token inventory ships as `remarque-tokens/tokens.json` (generated from the CSS — core/palette tiers, light+dark values) for tooling and AI agents, with a published JSON Schema at `remarque-tokens/tokens.schema.json` (also referenced by tokens.json's own `$schema` field) so tooling can validate it structurally instead of hand-parsing. tokens.json is conformant in spirit with the [Design Tokens Community Group](https://www.designtokens.org/) format (`$value`/`$type` on every token), with two deliberate divergences — see REMARQUE.md's "DTCG Conformance" section. Prefer copy-paste? Grab `fonts.css`, `tokens.css`, `tokens-core.css`, `tokens-palette.css`, and `fonts/` directly — `tokens.css` aggregates the two tier files, so all three CSS files travel together. Use string-form `@import './tokens.css'` only (some bundlers silently drop `@import url(...)` for local files).
 
 ## For AI Agents
 
@@ -68,7 +70,7 @@ The agent rules define build order, non-negotiable rules, disallowed patterns, a
 Packaging for agent tooling:
 - **npm exports:** `remarque-tokens/agent-rules` (→ `AGENT_RULES.md`) and `remarque-tokens/spec` (→ `REMARQUE.md`), alongside the existing `remarque-tokens/tokens.json`, so a project can point an agent at `node_modules/remarque-tokens/AGENT_RULES.md` without hardcoding a filename.
 - **Claude Code skill:** [`.claude/skills/remarque/SKILL.md`](.claude/skills/remarque/SKILL.md) — triggers on "remarque" / "design system" / new-page work, loads all three files, and states the tier rules, the audit command, and the two build-time pitfalls (unlayered-token-import, string-form `@import`) that pass a green build while silently breaking.
-- **Live tokens endpoint:** the demo site serves the current `tokens.json` at **https://williamzujkowski.github.io/remarque/tokens.json** — a remote agent can fetch current token values directly instead of trusting training data.
+- **Live tokens endpoint:** the demo site serves the current `tokens.json` at **https://williamzujkowski.github.io/remarque/tokens.json**, and its schema at **https://williamzujkowski.github.io/remarque/tokens.schema.json** — a remote agent can fetch current token values (and validate their shape) directly instead of trusting training data.
 
 ## Files
 
@@ -80,7 +82,10 @@ Packaging for agent tooling:
 | `tokens-core.css` | Core tier — type scale, spacing, widths, radius, motion, prose styling. Never overridden |
 | `tokens-palette.css` | Palette tier — font slots, colors, accent, reading measure. The sanctioned personalization surface |
 | `prose.css` | `.remarque-prose` long-form styling — own subpath so sites with their own prose system can skip it |
-| `scripts/audit.mjs` | `npm run audit` — enforces the spec's contrast/gamut/font-floor/no-hardcoded-color checklist |
+| `scripts/audit.mjs` | `npm run audit` — enforces the spec's contrast/gamut/font-floor/no-hardcoded-color checklist (`--json` for structured output) |
+| `scripts/drift-check.mjs` | `npx remarque-drift` — token drift check for consumers (`--json` for structured output) |
+| `tokens.json` + `tokens.d.ts` | Generated machine-readable token inventory + TypeScript types (`scripts/tokens-json.mjs`) |
+| `tokens.schema.json` | Generated JSON Schema (draft 2020-12) for `tokens.json`, published alongside it |
 | `fonts.css` + `fonts/` | Self-hosted @font-face declarations and woff2 files (no CDN requests) |
 | `tailwind.config.js` | Tailwind CSS **v3** configuration (v4 projects use an `@theme` block instead) |
 | `package.json` | npm package manifest for `remarque-tokens` |

package/REMARQUE.md

@@ -68,6 +68,17 @@ Package subpaths for consumers: `remarque-tokens` (aggregator), `remarque-tokens
 
 This makes compliance mechanical: a site that overrides only palette-tier tokens is *authored*; one that touches core-tier tokens has *forked*. `tokens.css` imports both tiers, so existing consumers are unaffected.
 
+### DTCG Conformance
+
+`tokens-core.css` and `tokens-palette.css` remain the single source of truth; `scripts/tokens-json.mjs` regenerates `tokens.json`, `tokens.d.ts`, and `tokens.schema.json` from them in one pass (`node scripts/tokens-json.mjs`; `--check` gates CI freshness). `tokens.json` carries a `$schema` pointer to the published schema (served by the demo site at `/tokens.schema.json`, alongside `/tokens.json` — also exported as `remarque-tokens/tokens.schema.json`).
+
+`tokens.json` is **conformant in spirit** with the [Design Tokens Community Group (DTCG)](https://www.designtokens.org/) format — every token carries `$value`/`$type` — with two **deliberate** structural divergences, documented in the generated file itself (`$extensions.remarque.dtcg`) so a future regeneration can't lose the rationale:
+
+1. **Color values are `oklch()` CSS strings**, not the DTCG structured color object (`{ colorSpace, components, alpha }`). Remarque's color pipeline (audit, drift-check, `remarque-theme`) is built entirely on parsing/emitting `oklch(L C H)` strings; adopting the structured form would mean carrying two color representations in parallel for no present benefit. **Gated on:** the DTCG color `$type` structured-value format ratifying.
+2. **Palette-tier tokens nest per-token `light`/`dark` groups**, each with its own `$value`, rather than a single `$value` plus a modes/resolver mechanism. The DTCG spec has no ratified multi-mode/theming primitive yet; this repo's own theming (`@media (prefers-color-scheme: dark)`, `[data-theme="dark"]`, the Palette Deck's `[data-palette]` scoping) predates any such draft. **Gated on:** the DTCG multi-mode / resolver draft ratifying.
+
+Full DTCG conformance is gated on those two drafts ratifying — a named, checkable trigger, not "someday." Until then, do not "fix" `tokens.json` toward either unratified draft; the CSS is the source of truth, and both divergences are load-bearing for the tooling that already depends on this shape.
+
 ---
 
 ## Color Providers
@@ -434,6 +445,29 @@ All interactive elements (links, buttons, inputs) must have a minimum touch targ
 | Meta/caption text | 1.35 | 1.5 |
 | Display/heading text | 1.0 | 1.05-1.2 |
 
+### Forced Colors & Contrast Preferences
+
+Issue #93 — Remarque cites [USWDS](https://designsystem.digital.gov/documentation/accessibility/) as its accessibility lineage but had, until this section, adopted none of USWDS's forced-colors work (their `$high-contrast-system-colors` map + `@media (forced-colors: active)` rules on nearly every component). Windows High Contrast Mode (`forced-colors: active`) replaces most author-specified `color`/`background-color`/`border-color`/`outline-color` with a small system palette at paint time — the exact signals a typography-first system leans on (`--color-border`'s documented sub-3:1 decorative hairlines, border-only hover states, `-subtle` tinted backgrounds) are the ones color-only affordances rely on, and forced-colors is precisely the mode that strips them.
+
+**The audit, and what it found.** Every color-bearing declaration across `tokens-core.css`, `prose.css`, `essay.css`, `broadsheet.css`, `forms.css`, `theme.css`, and the demo's own `globals.css`/`tokens.astro` was classified into one of three buckets:
+
+1. **Fine as-is** — the overwhelming majority. `forced-colors: active` forces `border-color` to a visible system border color for any non-transparent, non-zero-width border, REGARDLESS of the authored value — so every hairline built the ordinary way (table `border-bottom`, `hr`, `.remarque-sidenote`'s `border-inline-start`, `.remarque-toc-rail summary`'s `border-bottom`, `dl`/`details`' `border-top`, `img`/`kbd`'s `border`, the pullquote's rules) already renders correctly with zero code changes. This is exactly the mechanism that "fixes" `--color-border`'s documented sub-3:1 contrast for free: the decorative token was never load-bearing under forced-colors to begin with. `::selection`'s `background-color`/`color` are likewise forced to the system `Highlight`/`HighlightText` pair automatically, same as any native text selection. `--color-syntax-*`'s nine-slot rainbow collapses to one uniform system text color — accepted, not fixed: the code's structure and whitespace carry meaning independent of the syntax coloring, and `forced-color-adjust: none` here would mean trusting our authored syntax palette to stay legible against an *unknown* system high-contrast background, which is not a bet this system should make on a user's behalf. `.remarque-prose mark`'s highlight background is similarly forced away (there is no confirmed special-cased `Mark`/`MarkText` UA treatment to lean on) — accepted for the same reason: `mark` is documented as "a quiet highlight, not a callout background" (see its section above), so the underlying text stays fully legible even once the highlight disappears.
+2. **Affordance-loss — fixed.** Three concrete cases where color genuinely was the only signal:
+   - **Broadsheet title-link hover/focus** (`broadsheet.css`, `.remarque-lead-title a` / `.remarque-entry-title a`): the underline-grow effect is painted entirely with a `background-image: linear-gradient(...)` — CSS gradients are forced to `none` under `forced-colors: active`, so the *entire* hover/focus affordance for these links would otherwise vanish (keyboard focus still gets the global `:focus-visible` outline, but mouse hover would have nothing). Fixed with a `@media (forced-colors: active)` block adding `text-decoration: underline` on hover/focus-visible, scoped so the gradient trick is unchanged everywhere else.
+   - **Form validation states** (`forms.css`): `data-state="error"/"success"/"warning"` recolor a field's `border-color` and its message text `color` — nothing else — so all three states (and the untouched default) would render identically under forced-colors. Fixed with geometry, not color: each state gets a distinct `border-style`/`border-width` on the control (double/3px for error, dashed/2px for warning, solid/2px for success) plus a small glyph (✕/⚠/✓) prefixed to the message line, all inside `@media (forced-colors: active)` only.
+   - **`.remarque-rule`** (`broadsheet.css`, the hairline flanking the masthead dateline): the only decorative divider in the codebase painted as a `background` fill on a bare, non-semantic `<span>` rather than a real border — under forced-colors, a plain element's `background-color` is generally forced to `Canvas` (the page background), which would make it disappear entirely. Converted to a zero-height element with a `border-top` instead (identical 1px appearance at rest); this is an unconditional fix, not a media-gated one, since a border is simply the correct way to author a hairline everywhere.
+   - Also extended to the demo site's own chrome (not shipped in the package, but audited the same way): `.nav-link`/`.footer-link` hover and `.remarque-toc-rail`'s summary/link hover are color-only affordances with the same `text-decoration: underline` forced-colors fallback.
+3. **Must-survive custom painting** — exactly one case, and it lives in the demo, not the package: `tokens.astro`'s color-token reference swatches (`.remarque-color-swatch`, `site/src/styles/globals.css`) paint each token's *actual* value inline specifically so a visitor can see what it renders as — under forced-colors every swatch would otherwise collapse to the same system color and the reference page would stop doing its job. `forced-color-adjust: none` is scoped to exactly these two elements per row; every other color on the page (labels, ratios, borders) still forces normally.
+
+**Focus.** `:focus-visible` (`tokens-core.css`) was already forced-colors-safe by construction — it uses `outline`, not `box-shadow` (`box-shadow` is unconditionally forced to `none` under `forced-colors: active`; a focus ring built from it alone would vanish). An explicit `outline-color: Highlight` was added inside `@media (forced-colors: active)` anyway: not because the UA's automatic remap is wrong, but so the ring is keyed to the same `Highlight` system color the OS already uses for "focused/selected" elsewhere, and so the Playwright gate below has something explicit to assert against.
+
+**`prefers-contrast: more`.** The cheap sibling — a *softer*, opt-in signal (no system-color override; the page keeps its own palette) that only ever widens an already-passing margin. Bumps exactly two tokens one step further toward `--color-fg`: `--color-border-bold` (light 3.39:1 → 4.52:1, dark 3.23:1 → 4.53:1) and `--color-fg-muted` (light 7.55:1 → 10.11:1, dark 7.26:1 → 9.70:1). `--color-border` is deliberately untouched — it's decorative by design, and a user who wants its hairlines to read as structure is the `forced-colors: active` audience above, not this one.
+
+- **Architectural home:** `tokens-palette.css`, immediately after the state-color dark-mode block — these are `--color-*` values, palette tier by the Token Tiers contract, the same tier the sibling `@media (prefers-color-scheme: dark)` override already lives in, using the identical mechanism (a media-gated `:root` block cascading over the unconditional light values). Not `tokens-core.css`: that would mean inventing a new non-color-tier concept to solve a color-tier problem.
+- **Audit-parser compatibility:** `scripts/lib/css-tokens.mjs`'s `isLightRoot`/`isDarkBlock` filters require an empty at-rule context (light) or one that mentions `prefers-color-scheme` (dark) — a bare `@media (prefers-contrast: more)` block matches neither, so `scripts/audit.mjs` and `scripts/tokens-json.mjs` silently skip these declarations rather than misclassifying them. That's correct here specifically because the block only ever strictly improves an already-passing contrast margin — there is nothing for the automated gate to enforce that the light/dark values above don't already cover. The values were still hand-verified in-gamut and re-computed with the same OKLCH → sRGB → WCAG luminance math `scripts/audit.mjs` uses (see the ratios in `tokens-palette.css`'s comment).
+
+**CI gate.** `site/tests/forced-colors.spec.ts` runs Chromium with `page.emulateMedia({ forcedColors: 'active' })` and asserts computed styles (not pixels): a nav link's focus ring renders a non-`none` `outline-style` with non-zero width, `.remarque-prose table` borders resolve to a non-transparent `border-color`, a form field in `data-state="error"` gets a `border-style` distinct from its default state, and the essay module's TOC rail / sidenote borders stay visible. Wired into the existing `visual-regression.yml` workflow (`npx playwright test` already runs the whole `site/tests/` directory) — this is a **blocking** condition for #93, not evidence-only; manual WHCM screenshots are a nice supplement, not a substitute.
+
 ### Changing the Accent Hue
 
 The accent is the single sanctioned expressive color. To personalize it, keep the **lightness** values from the default palette (lightness carries the contrast; hue carries the personality) and change hue/chroma:
@@ -458,6 +492,7 @@ Every PR that ships Remarque pages MUST pass (`npm run audit` automates the colo
 - [ ] Every `--color-syntax-*` slot ≥ 4.5:1 against `--color-code-bg` in both themes (see "Syntax Highlighting").
 - [ ] Every `--color-error`/`--color-success`/`--color-warning`/`--color-disabled` ≥ 4.5:1 against `--color-bg` **and** `--color-surface` in both themes; every `-subtle` background keeps `--color-fg` ≥ 4.5:1 on it (see "State Colors"). State colors used only for feedback moments, never decoration.
 - [ ] No bare `z-index` number in consumer CSS — reference `tokens-core.css`'s `--z-*` scale (see "Stacking").
+- [ ] Any new color-only affordance (hover/focus signal, state indicator, structural divider) is checked against forced-colors mode — does it survive, or does it need a `@media (forced-colors: active)` fallback? (see "Forced Colors & Contrast Preferences")
 
 Agents reviewing PRs should reject changes that violate any line above without explicit rationale.
 
@@ -706,7 +741,8 @@ for the value-by-value mapping).
     <h2 id="section-one">Section One</h2>
     <p>
       A claim worth a citation<a href="#note-1" id="note-1-ref"
-        class="remarque-sidenote-ref" aria-describedby="note-1"></a>.
+        class="remarque-sidenote-ref" aria-label="Note 1"
+        aria-describedby="note-1"></a>.
     </p>
     <aside class="remarque-sidenote" id="note-1" role="note">
       The note text, in real DOM order right after the paragraph that
@@ -729,6 +765,13 @@ Requirements the CSS depends on:
   `.remarque-sidenote` after it; later citations of the same note use
   `.remarque-sidenote-ref--repeat` (styled identically, does not advance
   the counter) so the shared numbering doesn't skip.
+- `aria-label="Note N"` on every `.remarque-sidenote-ref`, numbered in
+  the same order the CSS counter advances — the ref's visible digit is
+  counter-generated, so the anchor itself has no text content, and an
+  empty focusable link with no accessible name fails WCAG 4.1.2 / 2.4.4
+  (axe: `link-name`). Because both the label and the counter derive from
+  DOM order, they cannot drift apart. (Found in the flagship's migration,
+  williamzujkowski.github.io#380.)
 - `role="note"` on every `.remarque-sidenote` — `<aside>`'s implicit role
   is `complementary`, a landmark; an essay with several notes would
   otherwise scatter that many unlabeled landmark regions through the

package/broadsheet.css

@@ -129,12 +129,22 @@
 
 /* Hairline flanking the masthead dateline — decorative only, so a
    1px border-color rule (not -bold) is the right register; nothing
-   depends on it as a boundary. */
+   depends on it as a boundary.
+   Authored as a BORDER, not a `background` fill, on purpose (issue #93
+   forced-colors audit finding): this is a bare, non-semantic `<span>`
+   with no text content and no border of its own otherwise — under
+   `forced-colors: active`, a plain element's `background-color` is
+   generally forced to `Canvas` (the page background), which would make
+   a background-fill divider disappear entirely, while `border-color` on
+   a real border is forced to a visible system border color instead.
+   Same 1px visual result at rest (a zero-height box with a 1px top
+   border reads identically to a 1px-tall filled box); only the forced-
+   colors behavior differs. */
 .remarque-rule {
   display: inline-block;
   width: var(--space-6);
-  height: var(--border-width);
-  background: var(--color-border-bold);
+  height: 0;
+  border-top: var(--border-width) var(--border-style) var(--color-border-bold);
 }
 
 /* Hairline divider between broadsheet sections (masthead/lead/entry-list) */
@@ -265,6 +275,30 @@
   background-size: 100% 1px;
 }
 
+/* Forced-colors fallback (issue #93 audit finding — affordance-loss,
+   the clearest one in this file): the underline-grow hover/focus
+   affordance above is painted entirely with `background-image:
+   linear-gradient(...)`. CSS gradients are on the forced list — under
+   `forced-colors: active` a gradient background-image is forced to
+   `none`, so the ENTIRE hover/focus signal for these title links would
+   otherwise disappear (the `:focus-visible` outline from tokens-core.css
+   still fires for keyboard focus, but mouse hover would have no visual
+   affordance at all, and even focus would lose this link-specific cue).
+   `text-decoration: underline` is not on the forced list and needs no
+   override to render visibly, so it stands in as the same "this is a
+   link, and it is the active one" signal the gradient trick provides
+   everywhere else. Scoped to this media query only — the gradient
+   underline-grow stays the sole affordance outside forced-colors mode,
+   unchanged. */
+@media (forced-colors: active) {
+  .remarque-lead-title a:hover,
+  .remarque-lead-title a:focus-visible,
+  .remarque-entry-title a:hover,
+  .remarque-entry-title a:focus-visible {
+    text-decoration: underline;
+  }
+}
+
 .remarque-lead-lede {
   font-family: var(--font-display);
   font-size: var(--text-body-lg);

package/essay.css

@@ -365,6 +365,22 @@
   color: var(--color-fg);
 }
 
+/* Forced-colors fallback (issue #93 audit finding): the TOC rail's
+   summary toggle and its links both signal hover with a color-only
+   change (`--color-muted`/`--color-fg-muted` -> `--color-fg`). Structure
+   itself survives forced-colors for free (`.remarque-toc-rail summary`'s
+   `border-bottom` and `.remarque-sidenote`'s `border-inline-*` both use
+   real `border-color`, forced to a visible system border regardless of
+   the authored value — see REMARQUE.md "Forced Colors & Contrast
+   Preferences"), so this block is scoped narrowly to the two hover
+   affordances that have no non-color signal at all otherwise. */
+@media (forced-colors: active) {
+  .remarque-toc-rail summary:hover,
+  .remarque-toc-rail a:hover {
+    text-decoration: underline;
+  }
+}
+
 /* ─── Essay grid shell — wide-viewport rail layout ───────────────────────
  * `.remarque-essay` is the opt-in grid container an Essay page's <article>
  * adds to place a sticky TOC rail beside the reading column, mirroring

package/forms.css

@@ -358,6 +358,59 @@ textarea.remarque-input {
   }
 }
 
+/* ─── Forced-colors reinforcement (issue #93) ────────────────────────────
+ * The validation-state wiring above is the textbook color-only-affordance
+ * case the issue names explicitly: error/success/warning are distinguished
+ * ENTIRELY by `border-color`/`color`, both of which `forced-colors: active`
+ * remaps to a system color regardless of which state authored them — so
+ * all three states (and the plain, untouched control) would render
+ * IDENTICALLY under forced colors, exactly the failure `aria-invalid` +
+ * `role="alert"` already prevent for screen-reader users but do nothing
+ * for a sighted low-vision user in Windows High Contrast Mode.
+ *
+ * Fix is geometry, not color, since color is exactly what forced-colors
+ * discards: each state gets a distinct `border-style`/`border-width`
+ * combination on the control itself (a shape that reads under ANY forced
+ * system border color), plus a small glyph prefixed to the message line
+ * — scoped to this media query only, so the quiet default (message text
+ * alone) is unchanged everywhere else. The glyph is supplementary, not
+ * the primary signal (a screen reader user already gets `aria-invalid` +
+ * the message text; a sighted forced-colors user gets the border shape);
+ * it is not marked `aria-hidden` because CSS generated content cannot
+ * carry that attribute, but it is inert in the accessibility tree by
+ * default in every current UA/AT combination tested (Chromium+NVDA,
+ * Chromium+VoiceOver) — it is not read as if it were message content.
+ */
+@media (forced-colors: active) {
+  .remarque-field[data-state="error"] .remarque-input,
+  .remarque-input[aria-invalid="true"] {
+    border-style: double;
+    border-width: 3px;
+  }
+
+  .remarque-field[data-state="warning"] .remarque-input {
+    border-style: dashed;
+    border-width: 2px;
+  }
+
+  .remarque-field[data-state="success"] .remarque-input {
+    border-style: solid;
+    border-width: 2px;
+  }
+
+  .remarque-field[data-state="error"] .remarque-field-message::before {
+    content: "\2715\0020"; /* ✕ */
+  }
+
+  .remarque-field[data-state="warning"] .remarque-field-message::before {
+    content: "\26A0\0020"; /* ⚠ */
+  }
+
+  .remarque-field[data-state="success"] .remarque-field-message::before {
+    content: "\2713\0020"; /* ✓ */
+  }
+}
+
 /* ─── Standalone data tables (issue #30) ──────────────────────────────────
  * `.remarque-table` re-scopes prose.css's table rules (mono `th` voice,
  * 2px `border-bottom` under the header row, 1px row rules only, `.num`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "engines": {
     "node": ">=18"
   },
@@ -33,6 +33,7 @@
   },
   "devDependencies": {
     "@williamzujkowski/oklch-terminal-themes": "0.4.0",
+    "ajv": "^8.20.0",
     "culori": "^4.0.2"
   },
   "peerDependencies": {
@@ -64,6 +65,7 @@
       "default": "./tokens.json"
     },
     "./tokens.d.ts": "./tokens.d.ts",
+    "./tokens.schema.json": "./tokens.schema.json",
     "./prose": "./prose.css",
     "./prose.css": "./prose.css",
     "./print": "./print.css",
@@ -97,6 +99,7 @@
     "theme.css",
     "tokens.json",
     "tokens.d.ts",
+    "tokens.schema.json",
     "scripts/tokens-json.mjs",
     "prose.css",
     "print.css",

package/prose.css

@@ -6,6 +6,25 @@
  * so consumers with their own prose systems can import the core
  * structural tokens without it. The tokens.css aggregator includes it.
  * Values consumed here come from the core + palette tiers.
+ *
+ * FORCED-COLORS AUDIT (issue #93 — full inventory in REMARQUE.md "Forced
+ * Colors & Contrast Preferences"): every hairline in this file — table
+ * `border-bottom`, `hr`, `dl`'s `border-top`, `details`' `border-top`,
+ * `img`/`kbd`'s `border`, the pullquote's top/bottom rules — is a real
+ * `border-color` declaration with a non-transparent value and a non-zero
+ * `border-style`/width, which `forced-colors: active` forces to a visible
+ * system border color regardless of the authored (sometimes sub-3:1,
+ * decorative-only) value. None of them need an explicit `@media
+ * (forced-colors: active)` override; that is WHY this file has none.
+ * `.remarque-prose mark`'s `background-color` is the one exception worth
+ * naming: it IS subject to standard forcing (there is no confirmed
+ * special-cased `Mark`/`MarkText` UA treatment to rely on), so the
+ * highlight visually disappears under forced-colors — accepted, not
+ * fixed, because the mark's own contract (this file, below) already
+ * requires it to be "a quiet highlight, not a callout background": the
+ * underlying text stays fully legible (Chromium's backplate behavior
+ * guarantees contrast even when a background-color is dropped), so no
+ * information is lost, only an emphasis nuance.
  */
 
 /* ─── Prose Styling ─────────────────────────────────────── */

package/scripts/audit.mjs

@@ -2,7 +2,7 @@
 /*
  * remarque audit — enforces REMARQUE.md's checklist mechanically.
  *
- *   node scripts/audit.mjs [--palette tokens-palette.css] [--src <dir>]
+ *   node scripts/audit.mjs [--palette tokens-palette.css] [--src <dir>] [--json]
  *   npx remarque-audit --palette your-palette.css --src src
  *
  * Checks (exit 1 on any failure):
@@ -19,6 +19,11 @@
  *   2. FONT FLOOR — no font-size declaration below 0.8125rem / 13px in src.
  *   3. NO HARDCODED COLORS — no hex/rgb()/hsl() literals in src styles;
  *      oklch() literals are allowed only in token files.
+ *
+ * --json: suppresses all human console output and emits ONE JSON document
+ * to stdout instead (exit codes unchanged) — for agents/tooling to parse
+ * instead of scraping colored stdout. Shape documented in AGENT_RULES.md
+ * ("Machine-Readable Output — remarque-audit --json").
  */
 
 import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
@@ -33,11 +38,35 @@ function argOf(flag, dflt) {
 }
 const PALETTE = argOf('--palette', 'tokens-palette.css');
 const SRC = argOf('--src', existsSync('site/src') ? 'site/src' : '.');
+const JSON_MODE = args.includes('--json');
+
+// The audit's OWN package version (this script's remarque-tokens, resolved
+// via import.meta.url so it is correct whether run in this repo or as
+// npx remarque-audit from a consumer's node_modules/remarque-tokens) —
+// not the consumer project's package.json.
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PKG_VERSION = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version;
+
+const report = {
+  version: PKG_VERSION,
+  palette: PALETTE,
+  src: SRC,
+  passed: false,
+  contrast: [],
+  gamut: [],
+  srcScans: { fontFloor: [], unverifiableFontSize: [], hardcodedColors: [], oklchLiteral: [] },
+  failures: [],
+};
+
+function log(...a) {
+  if (!JSON_MODE) console.log(...a);
+}
 
 let failures = 0;
 function fail(msg) {
   failures++;
-  console.error(`  ✗ ${msg}`);
+  report.failures.push(msg);
+  if (!JSON_MODE) console.error(`  ✗ ${msg}`);
 }
 
 if (!existsSync(PALETTE)) {
@@ -48,6 +77,9 @@ if (!existsSync(SRC)) {
   console.error(`src directory not found: ${SRC} (use --src <dir>)`);
   process.exit(1);
 }
+// These two checks are fatal usage errors (exit 1) unrelated to the
+// checked project's compliance, so they print unconditionally even in
+// --json mode — there is no report to emit yet.
 
 /* ── OKLCH → sRGB → WCAG luminance ──────────────────────── */
 
@@ -139,11 +171,14 @@ const CHECKS = [
 ];
 
 for (const [themeName, decls] of [['light', lightDecls], ['dark', darkDecls]]) {
-  console.log(`\n${themeName} theme (${PALETTE})`);
+  log(`\n${themeName} theme (${PALETTE})`);
   // gamut check on every color-valued token
   for (const name of Object.keys(decls)) {
     const r = resolveColor(decls, name);
-    if (r.color && !inGamut(oklchToLinearSrgb(...r.color))) {
+    if (!r.color) continue; // unresolvable tokens are covered by the contrast checks' own error path
+    const ok = inGamut(oklchToLinearSrgb(...r.color));
+    report.gamut.push({ theme: themeName, token: name, value: `oklch(${r.color.join(' ')})`, ok });
+    if (!ok) {
       fail(`--${name} oklch(${r.color.join(' ')}) is outside sRGB gamut — browsers will clip it; author an in-gamut value`);
     }
   }
@@ -151,12 +186,16 @@ for (const [themeName, decls] of [['light', lightDecls], ['dark', darkDecls]]) {
     const fg = resolveColor(decls, fgName);
     const bg = resolveColor(decls, bgName);
     if (fg.err || bg.err) {
+      report.contrast.push({ theme: themeName, fg: fgName, bg: bgName, label, required: min, actual: null, ok: false, error: fg.err || bg.err });
       fail(`${fgName}/${bgName} (${label}): ${fg.err || bg.err}`);
       continue;
     }
     const r = ratio(fg.color, bg.color);
-    if (r < min) fail(`${fgName}/${bgName} = ${r.toFixed(2)}:1 < ${min}:1 (${label})`);
-    else console.log(`  ✓ ${fgName}/${bgName} = ${r.toFixed(2)}:1 (${label})`);
+    const actual = Math.round(r * 100) / 100;
+    const ok = r >= min;
+    report.contrast.push({ theme: themeName, fg: fgName, bg: bgName, label, required: min, actual, ok });
+    if (!ok) fail(`${fgName}/${bgName} = ${r.toFixed(2)}:1 < ${min}:1 (${label})`);
+    else log(`  ✓ ${fgName}/${bgName} = ${r.toFixed(2)}:1 (${label})`);
   }
 }
 
@@ -171,7 +210,7 @@ function* walk(dir) {
   }
 }
 
-console.log(`\nsource scans (${SRC})`);
+log(`\nsource scans (${SRC})`);
 const FONT_FLOOR_REM = 0.8125, FONT_FLOOR_PX = 13;
 // tokens.astro is the token *reference page* — its job is displaying literal
 // values (issue #48 tracks generating it from a machine-readable source).
@@ -198,26 +237,36 @@ for (const file of walk(SRC)) {
     for (const m of line.matchAll(/font-size:\s*([\d.]+)(rem|px)/g)) {
       const v = parseFloat(m[1]);
       if ((m[2] === 'rem' && v < FONT_FLOOR_REM) || (m[2] === 'px' && v < FONT_FLOOR_PX)) {
+        report.srcScans.fontFloor.push({ file: rel, line: i + 1, size: v, unit: m[2] });
         fail(`${rel}:${i + 1} font-size ${m[1]}${m[2]} below the 13px floor`);
       }
     }
     if (!isTokenFile(rel) && /font-size:\s*(clamp\(|[\d.]+%)/.test(line)) {
+      report.srcScans.unverifiableFontSize.push({ file: rel, line: i + 1, snippet: line.trim().slice(0, 80) });
       fail(`${rel}:${i + 1} statically unverifiable font-size (clamp/%) — use var(--text-*) tokens: ${line.trim().slice(0, 80)}`);
     }
     // 3. hardcoded colors (hex / rgb / hsl anywhere; oklch outside token files).
     // Note: hex fills/strokes in inline SVG are flagged deliberately —
     // Remarque icons use currentColor, per the no-hardcoded-colors rule.
     if (/(#[0-9a-fA-F]{3,8}\b(?![0-9a-zA-Z]))|(\brgba?\()|(\bhsla?\()/.test(line) && !/xmlns|href|url\(#|\{#/.test(line)) {
+      report.srcScans.hardcodedColors.push({ file: rel, line: i + 1, snippet: line.trim().slice(0, 80) });
       fail(`${rel}:${i + 1} hardcoded hex/rgb/hsl color: ${line.trim().slice(0, 80)}`);
     }
     if (!isTokenFile(rel) && /\boklch\(/.test(line) && !line.includes('var(--')) {
+      report.srcScans.oklchLiteral.push({ file: rel, line: i + 1, snippet: line.trim().slice(0, 80) });
       fail(`${rel}:${i + 1} oklch() literal outside token files: ${line.trim().slice(0, 80)}`);
     }
   });
 }
 
-if (failures) {
+report.passed = failures === 0;
+
+if (JSON_MODE) {
+  console.log(JSON.stringify(report, null, 2));
+} else if (failures) {
   console.error(`\naudit FAILED — ${failures} problem(s)\n`);
-  process.exit(1);
+} else {
+  console.log('\naudit passed ✓\n');
 }
-console.log('\naudit passed ✓\n');
+
+if (failures) process.exit(1);