@vectoriox/iox-ui 5.14.0 → 5.16.0

package/index.d.ts

@@ -184,9 +184,11 @@ declare class BuilderImageComponent {
     alt: string;
     nodeId: string;
     /**
-     * What a MARKED image shows while it has no source (design-system DS3) — set by each renderer from
-     * the shared `emptyImageSrc` (`@vectoriox/iox-ui/design-core`): the "Add image" label on the canvas,
-     * the blank on the live site, `null` for an unmarked image, which therefore renders as before.
+     * What a MARKED image shows WHENEVER it has no source (design-system DS3) — set by each renderer
+     * from the shared `emptyImagePlaceholder` (`@vectoriox/iox-ui/design-core`): the "Add image" label
+     * on the canvas, the blank on the live site, `null` for an unmarked image, which therefore renders
+     * as before. It does not depend on `src`, so clearing the source (a binding emptied, a context slot
+     * not yet filled) shows it with no re-render; a renderer re-sets it only when the MARKER changes.
      */
     emptySrc: string | null;
     /**
@@ -200,8 +202,16 @@ declare class BuilderImageComponent {
      * filled when the visitor interacts (see element-context-state-plan.md).
      */
     get srcAttr(): string | null;
+    private get showsPlaceholder();
     /** `data-iox-empty` while the placeholder stands in — the hook the shared fill rule keys on. */
     get emptyAttr(): '' | null;
+    /**
+     * The placeholder is not the author's picture, so it never carries the author's alt: it is
+     * decorative (`alt=""`) and hidden from assistive technology — on the live site, in Preview and on
+     * the canvas alike (the canvas label is painted inside the placeholder, not announced as content).
+     */
+    get altAttr(): string;
+    get ariaHiddenAttr(): 'true' | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<BuilderImageComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<BuilderImageComponent, "img[iox-img]", never, { "src": { "alias": "src"; "required": false; }; "alt": { "alias": "alt"; "required": false; }; "nodeId": { "alias": "nodeId"; "required": false; }; "emptySrc": { "alias": "emptySrc"; "required": false; }; }, {}, never, never, false, never>;
 }
@@ -247,6 +257,11 @@ declare class BuilderIconComponent {
 /**
  * Directive-host link: the `<a>` IS the host — no wrapper. Content is the label; styles come from
  * `.iox-node` (the legacy `style` input is kept for builder compat but no longer inline-applied).
+ *
+ * Outside a preview (`IS_PREVIEW` unprovided — the editing canvas, the design sampler) the link keeps
+ * its real `href` so it LOOKS like the live site's (the UA link styles key on it) and stays clickable
+ * so the canvas can select it, but no click navigates: plain, modified (cmd/ctrl/shift) and middle
+ * clicks all have their default cancelled here.
  */
 declare class BuilderLinkComponent {
     isPreview: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.14.0",
+  "version": "5.16.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/empty-image.ts

@@ -41,12 +41,21 @@ export function emptyImageLabelSrc(label: string): string {
 }
 
 /**
- * The `src` a node's Image renders when its own source is empty: the canvas label (when `label` is
- * given) or the live blank for a MARKED node; `null` — render exactly as before — for an unmarked
- * node or one that has a source.
+ * What a node's Image shows WHENEVER its source is empty: the canvas label (when `label` is given) or
+ * the live blank for a MARKED node; `null` — render exactly as before — for an unmarked node. It does
+ * not look at the source, so a renderer computes it once per marker/label and the component falls
+ * back to it the moment its source is cleared (a binding emptied, a context slot not yet filled).
  */
-export function emptyImageSrc(node: { elementStyle?: string | null } | null | undefined, src: unknown, label?: string | null): string | null {
-    if (src != null && src !== '') return null;
+export function emptyImagePlaceholder(node: { elementStyle?: string | null } | null | undefined, label?: string | null): string | null {
     if (!hasElementStyleMarker(node)) return null;
     return label ? emptyImageLabelSrc(label) : EMPTY_IMAGE_SRC;
 }
+
+/**
+ * The `src` a node's Image renders for a given source: its placeholder while the source is empty,
+ * `null` once it has one (the source itself renders) or when the node is unmarked.
+ */
+export function emptyImageSrc(node: { elementStyle?: string | null } | null | undefined, src: unknown, label?: string | null): string | null {
+    if (src != null && src !== '') return null;
+    return emptyImagePlaceholder(node, label);
+}

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 = {
@@ -1410,7 +1419,7 @@ export const SPEC_ELEMENT_STYLES = [
       "fontSize": "var(--iox-size-lead)",
       "fontWeight": "var(--iox-weight-body)",
       "lineHeight": "var(--iox-leading-body)",
-      "color": "var(--iox-text)"
+      "color": "inherit"
     }
   },
   {
@@ -1425,7 +1434,7 @@ export const SPEC_ELEMENT_STYLES = [
       "fontSize": "var(--iox-size-body)",
       "fontWeight": "var(--iox-weight-body)",
       "lineHeight": "var(--iox-leading-body)",
-      "color": "var(--iox-text)"
+      "color": "inherit"
     }
   },
   {
@@ -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';