@halftone-ds/tokens 1.1.0 → 1.3.0

package/README.md

@@ -2,12 +2,13 @@
 
 The token build behind [Halftone](https://github.com/itsHendri/halftone). One `tokens.json` in the
 [W3C design-token format](https://www.designtokens.org/tr/2025.10/format/) becomes everything an app reads,
-and the build refuses any palette that falls below WCAG AA.
+and every build checks the palette against WCAG AA.
 
 ```bash
 npm install -D @halftone-ds/tokens
 npx halftone-tokens build      # write every output in tokens/tokens.config.json
 npx halftone-tokens check      # write nothing; exit 1 if an output is stale (CI)
+npx halftone-tokens build --strict   # fail on contrast instead of warning (or HALFTONE_STRICT=1)
 npx halftone-tokens figma      # mirror the tokens into Figma Variables
 ```
 
@@ -45,11 +46,90 @@ npx halftone-tokens figma      # mirror the tokens into Figma Variables
 | `llms` | a tokens section for `llms.txt` |
 | `figma` | the input `halftone-tokens figma` pushes to Figma Variables |
 
+## Themes
+
+A theme is a recipe (brand colour, neutral, radius, fonts, icon stroke, depth, density, border, typeset) that
+`theme apply` expands into `tokens.json`, recording it so `theme show` can tell when tokens were edited by hand.
+
+```bash
+npx halftone-tokens theme apply <theme> [--dry-run] [--force]   # write it into tokens.json and rebuild
+npx halftone-tokens theme show [--check]       # the applied theme, and any hand edits since
+npx halftone-tokens theme presets              # the presets and their codes
+npx halftone-tokens theme encode <theme>       # the Halftone code for a theme
+npx halftone-tokens theme decode <code> [--json]   # what a code holds
+npx halftone-tokens theme resolve [--json]     # the code for tokens.json as it is (exit 1 if none or edited)
+npx halftone-tokens theme shadcn <theme> [--out file] [--fonts-url url]   # a shadcn registry:theme item
+```
+
+`<theme>` is a Halftone code (`ht1-…`, `ht2-…`, `ht3-…`), a preset name, a recipe `.json`, a system
+`.halftone.json` (see Systems), or a
+[shadcn/ui](https://ui.shadcn.com/create) preset code (`b5owWMfJ8l`). A shadcn code becomes the nearest Halftone
+recipe, and what it approximates or drops (shadcn-only greys, radius steps, fonts outside the list, icon
+libraries, chart colours, menu options, styles) is listed on stderr. The other way, `theme shadcn` writes the
+theme as a `registry:theme` item for `npx shadcn add`: colours for light and dark, radius, shadows, and its fonts
+as `registry:font` dependencies (hosted at halftonedesignsystem.com/r/font, or `--fonts-url`).
+
+From code: `decodeShadcnPreset`, `recipeFromShadcn`, `shadcnTheme` and `shadcnFont` in
+`@halftone-ds/tokens/theme` (browser-safe). The preset codec is ported from shadcn/ui (MIT).
+
+## Systems
+
+A **system** (`name.halftone.json`, what the Halftone Studio saves) is a recipe plus whatever was edited by hand
+on top of it: a seed per colour role (brand, neutral, danger, success, warning, info) with a 50–950 ramp, steps
+edited by hand, the role mapping for light and dark, text styles (h1–h4, lead, p, large, small, muted, code,
+blockquote), any Google Fonts family, corners, shadows, borders, named extras, component edits (Button, Chip,
+Badge, Input), and the brand (name, logos, icon background).
+
+```bash
+npx halftone-tokens theme apply ./acme.halftone.json   # writes tokens.json and records the system
+npx halftone-tokens theme show                         # the system, its overrides, and any contrast warnings
+npx halftone-tokens theme encode ./acme.halftone.json  # its ht- code, when it has no overrides
+```
+
+- `tokens.json` records the document under `$extensions`, without its brand images. A system with overrides has
+  no `ht-` code: a code only carries a recipe.
+- Generated colours are fixed for contrast as a recipe's are. A colour chosen by hand (a mapped role, an edited
+  step) is never moved: a pairing it fails is a warning.
+- A status ramp from a seed replaces the file's; applying a theme without one puts the curated ramp back.
+- Edited text styles are written as `semantic.type.<style>.{size,leading,weight,tracking,font}`, corners as
+  `semantic.radius.<step>` (the build uses them as fixed px), extras under `extra.*` (exported, not drawn by
+  the kits).
+- Every text style (`h1 h2 h3 h4 lead p large small muted code blockquote`), edited or not, is built as
+  `--type-<style>-{size,leading,weight,tracking}` (plus `-font` on Tailwind 4). nativewind3 adds the `text-`,
+  `leading-`, `tracking-` and `font-type-<style>` keys; shadcn-web adds `type-<style>` utilities; ts-theme adds
+  `TOKENS.textStyles`. With no edits they draw exactly what Tailwind's `text-*` classes did, with one exception:
+  tracking is em on every platform, so on native it scales with the style's size (NativeWind's own `tracking-*`
+  are fixed px there: `tracking-tight` is -0.25px). `themeVars` carries the styles to live previews
+  (`textStyleVars`, `themeTextStyles`).
+- Every theme writes a component layer, `semantic.component.<button|chip|badge|input>`: a corner, heights and
+  padding, a text style and each variant's fill, label, border and pressed colours (references to semantic
+  colours). Both kits read it as `--button-*`, `--chip-*`, `--badge-*` and `--field-*` (`bg-button-primary-bg`,
+  `rounded-chip`, `h-button-md`, `text-type-button` in nativewind3; `type-button` and the same colours in
+  shadcn-web), so a Button looks the same in both. A system's `components` sets any of it (roles by name, a
+  Foundations corner or px). The build's contrast gate checks every variant's label on its fill.
+
+From code (`@halftone-ds/tokens/system`, also in `/theme`, browser-safe): `normalizeSystem` / `validateSystem`,
+`createSystem`, `migrate(recipe | code, brand)` and `systemToRecipe`, `generateSystem(system, tokens)` (the same
+shape as `generateTheme`, plus `warnings`), `systemRamps`, `textStyles`, `systemRadii`, `systemCode` and
+`applySystem`. The document's shape is described in `lib/system/schema.mjs`.
+
 ## Guarantees
 
-- **Contrast gate.** Every `X` / `X-foreground` pairing, body and muted text on every surface, each status
-  colour used as text, and each status icon on its own tint must clear WCAG AA in both themes, or the build
-  fails, names the pairing, prints the ratio, and writes nothing.
+- **Contrast check.** Every `X` / `X-foreground` pairing, body and muted text on every surface, each status
+  colour used as text, and each status icon on its own tint is checked against WCAG AA in both themes. A
+  pairing that falls short is named with its ratio, and the generated DESIGN.md lists it. By default that is a
+  warning and the build carries on; with `--strict` (or `HALFTONE_STRICT=1`) the build fails and writes
+  nothing. The same goes for a tone's text on a tint the palette can't carry, when the config has `scan`.
+- **APCA, for reading only.** `apcaContrast(text, background)` (from `@halftone-ds/tokens/theme` or
+  `@halftone-ds/tokens/lib/apca`) gives the APCA Lc of a pair, and `contrastReport(theme.resolved)` lists every
+  pairing the gate checks, in both themes, with its WCAG ratio, `pass`, and Lc. Lc is advisory: WCAG AA stays
+  the gate, and nothing fails on APCA.
+- **Colour vision, as a warning.** `cvdWarnings(theme.resolved)` (from `@halftone-ds/tokens/theme` or
+  `@halftone-ds/tokens/lib/cvd`) simulates protanopia, deuteranopia and tritanopia (Machado 2009,
+  `simulateCvd`) and lists the status pairs (success / destructive and the rest) and adjacent chart colours
+  that end up closer than OKLab ΔE 0.05 under any of them, or under normal sight. `theme apply` prints them.
+  Nothing fails on it: the kit pairs every status with an icon or a label, and the warning says where colour
+  alone stops doing the work.
 - **Text on tints.** A status colour as text on its own tint (`text-success` on `bg-success/15`) loses
   contrast fast: 4.09:1 with a typical green. The build works out, per colour, the strongest tint that
   still clears AA in both themes, and writes it into `DESIGN.md` and the `llms` section

package/cli.mjs

@@ -2,7 +2,7 @@
 /**
  * halftone-tokens — turns tokens/tokens.json into everything an app reads.
  *
- *   halftone-tokens build    resolve, run the contrast gate, write every target in tokens.config.json
+ *   halftone-tokens build    resolve, check contrast, write every target in tokens.config.json
  *   halftone-tokens check    same, but write nothing; exit 1 if any generated file is stale (CI)
  *   halftone-tokens figma    mirror the tokens into Figma Variables (see push-figma.mjs)
  *   halftone-tokens theme    apply, show or list themes (see lib/theme-cli.mjs)
@@ -10,6 +10,9 @@
  *
  *   --root <dir>        app root (default: cwd); every path in the config is relative to it
  *   --config <file>     default: tokens/tokens.config.json
+ *   --strict            fail (exit 1) on contrast instead of warning; also HALFTONE_STRICT=1 in the environment.
+ *                       Every pairing below WCAG AA, and every tone's text on a tint the palette can't carry, is
+ *                       named either way; Halftone's own kits build strict, so they never ship below AA.
  *
  * tokens.config.json: { "source": "tokens/tokens.json", "targets": { "<target>": { …options } } }
  * Targets live in ./targets/<name>.mjs and return [{ path, contents }]. All outputs are GENERATED —
@@ -19,14 +22,14 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { checkContrast, AA, describeTintLimits, textOnTintLimits } from './lib/contrast.mjs';
+import { checkContrast, AA, componentFailures, describeTintLimits, textOnTintLimits } from './lib/contrast.mjs';
 import { scanTintText } from './lib/scan.mjs';
 import { loadTokens } from './lib/resolve.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 
 /** Flags that take a value; every other --flag is a boolean. */
-const VALUE_FLAGS = new Set(['root', 'config']);
+const VALUE_FLAGS = new Set(['root', 'config', 'out', 'fonts-url']);
 
 function parseArgs(argv) {
   const [command = 'build', ...rest] = argv;
@@ -68,38 +71,54 @@ export async function run(argv = process.argv.slice(2)) {
 
   if (command === 'theme') {
     const { themeCommand } = await import('./lib/theme-cli.mjs');
-    const rebuild = ['build', '--root', root, ...(flags.config ? ['--config', flags.config] : [])];
+    const rebuild = ['build', '--root', root, ...(flags.config ? ['--config', flags.config] : []), ...(flags.strict ? ['--strict'] : [])];
     return themeCommand({ positional, flags, root, sourcePath: join(root, source), config, build: () => run(rebuild) });
   }
   const ctx = await loadTokens(join(root, source));
   ctx.root = root;
   ctx.header = `GENERATED by \`npm run tokens:build\` from ${source} — do not edit by hand.`;
 
-  const failures = checkContrast(ctx.colors, { strict: true });
+  // Contrast is checked on every build. By default a problem is a warning (the palette is the designer's
+  // call); --strict or HALFTONE_STRICT=1 makes it an error, which is how Halftone's own CI builds the kits.
+  const strict = flags.strict === true || /^(1|true)$/i.test(process.env.HALFTONE_STRICT ?? '');
+  let warnings = 0;
+  const gate = (title, body) => {
+    console.error(`\n${title} ${strict ? 'FAILED' : 'WARNING'} — ${body}`);
+    if (strict) process.exit(1);
+    warnings++;
+  };
+
+  // `strict: true` here is the full set of pairings (muted and accent surfaces too), not the CLI flag.
+  const base = checkContrast(ctx.colors, { strict: true });
+  // The components' own pairings (a Button variant's label on its fill), once per colour pair.
+  const seen = new Set(base.map((line) => /^\s+(\w+) .*\((#\w+) on (#\w+)\)$/.exec(line)?.slice(1).join(' ')));
+  const failures = [...base, ...componentFailures(ctx.components, ctx.colors, seen)];
+  ctx.contrastFailures = failures;
   if (failures.length) {
-    console.error(
-      `\ntokens:build FAILED — ${failures.length} colour pairing(s) below WCAG AA (${AA}:1):\n\n${failures.join('\n')}\n\n` +
+    gate(
+      'tokens:build',
+      `${failures.length} colour pairing(s) below WCAG AA (${AA}:1):\n\n${failures.join('\n')}\n\n` +
         'Darken the fill, or flip its -foreground between neutral.0 and neutral.950.\n' +
         'A brightened accent (usually the dark theme) needs dark text, not white.\n' +
         'Or let the theme generator fix it: `halftone-tokens theme apply <code|preset>` keeps the hue and adjusts the lightness.\n'
     );
-    process.exit(1);
   }
 
-  // The palette passes; now the source: a tone's text on its own tint, beyond what this palette allows.
+  // Then the source: a tone's text on its own tint, beyond what this palette allows.
   if (config.scan?.length) {
     const limits = textOnTintLimits(ctx.colors);
     const problems = scanTintText(root, config.scan, limits);
     if (problems.length) {
-      console.error(
-        `\nhalftone-tokens: ${problems.length} class string(s) put a tone's text on its own tint below WCAG AA (${AA}:1):\n\n${problems.join('\n')}\n\n` +
+      gate(
+        'halftone-tokens',
+        `${problems.length} class string(s) put a tone's text on its own tint below WCAG AA (${AA}:1):\n\n${problems.join('\n')}\n\n` +
           `This palette allows: ${describeTintLimits(limits)}.\n` +
           'Use text-foreground on the tint (let the tint, an icon or a dot carry the colour), or a lighter tint.\n' +
           'An element that holds only an icon may keep its tone: add a `halftone-tokens-ignore tint-text` comment.\n'
       );
-      process.exit(1);
     }
   }
+  const contrast = warnings ? `${warnings} contrast warning(s), run with --strict to fail` : 'contrast AA ✓';
 
   const files = [];
   for (const [name, options] of Object.entries(config.targets ?? {})) {
@@ -116,7 +135,7 @@ export async function run(argv = process.argv.slice(2)) {
       console.error(`halftone-tokens check: ${stale.length} generated file(s) out of date — run \`npm run tokens:build\`:\n${stale.map((f) => `  ${f.path}`).join('\n')}`);
       process.exit(1);
     }
-    console.log(`halftone-tokens check: ${files.length} files up to date · contrast AA ✓`);
+    console.log(`halftone-tokens check: ${files.length} files up to date · ${contrast}`);
     return;
   }
 
@@ -125,7 +144,7 @@ export async function run(argv = process.argv.slice(2)) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, f.contents);
   }
-  console.log(`tokens:build → ${files.map((f) => f.path).join(', ')} · contrast AA ✓`);
+  console.log(`tokens:build → ${files.map((f) => f.path).join(', ')} · ${contrast}`);
 }
 
 // npm runs bins through a symlink in node_modules/.bin, so compare real paths.

package/lib/apca.mjs

@@ -0,0 +1,55 @@
+/**
+ * APCA (the Accessible Perceptual Contrast Algorithm, APCA-W3 0.0.98G-4g), the candidate contrast method
+ * for WCAG 3. ADVISORY ONLY: the build gates on WCAG 2.1 AA (contrast.mjs) and nothing here can fail it.
+ * The docs studio shows Lc beside the WCAG ratio so a re-brand can be read both ways.
+ *
+ * Unlike the WCAG ratio, APCA is not symmetric: the text colour comes first. Lc is positive for dark text
+ * on a light background and negative for light on dark; compare |Lc| against the guidance (roughly 75 for
+ * body text, 60 for other content text, 45 for large text, 30 for icons and other non-text).
+ */
+
+// The 0.0.98G-4g constants, as published in apca-w3.
+const TRC = 2.4;
+const [R, G, B] = [0.2126729, 0.7151522, 0.072175];
+const NORM_BG = 0.56;
+const NORM_TXT = 0.57;
+const REV_TXT = 0.62;
+const REV_BG = 0.65;
+const BLK_THRS = 0.022;
+const BLK_CLMP = 1.414;
+const SCALE = 1.14;
+const LO_OFFSET = 0.027;
+const LO_CLIP = 0.1;
+const DELTA_Y_MIN = 0.0005;
+
+function parseHex(hex) {
+  const m = /^#?([0-9a-f]{6})$/i.exec(String(hex).trim());
+  if (!m) throw new Error(`Expected a 6-digit hex colour, got "${hex}"`);
+  const n = parseInt(m[1], 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+/** APCA's screen luminance Y: a simple 2.4 power curve, not the sRGB piecewise one WCAG uses. */
+export function apcaLuminance(hex) {
+  const [r, g, b] = parseHex(hex).map((c) => (c / 255) ** TRC);
+  return R * r + G * g + B * b;
+}
+
+/** Soft-clamp near-black, as APCA does, so very dark pairs don't report inflated contrast. */
+const clampBlack = (y) => (y > BLK_THRS ? y : y + (BLK_THRS - y) ** BLK_CLMP);
+
+/** Lc (lightness contrast) of `text` on `background`, about -108 to 106. 0 means no usable contrast. */
+export function apcaContrast(text, background) {
+  const yTxt = clampBlack(apcaLuminance(text));
+  const yBg = clampBlack(apcaLuminance(background));
+  if (Math.abs(yBg - yTxt) < DELTA_Y_MIN) return 0;
+
+  if (yBg > yTxt) {
+    // Dark text on a light background.
+    const sapc = (yBg ** NORM_BG - yTxt ** NORM_TXT) * SCALE;
+    return sapc < LO_CLIP ? 0 : (sapc - LO_OFFSET) * 100;
+  }
+  // Light text on a dark background.
+  const sapc = (yBg ** REV_BG - yTxt ** REV_TXT) * SCALE;
+  return sapc > -LO_CLIP ? 0 : (sapc + LO_OFFSET) * 100;
+}

package/lib/color.mjs

@@ -3,6 +3,7 @@
  *   hexToHslTriplet  NativeWind 4 / shadcn v3 CSS variables (`221.2 83.2% 53.3%`)
  *   hexToOklch       Tailwind 4 / shadcn web CSS variables (`oklch(0.546 0.2152 262.88)`)
  *   contrast         WCAG 2.1 ratio, for the gate in contrast.mjs
+ *   deltaEOK         OKLab distance, for the colour-vision check in cvd.mjs
  */
 
 function parseHex(hex) {
@@ -37,15 +38,34 @@ export function hexToHslTriplet(hex) {
 const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
 const fromLinear = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
 
-/** Hex → [L 0–1, C, H degrees], unrounded. */
-export function hexToOklchParts(hex) {
-  const [r, g, b] = parseHex(hex).map((c) => toLinear(c / 255));
+/** Hex → linear-light sRGB [r, g, b], 0–1. */
+export const hexToLinearRgb = (hex) => parseHex(hex).map((c) => toLinear(c / 255));
+
+/** Linear-light sRGB → 8-bit hex (clamped). */
+export const linearRgbToHex = (rgb) => toHex(rgb.map((c) => Math.round(Math.min(1, Math.max(0, fromLinear(c))) * 255)));
+
+/** Hex → OKLab [L 0–1, a, b], unrounded. */
+export function hexToOklab(hex) {
+  const [r, g, b] = hexToLinearRgb(hex);
   const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
   const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
   const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
-  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
-  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
-  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ];
+}
+
+/** ΔE in OKLab: the straight-line distance, L on its 0–1 scale (about 0.02 is a just-noticeable difference). */
+export function deltaEOK(a, b) {
+  const [p, q] = [hexToOklab(a), hexToOklab(b)];
+  return Math.hypot(p[0] - q[0], p[1] - q[1], p[2] - q[2]);
+}
+
+/** Hex → [L 0–1, C, H degrees], unrounded. */
+export function hexToOklchParts(hex) {
+  const [L, A, B] = hexToOklab(hex);
   const C = Math.hypot(A, B);
   const H = C < 1e-4 ? 0 : ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360;
   return [L, C < 1e-4 ? 0 : C, H];
@@ -67,7 +87,7 @@ function oklchToLinearRgb([L, C, H]) {
 
 /** [L, C, H] → 8-bit sRGB hex (clamped). */
 export function oklchPartsToHex(parts) {
-  return toHex(oklchToLinearRgb(parts).map((c) => Math.round(Math.min(1, Math.max(0, fromLinear(c))) * 255)));
+  return linearRgbToHex(oklchToLinearRgb(parts));
 }
 
 /** Whether [L, C, H] lies inside sRGB (no channel clipped). */

package/lib/contrast.mjs

@@ -3,7 +3,9 @@
  * colour will happily fail WCAG without anyone noticing. Every pairing the kit actually renders is
  * checked here, and a failure stops the build.
  */
+import { apcaContrast } from './apca.mjs';
 import { blend, contrast } from './color.mjs';
+import { componentPairs } from './theme/components.mjs';
 
 export const AA = 4.5; // WCAG 2.1 AA, normal text. Kit labels are 16px — not "large text".
 export const AA_NON_TEXT = 3; // WCAG 1.4.11, icons and other meaningful non-text.
@@ -33,8 +35,10 @@ export function contrastPairs(hex, mode, { strict = false, fg: only } = {}) {
     if (!only || fgName === only) out.push({ mode, label, fgName, bgName, fg, bg, threshold, ratio: contrast(fg, bg) });
   };
 
-  for (const name of ['primary', 'secondary', 'destructive', 'success', 'warning', 'info', 'accent', 'card', 'popover', 'muted', 'sidebar', 'sidebar-primary', 'sidebar-accent']) {
+  for (const name of ['primary', 'button', 'secondary', 'destructive', 'success', 'warning', 'info', 'accent', 'card', 'popover', 'muted', 'sidebar', 'sidebar-primary', 'sidebar-accent']) {
     const fg = `${name}-foreground`;
+    // A solid button is the primary pairing again: counted once.
+    if (name === 'button' && hex.button === hex.primary && hex[fg] === hex['primary-foreground']) continue;
     if (hex[name] && hex[fg]) add(`${fg} on ${name}`, fg, name, hex[fg], hex[name], AA);
   }
   for (const surface of ['background', 'card', 'muted']) {
@@ -50,6 +54,14 @@ export function contrastPairs(hex, mode, { strict = false, fg: only } = {}) {
     }
   }
 
+  // A field whose line is its only boundary (filled, underline: field-edge isn't the input colour) needs that
+  // line at 3:1 (WCAG 1.4.11) on the field and on the surfaces it sits on.
+  if (hex['field-edge'] && hex.input && hex['field-edge'] !== hex.input) {
+    for (const surface of ['field', 'background', 'card']) {
+      if (hex[surface]) add(`field-edge on ${surface}`, 'field-edge', surface, hex['field-edge'], hex[surface], AA_NON_TEXT);
+    }
+  }
+
   // A tone's icon on that tone's own tint — Alert, IconCircle, SwipeToConfirm.
   for (const tone of TONES) {
     if (!hex[tone] || !hex.background) continue;
@@ -60,6 +72,17 @@ export function contrastPairs(hex, mode, { strict = false, fg: only } = {}) {
   return out;
 }
 
+/**
+ * Every pairing the build checks (the strict set), in both modes, for a table people read: each row has
+ * `pass` against its WCAG threshold, and `apca`, the APCA Lc of the same pair. APCA is advisory and never
+ * decides `pass`. `hex` is { light: { name: '#rrggbb' }, dark: { … } }, as a generated theme's `resolved`.
+ */
+export function contrastReport(hex, { strict = true } = {}) {
+  return ['light', 'dark'].flatMap((mode) =>
+    contrastPairs(hex[mode] ?? {}, mode, { strict }).map((r) => ({ ...r, pass: r.ratio >= r.threshold, apca: apcaContrast(r.fg, r.bg) })),
+  );
+}
+
 /** The failing pairings as report lines. */
 export function contrastFailures(hex, mode, options) {
   return contrastPairs(hex, mode, options)
@@ -103,3 +126,35 @@ export function checkContrast(colors, options) {
   const of = (mode) => Object.fromEntries(colors.map((c) => [c.name, c[mode]]));
   return [...contrastFailures(of('light'), 'light', options), ...contrastFailures(of('dark'), 'dark', options)];
 }
+
+/**
+ * The component layer's label-on-fill pairings (lib/theme/components.mjs), in both modes, as rows like contrastReport's:
+ * { mode, label, fgName, bgName, fg, bg, threshold, ratio, component, variant }. `bgName` is the fill's role.
+ */
+export function componentContrast(components, background) {
+  return ['light', 'dark'].flatMap((mode) =>
+    componentPairs(components, mode, background[mode], blend).map((p) => ({
+      mode,
+      label: p.label,
+      fgName: p.fgRole,
+      bgName: p.bgRole,
+      fg: p.fg,
+      bg: p.bg,
+      threshold: AA,
+      ratio: contrast(p.fg, p.bg),
+      component: p.component,
+      variant: p.variant,
+    }))
+  );
+}
+
+/** The failing component pairings as report lines, leaving out any colour pair `seen` already reports ('mode fg bg'). */
+export function componentFailures(components, colors, seen = new Set()) {
+  const background = Object.fromEntries(['light', 'dark'].map((mode) => [mode, colors.find((c) => c.name === 'background')?.[mode] ?? '#ffffff']));
+  const lines = new Set();
+  for (const r of componentContrast(components, background)) {
+    if (r.ratio >= r.threshold || seen.has(`${r.mode} ${r.fg} ${r.bg}`)) continue;
+    lines.add(`  ${r.mode.padEnd(5)} ${r.label.padEnd(36)} ${r.ratio.toFixed(2)} / ${r.threshold}  (${r.fg} on ${r.bg})`);
+  }
+  return [...lines];
+}

package/lib/cvd.mjs

@@ -0,0 +1,97 @@
+/**
+ * Colour-vision check. The contrast gate proves every tone reads against its surface; it says nothing
+ * about whether two tones can be told apart by someone who cannot see red from green. This simulates the
+ * three dichromacies and measures what is left of the difference between tones that carry meaning:
+ *
+ *   simulateCvd(hex, type)  what a protanope, deuteranope or tritanope sees: Machado, Oliveira & Fernandes
+ *                           2009 at severity 1.0, applied in linear-light sRGB. One model for all three
+ *                           (Viénot 1999 covers only protan and deutan; for reds, greens and ambers the two
+ *                           land within about 0.03 ΔE of each other, Machado moves saturated blues more)
+ *   cvdWarnings(resolved)   pairs that fall below MIN_DELTA_E under any vision, per mode
+ *
+ * A warning, never a failure: a red/green pair can still be told apart by its icon, label or position,
+ * and the kit always gives a status one of those. The check says when colour alone stops doing the work.
+ * Pure ESM, no Node APIs: the docs studio runs it in the browser.
+ */
+import { deltaEOK, hexToLinearRgb, linearRgbToHex } from './color.mjs';
+
+export const CVD_TYPES = ['protanopia', 'deuteranopia', 'tritanopia'];
+
+/** Machado et al. 2009, severity 1.0, rows → linear R, G, B. */
+const MATRICES = {
+  protanopia: [
+    [0.152286, 1.052583, -0.204868],
+    [0.114503, 0.786281, 0.099216],
+    [-0.003882, -0.048116, 1.051998],
+  ],
+  deuteranopia: [
+    [0.367322, 0.860646, -0.227968],
+    [0.280085, 0.672501, 0.047413],
+    [-0.01182, 0.04294, 0.968881],
+  ],
+  tritanopia: [
+    [1.255528, -0.076749, -0.178779],
+    [-0.078411, 0.930809, 0.147602],
+    [0.004733, 0.691367, 0.3039],
+  ],
+};
+
+/** `hex` as a dichromat sees it. `type` 'none' (or anything falsy) returns it unchanged. */
+export function simulateCvd(hex, type) {
+  if (!type || type === 'none') return hex.toLowerCase();
+  const m = MATRICES[type];
+  if (!m) throw new Error(`simulateCvd: unknown vision "${type}", expected one of ${CVD_TYPES.join(', ')}`);
+  const rgb = hexToLinearRgb(hex);
+  return linearRgbToHex(m.map((row) => row[0] * rgb[0] + row[1] * rgb[1] + row[2] * rgb[2]));
+}
+
+/**
+ * The smallest OKLab distance two tones that mean different things may keep. About 0.02 is one
+ * just-noticeable difference for large patches side by side; a status dot or a 2px chart line is small and
+ * seldom right next to its partner, so this asks for a couple and a half of them.
+ */
+export const MIN_DELTA_E = 0.05;
+
+/** The status tones are each other's alternatives; a chart's adjacent series sit side by side. */
+export const DISTINCT_PAIRS = [
+  ['success', 'destructive'],
+  ['success', 'warning'],
+  ['warning', 'destructive'],
+  ['info', 'success'],
+  ['info', 'warning'],
+  ['info', 'destructive'],
+  ['chart-1', 'chart-2'],
+  ['chart-2', 'chart-3'],
+  ['chart-3', 'chart-4'],
+  ['chart-4', 'chart-5'],
+];
+
+/** The pairs as one vision sees them in one mode: `hex` is { name: '#rrggbb' }. */
+export function pairDistances(hex, type, pairs = DISTINCT_PAIRS) {
+  return pairs
+    .filter(([a, b]) => hex[a] && hex[b])
+    .map(([a, b]) => {
+      const [sa, sb] = [simulateCvd(hex[a], type), simulateCvd(hex[b], type)];
+      return { a, b, vision: type || 'none', fg: sa, bg: sb, deltaE: deltaEOK(sa, sb) };
+    });
+}
+
+/**
+ * Every pair, mode and vision (normal sight included) below `threshold`: `resolved` is
+ * { light: { name: hex }, dark: { … } }, the shape `generateTheme` returns as `theme.resolved`.
+ * A pair that collides under several visions is reported once per vision, worst first.
+ */
+export function cvdWarnings(resolved, { pairs = DISTINCT_PAIRS, threshold = MIN_DELTA_E } = {}) {
+  const out = [];
+  for (const mode of ['light', 'dark']) {
+    if (!resolved[mode]) continue;
+    for (const type of ['none', ...CVD_TYPES]) {
+      for (const d of pairDistances(resolved[mode], type, pairs)) if (d.deltaE < threshold) out.push({ mode, ...d });
+    }
+  }
+  return out.sort((x, y) => x.deltaE - y.deltaE);
+}
+
+/** The warnings as report lines, like contrastFailures'. */
+export const describeCvdWarnings = (warnings) =>
+  warnings.map((w) => `  ${w.mode.padEnd(5)} ${`${w.a} / ${w.b}`.padEnd(24)} ${w.vision.padEnd(12)} ΔE ${w.deltaE.toFixed(3)}  (${w.fg} vs ${w.bg})`);