remarque-tokens 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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).

package/REMARQUE.md

@@ -445,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:
@@ -469,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.
 

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.20.0",
+  "version": "0.21.0",
   "engines": {
     "node": ">=18"
   },

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/lib/css-tokens.mjs

@@ -68,8 +68,30 @@ export const isLightRoot = (b) =>
    class-convention :root.dark / html.dark (compatibility bridge). A scoped
    deck palette's dark block ([data-palette="name"][data-theme="dark"])
    already matches unchanged: DARKISH finds the [data-theme="dark"]
-   substring, and the selector starts with "[". */
+   substring, and the selector starts with "[".
+   Both recognition paths are CONTEXT-EXACT (issue #93 fix): a block only
+   counts as "the" dark override when its enclosing at-rule is either
+   absent (top-level) or is the plain, non-compounded `@media
+   (prefers-color-scheme: dark)` query — not some unrelated or compounded
+   at-rule (`@media print`, `@media (prefers-contrast: more)`, `@media
+   (prefers-contrast: more) and (prefers-color-scheme: dark)`, ...) that
+   merely happens to reuse the same selector text or mention the same
+   media-feature name. Before this guard, substring matching on `context`
+   (`.includes('prefers-color-scheme')`) and on `prelude` (DARKISH, with
+   no context check at all) meant ANY nested reuse of `[data-theme=
+   "dark"]`/`:root.dark`, or any compound query merely containing
+   `prefers-color-scheme: dark` as one of several conditions, was
+   misread as an unconditional dark value — silently clobbering the real
+   one (`declsOf` last-write-wins). tokens-palette.css's `@media
+   (prefers-contrast: more)` block is the case that surfaced this: it
+   deliberately reuses the `[data-theme="dark"], :root.dark` selector,
+   scoped to a NARROWER condition, and must NOT be read as redefining
+   dark mode itself. */
+const isPlainDarkSchemeMedia = (context) =>
+  /^@media\s*\(\s*prefers-color-scheme\s*:\s*dark\s*\)$/.test(context.trim());
+
 export const isDarkBlock = (b) =>
-  (b.context.includes('prefers-color-scheme') && b.context.includes('dark') &&
+  (isPlainDarkSchemeMedia(b.context) &&
     parts(b.prelude).some((s) => ROOTISH.test(s) && !DARKISH.test(s))) ||
-  parts(b.prelude).some((s) => DARKISH.test(s) && (ROOTISH.test(s) || s.startsWith('.') || s.startsWith('[')));
+  (b.context === '' &&
+    parts(b.prelude).some((s) => DARKISH.test(s) && (ROOTISH.test(s) || s.startsWith('.') || s.startsWith('['))));

package/tokens-core.css

@@ -247,3 +247,39 @@ html {
   border-radius: var(--radius-sm);
   transition: outline-color var(--motion-fast) var(--motion-easing);
 }
+
+/* ─── Forced Colors (Windows High Contrast Mode) ────────────
+ * Issue #93 — see REMARQUE.md "Forced Colors & Contrast Preferences" for
+ * the full site-wide audit; this block covers only what tokens-core.css
+ * itself is responsible for (focus + selection), which is why it is
+ * SHORT: most of Remarque's structural borders (prose/essay/broadsheet
+ * hairlines) already render correctly for free — `forced-colors: active`
+ * forces any non-transparent, non-zero-width `border-color` to a system
+ * border color regardless of the sub-3:1 authored value, so `--color-
+ * border`'s decorative-only hairlines stand in as real system-color
+ * rules exactly where they need to.
+ *
+ * Focus (WCAG 2.4.7 / 2.4.11): `outline` (not `box-shadow`) is the
+ * forced-colors-safe mechanism — `box-shadow` is unconditionally
+ * suppressed under forced-colors, so a focus indicator built from it
+ * alone would vanish entirely; `outline-style`/`outline-width` survive
+ * (only `outline-color` is remapped to a system color), so the
+ * `:focus-visible` rule above was already compliant by construction.
+ * This rule is a defensive, explicit restatement — pinning to the
+ * `Highlight` system color keyword rather than trusting the UA's
+ * default remap of our `--color-focus-ring` value keeps the ring keyed
+ * to the SAME system color users already recognize as "focused/
+ * selected" elsewhere in their OS, and gives the Playwright forced-
+ * colors gate (site/tests/forced-colors.spec.ts) something explicit to
+ * assert against rather than an implementation-defined remap. */
+@media (forced-colors: active) {
+  :focus-visible {
+    outline-color: Highlight;
+  }
+
+  /* `::selection`'s `background-color`/`color` are themselves on the
+     forced list (mapped to `Highlight`/`HighlightText` automatically,
+     same as any native text selection) — no override needed here; kept
+     as a comment, not a rule, so a future reader doesn't wonder whether
+     selection was audited (it was — see the inventory in REMARQUE.md). */
+}

package/tokens-palette.css

@@ -228,3 +228,69 @@
   --color-warning-subtle: oklch(0.22 0.04 85);
   --color-disabled:       var(--color-muted);
 }
+
+/* ─── prefers-contrast: more ────────────────────────────────
+ * Issue #93 — the cheap sibling of the forced-colors pass (see
+ * REMARQUE.md "Forced Colors & Contrast Preferences"). `prefers-
+ * contrast: more` is a SOFTER, opt-in signal than `forced-colors:
+ * active` (no system-color override — the page keeps painting its own
+ * palette) so the fix is proportionate: bump the two tokens the audit
+ * already treats as "read at a distance" thresholds — `--color-border-
+ * bold` (WCAG 1.4.11's 3:1 non-text floor) and `--color-fg-muted`
+ * (the AAA 7:1 secondary-text floor) — one step further toward
+ * `--color-fg`, not a second palette. `--color-border` stays untouched:
+ * it is decorative BY DESIGN (documented sub-3:1), and `prefers-
+ * contrast` users who want its 1.34:1 hairlines to read as structure
+ * are exactly the `forced-colors: active` audience already covered
+ * above — conflating the two would blur why each exists.
+ *
+ * ARCHITECTURAL HOME: tokens-palette.css, not tokens-core.css. These are
+ * `--color-*` values — palette tier by the Token Tiers contract, the
+ * same tier that already carries the `@media (prefers-color-scheme:
+ * dark)` override immediately above using the identical mechanism (a
+ * media-gated `:root` block cascading over the unconditional light
+ * values). A `prefers-contrast` override belongs wherever its sibling
+ * `prefers-color-scheme` override already lives, not in core, which
+ * would first require inventing a NEW non-color-tier concept for a
+ * color-tier problem.
+ *
+ * AUDIT-PARSER COMPATIBILITY (scripts/lib/css-tokens.mjs): a plain
+ * `@media (prefers-contrast: more)` block does not match `isLightRoot`
+ * (which requires `context === ''`, i.e. no enclosing at-rule at all)
+ * or `isDarkBlock` (which requires the context to mention
+ * `prefers-color-scheme`) — so `scripts/audit.mjs` and `scripts/
+ * tokens-json.mjs` both silently SKIP these declarations rather than
+ * misclassifying them as light or dark base values. That is the
+ * correct behavior (verified 2026-07 against the current parser): this
+ * block only ever WIDENS an already-passing contrast margin, so it has
+ * nothing to gate on — the light/dark values above remain the ones CI
+ * enforces, and a `prefers-contrast: more` visitor only ever sees a
+ * result that is contrast-equal-or-better. Values below are still
+ * hand-verified in-gamut and re-computed against the same OKLCH → sRGB
+ * → WCAG luminance math `scripts/audit.mjs` uses (see the ratios in
+ * each comment) — just not by the automated gate, since there is
+ * nothing to gate on the fact that this is a strictly-improving branch.
+ */
+@media (prefers-contrast: more) {
+  :root {
+    --color-border-bold: oklch(0.55 0.01 80);  /* 3.39:1 -> 4.52:1 on bg */
+    --color-fg-muted:     oklch(0.36 0.015 80); /* 7.55:1 -> 10.11:1 on bg (9.82:1 on surface) */
+  }
+
+  [data-theme="dark"],
+  :root.dark {
+    --color-border-bold: oklch(0.58 0.01 80);  /* 3.23:1 -> 4.53:1 on bg */
+    --color-fg-muted:     oklch(0.78 0.01 80);  /* 7.26:1 -> 9.70:1 on bg (9.22:1 on surface) */
+  }
+}
+
+/* System dark preference (no explicit [data-theme] toggle set) needs its
+   own compound query — mirrors the plain dark-mode block's split between
+   `@media (prefers-color-scheme: dark)` and the `[data-theme="dark"]` /
+   `:root.dark` bridge above. */
+@media (prefers-contrast: more) and (prefers-color-scheme: dark) {
+  :root {
+    --color-border-bold: oklch(0.58 0.01 80);
+    --color-fg-muted:     oklch(0.78 0.01 80);
+  }
+}

package/tokens.d.ts

@@ -1,6 +1,6 @@
 /*
  * Remarque design tokens — GENERATED from tokens.json by
- * scripts/tokens-json.mjs (v0.20.0). Do not edit — the CSS
+ * scripts/tokens-json.mjs (v0.21.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

package/tokens.json

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