@handamade/psi-tokens 0.18.0 → 0.19.0

package/README.md

@@ -35,6 +35,22 @@ All tokens are CSS custom properties: `--psi-bg-primary`, `--psi-fg-secondary`,
 
 Run `pnpm new-theme` to scaffold a customer brand theme (palette + slot mapping).
 
+## Deriving a brand from a prompt
+
+`@handamade/psi-tokens/generate` (D57) derives a brand at runtime instead of scaffolding one by hand:
+
+```ts
+import { parsePrompt, deriveTheme, serializeCustomerTheme } from "@handamade/psi-tokens/generate";
+
+const vector = parsePrompt("a calm dark fintech brand");   // deterministic BrandVector
+const pair = deriveTheme(vector);                          // AA-solved light + dark DerivedTheme pair
+const { filename, source, registration } = serializeCustomerTheme(pair); // customers/<name>.ts
+```
+
+- `parsePrompt` is deterministic — an FNV-1a hash seeds a PRNG, so an unrecognised prompt still derives a coherent brand.
+- `deriveTheme` solves both members of the pair independently to WCAG AA by binary-searching lightness; it never returns a below-AA theme, because it throws instead of returning one if the solver can't clear the matrix.
+- `serializeCustomerTheme` emits `customers/<name>.ts` source in the CLI's own layout (`pnpm new-theme`'s `Palette` + `SlotMap`), extended to a pair: two `SlotMap`s (light and dark) and, unlike the CLI's override-free scaffold, the solved `ThemeDef` overrides each member needs to clear AA — the same kind of hand-tuned correction `acmeOverrides` carries in `customers/acme.ts`, but derived rather than hand-tuned.
+
 ## Machine-readable artifacts
 
 For AI and tooling, see [llms.txt](./llms.txt):
@@ -42,6 +58,7 @@ For AI and tooling, see [llms.txt](./llms.txt):
 - `dist/guidance.json` — Variant intent, usage rules, state derivation
 - `dist/dtcg/{theme}.json` — W3C DTCG format export
 - `dist/components/{name}.vars.css` — Component-specific token declarations
+- `dist/generate/` — Compiled `./generate` subpath (`parsePrompt`, `deriveTheme`, `serializeCustomerTheme`, and lower-level helpers)
 
 ## Note
 

package/dist/contrast-matrix.d.ts

@@ -0,0 +1,34 @@
+import type { ResolvedTheme } from "./dsl/resolver.js";
+export interface ContrastPair {
+    fg: string;
+    bg: string;
+    minRatio: number;
+}
+export interface ContrastResult extends ContrastPair {
+    ratio: number;
+    pass: boolean;
+}
+/**
+ * Composite a foreground hex color with alpha onto an opaque background hex.
+ * Uses sRGB blending (gamma-encoded): mixed = fg * alpha + bg * (1 - alpha).
+ * Returns an opaque hex color matching browser rendering.
+ */
+export declare function compositeHex(fgHex: string, alpha: number, bgHex: string): string;
+/**
+ * Check contrast ratios for a set of fg/bg pairs in a resolved theme.
+ *
+ * Alpha handling:
+ * - bg with alpha (e.g. fillTint*) is composited onto bgPrimary
+ * - fg with alpha (e.g. fgSecondary) is composited onto the bg token
+ *
+ * bgPrimary is used as the base surface for alpha-bg compositing.
+ */
+export declare function checkContrast(resolved: ResolvedTheme, pairs: ContrastPair[]): ContrastResult[];
+/**
+ * Standard WCAG AA contrast pairs that every theme must pass.
+ */
+export declare const wcagAAPairs: ContrastPair[];
+/** Solid component-variant labels on their variant backgrounds (spec: "every
+ * button/tag label on its variant background ≥ 4.5"). Tint-variant labels are
+ * already covered by the fg-on-tint pairs in wcagAAPairs. */
+export declare const componentLabelPairs: ContrastPair[];

package/dist/contrast-matrix.js

@@ -0,0 +1,130 @@
+import { wcagContrast, formatHex, rgb } from "culori";
+// ── Alpha compositing ─────────────────────────────────────────────
+/**
+ * Composite a foreground hex color with alpha onto an opaque background hex.
+ * Uses sRGB blending (gamma-encoded): mixed = fg * alpha + bg * (1 - alpha).
+ * Returns an opaque hex color matching browser rendering.
+ */
+export function compositeHex(fgHex, alpha, bgHex) {
+    const f = rgb(fgHex);
+    const b = rgb(bgHex);
+    if (!f)
+        throw new Error(`compositeHex: unparseable color "${fgHex}"`);
+    if (!b)
+        throw new Error(`compositeHex: unparseable color "${bgHex}"`);
+    const hex = formatHex({
+        mode: "rgb",
+        r: f.r * alpha + b.r * (1 - alpha),
+        g: f.g * alpha + b.g * (1 - alpha),
+        b: f.b * alpha + b.b * (1 - alpha),
+    });
+    if (!hex)
+        throw new Error(`compositeHex: could not format the blend of "${fgHex}" and "${bgHex}"`);
+    return hex;
+}
+/**
+ * Composite a foreground color with alpha onto an opaque background.
+ * Delegates to compositeHex for sRGB blending.
+ */
+function compositeOnBackground(fg, bg) {
+    const alpha = fg.oklch.alpha ?? 1;
+    if (alpha >= 1) {
+        return fg.hex;
+    }
+    return compositeHex(fg.hex, alpha, bg.hex);
+}
+// ── Contrast checker ──────────────────────────────────────────────
+/**
+ * Check contrast ratios for a set of fg/bg pairs in a resolved theme.
+ *
+ * Alpha handling:
+ * - bg with alpha (e.g. fillTint*) is composited onto bgPrimary
+ * - fg with alpha (e.g. fgSecondary) is composited onto the bg token
+ *
+ * bgPrimary is used as the base surface for alpha-bg compositing.
+ */
+export function checkContrast(resolved, pairs) {
+    const bgPrimary = resolved.bgPrimary;
+    if (!bgPrimary) {
+        throw new Error("Theme must include bgPrimary for contrast checking");
+    }
+    return pairs.map((pair) => {
+        const fgToken = resolved[pair.fg];
+        const bgToken = resolved[pair.bg];
+        if (!fgToken) {
+            throw new Error(`Unknown foreground token: "${pair.fg}"`);
+        }
+        if (!bgToken) {
+            throw new Error(`Unknown background token: "${pair.bg}"`);
+        }
+        // Resolve effective bg: if bg has alpha, composite onto bgPrimary
+        const bgAlpha = bgToken.oklch.alpha ?? 1;
+        const effectiveBgHex = bgAlpha < 1
+            ? compositeOnBackground(bgToken, bgPrimary)
+            : bgToken.hex;
+        // Resolve effective fg: if fg has alpha, composite onto the bg
+        const fgAlpha = fgToken.oklch.alpha ?? 1;
+        const effectiveFgHex = fgAlpha < 1
+            ? compositeOnBackground(fgToken, bgToken)
+            : fgToken.hex;
+        const ratio = wcagContrast(effectiveFgHex, effectiveBgHex);
+        return {
+            ...pair,
+            ratio: Math.round(ratio * 100) / 100,
+            pass: ratio >= pair.minRatio,
+        };
+    });
+}
+// ── Default contrast pairs ────────────────────────────────────────
+const bgSurfaces = [
+    "bgPrimary",
+    "bgSecondary",
+    "fillNeutral1",
+    "fillNeutral2",
+    "fillNeutral3",
+    "fillNeutral4",
+    "fillNeutral5",
+    "fillNeutral6",
+];
+/**
+ * Standard WCAG AA contrast pairs that every theme must pass.
+ */
+export const wcagAAPairs = [
+    // fgPrimary on all surfaces
+    ...bgSurfaces.map((bg) => ({ fg: "fgPrimary", bg, minRatio: 4.5 })),
+    // fgSecondary on all surfaces
+    ...bgSurfaces.map((bg) => ({ fg: "fgSecondary", bg, minRatio: 4.5 })),
+    // Semantic fg on primary background
+    { fg: "fgAccent", bg: "bgPrimary", minRatio: 4.5 },
+    { fg: "fgSuccess", bg: "bgPrimary", minRatio: 4.5 },
+    { fg: "fgWarning", bg: "bgPrimary", minRatio: 4.5 },
+    { fg: "fgDanger", bg: "bgPrimary", minRatio: 4.5 },
+    // Semantic fg on their tint backgrounds
+    { fg: "fgAccent", bg: "fillTintAccent", minRatio: 4.5 },
+    { fg: "fgSuccess", bg: "fillTintSuccess", minRatio: 4.5 },
+    { fg: "fgWarning", bg: "fillTintWarning", minRatio: 4.5 },
+    { fg: "fgDanger", bg: "fillTintDanger", minRatio: 4.5 },
+    // Primary text on a selected table row's accent wash (D62). Distinct from
+    // the fgAccent/fillTintAccent pair above: a selected row keeps ordinary
+    // body text, it does not recolor it to the accent.
+    { fg: "fgPrimary", bg: "fillTintAccent", minRatio: 4.5 },
+    // Toast's status icon on the elevated surface (D64/D65). The three pairs
+    // above gate these foregrounds on bgPrimary; --psi-surface-bg — what Toast,
+    // Menu and Dialog all alias — resolves to bgSecondary, which was ungated for
+    // the semantic foregrounds until Toast put an icon there. Held at 4.5 even
+    // though an icon is non-text content (WCAG 1.4.11 would allow 3.0): the
+    // colours clear 4.5 anyway, and the matrix's posture is a single floor.
+    { fg: "fgSuccess", bg: "bgSecondary", minRatio: 4.5 },
+    { fg: "fgWarning", bg: "bgSecondary", minRatio: 4.5 },
+    { fg: "fgDanger", bg: "bgSecondary", minRatio: 4.5 },
+];
+/** Solid component-variant labels on their variant backgrounds (spec: "every
+ * button/tag label on its variant background ≥ 4.5"). Tint-variant labels are
+ * already covered by the fg-on-tint pairs in wcagAAPairs. */
+export const componentLabelPairs = [
+    { fg: "fgOnAccent", bg: "fillAccent", minRatio: 4.5 }, // Button/IconButton/Tag accent label, Checkbox check, outline hover (D37)
+    { fg: "fgStaticWhite", bg: "fillDanger", minRatio: 4.5 }, // Button/IconButton/Tag danger
+    { fg: "fgStaticWhite", bg: "fillSuccess", minRatio: 4.5 }, // Tag success
+    { fg: "fgStaticBlack", bg: "fillWarning", minRatio: 4.5 }, // Tag warning (D22)
+    { fg: "fgOnInverted", bg: "bgInverted", minRatio: 4.5 }, // Tooltip label (D46 inversion pair)
+];

package/dist/dsl/builders.d.ts

@@ -0,0 +1,7 @@
+import type { CapOp, DeltaOp, SetOp, SlotRef, TokenDef, TokenRef } from "./types.js";
+export declare function set(value: number): SetOp;
+export declare function delta(value: number): DeltaOp;
+export declare function cap(value: number): CapOp;
+export declare const slot: Record<string, SlotRef>;
+export declare const ref: Record<string, TokenRef>;
+export declare function token(def: TokenDef): TokenDef;

package/dist/dsl/builders.js

@@ -0,0 +1,25 @@
+// ── Channel operation builders ──────────────────────────────────────
+export function set(value) {
+    return { op: "set", value };
+}
+export function delta(value) {
+    return { op: "delta", value };
+}
+export function cap(value) {
+    return { op: "cap", value };
+}
+// ── Source proxies ──────────────────────────────────────────────────
+export const slot = new Proxy({}, {
+    get(_target, prop) {
+        return { type: "slot", name: prop };
+    },
+});
+export const ref = new Proxy({}, {
+    get(_target, prop) {
+        return { type: "ref", name: prop };
+    },
+});
+// ── Token builder ───────────────────────────────────────────────────
+export function token(def) {
+    return { ...def };
+}

package/dist/dsl/resolver.d.ts

@@ -0,0 +1,3 @@
+import type { Palette, ResolvedToken, SlotMap, ThemeDef } from "./types.js";
+export type ResolvedTheme = Record<string, ResolvedToken>;
+export declare function resolve(theme: ThemeDef, palette: Palette, slots: SlotMap): ResolvedTheme;

package/dist/dsl/resolver.js

@@ -0,0 +1,114 @@
+import { formatHex, clampChroma } from "culori";
+// ── Channel operation application ──────────────────────────────────
+function applyOp(base, op) {
+    if (!op)
+        return base;
+    switch (op.op) {
+        case "set":
+            return op.value;
+        case "delta":
+            return base + op.value;
+        case "cap":
+            return Math.min(base, op.value);
+    }
+}
+// ── Formula string generation ──────────────────────────────────────
+function formatOp(channel, op) {
+    return `${channel} ${op.op}(${op.value})`;
+}
+function formatFormula(def) {
+    const source = def.from.type === "slot"
+        ? `slot(${def.from.name})`
+        : `ref(${def.from.name})`;
+    const ops = [];
+    if (def.l)
+        ops.push(formatOp("L", def.l));
+    if (def.c)
+        ops.push(formatOp("C", def.c));
+    if (def.h)
+        ops.push(formatOp("H", def.h));
+    if (def.alpha !== undefined)
+        ops.push(`alpha(${def.alpha})`);
+    return ops.length > 0 ? `${source} → ${ops.join(", ")}` : source;
+}
+// ── Resolver ───────────────────────────────────────────────────────
+export function resolve(theme, palette, slots) {
+    const cache = new Map();
+    function resolveToken(name) {
+        const cached = cache.get(name);
+        if (cached)
+            return cached;
+        const def = theme[name];
+        if (!def) {
+            throw new Error(`Unknown token: "${name}"`);
+        }
+        // Resolve base L/C/H from source
+        let baseL;
+        let baseC;
+        let baseH;
+        let baseAlpha;
+        if (def.from.type === "slot") {
+            const paletteName = slots[def.from.name];
+            if (!paletteName) {
+                throw new Error(`Unknown slot: "${def.from.name}"`);
+            }
+            const entry = palette[paletteName];
+            if (!entry) {
+                throw new Error(`Unknown palette entry: "${paletteName}" (from slot "${def.from.name}")`);
+            }
+            baseL = entry.l;
+            baseC = entry.c;
+            baseH = entry.h;
+        }
+        else {
+            // ref — recursively resolve the referenced token
+            const refToken = resolveToken(def.from.name);
+            baseL = refToken.oklch.l;
+            baseC = refToken.oklch.c;
+            baseH = refToken.oklch.h;
+            baseAlpha = refToken.oklch.alpha;
+        }
+        // Apply channel operations
+        const l = applyOp(baseL, def.l);
+        const c = applyOp(baseC, def.c);
+        const h = applyOp(baseH, def.h);
+        const alpha = def.alpha ?? baseAlpha;
+        // Build OKLCH color for culori
+        const oklchColor = {
+            mode: "oklch",
+            l,
+            c,
+            h,
+        };
+        if (alpha !== undefined) {
+            oklchColor.alpha = alpha;
+        }
+        // Gamut-map to sRGB via chroma clamping
+        const clamped = clampChroma(oklchColor, "oklch", "rgb");
+        // Extract the gamut-mapped OKLCH values
+        const clampedL = clamped?.l ?? l;
+        const clampedC = clamped?.c ?? 0;
+        const clampedH = clamped?.h ?? h;
+        // Generate hex (always 6-digit sRGB)
+        const hex = formatHex(clamped ?? oklchColor) ?? "#000000";
+        const resolved = {
+            name,
+            oklch: {
+                l: clampedL,
+                c: clampedC,
+                h: clampedH,
+                ...(alpha !== undefined ? { alpha } : {}),
+            },
+            hex,
+            formula: formatFormula(def),
+            ...(def.scopes !== undefined ? { scopes: def.scopes } : {}),
+        };
+        cache.set(name, resolved);
+        return resolved;
+    }
+    const result = {};
+    for (const name of Object.keys(theme)) {
+        result[name] = resolveToken(name);
+    }
+    return result;
+}

package/dist/dsl/types.d.ts

@@ -0,0 +1,59 @@
+export interface SetOp {
+    readonly op: "set";
+    readonly value: number;
+}
+export interface DeltaOp {
+    readonly op: "delta";
+    readonly value: number;
+}
+export interface CapOp {
+    readonly op: "cap";
+    readonly value: number;
+}
+export type ChannelOp = SetOp | DeltaOp | CapOp;
+export interface SlotRef {
+    readonly type: "slot";
+    readonly name: string;
+}
+export interface TokenRef {
+    readonly type: "ref";
+    readonly name: string;
+}
+export type TokenSource = SlotRef | TokenRef;
+export interface TokenDef {
+    readonly from: TokenSource;
+    readonly l?: ChannelOp;
+    readonly c?: ChannelOp;
+    readonly h?: ChannelOp;
+    readonly alpha?: number;
+    /** D46: property groups / CSS properties this token may bind to
+     * (see src/scopes.ts). Unscoped tokens are valid everywhere. */
+    readonly scopes?: readonly string[];
+}
+export interface PaletteEntry {
+    readonly l: number;
+    readonly c: number;
+    readonly h: number;
+}
+export type Palette = Record<string, PaletteEntry>;
+export interface SlotMap {
+    readonly ink: string;
+    readonly canvas: string;
+    readonly accent: string;
+    readonly success: string;
+    readonly warning: string;
+    readonly danger: string;
+}
+export type ThemeDef = Record<string, TokenDef>;
+export interface ResolvedToken {
+    readonly name: string;
+    readonly oklch: {
+        readonly l: number;
+        readonly c: number;
+        readonly h: number;
+        readonly alpha?: number;
+    };
+    readonly hex: string;
+    readonly formula: string;
+    readonly scopes?: readonly string[];
+}

package/dist/dsl/types.js

@@ -0,0 +1,2 @@
+// ── Channel operations ──────────────────────────────────────────────
+export {};

package/dist/generate/derive.d.ts

@@ -0,0 +1,20 @@
+import { type ResolvedTheme } from "../dsl/resolver.js";
+import { type CustomerTheme } from "../themes/customers/index.js";
+import type { BrandVector } from "./types.js";
+export interface DerivedTheme {
+    mode: "light" | "dark";
+    customerTheme: CustomerTheme;
+    resolved: ResolvedTheme;
+    customProperties: Record<string, string>;
+}
+export interface DerivedPair {
+    vector: BrandVector;
+    light: DerivedTheme;
+    dark: DerivedTheme;
+}
+/**
+ * Derive both members of a brand from one vector, each solved to AA
+ * independently (D57). The header toggle then selects between them — there is
+ * nothing left to recompute.
+ */
+export declare function deriveTheme(v: BrandVector): DerivedPair;

package/dist/generate/derive.js

@@ -0,0 +1,232 @@
+import { checkContrast, componentLabelPairs, wcagAAPairs } from "../contrast-matrix.js";
+import { resolve } from "../dsl/resolver.js";
+import { cap, set, slot, token } from "../dsl/builders.js";
+import { assembleCustomerTheme, } from "../themes/customers/index.js";
+import { buildBrandPalette } from "./palette.js";
+import { hexFor, solveL } from "./solve.js";
+/** camelCase token name → --psi-kebab-case custom property. */
+function cssName(token) {
+    return `--psi-${token.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)}`;
+}
+/** The channels of `hex` with an exact alpha. checkContrast composites
+ * tok.hex (gamut-clamped, 8-bit per channel) with the unrounded alpha, so
+ * this is the only form that renders precisely what was validated. hex8
+ * cannot: it quantizes alpha to 1/255, which moves the composited result a
+ * full channel step and drops near-threshold pairs below 4.5 (measured: 384
+ * of 1225 sampled prompts had a pair render under AA with hex8). Deliberately
+ * not `oklch(l c h / a)` either — the browser would recompute RGB from OKLCH
+ * and could land a bit away from `formatHex`'s own rounding, reintroducing
+ * the same class of mismatch between what was validated and what renders. */
+function withAlpha(hex, alpha) {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return `rgb(${r} ${g} ${b} / ${alpha})`;
+}
+/**
+ * The gate, and it must be the SAME set `scripts/build.ts` runs over every
+ * committed theme: `[...wcagAAPairs, ...componentLabelPairs]`, 33 pairs.
+ *
+ * Checking only `wcagAAPairs` (28) is what let "a theme derived from any
+ * prompt clears the AA matrix by construction" ship false a third time. The
+ * five-pair delta is `componentLabelPairs` — solid variant labels on their
+ * fills — and the first of them, `fgOnAccent` on `fillAccent`, sat right at
+ * the threshold: `bold calm app` (hue 146, `vivid`) rendered it at 4.4979:1 in
+ * BOTH modes while the console printed "zero failures — by construction", and
+ * the `customers/bold-calm-app.ts` that prompt emitted threw in `pnpm build`,
+ * which had been checking all 33 the whole time.
+ *
+ * `buildBrandPalette` is what makes the extra five pass by construction (see
+ * `accentLightness` there for why the fix has to be upstream of this loop
+ * rather than another escalating target inside it).
+ */
+const AA_MATRIX = [...wcagAAPairs, ...componentLabelPairs];
+const BASE_TARGET = 4.5;
+const TARGET_ESCALATION = 0.1;
+const MAX_OUTER_ATTEMPTS = 40;
+/** The four text tokens this function solves, mapped to the palette slot
+ * their colour anchors on. The second element is the SLOT name ("accent"),
+ * not the palette key ("brandAccent") — `slot.accent` is what a TokenDef
+ * sources from, while the anchor is looked up through `slots` to reach the
+ * palette entry. */
+const TEXT_TOKENS = [
+    ["fgAccent", "accent"],
+    ["fgSuccess", "success"],
+    ["fgWarning", "warning"],
+    ["fgDanger", "danger"],
+];
+/** bg token name → the text token whose colour it derives from (light.ts /
+ * dark.ts: `fillTintAccent: token({ from: ref.fgAccent, ... })`, etc). Lets
+ * the escalation loop trace a failing pair like `{ fg: "fgPrimary", bg:
+ * "fillTintAccent" }` (the D62 selected-row pair) back to the token that
+ * actually controls it, even though that token appears nowhere in the pair
+ * itself. */
+const TINT_SOURCE = {
+    fillTintAccent: "fgAccent",
+    fillTintSuccess: "fgSuccess",
+    fillTintWarning: "fgWarning",
+    fillTintDanger: "fgDanger",
+};
+/**
+ * Per-hue overrides that keep the AA matrix clean, in exactly the shape acme
+ * carries by hand (`acmeOverrides`). Text tokens force their own L in the base
+ * themes, so the free variables here are that L and the chroma cap.
+ *
+ * Solving each text token to exactly 4.5:1 against the canvas is not enough:
+ * `wcagAAPairs` also gates the SAME foreground against its own tint fill
+ * (`fillTintAccent` etc.) — canvas tinted 12–15% toward the very colour being
+ * tested — and, for the status tokens, against `bgSecondary`. Both are
+ * strictly harder than plain canvas contrast (the tint background is closer
+ * in colour to the foreground than the canvas is), so a token solved to land
+ * exactly on the canvas threshold lands *under* AA on those pairs — this is
+ * what the initial `it.each` sweep caught (5 prompts, both text-on-canvas and
+ * text-on-tint failures, e.g. `fgAccent/fillTintAccent 3.88<4.5`).
+ *
+ * The accept/reject gate for the whole function is the FULL `AA_MATRIX`
+ * sweep against the real resolved theme, not a per-token subset: a per-token
+ * filter (`p.fg === name`) is blind to cross pairs whose `bg` a token
+ * controls indirectly but whose `fg` is something else — e.g. `{ fg:
+ * "fgPrimary", bg: "fillTintAccent" }` (D62) is only visible once
+ * `fillTintAccent`'s own dependency on `fgAccent` is traced via
+ * `TINT_SOURCE`. Solving each token in isolation and declaring victory once
+ * IT is happy would leave that pair free to fail with no one watching. Each
+ * outer pass solves all four tokens at their current targets, resolves the
+ * real theme, and checks every pair in `wcagAAPairs`; any failure escalates
+ * the target of whichever token owns it (traced through `TINT_SOURCE` when
+ * the failure isn't already `fg === token`) and the whole thing is retried.
+ * The loop cannot return successfully while any pair in the matrix fails —
+ * it either converges within `MAX_OUTER_ATTEMPTS` or throws.
+ */
+function solveOverrides(palette, slots, mode) {
+    const canvas = palette[slots.canvas];
+    const canvasHex = hexFor(canvas.l, canvas.c, canvas.h);
+    const direction = mode === "light" ? "darker" : "lighter";
+    // Solve a single text token's L/chroma against a given canvas-contrast
+    // target. Reduces chroma and re-solves when the target is unreachable at
+    // the anchor's own chroma — exactly what acme's hand-tuned caps
+    // (`acmeOverrides`) do by hand. Reading `.cleared` is not optional:
+    // `solveL` returns its most legible available value when it gives up, so
+    // ignoring the flag would ship a below-AA colour that looks like a solved
+    // one.
+    function solveOne(slotName, target) {
+        const anchor = palette[slots[slotName]];
+        let c = anchor.c;
+        let solved = solveL({ c, h: anchor.h, against: canvasHex, target, direction });
+        while (!solved.cleared && c > 0) {
+            c = Math.max(0, c - 0.008);
+            solved = solveL({ c, h: anchor.h, against: canvasHex, target, direction });
+        }
+        if (!solved.cleared) {
+            throw new Error(`solveOverrides: ${slotName} cannot clear ${target}:1 against ${canvasHex} at any chroma`);
+        }
+        // Deliberately NO `scopes`. `assembleCustomerTheme` inherits the base
+        // token's scopes when an override declares none (D46), and the base
+        // declarations are not uniform: `fgDanger` is `["text", "border"]` in both
+        // light.ts and dark.ts, while the other three are `["text"]`. Hardcoding
+        // `["text"]` here silently narrowed fgDanger — invisible in-memory (the
+        // console never runs the scope gate) but fatal in the token build, which
+        // rejects the emitted `customers/<name>.ts` with
+        // `Scope drift for token "fgDanger": light declares ["text","border"],
+        // <name> declares ["text"]` before the contrast gate is even reached.
+        return token({
+            from: slot[slotName],
+            l: set(Number(solved.l.toFixed(4))),
+            c: cap(Number(c.toFixed(4))),
+        });
+    }
+    const targets = {};
+    for (const [name] of TEXT_TOKENS)
+        targets[name] = BASE_TARGET;
+    let overrides = {};
+    let lastFailures = [];
+    for (let outer = 0; outer < MAX_OUTER_ATTEMPTS; outer++) {
+        overrides = {};
+        for (const [name, slotName] of TEXT_TOKENS) {
+            overrides[name] = solveOne(slotName, targets[name]);
+        }
+        const trialResolved = resolve(assembleCustomerTheme({ palette, slots, base: mode, overrides }), palette, slots);
+        const failures = checkContrast(trialResolved, AA_MATRIX).filter((r) => !r.pass);
+        if (failures.length === 0) {
+            lastFailures = [];
+            break;
+        }
+        lastFailures = failures.map((f) => `${f.fg}/${f.bg} ${f.ratio}<${f.minRatio}`);
+        let escalatedAny = false;
+        for (const f of failures) {
+            const owner = f.fg in targets ? f.fg : TINT_SOURCE[f.bg];
+            if (owner !== undefined && owner in targets) {
+                targets[owner] = targets[owner] + TARGET_ESCALATION;
+                escalatedAny = true;
+            }
+        }
+        // A failing pair this loop cannot trace to any of the four tokens it
+        // controls (fg isn't one of them, bg isn't a tint of one of them) is not
+        // something escalating a target will ever fix — retrying would just burn
+        // the remaining attempts for no reason, so give up immediately with the
+        // specific failures rather than a generic "still fails" after 40 no-op
+        // attempts.
+        if (!escalatedAny) {
+            throw new Error(`solveOverrides: failure(s) outside the four solved tokens' control: ${lastFailures.join(", ")}`);
+        }
+    }
+    if (lastFailures.length > 0) {
+        throw new Error(`solveOverrides: still fails after ${MAX_OUTER_ATTEMPTS} escalations: ${lastFailures.join(", ")}`);
+    }
+    return overrides;
+}
+function deriveMember(v, palette, slots, mode) {
+    const customerTheme = {
+        palette,
+        slots,
+        base: mode,
+        overrides: solveOverrides(palette, slots, mode),
+        ...(v.fonts ? { fonts: v.fonts } : {}),
+        componentOverrides: { "control-radius": `var(--psi-radius-${v.radius})` },
+    };
+    const resolved = resolve(assembleCustomerTheme(customerTheme), palette, slots);
+    const customProperties = {};
+    for (const [name, tok] of Object.entries(resolved)) {
+        // tok.hex is always opaque — formatHex discards alpha. Tokens like
+        // fillTint* and the scrims carry alpha, and dropping it makes them
+        // byte-identical to the token they derive from (e.g. fillTintAccent
+        // would render as fgAccent at full strength): checkContrast composites
+        // alpha correctly, so the AA sweep would still pass while the shipped
+        // custom property renders the guarantee false in the browser. `withAlpha`
+        // carries the exact float alpha checkContrast validated against — see its
+        // own comment for why hex8 (1/255 alpha quantization) isn't safe here.
+        const alpha = tok.oklch.alpha;
+        customProperties[cssName(name)] =
+            alpha === undefined || alpha >= 1 ? tok.hex : withAlpha(tok.hex, alpha);
+    }
+    for (const [name, value] of Object.entries(customerTheme.componentOverrides ?? {})) {
+        customProperties[`--psi-${name}`] = value;
+    }
+    return { mode, customerTheme, resolved, customProperties };
+}
+/**
+ * Derive both members of a brand from one vector, each solved to AA
+ * independently (D57). The header toggle then selects between them — there is
+ * nothing left to recompute.
+ */
+export function deriveTheme(v) {
+    const { palette, lightSlots, darkSlots } = buildBrandPalette(v);
+    const pair = {
+        vector: v,
+        light: deriveMember(v, palette, lightSlots, "light"),
+        dark: deriveMember(v, palette, darkSlots, "dark"),
+    };
+    // Belt and braces: the solver targets the text pairs directly, but the AA
+    // matrix covers more than those — including the five `componentLabelPairs`
+    // no target inside `solveOverrides` can move, which is exactly why this
+    // check runs over `AA_MATRIX` and not the narrower `wcagAAPairs`. A residual
+    // failure means a bug in the solver or the palette anchors, not bad input,
+    // so surface it loudly in development.
+    for (const member of [pair.light, pair.dark]) {
+        const failures = checkContrast(member.resolved, AA_MATRIX).filter((r) => !r.pass);
+        if (failures.length > 0) {
+            throw new Error(`deriveTheme: ${member.mode} left ${failures.length} AA failure(s): ` +
+                failures.map((f) => `${f.fg}/${f.bg} ${f.ratio}<${f.minRatio}`).join(", "));
+        }
+    }
+    return pair;
+}