@scattered-light/loomiere 0.0.0-stage → 0.1.0

package/generator/color.mjs

@@ -0,0 +1,130 @@
+/**
+ * Color ramps, built the way Leonardo builds them.
+ *
+ * 1. A palette's key colors (the brand colors) define a path through OKLCH from paper
+ *    (the lightest color in the system) to ink (the darkest). Chroma and hue are
+ *    interpolated between keys by lightness, so the ramp bends through every brand color.
+ * 2. Each step is placed on that path where its contrast against paper hits a target
+ *    ratio. Every palette that shares a contrast table has the same contrast at the same
+ *    step, so `500` means "AA on paper" in every palette.
+ * 3. Optionally, keys land exactly: each key replaces the target of the step closest to
+ *    its own contrast, unless that step is locked (by default 500 stays at 4.5:1).
+ * 4. A `tone` tints a palette the way a transparent color layered over a grayscale does.
+ *    It is how neutrals get their temperature: the tone is blended into the path at an
+ *    intensity that can change from the light end to the dark end on a log curve.
+ */
+import { clampChroma, formatHex, interpolate, oklch, wcagContrast } from 'culori';
+
+const hueOf = (c, fallback = 0) => (c.c > 0.002 && c.h !== undefined ? c.h : fallback);
+const lerpHue = (a, b, t) => (a + (((b - a + 540) % 360) - 180) * t + 360) % 360;
+
+/**
+ * Tone as an overlay: `color` at `intensity` over gray. Intensity is a number, or
+ * [light, dark] interpolated geometrically along lightness (a log curve), so a tone can
+ * be strong in the darks and faint in the lights, or the reverse.
+ */
+function toneAt(tone, l, paperL, inkL) {
+  if (!tone) return null;
+  const [a, b] = Array.isArray(tone.intensity) ? tone.intensity : [tone.intensity, tone.intensity];
+  const t = (paperL - l) / (paperL - inkL);
+  const alpha = a > 0 && b > 0 ? a * (b / a) ** t : a + (b - a) * t;
+  const gray = { mode: 'oklch', l, c: 0, h: 0 };
+  // Mix in Oklab so the blend behaves like a transparent layer, then keep the gray's lightness.
+  const mixed = oklch(interpolate([gray, tone.color], 'oklab')(alpha));
+  return { c: mixed.c ?? 0, h: hueOf(mixed, oklch(tone.color).h ?? 0) };
+}
+
+/** Returns L → OKLCH color along the palette's path. */
+export function makePath({ keys, paper, ink, tone }) {
+  const p = oklch(paper);
+  const i = oklch(ink);
+  const ks = keys.map((k) => oklch(k)).sort((a, b) => b.l - a.l);
+  const firstHue = hueOf(ks[0] ?? oklch(tone?.color ?? paper));
+  const lastHue = hueOf(ks.at(-1) ?? oklch(tone?.color ?? ink));
+  const base = (l) => toneAt(tone, l, p.l, i.l) ?? { c: 0, h: firstHue };
+
+  // Without a tone the ends are paper and ink themselves. With a tone, the ends follow the
+  // tone, and keys bend the path away from it only near themselves.
+  const pts = [
+    { l: p.l, ...(tone ? base(p.l) : { c: p.c ?? 0, h: hueOf(p, firstHue) }) },
+    ...ks.map((k) => ({ l: k.l, c: k.c ?? 0, h: hueOf(k, firstHue) })),
+    { l: i.l, ...(tone ? base(i.l) : { c: i.c ?? 0, h: hueOf(i, lastHue) }) },
+  ];
+  if (!tone) {
+    pts[0].c = 0;
+    pts[0].h = firstHue;
+  }
+
+  return (l) => {
+    for (let j = 0; j < pts.length - 1; j++) {
+      const a = pts[j];
+      const b = pts[j + 1];
+      if (l <= a.l && l >= b.l) {
+        const t = a.l === b.l ? 0 : (a.l - l) / (a.l - b.l);
+        let c = a.c + (b.c - a.c) * t;
+        let h = lerpHue(a.h, b.h, t);
+        if (tone) {
+          // Follow the tone, plus whatever offset the neighboring keys ask for.
+          const here = base(l);
+          const offA = { c: a.c - base(a.l).c, h: ((a.h - base(a.l).h + 540) % 360) - 180 };
+          const offB = { c: b.c - base(b.l).c, h: ((b.h - base(b.l).h + 540) % 360) - 180 };
+          c = Math.max(0, here.c + offA.c + (offB.c - offA.c) * t);
+          h = (here.h + offA.h + (offB.h - offA.h) * t + 360) % 360;
+        }
+        return clampChroma({ mode: 'oklch', l, c, h }, 'oklch');
+      }
+    }
+    return { mode: 'oklch', l, c: 0, h: 0 };
+  };
+}
+
+/**
+ * Finds the color on the path whose contrast against paper is `ratio`. It errs on the
+ * darker side, after rounding to hex, so a step never falls short of its target.
+ */
+export function atContrast(path, ratio, paper, ink) {
+  // A target darker than ink can reach lands on ink itself.
+  if (wcagContrast(ink, paper) <= ratio) return formatHex(ink);
+  let lo = oklch(ink).l;
+  let hi = oklch(paper).l;
+  for (let n = 0; n < 40; n++) {
+    const mid = (lo + hi) / 2;
+    if (wcagContrast(path(mid), paper) >= ratio) lo = mid;
+    else hi = mid;
+  }
+  let hex = formatHex(path(lo));
+  for (let l = lo; wcagContrast(hex, paper) < ratio && l > oklch(ink).l; l -= 0.0005) hex = formatHex(path(l));
+  return hex;
+}
+
+/**
+ * Builds one palette. `targets` is { step: ratio }. Returns [{ step, hex, ratio, key }].
+ * With `exact`, each key replaces the nearest unlocked step's target (compared on a log
+ * scale), so the brand color itself appears in the palette. Without it, keys only shape
+ * the path, as in Leonardo.
+ */
+export function palette({ keys = [], exact = false, paper, ink, tone, targets, locked = [] }) {
+  const path = makePath({ keys, paper, ink, tone });
+  const steps = Object.keys(targets);
+  const ratios = { ...targets };
+  const keyAt = {};
+  for (const key of exact ? keys : []) {
+    const r = wcagContrast(key, paper);
+    let best = null;
+    for (const step of steps) {
+      if (locked.includes(Number(step)) || keyAt[step]) continue;
+      const d = Math.abs(Math.log(targets[step]) - Math.log(r));
+      if (!best || d < best.d) best = { step, d };
+    }
+    if (best) {
+      ratios[best.step] = r;
+      keyAt[best.step] = key;
+    }
+  }
+  return steps.map((step) => ({
+    step,
+    hex: keyAt[step] ? formatHex(keyAt[step]) : atContrast(path, ratios[step], paper, ink),
+    ratio: ratios[step],
+    key: keyAt[step] ?? null,
+  }));
+}

package/generator/data-colors.mjs

@@ -0,0 +1,104 @@
+/**
+ * Checks and fixes for the categorical data colors (brand color.data).
+ *
+ * Each color is checked against paper (can a bar or line be seen?) and against its
+ * neighbors in the series order (can two adjacent series be told apart?), for typical
+ * color vision and for the three kinds of color blindness, simulated with Machado et al.
+ * (2009) at full strength. nudgeDataColor finds the nearest color that clears every check.
+ */
+import {
+  differenceCiede2000,
+  displayable,
+  filterGrayscale,
+  filterDeficiencyDeuter,
+  filterDeficiencyProt,
+  filterDeficiencyTrit,
+  formatHex,
+  oklch,
+  wcagContrast,
+} from 'culori';
+
+/** ΔE (CIEDE2000) under which two neighbors are hard to tell apart. */
+export const DISTINCT = 10;
+/** WCAG 1.4.11 asks 3:1 for graphics that carry meaning. */
+export const DATA_CONTRAST = 3;
+
+export const VISIONS = {
+  typical: { label: 'Typical vision', see: (c) => c },
+  protan: { label: 'Red-blind (protan)', see: filterDeficiencyProt(1) },
+  deutan: { label: 'Green-blind (deutan)', see: filterDeficiencyDeuter(1) },
+  tritan: { label: 'Blue-blind (tritan)', see: filterDeficiencyTrit(1) },
+  achromat: { label: 'No color (achromat)', see: filterGrayscale(1) },
+};
+/** The everyday checks. Telling every neighbor apart in grayscale is the achromatopsia theme's job. */
+const CHECKED = ['typical', 'protan', 'deutan', 'tritan'];
+
+const ΔE = differenceCiede2000();
+
+function distance(a, b, vision) {
+  const { see } = VISIONS[vision];
+  return ΔE(see(a), see(b));
+}
+
+/**
+ * Every problem in the list, in order: { i, kind: 'contrast' | 'neighbor', vision?, with?, value }.
+ * A neighbor problem belongs to the later color of the two, since that is the one a fix moves.
+ */
+export function checkDataColors(data, paper, goal = DATA_CONTRAST) {
+  const problems = [];
+  data.forEach(([, hex], i) => {
+    const r = wcagContrast(hex, paper);
+    if (r < goal) problems.push({ i, kind: 'contrast', value: r });
+    if (i === 0) return;
+    for (const vision of CHECKED) {
+      const d = distance(data[i - 1][1], hex, vision);
+      if (d < DISTINCT) problems.push({ i, kind: 'neighbor', vision, with: i - 1, value: d });
+    }
+  });
+  return problems;
+}
+
+/**
+ * Which colors a color must stay distinct from: `reach` places either side of it in the
+ * series order, as seen with each of `visions`, by at least `distinct`.
+ */
+const ALL = { visions: CHECKED, distinct: DISTINCT, reach: 1 };
+
+function passes(hex, data, i, paper, goal, { visions, distinct, reach }) {
+  if (wcagContrast(hex, paper) < goal) return false;
+  for (let j = i - reach; j <= i + reach; j++) {
+    if (j === i || !data[j]) continue;
+    for (const vision of visions) if (distance(data[j][1], hex, vision) < distinct) return false;
+  }
+  return true;
+}
+
+/** True when data[i] needs no nudge under these rules. */
+export const dataColorPasses = (data, i, paper, goal = DATA_CONTRAST, rules = ALL) => passes(data[i][1], data, i, paper, goal, rules);
+
+/**
+ * The color closest to data[i] (by ΔE) that passes on paper and stays distinct from its
+ * neighbors (by default the one on each side, for every kind of vision). It searches
+ * lightness, small hue and chroma shifts, so the color keeps its character. Returns null
+ * if nothing nearby passes.
+ */
+export function nudgeDataColor(data, i, paper, goal = DATA_CONTRAST, rules = ALL) {
+  const start = oklch(data[i][1]);
+  const candidates = [];
+  for (let l = 0.2; l <= 0.97; l += 0.01) {
+    for (let dh = -48; dh <= 48; dh += 4) {
+      for (const k of [1, 0.85, 1.15, 0.7, 1.3]) {
+        const c = { mode: 'oklch', l, c: (start.c ?? 0) * k, h: ((start.h ?? 0) + dh + 360) % 360 };
+        if (!displayable(c)) continue;
+        if (wcagContrast(c, paper) < goal) continue;
+        candidates.push(c);
+      }
+    }
+  }
+  const scored = candidates.map((c) => ({ c, d: ΔE(start, c) })).sort((a, b) => a.d - b.d);
+  for (const { c } of scored) {
+    const hex = formatHex(c);
+    if (passes(hex, data, i, paper, goal, rules)) return hex;
+  }
+  return null;
+}

package/generator/format-brand.mjs

@@ -0,0 +1,60 @@
+/**
+ * Writes a brand file the way people write them: short objects and lists on one line,
+ * long ones broken up, a blank line between top-level sections. Used by the brand builder
+ * and the pair lab so a saved file stays readable in a diff.
+ */
+const WIDTH = 120;
+// A flat list or map of plain values (space steps, a contrast table) reads best on one line.
+const FLAT = 200;
+const PACKED = 100;
+const SECTION = 100;
+
+const oneLine = (value) => {
+  if (Array.isArray(value)) return `[${value.map(oneLine).join(', ')}]`;
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).map(([k, v]) => `${JSON.stringify(k)}: ${oneLine(v)}`);
+    return entries.length ? `{ ${entries.join(', ')} }` : '{}';
+  }
+  return JSON.stringify(value);
+};
+
+function format(value, indent, width = WIDTH) {
+  const flat = oneLine(value);
+  const isFlatMap = value && typeof value === 'object' && Object.values(value).every((v) => typeof v !== 'object');
+  if (isFlatMap) width = Math.max(width, FLAT);
+  if (indent.length + flat.length <= width || value === null || typeof value !== 'object') return flat;
+  const inner = `${indent}  `;
+  if (Array.isArray(value)) {
+    // Lists of short items (data colors, steps) pack several to a line.
+    if (value.every((item) => oneLine(item).length < 40)) {
+      const lines = [];
+      let line = '';
+      for (const item of value.map(oneLine)) {
+        if (line && inner.length + line.length + item.length + 2 > PACKED) {
+          lines.push(line);
+          line = '';
+        }
+        line += line ? ` ${item},` : `${item},`;
+      }
+      lines.push(line);
+      return `[\n${lines.map((l) => inner + l).join('\n').replace(/,$/, '')}\n${indent}]`;
+    }
+    return `[\n${value.map((item) => inner + format(item, inner)).join(',\n')}\n${indent}]`;
+  }
+  const entries = Object.entries(value).map(([k, v]) => `${inner}${JSON.stringify(k)}: ${format(v, inner)}`);
+  return `{\n${entries.join(',\n')}\n${indent}}`;
+}
+
+/** Sections that consume the rest of the brand go last: roles pick from the palettes above them. */
+const LAST = ['roles'];
+
+export function formatBrand(input) {
+  const brand = Object.fromEntries([
+    ...Object.entries(input).filter(([k]) => !LAST.includes(k)),
+    ...LAST.filter((k) => k in input).map((k) => [k, input[k]]),
+  ]);
+  const entries = Object.entries(brand).map(([k, v]) => `  ${JSON.stringify(k)}: ${format(v, '  ', SECTION)}`);
+  // Blank lines set off each section after the name and description.
+  const out = entries.map((line, i) => (i > 0 && typeof Object.values(brand)[i] === 'object' ? `\n${line}` : line));
+  return `{\n${out.join(',\n')}\n}\n`;
+}

package/generator/generate.mjs

@@ -0,0 +1,43 @@
+/**
+ * Brand → Primitive.
+ *
+ * Reads a brand file (the inputs) and the optional <brand>.overrides.json beside it (exact
+ * values pinned on top of the math), and writes DTCG token files to
+ * <generatedDir>/tokens/primitive/ plus the brand-specific semantic files (pairs, role scopes,
+ * emphasis) to <generatedDir>/tokens/semantic/. Those files are generated: edit the brand
+ * file, not them.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { buildPrimitives } from './brand.mjs';
+
+const ROLE_FILE_NOTE = 'Generated from roles in the brand file. Edit the brand file (or the Roles step of loomiere studio), not this file.';
+const PAIR_FILE_NOTE = 'Generated from color.pairs in the brand file. Edit the brand file (or use loomiere lab), not this file.';
+
+export const overridesFileFor = (brandFile) => brandFile.replace(/\.json$/, '.overrides.json');
+
+export function generate(brandFile, generatedDir) {
+  const overridesFile = overridesFileFor(brandFile);
+  const brand = JSON.parse(fs.readFileSync(brandFile, 'utf8'));
+  const overrides = fs.existsSync(overridesFile) ? JSON.parse(fs.readFileSync(overridesFile, 'utf8')) : {};
+
+  const { files, applied, pairs, problems, roleTokens } = buildPrimitives(brand, overrides);
+  if (problems.length) {
+    throw new Error(`Brand pairs need AA (4.5:1) text:\n  ${problems.join('\n  ')}\nPick a passing pair in \`loomiere lab\` or fix color.pairs in the brand file.`);
+  }
+
+  const primitiveDir = path.join(generatedDir, 'tokens', 'primitive');
+  const semanticDir = path.join(generatedDir, 'tokens', 'semantic');
+  fs.mkdirSync(primitiveDir, { recursive: true });
+  fs.mkdirSync(semanticDir, { recursive: true });
+  for (const [name, content] of Object.entries(files)) {
+    fs.writeFileSync(path.join(primitiveDir, `${name}.json`), `${JSON.stringify(content, null, 2)}\n`);
+  }
+  // Pairs live with the semantic tokens: they are named uses of the palette, with a dark mode.
+  fs.writeFileSync(path.join(semanticDir, 'pair.json'), `${JSON.stringify({ $description: PAIR_FILE_NOTE, ...pairs }, null, 2)}\n`);
+  for (const name of ['scope', 'emphasis']) {
+    fs.writeFileSync(path.join(semanticDir, `${name}.json`), `${JSON.stringify({ $description: ROLE_FILE_NOTE, ...roleTokens[name] }, null, 2)}\n`);
+  }
+  return { brand, applied, files };
+}

package/generator/pairs.mjs

@@ -0,0 +1,236 @@
+/**
+ * Contrast pairs between every palette color.
+ *
+ * Palettes don't change between modes (dark mode picks different steps), so a pair that
+ * passes here passes in every mode. scripts/check-contrast.mjs covers the other half: the
+ * semantic pairs as each mode resolves them.
+ *
+ * WCAG levels: AAA 7:1 and AA 4.5:1 for text, AA-large 3:1 for large text and UI parts.
+ */
+import { formatHex, interpolate, wcagContrast } from 'culori';
+
+export const LEVELS = [
+  ['AAA', 7],
+  ['AA', 4.5],
+  ['AA-large', 3],
+];
+
+export const levelFor = (ratio) => LEVELS.find(([, min]) => ratio >= min)?.[0] ?? null;
+
+/** Flattens the generated color group to [{ path, hex }], skipping data colors and on-colors. */
+export function paletteColors(color) {
+  const out = [];
+  for (const [role, group] of Object.entries(color)) {
+    if (group.$value) out.push({ path: `color.${role}`, hex: group.$value });
+    else if (role !== 'data') {
+      for (const [step, t] of Object.entries(group)) if (t.$value) out.push({ path: `color.${role}.${step}`, hex: t.$value });
+    }
+  }
+  return out;
+}
+
+/**
+ * For each color: every other color it reaches at least AA-large with, grouped by level,
+ * strongest first. Same-palette partners are included, so "colors on themselves" is the
+ * subset whose path shares the role.
+ */
+export function pairTable(colors) {
+  const table = {};
+  for (const a of colors) {
+    const entry = { AAA: [], AA: [], 'AA-large': [] };
+    for (const b of colors) {
+      if (a === b) continue;
+      const ratio = wcagContrast(a.hex, b.hex);
+      const level = levelFor(ratio);
+      if (level) entry[level].push({ path: b.path, ratio: Number(ratio.toFixed(2)) });
+    }
+    for (const list of Object.values(entry)) list.sort((x, y) => y.ratio - x.ratio);
+    table[a.path] = entry;
+  }
+  return table;
+}
+
+/**
+ * The text color for each step: the palette's own 50 or darkest step when it passes AA,
+ * so text stays in the family. Otherwise paper when it passes (so every 500 takes white
+ * text), else ink.
+ */
+export function onColor(role, step, palette, paper, ink) {
+  const hex = palette[step].$value;
+  const steps = Object.keys(palette);
+  const candidates = [steps[0], steps.at(-1)]
+    .filter((s) => s !== step)
+    .map((s) => ({ ref: `{color.${role}.${s}}`, ratio: wcagContrast(hex, palette[s].$value) }))
+    .filter((c) => c.ratio >= 4.5)
+    .sort((a, b) => b.ratio - a.ratio);
+  if (candidates.length) return candidates[0];
+  const vsPaper = wcagContrast(hex, paper);
+  const vsInk = wcagContrast(hex, ink);
+  return vsPaper >= 4.5 || vsPaper >= vsInk ? { ref: '{color.white}', ratio: vsPaper } : { ref: '{color.black}', ratio: vsInk };
+}
+
+/*
+ * Brand pairs: named background/text combinations from the brand file's color.pairs.
+ *
+ * Each pair becomes tokens (pair.<name>.bg, .fg, .accent, plus derived parts) and a
+ * .sl-pair-<name> class that re-points the semantic color tokens inside it, so anything
+ * built from semantic tokens takes on the pair. Parts that carry text are checked here
+ * and the build stops when one falls short of AA.
+ */
+
+/** Parts every pair has: the three a brand names, then four derived from them. */
+export const PAIR_PARTS = {
+  bg: 'Background',
+  fg: 'Text, icons and strong borders',
+  accent: 'Links, buttons and focus rings',
+  hover: 'Accent on hover',
+  active: 'Accent while pressed',
+  subtle: 'Accent wash for highlighted items, selection and mark',
+  emphasis: 'Stronger accent wash for selected and pressed items',
+  muted: 'Inset background for code',
+};
+
+/** The "why" for one part of a resolved pair. */
+export function describePart(part, { parts, sources }, spec) {
+  const r = (a, b) => `${wcagContrast(parts[a], parts[b]).toFixed(2)}:1`;
+  const label = PAIR_PARTS[part];
+  const source = sources[part];
+  switch (part) {
+    case 'bg':
+      return `${label}.`;
+    case 'fg':
+      return `${label}. ${r('fg', 'bg')} on bg.`;
+    case 'accent':
+      return spec.accent ? `${label}. ${r('accent', 'bg')} on bg.` : `${label}. The pair names no accent, so this is fg.`;
+    case 'hover':
+    case 'active':
+      return Array.isArray(source)
+        ? `${label}: accent moved ${100 - source[1]}% toward ${source[2]}. ${r(part, 'bg')} against bg, which is the button label.`
+        : `${label}: the accent itself, because moving it would drop the button label below AA.`;
+    default:
+      return Array.isArray(source)
+        ? `${label}: ${source[0]} ${source[1]}% into bg. fg on it is ${r('fg', part)}.`
+        : `${label}: ${source} itself, because a stronger tint would drop text below AA.`;
+  }
+}
+
+/**
+ * How each semantic color token reads a pair. A part name, or [part, percent, part] for
+ * color-mix(in oklab, part percent%, part). Semantic color tokens not listed (status,
+ * overlay) keep their global values inside a pair.
+ */
+export const PAIR_ROLES = {
+  'surface.canvas': 'bg',
+  'surface.raised': 'bg',
+  'surface.overlay': 'bg',
+  'surface.modal': 'bg',
+  'surface.tray': 'bg',
+  'text.primary': 'fg',
+  'text.secondary': 'fg',
+  'text.tertiary': 'fg',
+  'text.accent': 'accent',
+  'text.disabled': ['fg', 45, 'bg'],
+  'text.on-primary': 'bg',
+  'text.on-tint': 'fg',
+  'text.on-tint-strong': 'fg',
+  'text.on-inverse': 'bg',
+  'text.on-inverse-surface': 'bg',
+  'surface.inverse': 'fg',
+  'border.subtle': ['fg', 15, 'bg'],
+  'border.default': ['fg', 30, 'bg'],
+  'border.strong': 'fg',
+  'border.accent': 'accent',
+  'border.control': ['fg', 50, 'bg'],
+  'border.control-hover': 'fg',
+  'fill.subtle': ['fg', 12, 'bg'],
+  'fill.default': ['fg', 22, 'bg'],
+  'fill.strong': ['fg', 35, 'bg'],
+  'fill.stronger': ['fg', 45, 'bg'],
+  'fill.inverse': 'fg',
+  'fill.track': ['fg', 12, 'bg'],
+  'interactive.default': 'accent',
+  'interactive.hover': 'hover',
+  'interactive.active': 'active',
+  'interactive.disabled': ['fg', 35, 'bg'],
+  'interactive.tint': 'subtle',
+  'interactive.tint-hover': 'subtle',
+  'interactive.tint-active': 'emphasis',
+  'interactive.tint-strong': 'emphasis',
+  'focus.ring': 'accent',
+  'content.prose-color': 'fg',
+  'content.blockquote-border': 'accent',
+  'content.blockquote-cite': 'fg',
+  'content.code-background': 'muted',
+  'content.code-border': ['fg', 30, 'bg'],
+  'content.code-text': 'fg',
+  'content.field-border': ['fg', 30, 'bg'],
+  'content.hr-border': ['fg', 30, 'bg'],
+  'content.pre-border': ['fg', 30, 'bg'],
+  'content.kbd-background': 'fg',
+  'content.kbd-text': 'bg',
+  'content.link-color': 'accent',
+  'content.link-hover-color': 'hover',
+  'content.link-underline-color': ['accent', 50, 'bg'],
+  'content.link-underline-hover-color': 'accent',
+  'content.list-marker-color': 'accent',
+  'content.mark-background': 'subtle',
+  'content.selection-background': 'subtle',
+  'content.selection-text': 'fg',
+  'content.scrollbar-thumb': ['fg', 30, 'bg'],
+  'content.scrollbar-thumb-hover': ['fg', 45, 'bg'],
+};
+
+const AA = 4.5;
+
+/** color-mix(in oklab, a pct%, b) as a hex. */
+export const mixHex = (a, pct, b) => formatHex(interpolate([b, a], 'oklab')(pct / 100));
+
+/** "secondary.600" → "color.secondary.600"; "white", "black", "paper" and "ink" are the ends. */
+export function pairRef(ref) {
+  const name = { paper: 'white', ink: 'black' }[ref] ?? ref;
+  return `color.${name}`;
+}
+
+/**
+ * Resolves one mode of a pair to hexes and works out the derived parts. `hexOf` maps a
+ * token path to its hex. Returns { parts: { part: hex }, sources: { part: expression },
+ * problems: [message] }, where an expression is a token path or [path, pct, path].
+ */
+export function resolvePair(spec, hexOf) {
+  const problems = [];
+  const sources = { bg: pairRef(spec.bg), fg: pairRef(spec.fg), accent: pairRef(spec.accent ?? spec.fg) };
+  const parts = {};
+  for (const part of ['bg', 'fg', 'accent']) {
+    parts[part] = hexOf(sources[part]);
+    if (!parts[part]) problems.push(`${part} "${spec[part]}" is not a palette color`);
+  }
+  if (problems.length) return { parts, sources, problems };
+
+  const fgRatio = wcagContrast(parts.fg, parts.bg);
+  if (fgRatio < AA) problems.push(`fg ${spec.fg} on bg ${spec.bg} is ${fgRatio.toFixed(2)}:1, needs ${AA}:1`);
+  const accentRatio = wcagContrast(parts.accent, parts.bg);
+  if (spec.accent && accentRatio < AA) problems.push(`accent ${spec.accent} on bg ${spec.bg} is ${accentRatio.toFixed(2)}:1, needs ${AA}:1`);
+
+  // Derived parts fall back to a plain part rather than ever dropping below AA.
+  const derive = (part, [a, pct, b], check, fallback) => {
+    const hex = mixHex(parts[a], pct, parts[b]);
+    if (check(hex) >= AA) {
+      parts[part] = hex;
+      sources[part] = [a, pct, b];
+    } else {
+      parts[part] = parts[fallback];
+      sources[part] = fallback;
+    }
+  };
+  // The button label is bg, so hover and active must keep AA against bg.
+  // Without an accent, accent is fg, so hover and active move toward bg instead.
+  const away = spec.accent ? 'fg' : 'bg';
+  derive('hover', ['accent', 85, away], (hex) => wcagContrast(hex, parts.bg), 'accent');
+  derive('active', ['accent', 70, away], (hex) => wcagContrast(hex, parts.bg), 'accent');
+  // fg and accent text sit on these.
+  const textOn = (hex) => Math.min(wcagContrast(parts.fg, hex), wcagContrast(parts.accent, hex));
+  derive('subtle', ['accent', 12, 'bg'], textOn, 'bg');
+  derive('emphasis', ['accent', 22, 'bg'], textOn, 'subtle');
+  derive('muted', ['fg', 6, 'bg'], (hex) => wcagContrast(parts.fg, hex), 'bg');
+  return { parts, sources, problems, ratios: { fg: fgRatio, accent: accentRatio } };
+}