@vectoriox/iox-ui 5.25.0 → 5.27.0

package/generation-core/package.json

@@ -0,0 +1,3 @@
+{
+  "module": "../fesm2022/vectoriox-iox-ui-generation-core.mjs"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.25.0",
+  "version": "5.27.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -35,6 +35,10 @@
       "types": "./forms-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-forms-core.mjs"
     },
+    "./generation-core": {
+      "types": "./generation-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-generation-core.mjs"
+    },
     "./seo-core": {
       "types": "./seo-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-seo-core.mjs"

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