@vectoriox/iox-ui 5.25.0 → 5.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.25.0",
+  "version": "5.26.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/design-core/brand-neutrals.ts

@@ -0,0 +1,236 @@
+import {
+    AccentGround, atLightness, deriveAccentTokens, inSrgbGamut, oklabToRgb, parseHexColor, rgbToOklab, Rgb, toHexColor, wcagContrastRatio, WCAG_AA_TEXT,
+} from './brand';
+import { compositeOver, paintColours, quantizeRgb } from './colour-eval';
+import { SPEC_AXES } from './flavor-spec.generated';
+import { FlavorPalette, FlavorTintConfig, PRE_TINT_DEFAULT, TintId } from './design-token.model';
+import { resolveTokenValues } from './token-css';
+
+/**
+ * The whole colour system follows the brand (design-system DS9 — Doron, 2026-10-19: "I would imagine
+ * that once I change the colour of the brand, the whole colour system changes, but it doesn't").
+ *
+ * One brand colour in → every colour token of the look out, light and dark:
+ * - **Background tint** (`DesignChoices.tint`): Neutral is the look's own palette, untouched; Subtle and
+ *   Rich give every neutral role the flavor lists the BRAND's hue — the role keeps its own OKLab
+ *   lightness (so the look's light/dark structure and contrast survive) at the level's chroma (or its
+ *   own, when the flavor coloured it more), scaled by how chromatic the brand is: a grey brand tints
+ *   nothing. Material 3's neutral tonal palettes and Radix's tinted greys, as one table in the contract.
+ *   A pure-white page is capped just under white (the level's `groundMaxL`) so it can carry the tint; the flavor's paints rotate
+ *   with the brand (Glass's mesh); Midnight's glow already reads the accent.
+ * - **Accents**: the flavor's own quartet at its own seed, else derived from the brand ramp — and
+ *   `accent-text` is the first step that reads on EVERY ground (bg, surface, surface-2, the page's paint).
+ * - **Held pairs**: every text and line role is pushed until it clears its pair again on its grounds.
+ *   A no-op for the hand-tuned palette at its own seed — the generator's gate proves it.
+ *
+ * Port of iox-ai-guidance `design-system/colour.mjs` `flavorColours`; held equal to it by
+ * `flavor-fixtures.v1.json` (brand-neutrals.spec.ts). Change the maths THERE first.
+ */
+
+/** A seed below this OKLCH chroma tints at a proportionally lower strength. */
+export const TINT_FULL_CHROMA = 0.08;
+/** A neutral at least this chromatic was coloured on purpose: it keeps its hue offset from the flavor's seed. */
+export const TINT_OWN_HUE_CHROMA = 0.01;
+/** A brand below this chroma has no reliable hue: paints and coloured neutrals are not turned toward it. */
+export const TINT_TURN_CHROMA = 0.02;
+/** WCAG 1.4.11 — non-text contrast: UI boundaries, glyphs, focus indicators. */
+export const WCAG_AA_UI = 3;
+
+const PAGE = 'page';
+const GROUND_ROLES: ReadonlySet<string> = new Set(['bg']);
+const TEXT_GROUNDS: ReadonlyArray<string> = ['bg', 'surface', 'surface-2', PAGE];
+const INVERSE_GROUNDS: ReadonlyArray<string> = ['inverse-bg', 'inverse-surface'];
+const MODES = ['light', 'dark'] as const;
+
+/** The roles a derivation holds to their pair, on the grounds named (`page` = the page paint's colours). */
+export const HELD_CONTRAST: ReadonlyArray<readonly [string, ReadonlyArray<string>, number]> = [
+    ['text', TEXT_GROUNDS, WCAG_AA_TEXT],
+    ['text-muted', TEXT_GROUNDS, WCAG_AA_TEXT],
+    ['line-strong', TEXT_GROUNDS, WCAG_AA_UI],
+    ['danger', TEXT_GROUNDS, WCAG_AA_TEXT],
+    ['success', TEXT_GROUNDS, WCAG_AA_TEXT],
+    ['inverse-text', INVERSE_GROUNDS, WCAG_AA_TEXT],
+    ['inverse-muted', INVERSE_GROUNDS, WCAG_AA_TEXT],
+];
+
+/** One tint level of the contract (`axes.tints`). */
+export interface TintLevel {
+    readonly label: string;
+    readonly chroma?: Readonly<Record<string, number>>;
+    readonly ownScale?: number;
+    readonly paintChroma?: number;
+    /** A pure-white page is capped just under white so it can carry any chroma (at L 1 only white exists). */
+    readonly groundMaxL?: number;
+}
+export const TINT_LEVELS: Readonly<Record<TintId, TintLevel>> = SPEC_AXES.tints;
+
+/** What the colour derivation reads of a flavor. */
+export interface ColourFlavor {
+    readonly seed: string;
+    readonly palette: FlavorPalette;
+    readonly tint: FlavorTintConfig;
+}
+
+/** Every colour token of a look: `[light, dark]` per name. */
+export type FlavorColours = Record<string, [string, string]>;
+
+const upper = (hex: string) => hex.toUpperCase();
+const passesAll = (fg: string, bgs: ReadonlyArray<string>, min: number) => bgs.every(bg => wcagContrastRatio(fg, bg) >= min);
+
+/** The lightest/darkest version of `fg` (its own hue and chroma) that clears `min` on every ground. */
+export function ensureContrast(fg: string, bgs: ReadonlyArray<string>, min: number): string {
+    if (!parseHexColor(fg) || bgs.some(b => !parseHexColor(b)) || passesAll(fg, bgs, min)) return fg;
+    const lab = rgbToOklab(parseHexColor(fg) as Rgb);
+    const meanBgL = bgs.reduce((sum, b) => sum + rgbToOklab(parseHexColor(b) as Rgb).L, 0) / bgs.length;
+    const darker = lab.L <= meanBgL;
+    const chroma = Math.hypot(lab.a, lab.b);
+    const ua = chroma > 1e-6 ? lab.a : 0;
+    const ub = chroma > 1e-6 ? lab.b : 1e-6;
+    let lo = darker ? 0 : lab.L;
+    let hi = darker ? lab.L : 1;
+    let best = darker ? '#000000' : '#ffffff';
+    for (let i = 0; i < 30; i++) {
+        const mid = (lo + hi) / 2;
+        const candidate = toHexColor(atLightness(mid, ua, ub, chroma));
+        if (passesAll(candidate, bgs, min)) {
+            best = candidate;
+            if (darker) lo = mid; else hi = mid;
+        } else if (darker) hi = mid; else lo = mid;
+    }
+    return best;
+}
+
+const RGBA = /^rgba\(\s*(\d+),\s*(\d+),\s*(\d+),\s*([\d.]+)\s*\)$/i;
+const ALPHA_STEP = 0.01;
+
+/** A translucent `fg` (rgba) made just opaque enough to clear `min` on every ground, in 0.01 steps. */
+export function ensureAlpha(fg: string, bgs: ReadonlyArray<string>, min: number): string {
+    const m = RGBA.exec(String(fg ?? '').trim());
+    if (!m) return fg;
+    const [r, g, b] = [m[1], m[2], m[3]].map(Number);
+    const passes = (a: number) => bgs.every(bg => {
+        const ground = parseHexColor(bg) as Rgb;
+        return wcagContrastRatio(quantizeRgb(compositeOver({ r: r / 255, g: g / 255, b: b / 255, a }, ground)), ground) >= min;
+    });
+    let alpha = Number(m[4]);
+    if (passes(alpha)) return fg;
+    while (alpha < 1 && !passes(alpha)) alpha = Math.min(1, Math.round((alpha + ALPHA_STEP) * 100) / 100);
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+/** The colour at (L, hue angle) with the most chroma ≤ `chroma` that fits sRGB (a tint never overshoots its
+ *  level, and a stronger level never lands under a weaker one — `atLightness`'s ×0.82 steps can). */
+export function atLightnessMaxChroma(L: number, hue: number, chroma: number): Rgb {
+    const ua = Math.cos(hue);
+    const ub = Math.sin(hue);
+    const at = (c: number) => oklabToRgb({ L, a: ua * c, b: ub * c });
+    if (inSrgbGamut(at(chroma))) return at(chroma);
+    let lo = 0;
+    let hi = chroma;
+    for (let i = 0; i < 24; i++) {
+        const mid = (lo + hi) / 2;
+        if (inSrgbGamut(at(mid))) lo = mid; else hi = mid;
+    }
+    return at(lo);
+}
+
+/** The seed's OKLab hue angle and chroma — a grey seed keeps a stable (arbitrary) axis. */
+function seedHue(seed: string): { hue: number; chroma: number } {
+    const lab = rgbToOklab(parseHexColor(seed) as Rgb);
+    const chroma = Math.hypot(lab.a, lab.b);
+    const ua = chroma > 1e-6 ? lab.a : 0.0;
+    const ub = chroma > 1e-6 ? lab.b : 1e-6;
+    return { hue: Math.atan2(ub, ua), chroma };
+}
+
+const HEX_IN = /#[0-9a-f]{6}\b/gi;
+
+/** Every hex colour inside a paint (a gradient's stops) turned by `angle` radians of OKLab hue. */
+function rotatePaint(paint: string, angle: number, chromaScale: number): string {
+    return String(paint).replace(HEX_IN, hex => {
+        const lab = rgbToOklab(parseHexColor(hex) as Rgb);
+        const a = lab.a * Math.cos(angle) - lab.b * Math.sin(angle);
+        const b = lab.a * Math.sin(angle) + lab.b * Math.cos(angle);
+        return upper(toHexColor(atLightness(lab.L, a, b, Math.hypot(a, b) * chromaScale)));
+    });
+}
+
+/** The opaque colours a palette's named grounds show; `page` = every colour of the page's own paint. */
+function groundsOf(p: Readonly<Record<string, string>>, names: ReadonlyArray<string>): string[] {
+    const out: string[] = [];
+    for (const name of names) {
+        if (name === PAGE) {
+            const resolved = resolveTokenValues(Object.entries(p).map(([n, value]) => ({ name: n, value })))['page-bg'];
+            for (const c of paintColours(resolved)) if (c.a >= 1) out.push(toHexColor(c));
+        } else if (parseHexColor(p[name])) out.push(p[name]);
+    }
+    return [...new Set(out.map(upper))];
+}
+
+function holdContrast(p: Record<string, string>): void {
+    for (const [fg, names, min] of HELD_CONTRAST) {
+        if (parseHexColor(p[fg])) p[fg] = upper(ensureContrast(p[fg], groundsOf(p, names), min));
+        else if (RGBA.test(String(p[fg] ?? '').trim())) p[fg] = ensureAlpha(p[fg], groundsOf(p, names), min);
+    }
+}
+
+function tintPalette(p: Record<string, string>, flavor: ColourFlavor, level: TintLevel, seed: string): void {
+    const { hue: brandHue, chroma } = seedHue(seed);
+    const strength = Math.min(1, chroma / TINT_FULL_CHROMA);
+    const turn = chroma >= TINT_TURN_CHROMA ? brandHue - seedHue(flavor.seed).hue : 0;
+    for (const role of flavor.tint.roles) {
+        const rgb = parseHexColor(p[role]);
+        if (!rgb) continue;
+        const lab = rgbToOklab(rgb);
+        const L = GROUND_ROLES.has(role) ? Math.min(lab.L, level.groundMaxL ?? 1) : lab.L;
+        const own = Math.hypot(lab.a, lab.b);
+        const hue = own >= TINT_OWN_HUE_CHROMA ? Math.atan2(lab.b, lab.a) + turn : brandHue;
+        const c = Math.max(own * (level.ownScale ?? 1), (level.chroma?.[role] ?? 0) * flavor.tint.scale) * strength;
+        p[role] = upper(toHexColor(atLightnessMaxChroma(L, hue, c)));
+    }
+    for (const name of flavor.tint.paints ?? []) p[name] = rotatePaint(p[name], turn, level.paintChroma ?? 1);
+}
+
+/**
+ * The colour tokens of a flavor for a brand `seed` and a background `tint`, light and dark.
+ * Neutral at the flavor's own seed returns its palette exactly.
+ */
+export function flavorColours(flavor: ColourFlavor, choices: { seed?: string | null; tint?: TintId | null }): FlavorColours {
+    const seed = choices.seed || flavor.seed;
+    const level = TINT_LEVELS[choices.tint ?? PRE_TINT_DEFAULT];
+    const palette = {
+        light: { ...flavor.palette.light } as Record<string, string>,
+        dark: { ...flavor.palette.light, ...flavor.palette.dark } as Record<string, string>,
+    };
+    if (level?.chroma) for (const mode of MODES) tintPalette(palette[mode], flavor, level, seed);
+
+    if (seed.toLowerCase() !== flavor.seed.toLowerCase()) {
+        // Twice: the page paint may read the accent (Midnight's glow), so its grounds are known only once
+        // the fill is — and the fill never depends on the grounds.
+        for (let pass = 0; pass < 2; pass++) {
+            const derived = deriveAccentTokens(seed, {
+                bg: groundsOf(palette.light, TEXT_GROUNDS), bgDark: groundsOf(palette.dark, TEXT_GROUNDS),
+                inverseBg: groundsOf(palette.light, INVERSE_GROUNDS), inverseBgDark: groundsOf(palette.dark, INVERSE_GROUNDS),
+            });
+            for (const t of derived) {
+                palette.light[t.name] = upper(t.value);
+                if (t.values?.dark) palette.dark[t.name] = upper(t.values.dark);
+            }
+        }
+    }
+    for (const mode of MODES) {
+        const p = palette[mode];
+        p['accent-text'] = upper(ensureContrast(p['accent-text'], groundsOf(p, TEXT_GROUNDS), WCAG_AA_TEXT));
+        p['inverse-accent'] = upper(ensureContrast(p['inverse-accent'], groundsOf(p, INVERSE_GROUNDS), WCAG_AA_TEXT));
+        holdContrast(p);
+    }
+    const out: FlavorColours = {};
+    for (const name of Object.keys(flavor.palette.light)) out[name] = [palette.light[name], palette.dark[name]];
+    return out;
+}
+
+/** The grounds the PRE-DS9 accent derivation read: `bg` alone (light/dark), `inverse-bg` alone. */
+export function preTintAccentGrounds(palette: FlavorPalette): { bg: AccentGround; bgDark?: AccentGround; inverseBg?: AccentGround; inverseBgDark?: AccentGround } {
+    const dark = { ...palette.light, ...palette.dark };
+    return { bg: palette.light['bg'] ?? '', bgDark: dark['bg'], inverseBg: palette.light['inverse-bg'], inverseBgDark: dark['inverse-bg'] };
+}

package/src/design-core/brand.ts

@@ -57,10 +57,11 @@ export function oklabToRgb(c: OkLab): Rgb {
     };
 }
 
-const inGamut = (c: Rgb) => [c.r, c.g, c.b].every(v => v >= -1e-6 && v <= 1 + 1e-6);
+export const inSrgbGamut = (c: Rgb) => [c.r, c.g, c.b].every(v => v >= -1e-6 && v <= 1 + 1e-6);
+const inGamut = inSrgbGamut;
 
 /** The OKLab colour at (L, hue, chroma), chroma reduced until it fits sRGB. */
-function atLightness(L: number, hueA: number, hueB: number, chroma: number): Rgb {
+export function atLightness(L: number, hueA: number, hueB: number, chroma: number): Rgb {
     const len = Math.hypot(hueA, hueB) || 1;
     const ua = hueA / len, ub = hueB / len;
     let c = chroma;
@@ -231,19 +232,27 @@ export const ACCENT_TOKEN_NAMES = [
 ] as const;
 export type AccentTokenName = (typeof ACCENT_TOKEN_NAMES)[number];
 
+/** One ground, or every ground the accent must read on (DS9: the bg, the surfaces a scheme or a
+ *  container puts under the same text, the page's own paint) — the FIRST decides direction. */
+export type AccentGround = string | ReadonlyArray<string>;
+
 /** The backgrounds the accent must read on, light and (optionally) dark. Without an inverse
  *  background the inverse pair is not derived — the pack's own stays. */
 export interface AccentBackgrounds {
-    bg: string;
-    bgDark?: string;
-    inverseBg?: string;
-    inverseBgDark?: string;
+    bg: AccentGround;
+    bgDark?: AccentGround;
+    inverseBg?: AccentGround;
+    inverseBgDark?: AccentGround;
 }
 
+const groundList = (g: AccentGround | null | undefined): string[] =>
+    (g === undefined || g === null ? [] : typeof g === 'string' ? [g] : [...g]);
+const hasGround = (g: AccentGround | null | undefined) => groundList(g).length > 0;
+
 const RAMP_ORDER = RAMP_STEPS.map(s => s.step);
 const WHITE_HEX = toHexColor(WHITE);
 const BLACK_HEX = toHexColor(BLACK);
-const passesText = (fg: string, bg: string) => wcagContrastRatio(fg, bg) >= WCAG_AA_TEXT;
+const passesText = (fg: string, bg: AccentGround) => groundList(bg).every(g => wcagContrastRatio(fg, g) >= WCAG_AA_TEXT);
 const bestInkHex = (bg: string) =>
     (wcagContrastRatio(WHITE_HEX, bg) >= wcagContrastRatio(BLACK_HEX, bg) ? WHITE_HEX : BLACK_HEX);
 
@@ -279,7 +288,7 @@ export function deriveAccentTokens(
         const candidate = RAMP_ORDER[i] !== undefined ? step(RAMP_ORDER[i]) : null;
         return candidate && passesText(ink, candidate) ? candidate : step(accentStep);
     };
-    const firstOn = (steps: number[], bg: string) => step(steps.find(n => passesText(step(n), bg)) ?? steps[steps.length - 1]);
+    const firstOn = (steps: number[], bg: AccentGround) => step(steps.find(n => passesText(step(n), bg)) ?? steps[steps.length - 1]);
 
     const ink = hexOf('brandInk');
     const light = {
@@ -289,19 +298,20 @@ export function deriveAccentTokens(
         text: firstOn([500, 600, 700, 800, 900], against.bg),
     };
 
-    const dark = against.bgDark ? (() => {
+    const dark = hasGround(against.bgDark) ? (() => {
         const darkStep = [300, 200, 400].find(n => passesText(bestInkHex(step(n)), step(n))) ?? 300;
         const darkInk = bestInkHex(step(darkStep));
         return {
             accent: step(darkStep),
             ink: darkInk,
             hover: hoverFor(darkStep, darkInk),
-            text: firstOn([300, 200, 100, 50], against.bgDark),
+            text: firstOn([300, 200, 100, 50], against.bgDark as AccentGround),
         };
     })() : null;
 
-    const inverseOn = (inverseBg: string) => {
-        const toward = wcagContrastRatio(step(RAMP_ORDER[0]), inverseBg) >= wcagContrastRatio(step(RAMP_ORDER[RAMP_ORDER.length - 1]), inverseBg)
+    const inverseOn = (inverseBg: AccentGround) => {
+        const ground = groundList(inverseBg)[0];
+        const toward = wcagContrastRatio(step(RAMP_ORDER[0]), ground) >= wcagContrastRatio(step(RAMP_ORDER[RAMP_ORDER.length - 1]), ground)
             ? -1 : 1;
         const walk = RAMP_ORDER.filter(n => (toward < 0 ? n <= 500 : n >= 500));
         if (toward < 0) walk.reverse();
@@ -315,8 +325,8 @@ export function deriveAccentTokens(
         const fill = step(walk[walk.length - 1]);
         return { accent: fill, ink: passesText(inkOn(fill), fill) ? inkOn(fill) : bestInkHex(fill) };
     };
-    const inverse = against.inverseBg ? inverseOn(against.inverseBg) : null;
-    const inverseDark = against.inverseBg && against.inverseBgDark ? inverseOn(against.inverseBgDark) : null;
+    const inverse = hasGround(against.inverseBg) ? inverseOn(against.inverseBg as AccentGround) : null;
+    const inverseDark = hasGround(against.inverseBg) && hasGround(against.inverseBgDark) ? inverseOn(against.inverseBgDark as AccentGround) : null;
 
     const row = (name: AccentTokenName, value: string, darkValue?: string): FlavorTokenDef => ({
         name, value, type: 'color', group: 'colour', tier: 'semantic',

package/src/design-core/colour-eval.ts

@@ -0,0 +1,117 @@
+import { parseHexColor, Rgb, toHexColor } from './brand';
+
+/**
+ * What a token VALUE paints, as colours (design-system DS9): the evaluator the contrast audit and the
+ * brand-tinted neutrals read a resolved CSS value with. It understands exactly the colour syntax the
+ * contract writes — `#rgb`/`#rrggbb`, `rgb()`/`rgba()`, `transparent`, `currentColor`/`inherit`,
+ * `color-mix(in srgb, A p%, B)` (premultiplied, as CSS mixes), and a gradient layer list (each stop
+ * over the final plain layer: the page's paint shows every one of those to a reader somewhere).
+ * Port of iox-ai-guidance `design-system/colour.mjs` — held equal by the derivation fixtures.
+ */
+
+export interface Rgba extends Rgb { a: number; }
+
+const TRANSPARENT: Rgba = { r: 0, g: 0, b: 0, a: 0 };
+const NAMED: Readonly<Record<string, Rgba>> = {
+    transparent: TRANSPARENT,
+    white: { r: 1, g: 1, b: 1, a: 1 },
+    black: { r: 0, g: 0, b: 0, a: 1 },
+};
+const CURRENT_COLOR = new Set(['currentcolor', 'inherit']);
+const RGB_FN = /^rgba?\(([^)]*)\)$/i;
+const COLOR_MIX = /^color-mix\(\s*in srgb\s*,(.*)\)$/i;
+const MIX_STOP = /^(.*?)(?:\s+(\d+(?:\.\d+)?)%)?$/;
+const GRADIENT = /^(?:radial|linear|conic)-gradient\((.*)\)$/i;
+const STOP_POSITION = /\s+-?\d+(?:\.\d+)?%(\s+-?\d+(?:\.\d+)?%)?$/;
+const SHADOW_LAYER = /^(-?[\d.]+px|0)\s+(-?[\d.]+px|0)\s+(-?[\d.]+px|0)\s+(-?[\d.]+px|0)\s+(.+)$/;
+
+/** Split on top-level commas (never inside parentheses). */
+export function splitTopLevel(value: string, separator = ','): string[] {
+    const out: string[] = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of String(value ?? '')) {
+        if (ch === '(') depth++;
+        if (ch === ')') depth--;
+        if (ch === separator && depth === 0) { out.push(current.trim()); current = ''; continue; }
+        current += ch;
+    }
+    if (current.trim()) out.push(current.trim());
+    return out;
+}
+
+/** `top` composited over an opaque `under`. */
+export function compositeOver(top: Rgba, under: Rgb): Rgba {
+    const a = top.a;
+    return { r: top.r * a + under.r * (1 - a), g: top.g * a + under.g * (1 - a), b: top.b * a + under.b * (1 - a), a: 1 };
+}
+
+/** The 8-bit colour a screen shows — contrast is judged on WHAT SHIPS, as the derivation's grounds are. */
+export const quantizeRgb = (c: Rgb): Rgb => parseHexColor(toHexColor(c)) as Rgb;
+
+/** One CSS colour → RGBA, or null when it is not a colour this evaluator reads. `ink` = currentColor. */
+export function parseCssColour(value: string | null | undefined, ink?: Rgba | null): Rgba | null {
+    const v = String(value ?? '').trim();
+    const low = v.toLowerCase();
+    if (low in NAMED) return NAMED[low];
+    if (CURRENT_COLOR.has(low)) return ink ?? null;
+    const hex = parseHexColor(v);
+    if (hex) return { ...hex, a: 1 };
+    const rgb = RGB_FN.exec(v);
+    if (rgb) {
+        const p = rgb[1].split(/[\s,/]+/).filter(Boolean).map(Number);
+        return { r: p[0] / 255, g: p[1] / 255, b: p[2] / 255, a: p[3] ?? 1 };
+    }
+    const mix = COLOR_MIX.exec(v);
+    if (mix) return mixColours(splitTopLevel(mix[1]), ink);
+    return null;
+}
+
+function mixColours(parts: string[], ink: Rgba | null | undefined): Rgba | null {
+    const stop = (s: string) => {
+        const m = MIX_STOP.exec(s.trim()) as RegExpExecArray;
+        return { c: parseCssColour(m[1], ink), p: m[2] !== undefined ? Number(m[2]) / 100 : null };
+    };
+    const [x, y] = parts.map(stop);
+    if (!x?.c || !y?.c) return null;
+    const px = x.p ?? (y.p !== null ? 1 - y.p : 0.5);
+    const py = y.p ?? 1 - px;
+    const a = x.c.a * px + y.c.a * py;
+    if (a <= 0) return TRANSPARENT;
+    const channel = (k: keyof Rgb) => ((x.c as Rgba)[k] * (x.c as Rgba).a * px + (y.c as Rgba)[k] * (y.c as Rgba).a * py) / a;
+    return { r: channel('r'), g: channel('g'), b: channel('b'), a };
+}
+
+/**
+ * A paint → every colour a reader can meet ON it: a plain colour is one; a gradient layer list is each
+ * stop over the final plain layer, and that layer itself. The worst case is the one a check reads.
+ */
+export function paintColours(value: string | null | undefined, ink?: Rgba | null): Rgba[] {
+    const layers = splitTopLevel(String(value ?? ''));
+    if (!layers.length) return [];
+    const last = parseCssColour(layers[layers.length - 1], ink);
+    if (layers.length === 1) return last ? [last] : [];
+    if (!last) return [];
+    const ground: Rgba = { ...last, a: 1 };
+    const out: Rgba[] = [ground];
+    for (const layer of layers.slice(0, -1)) {
+        const g = GRADIENT.exec(layer);
+        if (!g) continue;
+        for (const part of splitTopLevel(g[1])) {
+            const colour = parseCssColour(part.replace(STOP_POSITION, ''), ink);
+            if (colour) out.push(compositeOver(colour, ground));
+        }
+    }
+    return out;
+}
+
+/** The outermost ring of a box-shadow list (`0 0 0 4px <colour>`) — a focus indicator's colour. */
+export function ringColour(shadow: string | null | undefined, ink?: Rgba | null): Rgba | null {
+    const layers = splitTopLevel(String(shadow ?? ''))
+        .map(l => SHADOW_LAYER.exec(l.trim()))
+        .filter((m): m is RegExpExecArray => !!m)
+        .map(m => ({ spread: parseFloat(m[4]) || 0, colour: m[5] }));
+    if (!layers.length) return null;
+    const outer = layers.reduce((a, b) => (b.spread >= a.spread ? b : a));
+    return parseCssColour(outer.colour, ink);
+}

package/src/design-core/contrast-audit.ts

@@ -0,0 +1,214 @@
+import { toHexColor, wcagContrastRatio, WCAG_AA_TEXT } from './brand';
+import { WCAG_AA_UI } from './brand-neutrals';
+import { compositeOver, paintColours, parseCssColour, quantizeRgb, Rgba, ringColour } from './colour-eval';
+import { ElementStyle, ELEMENT_STYLES } from './element-styles';
+import { SPEC_CONTRAST_AUDIT, SPEC_INK_SCOPES, SPEC_SCHEMES } from './flavor-spec.generated';
+import { DesignTokenLike, ResolvedMode, resolveSchemeTokenValues } from './token-css';
+
+/**
+ * The contrast AUDIT (design-system DS9). The contract's token pairs were all AA and Doron still found a
+ * button whose icon was "almost hard to see": the failures live in the PAIRINGS element styles make — an
+ * Icon dropped into a Primary button painted `icon-color` (accent-text) on the accent fill, 1:1 in a Brand
+ * section. So this resolves what each element style actually paints, the way CSS resolves it:
+ *
+ * - in every section scheme (`resolveSchemeTokenValues`), directly on the section and inside every
+ *   container style (Card, Panel, Navigation bar, Dialog);
+ * - `inherit` → the container's ink, a transparent fill → what is under it, translucent fills composited,
+ *   a gradient ground (Glass's mesh, Midnight's glow) checked at its worst stop;
+ * - base and hover; a button's icon read through the contract's `inkScopes` (it takes the button's ink),
+ *   its focus ring; the form parts the field baseline paints (`contrastAudit.formParts`).
+ *
+ * WCAG 2: 4.5:1 for text, 3:1 for glyphs, UI boundaries and focus indicators (1.4.11), judged on 8-bit
+ * colours. The same audit gates the contract (`colour.mjs auditContrast`, every flavor × tint × a seed
+ * sweep) and `contrast-audit.spec.ts` sweeps it here, so no pack or brand can regress.
+ */
+
+export interface ContrastFinding {
+    scheme: string;
+    /** `section`, or the container style the element sits in. */
+    container: string;
+    element: string;
+    part: string;
+    fg: string;
+    bg: string;
+    ratio: number;
+    min: number;
+    pass: boolean;
+}
+
+interface FormPart {
+    readonly part: string;
+    readonly fg: string | ReadonlyArray<string>;
+    readonly on?: string;
+    readonly any?: boolean;
+    readonly thumb?: string;
+    readonly min: number;
+}
+interface InkScope { readonly styles: ReadonlyArray<string>; readonly set: Readonly<Record<string, string>>; }
+
+const FORM_PARTS: ReadonlyArray<FormPart> = SPEC_CONTRAST_AUDIT.formParts;
+const INK_SCOPES: ReadonlyArray<InkScope> = SPEC_INK_SCOPES;
+const SCHEME_IDS: ReadonlyArray<string> = Object.keys(SPEC_SCHEMES);
+const CONTAINER_GROUPS: ReadonlySet<string> = new Set(['Layout', 'Overlays']);
+const NOT_CONTENT: ReadonlySet<string> = new Set(['rule', 'media']);
+const SECTION_STYLE = 'section';
+const ICON_STYLE = 'icon';
+const BUTTON_GROUP = 'Buttons';
+const GLYPH_GROUP = 'Media';
+const FORMS_GROUP = 'Forms';
+const DEFAULT_SCHEME = 'default';
+const SECTION = 'section';
+const FIELD = 'field';
+const WHITE: Rgba = { r: 1, g: 1, b: 1, a: 1 };
+const SINGLE_REF = /^var\(--iox-([\w-]+)\)$/;
+const TOKEN_REF = /var\(\s*--iox-([\w-]+)\s*(?:,([^()]*))?\)/g;
+
+type Values = Readonly<Record<string, string>>;
+type StyleMap = Readonly<Record<string, string>>;
+
+/** A style value with its var() references resolved against `values` (already-resolved tokens). */
+function resolveIn(values: Values, v: string | undefined): string {
+    const single = SINGLE_REF.exec(String(v ?? '').trim());
+    if (single) return values[single[1]] ?? (v as string);
+    return String(v ?? '').replace(TOKEN_REF, (ref, name: string, fallback?: string) =>
+        values[name] ?? (fallback !== undefined ? fallback.trim() : ref));
+}
+
+const overAll = (tops: Rgba[], unders: Rgba[]) => unders.flatMap(u => tops.map(t => compositeOver(t, u)));
+const opaque = (paints: Rgba[]) => paints.some(c => c.a > 0);
+
+const ownStyle = (e: ElementStyle) => (e.base ?? {}) as StyleMap;
+
+function inkScoped(values: Values, styleId: string): Values {
+    const scope = INK_SCOPES.find(s => s.styles.includes(styleId));
+    return scope ? { ...values, ...scope.set } : values;
+}
+
+/** Every pair a reader meets, for one set of token rows in one mode. */
+export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode: ResolvedMode): ContrastFinding[] {
+    const findings: ContrastFinding[] = [];
+    const styles = ELEMENT_STYLES;
+    const byId = new Map(styles.map(e => [e.id, e]));
+    const containers: Array<ElementStyle | null> = [
+        null,
+        ...styles.filter(e => CONTAINER_GROUPS.has(e.group) && ownStyle(e)['backgroundColor'] && e.id !== SECTION_STYLE),
+    ];
+    const content = styles.filter(e => !CONTAINER_GROUPS.has(e.group) && (ownStyle(e)['color'] || ownStyle(e)['backgroundColor'])
+        && e.group !== FORMS_GROUP && !NOT_CONTENT.has(e.id));
+    const notices = styles.filter(e => e.group === FORMS_GROUP && ownStyle(e)['color']);
+    const section = ownStyle(byId.get(SECTION_STYLE) as ElementStyle);
+    const iconColour = ownStyle(byId.get(ICON_STYLE) as ElementStyle)['color'];
+
+    for (const schemeId of SCHEME_IDS) {
+        const values = resolveSchemeTokenValues(rows, mode, schemeId);
+        const pageInk = parseCssColour(values['text']);
+        const page = paintColours(values['page-bg'], pageInk);
+        const sectionPaint = paintColours(values['section-bg'], pageInk);
+        const ground = opaque(sectionPaint)
+            ? sectionPaint.map(c => (c.a < 1 ? compositeOver(c, page[0] ?? WHITE) : c))
+            : page;
+        const sectionInk = parseCssColour(resolveIn(values, section['color']), pageInk);
+
+        for (const box of containers) {
+            const boxStyle = box ? ownStyle(box) : null;
+            const bgs = boxStyle ? overAll(paintColours(resolveIn(values, boxStyle['backgroundColor']), sectionInk), ground) : ground;
+            const boxInk = boxStyle?.['color'] && boxStyle['color'] !== 'inherit'
+                ? parseCssColour(resolveIn(values, boxStyle['color']), sectionInk) : sectionInk;
+            const where = { scheme: schemeId, container: box?.id ?? SECTION };
+            const record = (element: string, part: string, fg: string, bg: string, ratio: number, min: number) =>
+                findings.push({ ...where, element, part, fg, bg, ratio: Math.round(ratio * 100) / 100, min, pass: ratio >= min - 1e-9 });
+            const check = (element: string, part: string, fg: Rgba | null, under: Rgba[], min: number) => {
+                if (!fg) return;
+                for (const g of under) {
+                    const bg = quantizeRgb(g);
+                    const f = quantizeRgb(fg.a < 1 ? compositeOver(fg, bg) : fg);
+                    record(element, part, toHexColor(f), toHexColor(bg), wcagContrastRatio(f, bg), min);
+                }
+            };
+
+            check(box?.id ?? SECTION, 'text', boxInk, bgs, WCAG_AA_TEXT);
+            for (const e of content) {
+                const states: Array<[string, StyleMap]> = [['base', ownStyle(e)], ...(e.hover ? [['hover', { ...ownStyle(e), ...e.hover }] as [string, StyleMap]] : [])];
+                const glyph = e.group === GLYPH_GROUP;
+                for (const [state, s] of states) {
+                    const fill = s['backgroundColor'] ? paintColours(resolveIn(values, s['backgroundColor']), boxInk) : [];
+                    const under = fill.length && opaque(fill) ? overAll(fill, bgs) : bgs;
+                    const ink = s['color'] ? parseCssColour(resolveIn(values, s['color']), boxInk) : boxInk;
+                    check(e.id, state === 'base' ? (glyph ? 'glyph' : 'text') : `${state} text`, ink, under, glyph ? WCAG_AA_UI : WCAG_AA_TEXT);
+                    if (state === 'base' && e.group === BUTTON_GROUP) {
+                        check(e.id, 'icon', parseCssColour(resolveIn(inkScoped(values, e.id), iconColour), ink), under, WCAG_AA_UI);
+                        const focus = (e.focus as StyleMap | undefined)?.['boxShadow'];
+                        if (focus) check(e.id, 'focus ring', ringColour(resolveIn(values, focus), ink), bgs, WCAG_AA_UI);
+                    }
+                }
+            }
+            for (const part of FORM_PARTS) {
+                const fieldBg = paintColours(resolveIn(values, part.on ?? 'transparent'), boxInk);
+                const under = part.on && opaque(fieldBg) ? overAll(fieldBg, bgs) : bgs;
+                if (part.any) {
+                    for (const g of under) {
+                        const bg = quantizeRgb(g);
+                        const ratio = Math.max(...(part.fg as ReadonlyArray<string>).map(fg => {
+                            const c = parseCssColour(resolveIn(values, fg), boxInk);
+                            return c ? wcagContrastRatio(quantizeRgb(c.a < 1 ? compositeOver(c, bg) : c), bg) : 1;
+                        }));
+                        record(FIELD, part.part, '', toHexColor(bg), ratio, part.min);
+                    }
+                    continue;
+                }
+                const paint = parseCssColour(resolveIn(values, part.fg as string), boxInk);
+                check(FIELD, part.part, paint, under, part.min);
+                if (part.thumb && paint) {
+                    check(FIELD, `${part.part} thumb`, parseCssColour(resolveIn(values, part.thumb), boxInk), bgs.map(b => compositeOver(paint, b)), part.min);
+                }
+            }
+            if (box === null && schemeId === DEFAULT_SCHEME) {
+                for (const n of notices) {
+                    const fill = paintColours(resolveIn(values, ownStyle(n)['backgroundColor']), boxInk);
+                    check(n.id, 'text', parseCssColour(resolveIn(values, ownStyle(n)['color']), boxInk), overAll(fill, bgs), WCAG_AA_TEXT);
+                }
+            }
+        }
+    }
+    return findings;
+}
+
+/** The pairs the Design ▸ Colour tab lists for the CURRENT brand (Board 6 + DS9): what a filled button
+ *  shows, and the link on every section scheme — each the worst case on the section itself. */
+export enum ColourCheckId {
+    ButtonLabel = 'button-label',
+    ButtonIcon = 'button-icon',
+    Link = 'link',
+}
+
+export interface ColourCheck {
+    id: ColourCheckId;
+    /** The section scheme the pair sits in (`default` for the button). */
+    scheme: string;
+    fg: string;
+    bg: string;
+    ratio: number;
+    min: number;
+    passes: boolean;
+}
+
+const COLOUR_TAB_CHECKS: ReadonlyArray<{ id: ColourCheckId; element: string; part: string; schemes: ReadonlyArray<string> }> = [
+    { id: ColourCheckId.ButtonLabel, element: 'button-primary', part: 'text', schemes: [DEFAULT_SCHEME] },
+    { id: ColourCheckId.ButtonIcon, element: 'button-primary', part: 'icon', schemes: [DEFAULT_SCHEME] },
+    { id: ColourCheckId.Link, element: 'link', part: 'text', schemes: SCHEME_IDS },
+];
+
+/** The Colour tab's brand rows, from one audit of the rows the canvas wears. */
+export function colourTabChecks(rows: ReadonlyArray<DesignTokenLike>, mode: ResolvedMode): ColourCheck[] {
+    const findings = auditDesignContrast(rows, mode).filter(f => f.container === SECTION);
+    const out: ColourCheck[] = [];
+    for (const check of COLOUR_TAB_CHECKS) {
+        for (const scheme of check.schemes) {
+            const hits = findings.filter(f => f.scheme === scheme && f.element === check.element && f.part === check.part);
+            if (!hits.length) continue;
+            const worst = hits.reduce((a, b) => (b.ratio < a.ratio ? b : a));
+            out.push({ id: check.id, scheme, fg: worst.fg, bg: worst.bg, ratio: worst.ratio, min: worst.min, passes: worst.pass });
+        }
+    }
+    return out;
+}