@halftone-ds/tokens 1.1.0 → 1.2.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,48 @@ 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`, 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).
+
 ## 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 —
@@ -26,7 +29,7 @@ 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,51 @@ 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.`;
 
+  // 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 failures = checkContrast(ctx.colors, { strict: true });
+  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 +132,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 +141,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,6 +3,7 @@
  * 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';
 
 export const AA = 4.5; // WCAG 2.1 AA, normal text. Kit labels are 16px — not "large text".
@@ -33,8 +34,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 +53,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 +71,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)

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})`);

package/lib/resolve.mjs

@@ -5,7 +5,7 @@
  */
 import StyleDictionary from 'style-dictionary';
 import { readFileSync } from 'node:fs';
-import { DENSITY, DEPTH, shadowCss, TYPE, typeScale } from './theme/recipe.mjs';
+import { BUTTON, DEFAULT_RECIPE, DENSITY, DEPTH, FIELD, fieldWidth, shadowCss, TYPE, typeScale } from './theme/recipe.mjs';
 
 export const MODES = ['light', 'dark'];
 
@@ -68,6 +68,9 @@ export function radiusCalc(scale) {
  *                        (a token file from before themes gets the kit's defaults)
  *   type                 { size, scale, leading, leadingFactor, flow, measure } (semantic.type; defaults
  *                          for a token file from before the typeset)
+ *   shape.button/.field  the styles' numbers (semantic.button / .field), radii in px; a token file from
+ *                          before the styles gets solid buttons and outline fields, and colours to match
+ *   styles               { button, field }: the style names, from the recorded theme (or the defaults)
  */
 export async function loadTokens(sourcePath) {
   const source = JSON.parse(readFileSync(sourcePath, 'utf8'));
@@ -84,11 +87,34 @@ export async function loadTokens(sourcePath) {
     steps: radiusScales(prim),
   };
   const find = (list, name) => list.find((t) => cssName(t) === name)?.$value;
+  // Style colours a token file from before the styles doesn't have: what the components drew before.
+  const byName = Object.fromEntries(colors.map((c) => [c.name, c]));
+  const STYLE_FALLBACK = { button: 'primary', 'button-foreground': 'primary-foreground', 'button-edge': 'primary', field: 'input', 'field-edge': 'input' };
+  for (const [name, from] of Object.entries(STYLE_FALLBACK)) if (!byName[name] && byName[from]) colors.push({ ...byName[from], name });
   const shadows = (list, mode) =>
     Object.fromEntries(['1', '2', '3'].map((level) => [level, shadowCss(find(list, `shadow-${level}`) ?? DEPTH.soft[level][mode])]));
+  const borderWidth = find(semLight, 'border-width') ?? 1;
+  const md = radius.steps.find((s) => s.name === 'md')?.scale ?? 0.8;
+  const solid = BUTTON.solid;
+  const outline = FIELD.outline;
+  const fieldRound = find(semLight, 'field-round') ?? outline.round;
+  const fieldRoundBottom = find(semLight, 'field-round-bottom') ?? outline.roundBottom;
   const shape = {
     control: find(semLight, 'radius-control') ?? 9999,
-    borderWidth: find(semLight, 'border-width') ?? 1,
+    borderWidth,
+    button: {
+      alpha: find(semLight, 'button-alpha') ?? solid.alpha,
+      border: find(semLight, 'button-border-width') ?? solid.border,
+      edge: find(semLight, 'button-edge-width') ?? solid.edge,
+    },
+    field: {
+      alpha: { light: find(semLight, 'field-alpha') ?? outline.alpha.light, dark: find(semDark, 'field-alpha') ?? outline.alpha.dark },
+      border: find(semLight, 'field-border-width') ?? fieldWidth(outline.border, borderWidth),
+      edge: find(semLight, 'field-edge-width') ?? fieldWidth(outline.edge, borderWidth),
+      inset: find(semLight, 'field-inset') ?? outline.inset,
+      radius: Number((radius.base * md * fieldRound).toFixed(4)),
+      radiusBottom: Number((radius.base * md * fieldRoundBottom).toFixed(4)),
+    },
     stroke: find(semLight, 'icon-stroke') ?? 2,
     shadows: { light: shadows(semLight, 'light'), dark: shadows(semDark, 'dark') },
     density: {
@@ -97,7 +123,9 @@ export async function loadTokens(sourcePath) {
     },
   };
   const type = typeScale(Object.fromEntries(Object.entries(TYPE).map(([key, value]) => [key, find(semLight, `type-${key}`) ?? value])));
-  return { source, semLight, semDark, prim, colors, radius, shape, type };
+  const recorded = source.$extensions?.['com.halftonedesignsystem.theme']?.recipe ?? {};
+  const styles = { button: recorded.button ?? DEFAULT_RECIPE.button, field: recorded.field ?? DEFAULT_RECIPE.field };
+  return { source, semLight, semDark, prim, colors, radius, shape, type, styles };
 }
 
 /** Primitive tokens under a path prefix, e.g. group(prim, ['font', 'size']) → [{ key: 'xs', value: 12 }, …]. */

package/lib/theme/apply.mjs

@@ -30,10 +30,12 @@ function ownedValues(theme) {
   out['primitive.font.family.body'] = theme.fonts.body;
   out['primitive.font.family.mono'] = theme.fonts.mono;
   for (const [key, value] of Object.entries(theme.semantic.type)) out[`semantic.type.${key}`] = value;
+  for (const [key, value] of Object.entries(theme.semantic.button)) out[`semantic.button.${key}`] = value;
+  for (const [key, value] of Object.entries(theme.semantic.field)) out[`semantic.field.${key}`] = value;
   return out;
 }
 
-const TYPES = { radius: 'number', border: 'number', icon: 'number', density: 'number', type: 'number', shadow: 'shadow', font: 'fontFamily', color: 'color' };
+const TYPES = { radius: 'number', border: 'number', icon: 'number', density: 'number', type: 'number', button: 'number', field: 'number', shadow: 'shadow', font: 'fontFamily', color: 'color' };
 const DESCRIPTIONS = {
   'semantic.radius.control': 'Corner radius of mobile buttons and chips: rounded-control. 9999 = pills; otherwise the base radius.',
   'semantic.border.width': 'Width of `border` (px). border-2 and border-hairline stay explicit.',
@@ -53,6 +55,20 @@ const DESCRIPTIONS = {
   'semantic.type.leading': "Typeset: line height of running text (× size); the text sizes' line heights scale by leading / 1.75.",
   'semantic.type.flow': 'Typeset: space between blocks of long-form text (Prose), em.',
   'semantic.type.measure': 'Typeset: the longest line of long-form text (Prose), characters.',
+  'semantic.color.button': 'The primary button: bg-button (its alpha is button.alpha). Follows the theme\'s button style.',
+  'semantic.color.button-foreground': 'Text and icons on the primary button: text-button-foreground.',
+  'semantic.color.button-edge': 'The primary button\'s border and bottom edge: border-button-edge.',
+  'semantic.color.field': 'Text fields: bg-field (its alpha is field.alpha). Follows the theme\'s field style.',
+  'semantic.color.field-edge': 'Text fields\' border or bottom line: border-field-edge.',
+  'semantic.button.alpha': 'Opacity of the primary button\'s fill (0 = an outline button).',
+  'semantic.button.border-width': 'Primary button border, every side (px).',
+  'semantic.button.edge-width': 'Primary button bottom edge (px); raised buttons have a thicker, darker one.',
+  'semantic.field.alpha': 'Opacity of a text field\'s fill, per mode.',
+  'semantic.field.border-width': 'Text field border, top and sides (px).',
+  'semantic.field.edge-width': 'Text field bottom border (px).',
+  'semantic.field.round': '1 = text fields take the md radius on top, 0 = square.',
+  'semantic.field.round-bottom': '1 = text fields take the md radius at the bottom, 0 = square.',
+  'semantic.field.inset': '1 = text fields have inner padding, 0 = flush (underline fields).',
 };
 
 function typeOf(path) {