# Color-Scheme Accessibility Rules (scheme-a11y, epic #2489; re-grounded for the Color Ramp Restructure #2584/#2602) **IMPORTANT — this is the executable spec.** An agent tweaking a ramp or a scheme's `map` must be able to produce correct edits from **this document + `pnpm contrast:audit` output alone**. Every rule here is concrete. When in doubt, the AA text floor wins. zudo-doc ships **two color schemes** — `Default Light` and `Default Dark` — defined in `packages/zudo-doc/src/color-schemes-defaults/index.ts` (package-owned since the minimal-scaffold cutover, epic zudolab/zudo-doc#2651, Wave 6 #2661 — the former host copy, `src/config/color-schemes.ts`, was byte-identical to this and deleted; both the showcase and every `create-zudo-doc` project ride this package default unless they pass a `colorSchemes` override to `zudoDoc({...})`). A `ColorScheme` is `{ ramps, map }`: both schemes **share** one set of Tier-1 ramps (`base` — 5 stops, `accent` — 3 stops, `state` — 4 named colors: `danger`/`success`/`warning`/`info`) and differ only in their per-mode `map` (which ramp stop, or literal OKLCH override, each of the 4 base roles + 23 semantic roles points at). **This file is the single canonical color surface** — do NOT touch e2e fixtures (`e2e/fixtures/*/src/config/…`), which carry unguarded hex copies by design. <Note> **History.** An earlier iteration of this project (epic #2489/#2510) shipped 52 schemes — the 2 defaults above plus **50 ghostty-sourced ANSI terminal presets** in a since-deleted `src/config/color-tweak-presets.ts`, loaded live via a zdtp "Scheme…" dropdown. The Color Ramp Restructure (epic #2584, minimized in #2602) **deleted the preset file and the dropdown** — the ramps themselves are now the editable surface, via zdtp's **Palette** tab curve editor. Most of this skill's original content concerned deriving `semantic` overrides for those 50 ANSI-convention presets (`p8`–`p15` bright-variant mismatches); that recipe no longer applies to anything currently in the codebase and has been removed below. What remains is the contrast-pair matrix and OKLCH tuning methodology, re-grounded in the 2 current schemes. </Note> Both schemes currently **pass the full matrix with an empty allowlist** (`pnpm contrast:audit` → 25/25 pairs PASS for each). Keep it that way: a new allowlist entry is a last resort, not a starting point (§2.3). ## 1. The pair matrix + thresholds How a color renders decides its threshold: **text ≥ 4.5:1 (AA normal text), non-text graphics/UI ≥ 3.0:1 (WCAG 1.4.11).** Every pair below was verified to render as **text** somewhere in the product — evidence cited. AA text floors are **non-negotiable**; a pair drops to Tier 2 only with proof it never renders as text. The matrix is data-driven and lives in `scripts/contrast-pair-matrix.ts` (`PAIR_MATRIX`/`evaluateScheme`) — shared by `scripts/contrast-audit.ts` (the CLI), `scripts/contrast-suggest.ts` (--suggest derivation), and `src/config/__tests__/contrast.test.ts` (the vitest guard) so this skill, the audit tool, and the test can never drift. Resolve every pair through the package resolvers (`resolveSemanticColors` / `schemeToCssPairs` in `@takazudo/zudo-doc/color-scheme-utils`) — the same path production uses. Admonition backgrounds are `color-mix(in srgb, 12%, var(--color-bg))` (`packages/zudo-doc/src/content.css`). The **"Default ramp ref"** column is `SEMANTIC_RAMP_DEFAULTS` (`surface: { base: 4 }`, `muted: { base: 1 }`, `accent: { accent: 1 }`, `codeBg: { base: 3 }`, `codeFg: { base: 0 }`, …) — the Default Dark reference wiring. Default Light re-points several roles to a different ramp stop, and several roles on **both** schemes carry a **per-mode literal OKLCH override** instead of a ramp ref (an AA tune that only one mode needs) — see §1.1. ### Tier 1 — text, AA ≥ 4.5:1 | Pair (fg / bg) | Default ramp ref | Renders as text — evidence | Threshold | |---|---|---|---| | `fg` / `bg` | fg=`{base:0}`, bg=`{base:4}` | Body copy; `--zd-fg` on `--zd-bg`. `schemeToCssPairs` → `--zd-fg`/`--zd-bg`. | 4.5 | | `fg` / `surface` | surface=`{base:4}` (= `bg`) | Text on elevated panels: footer `bg-surface` (`packages/zudo-doc/src/footer/footer.tsx:89`), toolbar `bg-surface` (`…/doclayout/doc-layout-with-defaults.tsx:367`), dropdown/dialog panels (`…/i18n-version/version-switcher.tsx:216`, `…/island-types/index.ts:78`). | 4.5 | | `muted` / `bg` | muted=`{base:1}` | **Secondary body text** — blockquote body `text-muted italic` (`…/content/content-blockquote.tsx:11`), footer text (`footer.tsx:84,116,144`), TOC inactive links (`…/toc/toc.tsx:102`, `…/toc/mobile-toc.tsx:122`), doc-pager labels (`…/doc-pager/index.tsx:59`), `li::marker` (`content.css:163`), code-block title (`features.css:228`). Dual-role — see §3. **Multi-bg — see the three rows below (#2510).** | 4.5 | | `muted` / `surface` | muted=`{base:1}`, surface=`{base:4}` | Muted text on the **elevated surface** chrome: footer link/tag columns `text-muted` on the `