@vectoriox/iox-ui 5.14.0 → 5.15.0

package/package.json

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

package/src/design-core/design-apply.ts

@@ -0,0 +1,116 @@
+import { deriveBrandTokens } from './brand';
+import { SPEC_LEGACY_ALIASES } from './flavor-spec.generated';
+import { SWISS_FLAVOR } from './flavor';
+import { buildFlavorTokens } from './flavor-tokens';
+import { FlavorSeedPlan, planFlavorSeed, SeedBaseline, SeedExpectation } from './flavor-seed';
+import { DesignChoices, DesignTokenRow, flavorSourceStamp, StoredDesignTokenRow } from './design-token.model';
+import { flavorPackById, isRetiredFlavorId, packDesignChoices, StoredDesign } from './design-settings';
+
+/**
+ * Applying a look (design-system DS4): the COMPLETE `buildFlavorTokens` set for the chosen
+ * `DesignChoices`, merged into the org's rows by the §10 C2 rule — rewrite only what the previous
+ * seed wrote and nobody touched since, keep the author's rows, report what was kept. And the one
+ * migration the contract names: an org still on Swiss becomes Crisp.
+ * Pure plans; each caller (builder, the server-side site build) applies them with its own transport.
+ */
+
+const SEED_STAMP = /^flavor:([^@]+)@/;
+
+const expectations = (rows: ReadonlyArray<Pick<DesignTokenRow, 'name' | 'value' | 'values'>>): Map<string, SeedExpectation> =>
+    new Map(rows.map(r => [r.name, { value: r.value, ...(r.values?.dark ? { dark: r.values.dark } : {}) }]));
+
+/** Every row a design writes — `buildFlavorTokens` for its pack. Empty for an unknown pack. */
+export function designTokenRows(choices: DesignChoices): DesignTokenRow[] {
+    const pack = flavorPackById(choices.flavorId);
+    return pack ? buildFlavorTokens(pack, { ...choices, flavorId: pack.id }) : [];
+}
+
+/** What the F1/F2 Swiss seeding wrote: the four Swiss rows + the brand set derived from its seed. */
+function swissExpectations(seed: string | null): Map<string, SeedExpectation> {
+    const rows: Array<Pick<DesignTokenRow, 'name' | 'value' | 'values'>> =
+        SWISS_FLAVOR.tokens.map(t => ({ name: t.name, value: t.value, values: t.values }));
+    if (seed) {
+        try { rows.push(...deriveBrandTokens(seed, SWISS_FLAVOR).map(t => ({ name: t.name, value: t.value, values: t.values }))); }
+        catch { /* an unparseable stored seed proves nothing about the rows */ }
+    }
+    return expectations(rows);
+}
+
+/**
+ * What the PREVIOUS design wrote, as a baseline keyed by the row's own stamp: a row Swiss stamped is
+ * judged against what Swiss wrote, every other row against `buildFlavorTokens` of the stored choices
+ * (for an org with no design row, Crisp's defaults — exactly what DS2's interim seed wrote). In a
+ * Swiss org the only v2 rows are that interim seed's, so they are judged against Crisp's DEFAULTS,
+ * never against the brand-seeded Crisp the migration is about to write.
+ */
+export function designBaseline(previous: StoredDesign): SeedBaseline {
+    const retired = isRetiredFlavorId(previous.storedFlavorId);
+    const current = expectations(designTokenRows(retired ? packDesignChoices(previous.choices.flavorId) : previous.choices));
+    const swiss = swissExpectations(retired ? previous.storedSeed : null);
+    return (row: StoredDesignTokenRow) => {
+        const stampedBy = SEED_STAMP.exec(row.source ?? '')?.[1];
+        return stampedBy === SWISS_FLAVOR.id ? swiss.get(row.name) : current.get(row.name);
+    };
+}
+
+/** Apply `next` over the org's rows, judged against `previous` — the plan FlavorApplyService runs. */
+export function planDesignApply(
+    existing: ReadonlyArray<StoredDesignTokenRow>,
+    previous: StoredDesign,
+    next: DesignChoices,
+): FlavorSeedPlan {
+    const pack = flavorPackById(next.flavorId);
+    if (!pack) return { create: [], update: [], kept: [] };
+    return planFlavorSeed(designTokenRows(next), existing, flavorSourceStamp(pack.id), designBaseline(previous));
+}
+
+/** The rows a design is missing by name — the builder-load top-up (never touches an existing row). */
+export function missingDesignRows(existing: ReadonlyArray<{ name: string }>, choices: DesignChoices): DesignTokenRow[] {
+    const have = new Set((existing ?? []).map(r => r.name));
+    return designTokenRows(choices).filter(r => !have.has(r.name));
+}
+
+export interface SwissMigration {
+    /** The design the org now wears: Crisp, carrying the stored brand seed when it is a colour. */
+    choices: DesignChoices;
+    /** The token merge, the four legacy alias rewrites included. */
+    plan: FlavorSeedPlan;
+}
+
+const LEGACY_ALIASES: Readonly<Record<string, string>> = SPEC_LEGACY_ALIASES;
+
+/**
+ * Swiss → Crisp (spec `legacyAliases`; D1). Needed when the design row says a retired flavor, or when
+ * there is no design row but the org holds Swiss-stamped alias rows (F1 seeded those before the row
+ * existed). Idempotent: once the row says Crisp nothing is needed, and re-running the plan writes
+ * nothing.
+ *
+ * - The look: `planDesignApply` from Swiss to Crisp — Swiss-stamped rows untouched since Swiss seeded
+ *   them (incl. F2's `surface` / `line` / `accent`) become Crisp's; edited ones are kept.
+ * - The aliases: `radius-control` / `radius-surface` / `space-control` / `space-stack` are rewritten to
+ *   their alias reference ONLY while still machine-owned and untouched, so a node saved since F1 that
+ *   reads `var(--iox-radius-control)` keeps resolving — now to Crisp's button radius.
+ */
+export function planSwissMigration(existing: ReadonlyArray<StoredDesignTokenRow>, stored: StoredDesign): SwissMigration | null {
+    const swissAliasRows = (existing ?? []).filter(r => r.name in LEGACY_ALIASES && SEED_STAMP.exec(r.source ?? '')?.[1] === SWISS_FLAVOR.id);
+    const needed = isRetiredFlavorId(stored.storedFlavorId) || (!stored.hasRow && swissAliasRows.length > 0);
+    if (!needed) return null;
+
+    const choices = stored.choices;
+    const previous: StoredDesign = isRetiredFlavorId(stored.storedFlavorId) ? stored : { ...stored, storedFlavorId: SWISS_FLAVOR.id };
+    const plan = planDesignApply(existing, previous, choices);
+    const stamp = flavorSourceStamp(choices.flavorId);
+    const swiss = swissExpectations(null);
+    for (const row of (existing ?? []).filter(r => r.name in LEGACY_ALIASES)) {
+        const alias = LEGACY_ALIASES[row.name];
+        if (row.value === alias) continue;
+        const was = swiss.get(row.name);
+        const untouched = SEED_STAMP.test(row.source ?? '') && !!was && row.value === was.value && !row.values?.dark;
+        if (untouched && row._id) {
+            plan.update.push({ id: row._id, data: { value: alias, values: {}, source: stamp } });
+        } else {
+            plan.kept.push(row.name);
+        }
+    }
+    return { choices, plan };
+}

package/src/design-core/design-settings.ts

@@ -0,0 +1,194 @@
+import { SPEC_AXES, SPEC_FONT_ROLES } from './flavor-spec.generated';
+import { parseHexColor } from './brand';
+import { DesignChoices, DesignMode, FlavorPackV2, FontRoleToken, SPEC_FLAVORS } from './design-token.model';
+import type { FlavorRevertSnapshot } from './flavor-seed';
+
+/**
+ * The `settings.design` row (design-system plan §3f), read and written by ONE pair of functions so
+ * the builder, the server's public page read (the engine's mode) and the site build agree on what a
+ * stored row MEANS. The row is the settings collection's generic `config: [{ key, value }]`; values
+ * are strings there (Boolean "true"/"false", Object as JSON), but a reader also accepts the typed
+ * value a client control may have sent.
+ */
+
+/** The look a studio wears until it picks one (DS2's interim seed, and DS6's first-run selection). */
+export const DEFAULT_FLAVOR_ID = 'crisp';
+
+/** One `config` entry of a settings row. */
+export interface DesignConfigEntry {
+    key: string;
+    value: unknown;
+}
+
+export enum DesignConfigKey {
+    FlavorId = 'flavorId',
+    FlavorVersion = 'flavorVersion',
+    BrandSeed = 'brandSeed',
+    PairId = 'pairId',
+    Shape = 'shape',
+    Density = 'density',
+    Motion = 'motion',
+    PillButtons = 'pillButtons',
+    Mode = 'mode',
+    Fonts = 'fonts',
+    Revert = 'revert',
+}
+
+/** A stored design, resolved: `choices` is ALWAYS complete and valid (pack defaults fill the gaps). */
+export interface StoredDesign {
+    choices: DesignChoices;
+    /** The flavor id exactly as stored — `swiss` until the DS4 migration rewrites it; null when no row. */
+    storedFlavorId: string | null;
+    /** The seed exactly as stored (F2 orgs carry their brand colour here); null when absent. */
+    storedSeed: string | null;
+    flavorVersion: string | null;
+    revert: FlavorRevertSnapshot | null;
+    /** False when the org has never stored a design — DS6's first run. */
+    hasRow: boolean;
+}
+
+const MODES: ReadonlyArray<string> = SPEC_AXES.modes;
+const FONT_ROLE_TOKENS: ReadonlyArray<string> = SPEC_FONT_ROLES.map(r => r.token);
+
+/** The pack for an id; a retired id (Swiss) resolves to the pack that `replaces` it. */
+export function flavorPackById(id: string | null | undefined): FlavorPackV2 | undefined {
+    if (!id) return undefined;
+    return SPEC_FLAVORS.find(f => f.id === id) ?? SPEC_FLAVORS.find(f => f.replaces === id);
+}
+
+/** True when `id` names a retired flavor that a v2 pack replaces (Swiss → Crisp). */
+export function isRetiredFlavorId(id: string | null | undefined): boolean {
+    return !!id && !SPEC_FLAVORS.some(f => f.id === id) && SPEC_FLAVORS.some(f => f.replaces === id);
+}
+
+const defaultPack = (): FlavorPackV2 => flavorPackById(DEFAULT_FLAVOR_ID) as FlavorPackV2;
+
+const asString = (v: unknown): string | null => (typeof v === 'string' && v.trim() !== '' ? v.trim() : null);
+
+function asBoolean(v: unknown): boolean | null {
+    if (v === true || v === 'true') return true;
+    if (v === false || v === 'false') return false;
+    return null;
+}
+
+function asObject<T>(v: unknown): T | null {
+    if (v && typeof v === 'object') return v as T;
+    if (typeof v !== 'string' || v.trim() === '') return null;
+    try {
+        const parsed = JSON.parse(v);
+        return parsed && typeof parsed === 'object' ? parsed as T : null;
+    } catch {
+        return null;
+    }
+}
+
+function asFonts(v: unknown): DesignChoices['fonts'] | undefined {
+    const raw = asObject<Record<string, unknown>>(v);
+    if (!raw) return undefined;
+    const fonts: Partial<Record<FontRoleToken, string>> = {};
+    for (const role of FONT_ROLE_TOKENS) {
+        const family = raw[role];
+        if (typeof family === 'string' && family.trim() !== '') fonts[role as FontRoleToken] = family.trim();
+    }
+    return Object.keys(fonts).length ? fonts : undefined;
+}
+
+const keyOf = <K extends string>(table: Readonly<Record<K, unknown>>, v: string | null): K | null =>
+    v !== null && Object.prototype.hasOwnProperty.call(table, v) ? v as K : null;
+
+/** A config array → the key/value map (last entry wins, as the settings form writes it). */
+function configMap(config: ReadonlyArray<DesignConfigEntry> | null | undefined): Map<string, unknown> {
+    const map = new Map<string, unknown>();
+    for (const kv of config ?? []) if (kv && typeof kv.key === 'string') map.set(kv.key, kv.value);
+    return map;
+}
+
+/**
+ * A partial set of choices completed against its pack: every missing or invalid value falls back to
+ * the pack's own default (an unknown pair → the pack's first, a bad seed → the pack's seed).
+ */
+export function resolveDesignChoices(partial: Partial<DesignChoices> | null | undefined): DesignChoices {
+    const pack = flavorPackById(partial?.flavorId) ?? defaultPack();
+    const seed = asString(partial?.seed);
+    const pairId = asString(partial?.pairId);
+    const fonts = asFonts(partial?.fonts);
+    return {
+        flavorId: pack.id,
+        seed: seed && parseHexColor(seed) ? seed : pack.seed,
+        pairId: pairId && pack.pairs.some(p => p.id === pairId) ? pairId : pack.pairs[0]?.id ?? '',
+        shape: keyOf(SPEC_AXES.shapes, asString(partial?.shape)) ?? pack.defaults.shape,
+        density: keyOf(SPEC_AXES.densities, asString(partial?.density)) ?? pack.defaults.density,
+        motion: keyOf(SPEC_AXES.motions, asString(partial?.motion)) ?? pack.defaults.motion,
+        pillButtons: asBoolean(partial?.pillButtons) ?? pack.defaults.pillButtons,
+        mode: (MODES.includes(asString(partial?.mode) ?? '') ? asString(partial?.mode) : pack.defaults.mode) as DesignMode,
+        ...(fonts ? { fonts } : {}),
+    };
+}
+
+/** The pack's own defaults for `flavorId` — what picking a card means before anything is tuned. */
+export function packDesignChoices(flavorId: string): DesignChoices {
+    return resolveDesignChoices({ flavorId });
+}
+
+/** A stored `settings.design` config → the resolved design. No row (or no config) → Crisp's defaults. */
+export function readDesignConfig(config: ReadonlyArray<DesignConfigEntry> | null | undefined, hasRow = !!config): StoredDesign {
+    const map = configMap(config);
+    const storedFlavorId = asString(map.get(DesignConfigKey.FlavorId));
+    const storedSeed = asString(map.get(DesignConfigKey.BrandSeed));
+    const choices = resolveDesignChoices({
+        flavorId: storedFlavorId ?? undefined,
+        seed: storedSeed ?? undefined,
+        pairId: asString(map.get(DesignConfigKey.PairId)) ?? undefined,
+        shape: map.get(DesignConfigKey.Shape) as DesignChoices['shape'],
+        density: map.get(DesignConfigKey.Density) as DesignChoices['density'],
+        motion: map.get(DesignConfigKey.Motion) as DesignChoices['motion'],
+        pillButtons: asBoolean(map.get(DesignConfigKey.PillButtons)) ?? undefined,
+        mode: map.get(DesignConfigKey.Mode) as DesignMode,
+        fonts: map.get(DesignConfigKey.Fonts) as DesignChoices['fonts'],
+    });
+    return {
+        choices,
+        storedFlavorId,
+        storedSeed,
+        flavorVersion: asString(map.get(DesignConfigKey.FlavorVersion)),
+        revert: asObject<FlavorRevertSnapshot>(map.get(DesignConfigKey.Revert)),
+        hasRow,
+    };
+}
+
+/** The colour mode a stored config compiles in — what the public page read hands the engine. */
+export function designModeOf(config: ReadonlyArray<DesignConfigEntry> | null | undefined): DesignMode {
+    return readDesignConfig(config).choices.mode;
+}
+
+/** Resolved choices (+ the revert snapshot) → the config array a settings row stores. */
+export function designConfigEntries(
+    choices: DesignChoices,
+    flavorVersion: string | number,
+    revert?: FlavorRevertSnapshot | null,
+): DesignConfigEntry[] {
+    const c = resolveDesignChoices(choices);
+    return [
+        { key: DesignConfigKey.FlavorId, value: c.flavorId },
+        { key: DesignConfigKey.FlavorVersion, value: String(flavorVersion) },
+        { key: DesignConfigKey.BrandSeed, value: c.seed },
+        { key: DesignConfigKey.PairId, value: c.pairId },
+        { key: DesignConfigKey.Shape, value: c.shape },
+        { key: DesignConfigKey.Density, value: c.density },
+        { key: DesignConfigKey.Motion, value: c.motion },
+        { key: DesignConfigKey.PillButtons, value: String(c.pillButtons) },
+        { key: DesignConfigKey.Mode, value: c.mode },
+        ...(c.fonts ? [{ key: DesignConfigKey.Fonts, value: JSON.stringify(c.fonts) }] : []),
+        ...(revert ? [{ key: DesignConfigKey.Revert, value: JSON.stringify(revert) }] : []),
+    ];
+}
+
+/** Two choice sets describe the same look (fonts compared by role). */
+export function sameDesignChoices(a: DesignChoices, b: DesignChoices): boolean {
+    const x = resolveDesignChoices(a);
+    const y = resolveDesignChoices(b);
+    return x.flavorId === y.flavorId && x.seed.toLowerCase() === y.seed.toLowerCase() && x.pairId === y.pairId
+        && x.shape === y.shape && x.density === y.density && x.motion === y.motion
+        && x.pillButtons === y.pillButtons && x.mode === y.mode
+        && JSON.stringify(x.fonts ?? {}) === JSON.stringify(y.fonts ?? {});
+}

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

@@ -1,5 +1,5 @@
 import { FlavorTokenDef } from './flavor';
-import { DesignTokenRow, StoredDesignTokenRow } from './design-token.model';
+import { DesignTokenRow, StoredDesignTokenRow, USER_TOKEN_SOURCE } from './design-token.model';
 
 /**
  * Seeding and reverting a look, as pure plans (flavors F2, moved here from iox-cms-client in
@@ -82,42 +82,68 @@ export function planFlavorRevert(
     return plan;
 }
 
+/** What a previous seed wrote for one row — the "untouched" comparison base. */
+export interface SeedExpectation {
+    value: string;
+    dark?: string;
+}
+
+/**
+ * What the PREVIOUS seed wrote, per row: a map by name, or a function of the stored row (a baseline
+ * that depends on WHICH seed stamped the row — the Swiss → Crisp migration's case).
+ */
+export type SeedBaseline =
+    | ReadonlyMap<string, SeedExpectation>
+    | ((row: StoredDesignTokenRow) => SeedExpectation | undefined);
+
+const expectationFor = (baseline: SeedBaseline | null | undefined, row: StoredDesignTokenRow): SeedExpectation | undefined =>
+    !baseline ? undefined : typeof baseline === 'function' ? baseline(row) : baseline.get(row.name);
+
+const sameValue = (row: { value: string; values?: { dark?: string } }, e: SeedExpectation) =>
+    row.value === e.value && (row.values?.dark ?? '') === (e.dark ?? '');
+
 /**
  * The seeding MERGE: desired tokens vs existing rows, deciding create / update / keep. The §10 C2
  * rule — "an upgrade only rewrites untouched rows" — is a comparison against what the PREVIOUS
- * seed wrote (`oldExpected`): a seeded row whose value still equals it is the machine's and may be
- * rewritten; any drift means the author took it over, and their hand wins. A row without a
- * `flavor:` stamp is never touched at all. `group`/`tier` ride every write.
+ * seed wrote (`baseline`): a seeded row whose value still equals it is the machine's and may be
+ * rewritten; any drift means the author took it over, and their hand wins. A row the design did not
+ * write is never touched: no `flavor:` stamp, unless it is a `user` row (a font the author CHOSE in
+ * the design) whose value is exactly what the previous design wrote — that row is the design's own
+ * choice, so a new choice may replace it. `group`/`tier` ride every write; a desired row's own
+ * `source` (a chosen font's `user`) wins over the pack stamp.
  */
 export function planFlavorSeed(
-    desired: ReadonlyArray<FlavorTokenDef>,
+    desired: ReadonlyArray<FlavorTokenDef & { source?: string }>,
     existing: ReadonlyArray<StoredDesignTokenRow>,
     stamp: string,
-    oldExpected: Map<string, { value: string; dark?: string }> | null,
+    baseline: SeedBaseline | null,
 ): FlavorSeedPlan {
     const byName = new Map((existing ?? []).map(r => [r.name, r]));
     const plan: FlavorSeedPlan = { create: [], update: [], kept: [] };
     for (const def of desired ?? []) {
         if (!def?.name) continue;
         const row = byName.get(def.name);
+        const source = def.source ?? stamp;
         if (!row) {
             plan.create.push({
                 name: def.name,
                 type: def.type ?? DEFAULT_TOKEN_TYPE,
                 value: def.value,
                 ...(def.values ? { values: def.values } : {}),
-                source: stamp,
+                source,
                 ...classification(def),
             });
             continue;
         }
-        if (!isSeeded(row)) { plan.kept.push(def.name); continue; }
+        const old = expectationFor(baseline, row);
+        const designOwned = isSeeded(row) || (row.source === USER_TOKEN_SOURCE && !!old && sameValue(row, old));
+        if (!designOwned) { plan.kept.push(def.name); continue; }
         const sameAsDesired = row.value === def.value && (row.values?.dark ?? '') === (def.values?.dark ?? '');
-        if (sameAsDesired) continue; // already exactly this — nothing to write, nothing kept-against
-        const old = oldExpected?.get(def.name);
-        const untouched = !!old && row.value === old.value && (row.values?.dark ?? '') === (old.dark ?? '');
-        if (untouched && row._id) {
-            plan.update.push({ id: row._id, data: { value: def.value, values: def.values ?? {}, source: stamp, ...classification(def) } });
+        if (sameAsDesired && (row.source ?? '') === source) continue; // already exactly this
+        if (sameAsDesired && isSeeded(row) && source !== USER_TOKEN_SOURCE) continue; // same value, another pack's stamp — nothing to write
+        const untouched = !!old && sameValue(row, old);
+        if ((untouched || sameAsDesired) && row._id) {
+            plan.update.push({ id: row._id, data: { value: def.value, values: def.values ?? {}, source, ...classification(def) } });
         } else {
             plan.kept.push(def.name); // edited since seeding (or unverifiable) — the author's hand wins
         }

package/src/design-core/flavor-spec.generated.ts

@@ -1077,7 +1077,7 @@ export const SPEC_SPRINGS = {
 } as const;
 
 export const SPEC_FONTS = {
-  "Inter": "Inter:wght@400;500;600;700",
+  "Inter": "Inter:wght@300;400;500;600;700",
   "Inter Tight": "Inter+Tight:wght@500;600;700",
   "Manrope": "Manrope:wght@400;500;600;700",
   "IBM Plex Sans": "IBM+Plex+Sans:wght@400;500;600;700",
@@ -1092,12 +1092,21 @@ export const SPEC_FONTS = {
   "Figtree": "Figtree:wght@400;500;600;700;800",
   "Google Sans Flex": "Google+Sans+Flex:wght@400;500;600;700",
   "Bricolage Grotesque": "Bricolage+Grotesque:opsz,wght@12..96,500;12..96,700",
-  "Nunito": "Nunito:wght@400;600;700;800",
+  "Nunito": "Nunito:wght@300;400;600;700;800",
   "DM Sans": "DM+Sans:wght@400;500;700",
   "Archivo": "Archivo:wght@400;500;700",
   "Archivo Black": "Archivo+Black",
   "Syne": "Syne:wght@600;700;800",
-  "Space Mono": "Space+Mono:wght@400;700"
+  "Space Mono": "Space+Mono:wght@400;700",
+  "Poppins": "Poppins:ital,wght@0,300;0,400;0,500;0,600;0,700;1,400",
+  "Roboto": "Roboto:ital,wght@0,300;0,400;0,500;0,700;1,400",
+  "Lato": "Lato:ital,wght@0,300;0,400;0,700;1,400",
+  "Open Sans": "Open+Sans:ital,wght@0,300;0,400;0,600;0,700;1,400",
+  "Montserrat": "Montserrat:ital,wght@0,300;0,400;0,500;0,600;0,700;1,400",
+  "Raleway": "Raleway:wght@300;400;500;600;700",
+  "Playfair Display": "Playfair+Display:ital,wght@0,400;0,500;0,700;1,400",
+  "Oswald": "Oswald:wght@300;400;500;600;700",
+  "Ubuntu": "Ubuntu:ital,wght@0,300;0,400;0,500;0,700;1,400"
 } as const;
 
 export const SPEC_SCHEMES = {
@@ -1762,7 +1771,6 @@ export const SPEC_FIELD_CLASS_BASELINE = {
 export const SPEC_LEGACY_ALIASES = {
   "radius-control": "var(--iox-button-radius)",
   "radius-surface": "var(--iox-card-radius)",
-  "space-control": "var(--iox-button-pad)",
   "space-stack": "var(--iox-space-gap)"
 } as const;
 

package/src/design-core/flavor.ts

@@ -4,8 +4,9 @@ import { DesignTokenGroup, DesignTokenTier, DesignTokenType } from './design-tok
  * Flavors v1 (flavors-and-theming-plan.md, F1–F2): a pack is its TOKENS plus the accent hue
  * opinion the brand derivation reads. The per-type `defaults` map and its resolvers are gone
  * (design-system plan §3e, DS2): a new element is born wearing an ELEMENT STYLE
- * (`element-styles.ts`), which references tokens and is flavor-independent. Swiss survives only
- * until DS4 migrates orgs to Crisp.
+ * (`element-styles.ts`), which references tokens and is flavor-independent. Swiss is retired (DS4
+ * migrates `flavorId: swiss` orgs to Crisp); its pack stays as the migration's BASELINE — what F1/F2
+ * wrote, so "untouched since seeding" stays a comparison (`design-apply.ts`).
  */
 
 export interface FlavorTokenDef {
@@ -40,9 +41,9 @@ export function validateFlavorPack(pack: FlavorPack): string[] {
 }
 
 /**
- * Swiss — the F1 pack: four tokens (control/surface radius, control/stack spacing) and the hue
- * opinion F2's brand step reads. Kept until DS4 migrates `flavorId: swiss` orgs to Crisp; its four
- * rows are the spec's `legacyAliases`.
+ * Swiss — the retired F1 pack: four tokens (control/surface radius, control/stack spacing) and the
+ * hue opinion F2's brand step read. Three of its rows become the spec's `legacyAliases` on migration;
+ * `space-control` is a v2 token in every pack and takes Crisp's value.
  */
 export const SWISS_FLAVOR: FlavorPack = {
     id: 'swiss',

package/src/design-core/fonts.ts

@@ -77,19 +77,56 @@ export function parseFontFamilies(stack: string): string[] {
         .filter(Boolean);
 }
 
+/** Where Google serves the stylesheets, and the origin the font FILES come from (preconnect). */
+export const GOOGLE_FONTS_CSS_ORIGIN = 'https://fonts.googleapis.com';
+export const GOOGLE_FONTS_FILE_ORIGIN = 'https://fonts.gstatic.com';
+
+/** The ONE stylesheet URL for a catalog id — both renderers link exactly this (one per family, T7). */
+export function googleFontHref(id: string): string {
+    return `${GOOGLE_FONTS_CSS_ORIGIN}/css2?family=${id}&display=swap`;
+}
+
+const CATALOG_BY_LOWER = new Map(Object.entries(FONT_CATALOG).map(([family, id]) => [family.toLowerCase(), id]));
+
+/** The catalog id of a family name (case-insensitive), or null — a system or uploaded face has none. */
+export function catalogFontId(family: string | null | undefined): string | null {
+    return CATALOG_BY_LOWER.get(String(family ?? '').trim().toLowerCase()) ?? null;
+}
+
+const MONO_ROLE = 'font-mono';
+const ALWAYS_LOADED_ROLES = FONT_FAMILY_TOKENS.filter(role => role !== MONO_ROLE);
+const MONO_REFERENCE = /var\(\s*--iox-font-mono\b/;
+
+export interface FontsForTokensOptions {
+    /**
+     * The CSS that will actually render (node rules, element styles). `font-mono` is loaded only when
+     * something READS it — here or in another token's value — because no element style does: an org
+     * would otherwise download a monospace face for a site with no code on it.
+     */
+    usedCss?: string;
+}
+
 /**
- * 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).
+ * The Google css2 ids to load for a token set: every catalog family named by the display / body /
+ * label roles, plus mono when referenced (above). One id per family (T7 — one `<link>` per family, so
+ * one bad id cannot sink the others), in role order.
  */
-export function fontsForTokens(tokens: ReadonlyArray<DesignTokenLike> | null | undefined): string[] {
+export function fontsForTokens(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    opts: FontsForTokensOptions = {},
+): string[] {
+    const rows = (tokens ?? []).filter(t => !!t && typeof t.name === 'string');
+    const monoRead = MONO_REFERENCE.test(opts.usedCss ?? '')
+        || rows.some(t => t.name !== MONO_ROLE && MONO_REFERENCE.test(`${t.value ?? ''} ${t.values?.dark ?? ''}`));
+    const roles = monoRead ? FONT_FAMILY_TOKENS : ALWAYS_LOADED_ROLES;
     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 role of roles) {
+        const row = rows.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);
+            const id = catalogFontId(family);
+            if (id && !seen.has(id)) {
+                seen.add(id);
                 ids.push(id);
             }
         }

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

@@ -22,3 +22,5 @@ export * from './flavor-seed';
 export * from './spring';
 export * from './fonts';
 export * from './token-names';
+export * from './design-settings';
+export * from './design-apply';

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

@@ -1,5 +1,6 @@
 import { DesignMode } from './design-token.model';
 import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
+import { specTokenNames } from './token-names';
 
 /**
  * Design-token → CSS compilation, shared by BOTH renderers (flavors F0, design-system DS1).
@@ -14,6 +15,11 @@ import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
  *   4. reduced transparency `@media (prefers-reduced-transparency: reduce)`
  *   5. dark — LAST     `@media (prefers-color-scheme: dark)`
  *
+ * MODE (design-system D6) is a compile choice, never a row change: `auto` is the visitor-following
+ * order above; `light` compiles the base from light values and emits no dark block; `dark` compiles
+ * the base from DARK values (schemes and placeholders resolved from them too) and emits no dark block —
+ * so a Midnight site is dark for a light-OS visitor.
+ *
  * ⚠️ 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).
@@ -32,6 +38,16 @@ export interface DesignTokenLike {
 export interface TokenCssOptions {
     /** Selector that carries the variables instead of `:root` — a preview wrapper, a specimen. */
     scope?: string;
+    /** The studio's colour mode (`settings.design.mode`). Absent = `auto`. */
+    mode?: DesignMode;
+    /**
+     * Declare every SPEC token the rows lack as `initial` on the scope (the guaranteed-invalid value),
+     * so a `var()` inside the scope cannot inherit a same-named property from an ANCESTOR. The builder
+     * needs it: the admin's `:root` chrome tokens share names with org tokens (`accent`, `surface-2`…),
+     * and a missing org row would silently paint the canvas in admin chrome. With it, the canvas
+     * computes exactly what the live site computes for that row — unset.
+     */
+    isolate?: boolean;
 }
 
 export interface TokenCssBlocks {
@@ -114,6 +130,16 @@ const DARK: ResolvedMode = 'dark';
 
 const modeValue = (t: DesignTokenLike, mode: ResolvedMode): string => (mode === DARK ? darkOf(t) ?? t.value : t.value);
 
+/** The rows as ONE mode: each row's value in that mode, no dark override left. `auto` (or none) →
+ *  the rows unchanged. */
+function rowsForMode(rows: ReadonlyArray<DesignTokenLike>, mode: DesignMode | undefined): DesignTokenLike[] {
+    if (mode !== LIGHT && mode !== DARK) return [...rows];
+    return rows.map(t => {
+        const { values: _dropped, ...rest } = t;
+        return { ...rest, value: modeValue(t, mode) };
+    });
+}
+
 /** 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(
@@ -223,10 +249,14 @@ export function compileTokenCssBlocks(
     tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
     opts: TokenCssOptions = {},
 ): TokenCssBlocks {
-    const rows = usableTokens(tokens);
+    const rows = rowsForMode(usableTokens(tokens), opts.mode);
     const root = opts.scope ?? ROOT;
+    const present = new Set(rows.map(t => t.name));
+    const unset: Array<[string, string]> = opts.isolate
+        ? [...specTokenNames()].filter(name => !present.has(name)).map((name): [string, string] => [name, 'initial'])
+        : [];
     const base = [
-        rule(root, rows.map((t): [string, string] => [t.name, t.value])),
+        rule(root, [...unset, ...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), '  ')])),

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

@@ -30,3 +30,24 @@ export function unknownTokenReferences(css: string, alsoAllowed: Iterable<string
     const extra = new Set(alsoAllowed);
     return tokenReferences(css).filter(name => !spec.has(name) && !extra.has(name));
 }
+
+const LEGACY_SCOPE = /:not\(\s*\.iox-es\s*\)/;
+const RULE = /([^{}]+)\{([^{}]*)\}/g;
+
+/**
+ * Tokens read by a LEGACY rule — any rule whose selector is scoped `:not(.iox-es)` (the pre-DS2 look
+ * of a node that wears no element style, design-system §3b-bis). Such a rule must read NO token at
+ * all: a token it reads repaints a pre-DS2 page the moment the org's rows are seeded or a flavor is
+ * applied (D5). Returns `selector → names` for each offending rule; comments are ignored.
+ */
+export function legacyRuleTokenReferences(css: string): Array<{ selector: string; tokens: string[] }> {
+    const text = String(css ?? '').replace(/\/\*[\s\S]*?\*\//g, '');
+    const out: Array<{ selector: string; tokens: string[] }> = [];
+    for (const m of text.matchAll(RULE)) {
+        const selector = m[1].trim().replace(/\s+/g, ' ');
+        if (!LEGACY_SCOPE.test(selector)) continue;
+        const tokens = tokenReferences(m[2]);
+        if (tokens.length) out.push({ selector, tokens });
+    }
+    return out;
+}