@vectoriox/iox-ui 5.9.0 → 5.11.0

package/src/design-core/flavor-tokens.ts

@@ -0,0 +1,103 @@
+import { deriveAccentTokens } from './brand';
+import { cssString } from './fonts';
+import { SPEC_AXES } from './flavor-spec.generated';
+import {
+    DesignChoices, DesignTokenRow, FlavorPackV2, FlavorSpecToken, flavorSourceStamp, USER_TOKEN_SOURCE,
+} from './design-token.model';
+
+/**
+ * A flavor's COMPLETE token set for a studio's choices (design-system plan §3a/§3e). A flavor IS
+ * its token values, so switching flavor — or any choice — rewrites token rows and nothing else.
+ *
+ * Layering, each step over the last (the boards' `tokenMap`, with the product's colour math):
+ *   pack tokens → chosen font pair → shape · density · motion axes → pill-button rule →
+ *   the author's own font roles → a seed ≠ the pack's own re-derives the accent quartet.
+ *
+ * `mode` does not change rows — every row keeps its light value and its dark override; mode is
+ * how the stylesheet is compiled.
+ */
+
+const LABEL = 'label';
+const BUTTON_RADIUS = 'button-radius';
+const PILL_RADIUS = 'var(--iox-radius-pill)';
+const CONTROL_RADIUS = 'var(--iox-radius-sm)';
+const USER_FONT_FALLBACK = 'system-ui, sans-serif';
+
+type AxisTable = Readonly<Record<string, Readonly<Record<string, string>>>>;
+
+const axisValues = (table: AxisTable, id: string): Array<[string, string]> =>
+    Object.entries(table[id] ?? {}).filter(([k]) => k !== LABEL);
+
+/** The pack's own defaults as a full set of choices — what Apply means with nothing changed. */
+export function defaultDesignChoices(pack: FlavorPackV2): DesignChoices {
+    return {
+        flavorId: pack.id,
+        seed: pack.seed,
+        pairId: pack.pairs[0]?.id ?? '',
+        ...pack.defaults,
+    };
+}
+
+/** `'<Family>', system-ui, sans-serif` — the value a font role holds once the author picks a face. */
+export function userFontStack(family: string): string {
+    return `${cssString(family.trim())}, ${USER_FONT_FALLBACK}`;
+}
+
+const toRow = (t: FlavorSpecToken, source: string): DesignTokenRow => ({
+    name: t.name,
+    type: t.type,
+    value: t.value,
+    ...(t.dark !== undefined ? { values: { dark: t.dark } } : {}),
+    source,
+    group: t.group,
+    tier: t.tier,
+});
+
+export function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): DesignTokenRow[] {
+    const stamp = flavorSourceStamp(pack.id);
+    const rows = pack.tokens.map(t => toRow(t, stamp));
+    const byName = new Map(rows.map(r => [r.name, r]));
+
+    /** An override is ONE value in every mode — a pair or axis value has no dark twin. */
+    const set = (name: string, value: string, source = stamp) => {
+        const row = byName.get(name);
+        if (!row) return;
+        row.value = value;
+        delete row.values;
+        row.source = source;
+    };
+
+    const pair = pack.pairs.find(p => p.id === choices.pairId) ?? pack.pairs[0];
+    for (const [name, value] of Object.entries(pair?.tokens ?? {})) set(name, value);
+
+    const axes = SPEC_AXES;
+    for (const [name, value] of [
+        ...axisValues(axes.shapes, choices.shape),
+        ...axisValues(axes.densities, choices.density),
+        ...axisValues(axes.motions, choices.motion),
+    ]) set(name, value);
+
+    const buttonRadius = pack.tokens.find(t => t.name === BUTTON_RADIUS);
+    set(BUTTON_RADIUS, choices.pillButtons ? PILL_RADIUS : (buttonRadius?.overridden ? buttonRadius.value : CONTROL_RADIUS));
+
+    for (const [role, family] of Object.entries(choices.fonts ?? {})) {
+        if (typeof family === 'string' && family.trim() !== '') set(role, userFontStack(family), USER_TOKEN_SOURCE);
+    }
+
+    if (choices.seed && choices.seed.toLowerCase() !== pack.seed.toLowerCase()) {
+        const bg = byName.get('bg');
+        const inverseBg = byName.get('inverse-bg');
+        for (const accent of deriveAccentTokens(choices.seed, {
+            bg: bg?.value ?? '', bgDark: bg?.values?.dark,
+            inverseBg: inverseBg?.value, inverseBgDark: inverseBg?.values?.dark,
+        })) {
+            const row = byName.get(accent.name);
+            if (!row) continue;
+            row.value = accent.value;
+            if (accent.values?.dark) row.values = { dark: accent.values.dark };
+            else delete row.values;
+        }
+    }
+
+    return rows;
+}

package/src/design-core/flavor.ts

@@ -0,0 +1,137 @@
+import { styleKeyToKebab } from './css-names';
+import { DesignTokenGroup, DesignTokenTier, DesignTokenType } from './design-token.model';
+
+/**
+ * Flavors (flavors-and-theming-plan.md, F1): the design language a studio launches with,
+ * expressed as data. THE invariant — a flavor never writes a literal into a node; it writes
+ * tokens, and element defaults that REFERENCE tokens. To that end a pack's `defaults` map
+ * holds TOKEN NAMES, not CSS values: the resolver builds `var(--iox-<name>, <packValue>)`,
+ * so smuggling a literal in is impossible by construction, and the validator only has to
+ * check that every referenced token exists.
+ *
+ * The fallback is the bootstrap: until F2 seeds the org's `designtokens` rows, no `--iox-*`
+ * var is defined anywhere, and `var(--iox-radius-control, 4px)` must still paint identically
+ * in the builder canvas and the SSR page. Once tokens ARE seeded (or re-themed), the var wins
+ * over the fallback everywhere — which is exactly the §3 propagation story.
+ */
+
+export interface FlavorTokenDef {
+    name: string;
+    value: string;
+    /** Dark-scheme override, seeded into DesignToken.values.dark at F2. */
+    values?: { dark?: string };
+    type?: DesignTokenType;
+    group?: DesignTokenGroup;
+    tier?: DesignTokenTier;
+}
+
+export interface FlavorPack {
+    id: string;
+    /** Bumped when the pack's values change; seeding stamps `flavor:<id>@<version>` as DesignToken.source. */
+    version: number;
+    label: string;
+    blurb: string;
+    tokens: FlavorTokenDef[];
+    /** type → styleTrait → TOKEN NAME (never a CSS value — see the module header). */
+    defaults: Record<string, Record<string, string>>;
+    /** F2: the accent's hue rotation (degrees in OKLab) from the brand seed — a pack opinion. */
+    accentHueDeg?: number;
+}
+
+/** trait → `var(--iox-<token>, <packValue>)` for one node type. Unknown type → {}. */
+export function resolveFlavorDefaults(
+    type: string,
+    pack: FlavorPack | null | undefined,
+): Record<string, string> {
+    const map = pack?.defaults?.[type];
+    if (!map) return {};
+    const byName = new Map((pack!.tokens ?? []).map(t => [t.name, t.value]));
+    const out: Record<string, string> = {};
+    for (const [trait, tokenName] of Object.entries(map)) {
+        const fallback = byName.get(tokenName);
+        if (fallback === undefined) continue;   // validator fails the build; runtime stays safe
+        out[trait] = `var(--iox-${tokenName}, ${fallback})`;
+    }
+    return out;
+}
+
+/**
+ * The ENGINE's half of the cascade: kebab `prop: var(…)` declarations for every pack default
+ * the node's persisted styleProps does NOT set. Appended beside renderDefaultDeclarations —
+ * same guard-on-undefined discipline, so a node saved post-F1 (var already serialised via the
+ * builder's trait defaults) is untouched, and a legacy node picks the pack default up at
+ * render time. Node styleProps always wins.
+ */
+export function flavorDefaultDeclarations(
+    type: string,
+    styleProps: Record<string, any> | null | undefined,
+    pack: FlavorPack | null | undefined,
+): string[] {
+    const sp = styleProps ?? {};
+    const out: string[] = [];
+    for (const [trait, value] of Object.entries(resolveFlavorDefaults(type, pack))) {
+        if (sp[trait] === undefined) out.push(`${styleKeyToKebab(trait)}: ${value}`);
+    }
+    return out;
+}
+
+/**
+ * The CI gate (flavors plan §10 C4): a pack may only name types and traits that exist in the
+ * live component registry, and tokens it defines itself. Returns human-readable errors; a
+ * consumer spec feeds it the REAL registry and asserts [].
+ */
+export function validateFlavorPack(
+    pack: FlavorPack,
+    knownTraitsByType: Record<string, ReadonlySet<string> | string[]>,
+): string[] {
+    const errors: string[] = [];
+    const tokenNames = new Set((pack.tokens ?? []).map(t => t.name));
+    for (const t of pack.tokens ?? []) {
+        if (!t.name) errors.push(`${pack.id}: token with empty name`);
+        if (!t.value) errors.push(`${pack.id}: token "${t.name}" has no value`);
+    }
+    for (const [type, traits] of Object.entries(pack.defaults ?? {})) {
+        const known = knownTraitsByType[type];
+        if (!known) { errors.push(`${pack.id}: unknown component type "${type}"`); continue; }
+        const knownSet = known instanceof Set ? known : new Set(known);
+        for (const [trait, tokenName] of Object.entries(traits)) {
+            if (!knownSet.has(trait)) errors.push(`${pack.id}: "${type}" has no style trait "${trait}"`);
+            if (!tokenNames.has(tokenName)) errors.push(`${pack.id}: "${type}.${trait}" references undefined token "${tokenName}"`);
+            if (/[:(]|^#|\d/.test(tokenName)) errors.push(`${pack.id}: "${type}.${trait}" must name a token, not a value ("${tokenName}")`);
+        }
+    }
+    return errors;
+}
+
+/**
+ * Swiss — the default pack (flavors plan §8: "the flavor that can never embarrass anyone").
+ * Deliberately SMALL at F1: radius + control padding on the clickables, surface radius on Card.
+ * Colour, type and motion arrive with the brand step (F2) — a colour default here would repaint
+ * legacy pages before anyone chose anything.
+ */
+export const SWISS_FLAVOR: FlavorPack = {
+    id: 'swiss',
+    version: 1,
+    label: 'Swiss',
+    blurb: 'Grid discipline, hairline rules, near-zero motion.',
+    tokens: [
+        { name: 'radius-control', value: '4px', type: 'size', group: 'shape' },
+        { name: 'radius-surface', value: '4px', type: 'size', group: 'shape' },
+        { name: 'space-control', value: '10px 18px', type: 'spacing', group: 'space' },
+        { name: 'space-stack', value: '12px', type: 'spacing', group: 'space' },
+    ],
+    defaults: {
+        Button: { borderRadius: 'radius-control', padding: 'space-control' },
+        ButtonBlock: { borderRadius: 'radius-control', padding: 'space-control' },
+        Card: { borderRadius: 'radius-surface' },
+    },
+    // F2: Swiss turns the seed toward a cool counterpoint. NOTE deliberately: the brand tokens
+    // deriveBrandTokens() emits are SEEDED per org — they do not join `defaults` here, because a
+    // colour default repaints legacy nodes whose saved styleProps lack the key (the engine fills
+    // missing keys from config defaults). Coloured element defaults are a Swiss v2 upgrade
+    // decision (§10 C2), taken with the picker in front of the author — never a side effect.
+    accentHueDeg: 150,
+};
+
+/** What both renderers use until F2 lets an org choose. */
+export const DEFAULT_FLAVOR: FlavorPack = SWISS_FLAVOR;

package/src/design-core/fonts.ts

@@ -0,0 +1,98 @@
+import { SPEC_FONTS } from './flavor-spec.generated';
+import { DesignTokenLike } from './token-css';
+
+/**
+ * Fonts (design-system plan §5b, D7): ONE Google catalog for both renderers, and ONE face builder
+ * for the families a studio uploads.
+ */
+
+/** Family name → Google Fonts css2 `family=` id. Replaces the engine's private GOOGLE_FONTS map. */
+export const FONT_CATALOG: Readonly<Record<string, string>> = SPEC_FONTS;
+
+export type FontFormat = 'woff2' | 'woff' | 'truetype' | 'opentype';
+export type FontStyle = 'normal' | 'italic';
+
+/** One uploaded font FILE (spec `fontDescriptor`) — a family is all descriptors sharing `family`. */
+export interface FontDescriptor {
+    family: string;
+    /** 100–900, from the file's OS/2 `usWeightClass`. */
+    weight: number;
+    style: FontStyle;
+    url: string;
+    format: FontFormat;
+}
+
+/** The token roles whose values name the families a page renders in. */
+export const FONT_FAMILY_TOKENS = ['font-display', 'font-body', 'font-label', 'font-mono'] as const;
+
+const DEFAULT_WEIGHT = 400;
+const MIN_WEIGHT = 100;
+const MAX_WEIGHT = 900;
+const FONT_FORMATS: ReadonlyArray<FontFormat> = ['woff2', 'woff', 'truetype', 'opentype'];
+
+/**
+ * A CSS string literal, single-quoted: `\` and `'` escaped, line breaks and NUL dropped, and `<` /
+ * `>` hex-escaped (`\3c `) — the face CSS is inlined into a `<style>` by the SSR engine, where an
+ * uploaded family named `</style><script>` would otherwise close the element.
+ */
+export function cssString(value: string): string {
+    const body = String(value)
+        .replace(/[\r\n\f\0]/g, '')
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/</g, '\\3c ')
+        .replace(/>/g, '\\3e ');
+    return `'${body}'`;
+}
+
+const clampWeight = (w: unknown): number => {
+    const n = Math.round(Number(w));
+    return Number.isFinite(n) && n > 0 ? Math.min(MAX_WEIGHT, Math.max(MIN_WEIGHT, n)) : DEFAULT_WEIGHT;
+};
+
+/** One `@font-face` per file, carrying its real weight and style — so bold is never synthesised. */
+export function buildFontFaceCss(descriptors: ReadonlyArray<FontDescriptor> | null | undefined): string {
+    return (descriptors ?? [])
+        .filter(d => !!d && typeof d.family === 'string' && d.family.trim() !== '' && typeof d.url === 'string' && d.url !== '')
+        .map(d => {
+            const format = FONT_FORMATS.includes(d.format) ? ` format(${cssString(d.format)})` : '';
+            return [
+                '@font-face {',
+                `  font-family: ${cssString(d.family.trim())};`,
+                `  src: url(${cssString(d.url)})${format};`,
+                `  font-weight: ${clampWeight(d.weight)};`,
+                `  font-style: ${d.style === 'italic' ? 'italic' : 'normal'};`,
+                '  font-display: swap;',
+                '}',
+            ].join('\n');
+        })
+        .join('\n');
+}
+
+/** The family names in a CSS `font-family` stack, unquoted, in order. */
+export function parseFontFamilies(stack: string): string[] {
+    return String(stack ?? '')
+        .split(',')
+        .map(f => f.trim().replace(/^(['"])(.*)\1$/, '$2').trim())
+        .filter(Boolean);
+}
+
+/**
+ * The Google css2 ids to load for a token set: every catalog family named by a font role token,
+ * one id per family (T7 — one `<link>` per family, so one bad id cannot sink the others).
+ */
+export function fontsForTokens(tokens: ReadonlyArray<DesignTokenLike> | null | undefined): string[] {
+    const seen = new Set<string>();
+    const ids: string[] = [];
+    for (const role of FONT_FAMILY_TOKENS) {
+        const row = (tokens ?? []).find(t => t?.name === role);
+        for (const family of parseFontFamilies(row?.value ?? '')) {
+            const id = FONT_CATALOG[family];
+            if (id && !seen.has(family)) {
+                seen.add(family);
+                ids.push(id);
+            }
+        }
+    }
+    return ids;
+}

package/src/design-core/public-api.ts

@@ -0,0 +1,20 @@
+/**
+ * @vectoriox/iox-ui/design-core — the shared, FRAMEWORK-FREE core of the design system
+ * (design-system plan §3e): the token vocabulary, the flavor contract (generated 1:1 from
+ * iox-ai-guidance `flavor-spec.v1.json`), `buildFlavorTokens`, the token stylesheet compiler, the
+ * spring easing, the font catalog and face builder, and the seed/revert planners.
+ * Consumed by the builder, the SSR engine AND iox-cms (the server-side site build) — so nothing
+ * here may import Angular. The main entry re-exports all of it, so `@vectoriox/iox-ui` keeps working.
+ * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig
+ * paths — or `nest start` dies with ERR_REQUIRE_ESM while jest and build both pass.
+ */
+export * from './flavor-spec.generated';
+export * from './design-token.model';
+export * from './css-names';
+export * from './token-css';
+export * from './flavor';
+export * from './brand';
+export * from './flavor-tokens';
+export * from './flavor-seed';
+export * from './spring';
+export * from './fonts';

package/src/design-core/spring.ts

@@ -0,0 +1,49 @@
+/**
+ * A damped spring as a CSS `linear()` easing (design-system plan §3e) — the algorithm the spec's
+ * generator (`build-spec.mjs` `spring()`) uses to write `springs.lively`, so a spring computed at
+ * runtime is byte-identical to the one in the contract.
+ *
+ * `stiffness` is k (ω₀ = √k), `damping` the ratio ζ: < 1 under-damped, = 1 critically damped,
+ * > 1 over-damped. Both must be positive and finite — a zero or negative spring never settles.
+ * Duration = the last instant the curve is more than 0.1% away from rest, rounded up to 10ms.
+ */
+const SETTLE_TOLERANCE = 0.001;
+const SETTLE_HORIZON_S = 3;
+const SETTLE_STEP_S = 0.001;
+const SAMPLES = 40;
+const DECIMALS = 4;
+const ROUND_TO_MS = 10;
+
+/** Displacement from rest → target (0 → 1) of a unit-mass spring released at rest. */
+function springPosition(w0: number, damping: number): (t: number) => number {
+    if (damping < 1) {
+        const wd = w0 * Math.sqrt(1 - damping * damping);
+        return t => 1 - Math.exp(-damping * w0 * t) * (Math.cos(wd * t) + ((damping * w0) / wd) * Math.sin(wd * t));
+    }
+    if (damping === 1) return t => 1 - Math.exp(-w0 * t) * (1 + w0 * t);
+    // Over-damped: two real, negative roots. Written with exponentials of the roots, not cosh/sinh,
+    // which overflow for a stiff, heavily damped spring well inside the settle horizon.
+    const root = w0 * Math.sqrt(damping * damping - 1);
+    const r1 = -damping * w0 + root;
+    const r2 = -damping * w0 - root;
+    return t => 1 - (r2 * Math.exp(r1 * t) - r1 * Math.exp(r2 * t)) / (r2 - r1);
+}
+
+export interface LinearSpring {
+    easing: string;
+    duration: string;
+}
+
+export function springToLinear(stiffness: number, damping: number): LinearSpring {
+    if (!(Number.isFinite(stiffness) && stiffness > 0) || !(Number.isFinite(damping) && damping > 0)) {
+        throw new RangeError(`springToLinear: stiffness and damping must be > 0 (got ${stiffness}, ${damping})`);
+    }
+    const x = springPosition(Math.sqrt(stiffness), damping);
+    let settle = 0;
+    for (let t = 0; t < SETTLE_HORIZON_S; t += SETTLE_STEP_S) if (Math.abs(1 - x(t)) > SETTLE_TOLERANCE) settle = t;
+    const durationMs = Math.ceil((settle * 1000) / ROUND_TO_MS) * ROUND_TO_MS;
+    const points: number[] = [];
+    for (let i = 0; i <= SAMPLES; i++) points.push(+x((settle * i) / SAMPLES).toFixed(DECIMALS));
+    points[SAMPLES] = 1;
+    return { easing: `linear(${points.join(', ')})`, duration: `${durationMs}ms` };
+}

package/src/design-core/token-css.ts

@@ -0,0 +1,233 @@
+import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
+
+/**
+ * Design-token → CSS compilation, shared by BOTH renderers (flavors F0, design-system DS1).
+ *
+ * A token row is `{ name, value }` plus an optional per-scheme override `values.dark`.
+ * A value that references another token (`var(--iox-surface)`) passes through verbatim.
+ *
+ * Block order (design-system plan §3e, T8):
+ *   1. base            `:root { --iox-*: … }`
+ *   2. schemes         `.iox-scheme-<id> { overrides; every var()-referencing token re-declared }`
+ *   3. reduced motion  `@media (prefers-reduced-motion: reduce)`
+ *   4. reduced transparency `@media (prefers-reduced-transparency: reduce)`
+ *   5. dark — LAST     `@media (prefers-color-scheme: dark)`
+ *
+ * ⚠️ The appended-last contract: the dark block REDEFINES custom properties, so every consumer
+ * appends it AFTER all of its base rules — the engine pushes it after the page's css blocks, the
+ * builder registry keeps it as its last token rule (responsive A3 lesson).
+ */
+
+/** The transport-agnostic token row. `source` marks seeded rows (`flavor:<id>@<ver>`). */
+export interface DesignTokenLike {
+    name: string;
+    value: string;
+    /** Per-scheme overrides. Only `dark` exists today; absent means the base value everywhere. */
+    values?: { dark?: string };
+    type?: string;
+    source?: string;
+}
+
+export interface TokenCssOptions {
+    /** Selector that carries the variables instead of `:root` — a preview wrapper, a specimen. */
+    scope?: string;
+}
+
+export interface TokenCssBlocks {
+    /** Base, schemes and the two accessibility blocks — emitted BEFORE node rules. */
+    base: string;
+    /** The prefers-color-scheme block(s) — emitted AFTER every base rule. */
+    dark: string;
+}
+
+/** What `prefers-reduced-motion: reduce` collapses — the contract's complete list (`a11y.reducedMotion`). */
+export const REDUCED_MOTION_OVERRIDES: Readonly<Record<string, string>> = SPEC_A11Y.reducedMotion;
+
+/** What `prefers-reduced-transparency: reduce` makes solid — the contract's `a11y.reducedTransparency`. */
+export const REDUCED_TRANSPARENCY_OVERRIDES: Readonly<Record<string, string>> = SPEC_A11Y.reducedTransparency;
+
+const ROOT = ':root';
+const DEFAULT_SCHEME = 'default';
+const REFERENCE = 'var(';
+const MEDIA_DARK = '(prefers-color-scheme: dark)';
+const ACCESSIBILITY_MEDIA: ReadonlyArray<{ query: string; overrides: Readonly<Record<string, string>> }> = [
+    { query: '(prefers-reduced-motion: reduce)', overrides: REDUCED_MOTION_OVERRIDES },
+    { query: '(prefers-reduced-transparency: reduce)', overrides: REDUCED_TRANSPARENCY_OVERRIDES },
+];
+
+const usable = (t: DesignTokenLike | null | undefined): t is DesignTokenLike =>
+    !!t && typeof t.name === 'string' && t.name !== '' &&
+    typeof t.value === 'string' && t.value !== '';
+
+const darkOf = (t: DesignTokenLike): string | null => {
+    const dark = t.values?.dark;
+    return typeof dark === 'string' && dark !== '' ? dark : null;
+};
+
+const usableTokens = (tokens: ReadonlyArray<DesignTokenLike> | null | undefined): DesignTokenLike[] =>
+    (tokens ?? []).filter(usable);
+
+const declarations = (entries: ReadonlyArray<[string, string]>, indent: string): string =>
+    entries.map(([name, value]) => `${indent}--iox-${name}: ${value};`).join('\n');
+
+const rule = (selector: string, entries: ReadonlyArray<[string, string]>, indent = ''): string =>
+    entries.length ? `${indent}${selector} {\n${declarations(entries, indent + '  ')}\n${indent}}` : '';
+
+const media = (query: string, rules: ReadonlyArray<string>): string => {
+    const body = rules.filter(Boolean);
+    return body.length ? `@media ${query} {\n${body.join('\n')}\n}` : '';
+};
+
+const schemeSelector = (id: string, scope?: string) =>
+    scope ? `${scope} .iox-scheme-${id}` : `.iox-scheme-${id}`;
+
+const nonDefaultSchemes = (): ReadonlyArray<[string, Readonly<Record<string, string>>]> =>
+    Object.entries(SPEC_SCHEMES)
+        .filter(([id]) => id !== DEFAULT_SCHEME)
+        .map(([id, scheme]) => [id, scheme.set as Readonly<Record<string, string>>]);
+
+/** `{ 'iox-brand': '#2f6f62', … }` — the builder registry's input shape for base values. */
+export function tokensToVarMap(tokens: ReadonlyArray<DesignTokenLike> | null | undefined): Record<string, string> {
+    const map: Record<string, string> = {};
+    for (const t of usableTokens(tokens)) map[`iox-${t.name}`] = t.value;
+    return map;
+}
+
+/** Only the tokens that carry a dark override, as `{ 'iox-name': darkValue }`. */
+export function tokensToDarkVarMap(tokens: ReadonlyArray<DesignTokenLike> | null | undefined): Record<string, string> {
+    const map: Record<string, string> = {};
+    for (const t of usableTokens(tokens)) {
+        const dark = darkOf(t);
+        if (dark !== null) map[`iox-${t.name}`] = dark;
+    }
+    return map;
+}
+
+const TOKEN_REF = /var\(\s*--iox-([\w-]+)\s*(?:,([^()]*))?\)/g;
+const PLACEHOLDER = /\{\{\s*([\w-]+)\s*\}\}/g;
+
+type Mode = 'light' | 'dark';
+
+const modeValue = (t: DesignTokenLike, mode: Mode): string => (mode === 'dark' ? darkOf(t) ?? t.value : t.value);
+
+/** Every token's ROOT value in one mode, with `var(--iox-…)` references resolved against the same
+ *  set (recursively; a reference cycle or an unknown token is left as written). */
+export function resolveTokenValues(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    mode: Mode = 'light',
+): Record<string, string> {
+    const raw = new Map(usableTokens(tokens).map(t => [t.name, modeValue(t, mode)]));
+    const out: Record<string, string> = {};
+    const resolve = (name: string, trail: ReadonlySet<string>): string | null => {
+        if (name in out) return out[name];
+        const value = raw.get(name);
+        if (value === undefined || trail.has(name)) return null;
+        const next = new Set(trail).add(name);
+        return value.replace(TOKEN_REF, (ref, inner: string, fallback?: string) =>
+            resolve(inner, next) ?? (fallback !== undefined ? fallback.trim() : ref));
+    };
+    for (const name of raw.keys()) {
+        const value = resolve(name, new Set());
+        if (value !== null) out[name] = value;
+    }
+    return out;
+}
+
+/** A scheme value with its `{{token}}` placeholders replaced by resolved root values — or null
+ *  when a placeholder names a token the set does not have (the declaration is then omitted). */
+function substitute(template: string, resolved: Readonly<Record<string, string>>): string | null {
+    let missing = false;
+    const value = template.replace(PLACEHOLDER, (_, name: string) => {
+        if (!(name in resolved)) missing = true;
+        return resolved[name] ?? '';
+    });
+    return missing ? null : value;
+}
+
+const schemeEntries = (set: Readonly<Record<string, string>>, resolved: Readonly<Record<string, string>>) =>
+    Object.entries(set)
+        .map(([name, template]): [string, string | null] => [name, substitute(template, resolved)])
+        .filter((e): e is [string, string] => e[1] !== null);
+
+const hasPlaceholder = (value: string) => value.includes('{{');
+
+/**
+ * Section colour schemes (design-system plan §3c). Two rules, both about WHERE a custom property
+ * resolves:
+ *
+ * - ⚠️ Custom properties resolve where they are DECLARED: `--iox-card-bg: var(--iox-surface)`
+ *   declared on `:root` keeps `:root`'s surface inside `.iox-scheme-inverse`. So each scheme block
+ *   carries the spec's overrides PLUS every other token whose value references a token,
+ *   re-declared verbatim — re-resolving it in the section.
+ * - ⚠️ A scheme that SWAPS two tokens (Brand: accent ⇄ accent-ink) cannot write them as `var()`:
+ *   on one element `accent: var(--iox-accent-ink)` + `accent-ink: var(--iox-accent)` is a cycle,
+ *   and CSS makes both invalid. The contract writes `{{accent}}` instead — the token's ROOT value,
+ *   resolved here at compile time (and again from dark values for the dark twin).
+ */
+export function compileSchemeCss(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, scope?: string): string {
+    const rows = usableTokens(tokens);
+    if (!rows.length) return '';
+    const resolved = resolveTokenValues(rows, 'light');
+    return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
+        ...schemeEntries(set, resolved),
+        ...rows.filter(t => !(t.name in set) && t.value.includes(REFERENCE))
+            .map((t): [string, string] => [t.name, t.value]),
+    ])).filter(Boolean).join('\n');
+}
+
+/** The dark twin of both scheme rules: a re-declared token with a dark value would otherwise pin
+ *  the LIGHT value inside the section, and a `{{token}}` swap was resolved from LIGHT values. */
+function darkSchemeRules(rows: ReadonlyArray<DesignTokenLike>, scope: string | undefined): string[] {
+    const light = resolveTokenValues(rows, 'light');
+    const dark = resolveTokenValues(rows, 'dark');
+    const redeclared = rows.filter(t => {
+        const d = darkOf(t);
+        return d !== null && (t.value.includes(REFERENCE) || d.includes(REFERENCE));
+    });
+    return nonDefaultSchemes().map(([id, set]) => {
+        const swapped = Object.fromEntries(Object.entries(set).filter(([, v]) => hasPlaceholder(v)));
+        const lightSwap = new Map(schemeEntries(swapped, light));
+        return rule(schemeSelector(id, scope), [
+            ...schemeEntries(swapped, dark).filter(([name, value]) => lightSwap.get(name) !== value),
+            ...redeclared.filter(t => !(t.name in set)).map((t): [string, string] => [t.name, darkOf(t) as string]),
+        ], '  ');
+    });
+}
+
+function presentOverrides(rows: ReadonlyArray<DesignTokenLike>, overrides: Readonly<Record<string, string>>,
+    onlyWithDark: boolean): Array<[string, string]> {
+    return Object.entries(overrides).filter(([name]) => rows.some(t => t.name === name && (!onlyWithDark || darkOf(t) !== null)));
+}
+
+/** The token CSS as the two halves a renderer places around its node rules. */
+export function compileTokenCssBlocks(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    opts: TokenCssOptions = {},
+): TokenCssBlocks {
+    const rows = usableTokens(tokens);
+    const root = opts.scope ?? ROOT;
+    const base = [
+        rule(root, rows.map((t): [string, string] => [t.name, t.value])),
+        compileSchemeCss(rows, opts.scope),
+        ...ACCESSIBILITY_MEDIA.map(({ query, overrides }) =>
+            media(query, [rule(root, presentOverrides(rows, overrides, false), '  ')])),
+    ].filter(Boolean).join('\n');
+
+    const darkRows = rows.map((t): [string, string | null] => [t.name, darkOf(t)])
+        .filter((e): e is [string, string] => e[1] !== null);
+    const dark = darkRows.length ? [
+        media(MEDIA_DARK, [rule(root, darkRows, '  '), ...darkSchemeRules(rows, opts.scope)]),
+        // Glass carries dark glass values; without this the dark block (LAST) would out-rank the
+        // reduced-transparency swap and keep dark surfaces translucent.
+        ...ACCESSIBILITY_MEDIA.map(({ query, overrides }) =>
+            media(`${MEDIA_DARK} and ${query}`, [rule(root, presentOverrides(rows, overrides, true), '  ')])),
+    ].filter(Boolean).join('\n') : '';
+
+    return { base, dark };
+}
+
+/** One stylesheet string: base → schemes → reduced motion → reduced transparency → dark LAST. */
+export function compileTokenCss(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, opts: TokenCssOptions = {}): string {
+    const { base, dark } = compileTokenCssBlocks(tokens, opts);
+    return [base, dark].filter(Boolean).join('\n');
+}