@vectoriox/iox-ui 5.8.0 → 5.10.0

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

@@ -0,0 +1,99 @@
+import { deriveAccentTokens } from './brand';
+import { cssString } from './fonts';
+import { FLAVOR_SPEC } 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 = FLAVOR_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');
+        for (const accent of deriveAccentTokens(choices.seed, { bg: bg?.value ?? '', bgDark: bg?.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,88 @@
+import { FLAVOR_SPEC } 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>> = FLAVOR_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, with `\` and `'` escaped and line breaks dropped. */
+export function cssString(value: string): string {
+    return `'${String(value).replace(/[\r\n\f]/g, '').replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+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,37 @@
+/**
+ * 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).
+ * 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;
+
+export interface LinearSpring {
+    easing: string;
+    duration: string;
+}
+
+export function springToLinear(stiffness: number, damping: number): LinearSpring {
+    const w0 = Math.sqrt(stiffness);
+    const x = (t: number): number => {
+        if (damping < 1) {
+            const wd = w0 * Math.sqrt(1 - damping * damping);
+            return 1 - Math.exp(-damping * w0 * t) * (Math.cos(wd * t) + ((damping * w0) / wd) * Math.sin(wd * t));
+        }
+        return 1 - Math.exp(-w0 * t) * (1 + w0 * t);
+    };
+    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,183 @@
+import { FLAVOR_SPEC } 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 — movement and duration, never colour. */
+export const REDUCED_MOTION_OVERRIDES: Readonly<Record<string, string>> = {
+    'dur-fast': '0ms',
+    'dur-base': '0ms',
+    'dur-slow': '0ms',
+    'hover-lift': '0px',
+    'button-hover-x': '0px',
+    'button-hover-y': '0px',
+    'card-hover-x': '0px',
+    'card-lift': '0px',
+};
+
+/** What `prefers-reduced-transparency: reduce` makes solid — every glass surface, in one block. */
+export const REDUCED_TRANSPARENCY_OVERRIDES: Readonly<Record<string, string>> = {
+    'surface-glass': 'var(--iox-surface)',
+    'surface-glass-strong': 'var(--iox-surface)',
+    'blur-surface': 'none',
+};
+
+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(FLAVOR_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;
+}
+
+/**
+ * Section colour schemes (design-system plan §3c). ⚠️ 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.
+ */
+export function compileSchemeCss(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, scope?: string): string {
+    const rows = usableTokens(tokens);
+    if (!rows.length) return '';
+    return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
+        ...Object.entries(set),
+        ...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 the re-declaration rule: a re-declared token with a dark value would
+ *  otherwise pin the LIGHT value inside the section once the visitor is in dark mode. */
+function darkSchemeRules(rows: ReadonlyArray<DesignTokenLike>, scope: string | undefined): string[] {
+    const redeclared = rows.filter(t => {
+        const dark = darkOf(t);
+        return dark !== null && (t.value.includes(REFERENCE) || dark.includes(REFERENCE));
+    });
+    return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), 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');
+}