@vectoriox/iox-ui 5.24.0 → 5.26.0

package/src/design-core/contrast-audit.ts

@@ -0,0 +1,214 @@
+import { toHexColor, wcagContrastRatio, WCAG_AA_TEXT } from './brand';
+import { WCAG_AA_UI } from './brand-neutrals';
+import { compositeOver, paintColours, parseCssColour, quantizeRgb, Rgba, ringColour } from './colour-eval';
+import { ElementStyle, ELEMENT_STYLES } from './element-styles';
+import { SPEC_CONTRAST_AUDIT, SPEC_INK_SCOPES, SPEC_SCHEMES } from './flavor-spec.generated';
+import { DesignTokenLike, ResolvedMode, resolveSchemeTokenValues } from './token-css';
+
+/**
+ * The contrast AUDIT (design-system DS9). The contract's token pairs were all AA and Doron still found a
+ * button whose icon was "almost hard to see": the failures live in the PAIRINGS element styles make — an
+ * Icon dropped into a Primary button painted `icon-color` (accent-text) on the accent fill, 1:1 in a Brand
+ * section. So this resolves what each element style actually paints, the way CSS resolves it:
+ *
+ * - in every section scheme (`resolveSchemeTokenValues`), directly on the section and inside every
+ *   container style (Card, Panel, Navigation bar, Dialog);
+ * - `inherit` → the container's ink, a transparent fill → what is under it, translucent fills composited,
+ *   a gradient ground (Glass's mesh, Midnight's glow) checked at its worst stop;
+ * - base and hover; a button's icon read through the contract's `inkScopes` (it takes the button's ink),
+ *   its focus ring; the form parts the field baseline paints (`contrastAudit.formParts`).
+ *
+ * WCAG 2: 4.5:1 for text, 3:1 for glyphs, UI boundaries and focus indicators (1.4.11), judged on 8-bit
+ * colours. The same audit gates the contract (`colour.mjs auditContrast`, every flavor × tint × a seed
+ * sweep) and `contrast-audit.spec.ts` sweeps it here, so no pack or brand can regress.
+ */
+
+export interface ContrastFinding {
+    scheme: string;
+    /** `section`, or the container style the element sits in. */
+    container: string;
+    element: string;
+    part: string;
+    fg: string;
+    bg: string;
+    ratio: number;
+    min: number;
+    pass: boolean;
+}
+
+interface FormPart {
+    readonly part: string;
+    readonly fg: string | ReadonlyArray<string>;
+    readonly on?: string;
+    readonly any?: boolean;
+    readonly thumb?: string;
+    readonly min: number;
+}
+interface InkScope { readonly styles: ReadonlyArray<string>; readonly set: Readonly<Record<string, string>>; }
+
+const FORM_PARTS: ReadonlyArray<FormPart> = SPEC_CONTRAST_AUDIT.formParts;
+const INK_SCOPES: ReadonlyArray<InkScope> = SPEC_INK_SCOPES;
+const SCHEME_IDS: ReadonlyArray<string> = Object.keys(SPEC_SCHEMES);
+const CONTAINER_GROUPS: ReadonlySet<string> = new Set(['Layout', 'Overlays']);
+const NOT_CONTENT: ReadonlySet<string> = new Set(['rule', 'media']);
+const SECTION_STYLE = 'section';
+const ICON_STYLE = 'icon';
+const BUTTON_GROUP = 'Buttons';
+const GLYPH_GROUP = 'Media';
+const FORMS_GROUP = 'Forms';
+const DEFAULT_SCHEME = 'default';
+const SECTION = 'section';
+const FIELD = 'field';
+const WHITE: Rgba = { r: 1, g: 1, b: 1, a: 1 };
+const SINGLE_REF = /^var\(--iox-([\w-]+)\)$/;
+const TOKEN_REF = /var\(\s*--iox-([\w-]+)\s*(?:,([^()]*))?\)/g;
+
+type Values = Readonly<Record<string, string>>;
+type StyleMap = Readonly<Record<string, string>>;
+
+/** A style value with its var() references resolved against `values` (already-resolved tokens). */
+function resolveIn(values: Values, v: string | undefined): string {
+    const single = SINGLE_REF.exec(String(v ?? '').trim());
+    if (single) return values[single[1]] ?? (v as string);
+    return String(v ?? '').replace(TOKEN_REF, (ref, name: string, fallback?: string) =>
+        values[name] ?? (fallback !== undefined ? fallback.trim() : ref));
+}
+
+const overAll = (tops: Rgba[], unders: Rgba[]) => unders.flatMap(u => tops.map(t => compositeOver(t, u)));
+const opaque = (paints: Rgba[]) => paints.some(c => c.a > 0);
+
+const ownStyle = (e: ElementStyle) => (e.base ?? {}) as StyleMap;
+
+function inkScoped(values: Values, styleId: string): Values {
+    const scope = INK_SCOPES.find(s => s.styles.includes(styleId));
+    return scope ? { ...values, ...scope.set } : values;
+}
+
+/** Every pair a reader meets, for one set of token rows in one mode. */
+export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode: ResolvedMode): ContrastFinding[] {
+    const findings: ContrastFinding[] = [];
+    const styles = ELEMENT_STYLES;
+    const byId = new Map(styles.map(e => [e.id, e]));
+    const containers: Array<ElementStyle | null> = [
+        null,
+        ...styles.filter(e => CONTAINER_GROUPS.has(e.group) && ownStyle(e)['backgroundColor'] && e.id !== SECTION_STYLE),
+    ];
+    const content = styles.filter(e => !CONTAINER_GROUPS.has(e.group) && (ownStyle(e)['color'] || ownStyle(e)['backgroundColor'])
+        && e.group !== FORMS_GROUP && !NOT_CONTENT.has(e.id));
+    const notices = styles.filter(e => e.group === FORMS_GROUP && ownStyle(e)['color']);
+    const section = ownStyle(byId.get(SECTION_STYLE) as ElementStyle);
+    const iconColour = ownStyle(byId.get(ICON_STYLE) as ElementStyle)['color'];
+
+    for (const schemeId of SCHEME_IDS) {
+        const values = resolveSchemeTokenValues(rows, mode, schemeId);
+        const pageInk = parseCssColour(values['text']);
+        const page = paintColours(values['page-bg'], pageInk);
+        const sectionPaint = paintColours(values['section-bg'], pageInk);
+        const ground = opaque(sectionPaint)
+            ? sectionPaint.map(c => (c.a < 1 ? compositeOver(c, page[0] ?? WHITE) : c))
+            : page;
+        const sectionInk = parseCssColour(resolveIn(values, section['color']), pageInk);
+
+        for (const box of containers) {
+            const boxStyle = box ? ownStyle(box) : null;
+            const bgs = boxStyle ? overAll(paintColours(resolveIn(values, boxStyle['backgroundColor']), sectionInk), ground) : ground;
+            const boxInk = boxStyle?.['color'] && boxStyle['color'] !== 'inherit'
+                ? parseCssColour(resolveIn(values, boxStyle['color']), sectionInk) : sectionInk;
+            const where = { scheme: schemeId, container: box?.id ?? SECTION };
+            const record = (element: string, part: string, fg: string, bg: string, ratio: number, min: number) =>
+                findings.push({ ...where, element, part, fg, bg, ratio: Math.round(ratio * 100) / 100, min, pass: ratio >= min - 1e-9 });
+            const check = (element: string, part: string, fg: Rgba | null, under: Rgba[], min: number) => {
+                if (!fg) return;
+                for (const g of under) {
+                    const bg = quantizeRgb(g);
+                    const f = quantizeRgb(fg.a < 1 ? compositeOver(fg, bg) : fg);
+                    record(element, part, toHexColor(f), toHexColor(bg), wcagContrastRatio(f, bg), min);
+                }
+            };
+
+            check(box?.id ?? SECTION, 'text', boxInk, bgs, WCAG_AA_TEXT);
+            for (const e of content) {
+                const states: Array<[string, StyleMap]> = [['base', ownStyle(e)], ...(e.hover ? [['hover', { ...ownStyle(e), ...e.hover }] as [string, StyleMap]] : [])];
+                const glyph = e.group === GLYPH_GROUP;
+                for (const [state, s] of states) {
+                    const fill = s['backgroundColor'] ? paintColours(resolveIn(values, s['backgroundColor']), boxInk) : [];
+                    const under = fill.length && opaque(fill) ? overAll(fill, bgs) : bgs;
+                    const ink = s['color'] ? parseCssColour(resolveIn(values, s['color']), boxInk) : boxInk;
+                    check(e.id, state === 'base' ? (glyph ? 'glyph' : 'text') : `${state} text`, ink, under, glyph ? WCAG_AA_UI : WCAG_AA_TEXT);
+                    if (state === 'base' && e.group === BUTTON_GROUP) {
+                        check(e.id, 'icon', parseCssColour(resolveIn(inkScoped(values, e.id), iconColour), ink), under, WCAG_AA_UI);
+                        const focus = (e.focus as StyleMap | undefined)?.['boxShadow'];
+                        if (focus) check(e.id, 'focus ring', ringColour(resolveIn(values, focus), ink), bgs, WCAG_AA_UI);
+                    }
+                }
+            }
+            for (const part of FORM_PARTS) {
+                const fieldBg = paintColours(resolveIn(values, part.on ?? 'transparent'), boxInk);
+                const under = part.on && opaque(fieldBg) ? overAll(fieldBg, bgs) : bgs;
+                if (part.any) {
+                    for (const g of under) {
+                        const bg = quantizeRgb(g);
+                        const ratio = Math.max(...(part.fg as ReadonlyArray<string>).map(fg => {
+                            const c = parseCssColour(resolveIn(values, fg), boxInk);
+                            return c ? wcagContrastRatio(quantizeRgb(c.a < 1 ? compositeOver(c, bg) : c), bg) : 1;
+                        }));
+                        record(FIELD, part.part, '', toHexColor(bg), ratio, part.min);
+                    }
+                    continue;
+                }
+                const paint = parseCssColour(resolveIn(values, part.fg as string), boxInk);
+                check(FIELD, part.part, paint, under, part.min);
+                if (part.thumb && paint) {
+                    check(FIELD, `${part.part} thumb`, parseCssColour(resolveIn(values, part.thumb), boxInk), bgs.map(b => compositeOver(paint, b)), part.min);
+                }
+            }
+            if (box === null && schemeId === DEFAULT_SCHEME) {
+                for (const n of notices) {
+                    const fill = paintColours(resolveIn(values, ownStyle(n)['backgroundColor']), boxInk);
+                    check(n.id, 'text', parseCssColour(resolveIn(values, ownStyle(n)['color']), boxInk), overAll(fill, bgs), WCAG_AA_TEXT);
+                }
+            }
+        }
+    }
+    return findings;
+}
+
+/** The pairs the Design ▸ Colour tab lists for the CURRENT brand (Board 6 + DS9): what a filled button
+ *  shows, and the link on every section scheme — each the worst case on the section itself. */
+export enum ColourCheckId {
+    ButtonLabel = 'button-label',
+    ButtonIcon = 'button-icon',
+    Link = 'link',
+}
+
+export interface ColourCheck {
+    id: ColourCheckId;
+    /** The section scheme the pair sits in (`default` for the button). */
+    scheme: string;
+    fg: string;
+    bg: string;
+    ratio: number;
+    min: number;
+    passes: boolean;
+}
+
+const COLOUR_TAB_CHECKS: ReadonlyArray<{ id: ColourCheckId; element: string; part: string; schemes: ReadonlyArray<string> }> = [
+    { id: ColourCheckId.ButtonLabel, element: 'button-primary', part: 'text', schemes: [DEFAULT_SCHEME] },
+    { id: ColourCheckId.ButtonIcon, element: 'button-primary', part: 'icon', schemes: [DEFAULT_SCHEME] },
+    { id: ColourCheckId.Link, element: 'link', part: 'text', schemes: SCHEME_IDS },
+];
+
+/** The Colour tab's brand rows, from one audit of the rows the canvas wears. */
+export function colourTabChecks(rows: ReadonlyArray<DesignTokenLike>, mode: ResolvedMode): ColourCheck[] {
+    const findings = auditDesignContrast(rows, mode).filter(f => f.container === SECTION);
+    const out: ColourCheck[] = [];
+    for (const check of COLOUR_TAB_CHECKS) {
+        for (const scheme of check.schemes) {
+            const hits = findings.filter(f => f.scheme === scheme && f.element === check.element && f.part === check.part);
+            if (!hits.length) continue;
+            const worst = hits.reduce((a, b) => (b.ratio < a.ratio ? b : a));
+            out.push({ id: check.id, scheme, fg: worst.fg, bg: worst.bg, ratio: worst.ratio, min: worst.min, passes: worst.pass });
+        }
+    }
+    return out;
+}

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

@@ -1,7 +1,7 @@
 import { deriveBrandTokens } from './brand';
 import { SPEC_LEGACY_ALIASES } from './flavor-spec.generated';
 import { SWISS_FLAVOR } from './flavor';
-import { buildFlavorTokens } from './flavor-tokens';
+import { buildFlavorTokens, legacyFlavorTokens } from './flavor-tokens';
 import {
     FlavorRevertPlan, FlavorSeedOptions, FlavorSeedPlan, planFlavorRevert, planFlavorSeed, SeedBaseline, SeedExpectation, untouchedSeedRow,
 } from './flavor-seed';
@@ -28,6 +28,13 @@ export function designTokenRows(choices: DesignChoices): DesignTokenRow[] {
     return pack ? buildFlavorTokens(pack, { ...choices, flavorId: pack.id }) : [];
 }
 
+/** What a design wrote BEFORE DS9 (the look's own palette, the rows DS9 changed at their old values, the
+ *  accent derived against `bg` alone) — empty for an unknown pack. */
+export function legacyDesignTokenRows(choices: DesignChoices): DesignTokenRow[] {
+    const pack = flavorPackById(choices.flavorId);
+    return pack ? legacyFlavorTokens(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'>> =
@@ -39,18 +46,22 @@ function swissExpectations(seed: string | null): Map<string, SeedExpectation> {
     return expectations(rows);
 }
 
-/** What a v2 pack writes at its OWN defaults, by pack id — computed once per id per caller. */
-function packDefaultsLookup(): (packId: string) => Map<string, SeedExpectation> | undefined {
-    const cache = new Map<string, Map<string, SeedExpectation> | undefined>();
+/** What a v2 pack writes at its OWN defaults, by pack id — today and before DS9 (a studio seeded then holds
+ *  the old defaults) — computed once per id per caller. */
+function packDefaultsLookup(): (packId: string) => ReadonlyArray<Map<string, SeedExpectation>> {
+    const cache = new Map<string, ReadonlyArray<Map<string, SeedExpectation>>>();
     return packId => {
         if (!cache.has(packId)) {
             const pack = isRetiredFlavorId(packId) ? undefined : flavorPackById(packId);
-            cache.set(packId, pack && pack.id === packId ? expectations(designTokenRows(packDesignChoices(pack.id))) : undefined);
+            const choices = pack && pack.id === packId ? packDesignChoices(pack.id) : null;
+            cache.set(packId, choices ? [expectations(designTokenRows(choices)), expectations(legacyDesignTokenRows(choices))] : []);
         }
-        return cache.get(packId);
+        return cache.get(packId) as ReadonlyArray<Map<string, SeedExpectation>>;
     };
 }
 
+const present = (list: ReadonlyArray<SeedExpectation | undefined>): SeedExpectation[] => list.filter((e): e is SeedExpectation => !!e);
+
 /**
  * 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
@@ -66,14 +77,16 @@ function packDefaultsLookup(): (packId: string) => Map<string, SeedExpectation>
  */
 export function designBaseline(previous: StoredDesign): SeedBaseline {
     const retired = isRetiredFlavorId(previous.storedFlavorId);
-    const current = expectations(designTokenRows(retired ? packDesignChoices(previous.choices.flavorId) : previous.choices));
+    const wrote = retired ? packDesignChoices(previous.choices.flavorId) : previous.choices;
+    const current = expectations(designTokenRows(wrote));
+    const beforeTint = expectations(legacyDesignTokenRows(wrote));
     const swiss = swissExpectations(retired ? previous.storedSeed : null);
     const packDefaults = packDefaultsLookup();
     return (row: StoredDesignTokenRow) => {
         const stampedBy = SEED_STAMP.exec(row.source ?? '')?.[1];
         if (stampedBy === SWISS_FLAVOR.id) return swiss.get(row.name);
-        const ownDefault = stampedBy ? packDefaults(stampedBy)?.get(row.name) : undefined;
-        return [current.get(row.name), ownDefault].filter((e): e is SeedExpectation => !!e);
+        const ownDefaults = stampedBy ? packDefaults(stampedBy).map(m => m.get(row.name)) : [];
+        return present([current.get(row.name), beforeTint.get(row.name), ...ownDefaults]);
     };
 }
 
@@ -121,15 +134,18 @@ export function missingDesignRows(existing: ReadonlyArray<{ name: string }>, cho
 /**
  * The builder-load REPAIR (DS4.1): rows the design writes that are the machine's and nobody touched,
  * yet hold something other than the design's value, are rewritten — so an org heals on its next load
- * with no author action. Two shapes:
+ * with no author action. Three shapes:
  * - stamped by the current pack, light value exactly the pack's, dark half not: iox-cms dropped
  *   `values.dark` on every write from F0 to DS4 (`values` was an implicit relation), and a revert could
  *   leave the previous apply's dark behind;
  * - stamped by a v2 pack and still holding what THAT pack writes at its own defaults (its dark half
  *   possibly lost the same way) while the stored design says otherwise: an apply that judged the row
  *   edited (before 5.24.0, a lost dark half did) left it on the default — the six brand rows of a studio
- *   whose brand colour never reached its accent.
- * No author edit produces either shape — the Tokens panel edited the light value only, and since DS8 an
+ *   whose brand colour never reached its accent;
+ * - stamped by the current pack and still holding what the design wrote BEFORE DS9
+ *   (`legacyDesignTokenRows`): the contrast fixes — a 3:1 `line-strong`, a 3:1 focus ring, an
+ *   `accent-text` that reads on every ground — reach a studio that applied its look before them.
+ * No author edit produces any of these shapes — the Tokens panel edited the light value only, and since DS8 an
  * edit makes the row `source: user`, which this never touches.
  */
 export function designTokenRepairs(existing: ReadonlyArray<StoredDesignTokenRow>, choices: DesignChoices): FlavorSeedPlan['update'] {
@@ -137,6 +153,7 @@ export function designTokenRepairs(existing: ReadonlyArray<StoredDesignTokenRow>
     if (!pack) return [];
     const stamp = flavorSourceStamp(pack.id);
     const desired = new Map(designTokenRows(choices).map(r => [r.name, r]));
+    const beforeTint = expectations(legacyDesignTokenRows(choices));
     const packDefaults = packDefaultsLookup();
     const out: FlavorSeedPlan['update'] = [];
     for (const row of existing ?? []) {
@@ -145,8 +162,11 @@ export function designTokenRepairs(existing: ReadonlyArray<StoredDesignTokenRow>
         if (row.value === want.value && (row.values?.dark ?? '') === (want.values?.dark ?? '') && row.source === stamp) continue;
         const stampedBy = SEED_STAMP.exec(row.source ?? '')?.[1];
         const darkOnly = row.source === stamp && row.value === want.value;
-        const ownDefault = stampedBy ? packDefaults(stampedBy)?.get(row.name) : undefined;
-        if (!darkOnly && !(ownDefault && untouchedSeedRow(row, [ownDefault]))) continue;
+        const machineWrote = present([
+            ...(stampedBy ? packDefaults(stampedBy).map(m => m.get(row.name)) : []),
+            ...(stampedBy === pack.id ? [beforeTint.get(row.name)] : []),
+        ]);
+        if (!darkOnly && !untouchedSeedRow(row, machineWrote)) continue;
         out.push({ id: row._id, data: { value: want.value, values: want.values ?? {}, source: stamp, ...(want.group ? { group: want.group } : {}), ...(want.tier ? { tier: want.tier } : {}) } });
     }
     return out;

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

@@ -1,6 +1,6 @@
 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 { DesignChoices, DesignMode, FlavorPackV2, FontRoleToken, PRE_TINT_DEFAULT, SPEC_FLAVORS, TintId } from './design-token.model';
 import type { FlavorRevertSnapshot } from './flavor-seed';
 
 /**
@@ -30,6 +30,7 @@ export enum DesignConfigKey {
     Motion = 'motion',
     PillButtons = 'pillButtons',
     Mode = 'mode',
+    Tint = 'tint',
     Fonts = 'fonts',
     Revert = 'revert',
 }
@@ -121,6 +122,7 @@ export function resolveDesignChoices(partial: Partial<DesignChoices> | null | un
         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,
+        tint: keyOf(SPEC_AXES.tints, asString(partial?.tint)) ?? pack.defaults.tint,
         ...(fonts ? { fonts } : {}),
     };
 }
@@ -141,9 +143,14 @@ export function choicesForPack(flavorId: string, applied: DesignChoices | null |
     return resolveDesignChoices({ flavorId: pack.id, fonts: applied?.fonts });
 }
 
-/** A stored `settings.design` config → the resolved design. No row (or no config) → Crisp's defaults. */
+/**
+ * A stored `settings.design` config → the resolved design. No row (or no config) → Crisp's defaults. A
+ * row stored before DS9 has no `tint`: it was applied with the look's own palette, so it reads `neutral`
+ * (never the pack's new default — the studio's rows hold the palette, and nothing may repaint them unasked).
+ */
 export function readDesignConfig(config: ReadonlyArray<DesignConfigEntry> | null | undefined, hasRow = !!config): StoredDesign {
     const map = configMap(config);
+    const storedTint = asString(map.get(DesignConfigKey.Tint)) ?? (hasRow ? PRE_TINT_DEFAULT : null);
     const storedFlavorId = asString(map.get(DesignConfigKey.FlavorId));
     const storedSeed = asString(map.get(DesignConfigKey.BrandSeed));
     const choices = resolveDesignChoices({
@@ -155,6 +162,7 @@ export function readDesignConfig(config: ReadonlyArray<DesignConfigEntry> | null
         motion: map.get(DesignConfigKey.Motion) as DesignChoices['motion'],
         pillButtons: asBoolean(map.get(DesignConfigKey.PillButtons)) ?? undefined,
         mode: map.get(DesignConfigKey.Mode) as DesignMode,
+        tint: (storedTint ?? undefined) as TintId | undefined,
         fonts: map.get(DesignConfigKey.Fonts) as DesignChoices['fonts'],
     });
     return {
@@ -189,6 +197,7 @@ export function designConfigEntries(
         { key: DesignConfigKey.Motion, value: c.motion },
         { key: DesignConfigKey.PillButtons, value: String(c.pillButtons) },
         { key: DesignConfigKey.Mode, value: c.mode },
+        { key: DesignConfigKey.Tint, value: c.tint },
         ...(c.fonts ? [{ key: DesignConfigKey.Fonts, value: JSON.stringify(c.fonts) }] : []),
         ...(revert ? [{ key: DesignConfigKey.Revert, value: JSON.stringify(revert) }] : []),
     ];
@@ -200,6 +209,6 @@ export function sameDesignChoices(a: DesignChoices, b: DesignChoices): boolean {
     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
+        && x.pillButtons === y.pillButtons && x.mode === y.mode && x.tint === y.tint
         && JSON.stringify(x.fonts ?? {}) === JSON.stringify(y.fonts ?? {});
 }

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

@@ -41,6 +41,11 @@ export type ShapeId = keyof typeof SPEC_AXES.shapes;
 export type DensityId = keyof typeof SPEC_AXES.densities;
 export type MotionId = keyof typeof SPEC_AXES.motions;
 export type DesignMode = (typeof SPEC_AXES.modes)[number];
+/** Background tint (DS9): Neutral keeps the look's own palette; Subtle / Rich tint its neutrals with the brand. */
+export type TintId = keyof typeof SPEC_AXES.tints;
+export const TINT_IDS = Object.keys(SPEC_AXES.tints) as ReadonlyArray<TintId>;
+/** What a studio that stored its look BEFORE the tint existed wears: exactly the look's own palette. */
+export const PRE_TINT_DEFAULT: TintId = 'neutral';
 export type SchemeId = keyof typeof SPEC_SCHEMES;
 export type FontRoleToken = (typeof SPEC_FONT_ROLES)[number]['token'];
 
@@ -54,6 +59,9 @@ export interface DesignChoices {
     motion: MotionId;
     pillButtons: boolean;
     mode: DesignMode;
+    /** Absent = the pack's default (`defaults.tint`). `readDesignConfig` reads a row stored before DS9 as
+     *  `neutral` — the palette it was applied with. */
+    tint?: TintId;
     fonts?: Partial<Record<FontRoleToken, string>>;
 }
 
@@ -75,6 +83,19 @@ export interface FontPair {
     readonly families: ReadonlyArray<string>;
 }
 
+/** A flavor's own colour palette (the Neutral tint): every colour token, light + the dark values that differ. */
+export interface FlavorPalette {
+    readonly light: Readonly<Record<string, string>>;
+    readonly dark: Readonly<Record<string, string>>;
+}
+
+/** How a flavor takes the brand's tint: which neutral roles, how strongly, and its tinted paints. */
+export interface FlavorTintConfig {
+    readonly scale: number;
+    readonly roles: ReadonlyArray<string>;
+    readonly paints?: ReadonlyArray<string>;
+}
+
 /** A flavor exactly as the spec writes it. */
 export interface FlavorPackV2 {
     readonly id: string;
@@ -90,10 +111,15 @@ export interface FlavorPackV2 {
         readonly motion: MotionId;
         readonly pillButtons: boolean;
         readonly mode: DesignMode;
+        readonly tint: TintId;
     };
     readonly seed: string;
     readonly seeds: ReadonlyArray<string>;
     readonly pairs: ReadonlyArray<FontPair>;
+    readonly palette: FlavorPalette;
+    readonly tint: FlavorTintConfig;
+    /** What the contract wrote before DS9 for the rows DS9 changed at the Neutral tint (`legacyFlavorTokens`). */
+    readonly legacy: Readonly<Record<string, { readonly value: string; readonly dark?: string }>>;
     readonly tokens: ReadonlyArray<FlavorSpecToken>;
 }