@vectoriox/iox-ui 5.25.0 → 5.26.0

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

@@ -1,4 +1,5 @@
 import { deriveAccentTokens } from './brand';
+import { flavorColours, FlavorColours, preTintAccentGrounds } from './brand-neutrals';
 import { fontStackWithout, formatFontFamily } from './fonts';
 import { SPEC_AXES } from './flavor-spec.generated';
 import {
@@ -11,7 +12,8 @@ import {
  *
  * Layering, each step over the last (the boards' `tokenMap`, with the product's colour math):
  *   pack tokens → chosen font pair → shape · density · motion axes → pill-button rule →
- *   the author's own font roles → a seed ≠ the pack's own re-derives the accent quartet.
+ *   the author's own font roles → every COLOUR token from the brand seed and the background tint
+ *   (`flavorColours`, DS9: tinted neutrals, the accent quartet, the held contrast pairs).
  *
  * `mode` does not change rows — every row keeps its light value and its dark override; mode is
  * how the stylesheet is compiled.
@@ -91,13 +93,40 @@ export function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): D
         if (typeof family === 'string' && family.trim() !== '') set(role, userFontStack(family, byName.get(role)?.value), USER_TOKEN_SOURCE);
     }
 
+    setColours(byName, flavorColours(pack, { seed: choices.seed, tint: choices.tint ?? pack.defaults.tint }));
+
+    return rows;
+}
+
+/** Colour rows take their light value and the dark one only where it differs (the contract's own rule). */
+function setColours(byName: Map<string, DesignTokenRow>, colours: FlavorColours): void {
+    for (const [name, [light, dark]] of Object.entries(colours)) {
+        const row = byName.get(name);
+        if (!row) continue;
+        row.value = light;
+        if (dark !== undefined && dark !== light) row.values = { dark };
+        else delete row.values;
+    }
+}
+
+/**
+ * What the contract wrote for `choices` BEFORE DS9 — the baseline a studio that applied its look before
+ * the tint existed is judged against (`designBaseline`, `designTokenRepairs`): the look's own palette, the
+ * rows DS9 changed at their old values (`pack.legacy`), and a seed ≠ the pack's own re-deriving the accent
+ * set against `bg` alone, as `deriveAccentTokens` was called then. No held pairs, no tint.
+ */
+export function legacyFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): DesignTokenRow[] {
+    const rows = buildFlavorTokens(pack, { ...choices, seed: pack.seed, tint: 'neutral' });
+    const byName = new Map(rows.map(r => [r.name, r]));
+    for (const [name, old] of Object.entries(pack.legacy ?? {})) {
+        const row = byName.get(name);
+        if (!row) continue;
+        row.value = old.value;
+        if (old.dark !== undefined) row.values = { dark: old.dark };
+        else delete row.values;
+    }
     if (choices.seed && choices.seed.toLowerCase() !== pack.seed.toLowerCase()) {
-        const bg = byName.get('bg');
-        const inverseBg = byName.get('inverse-bg');
-        for (const accent of deriveAccentTokens(choices.seed, {
-            bg: bg?.value ?? '', bgDark: bg?.values?.dark,
-            inverseBg: inverseBg?.value, inverseBgDark: inverseBg?.values?.dark,
-        })) {
+        for (const accent of deriveAccentTokens(choices.seed, preTintAccentGrounds(pack.palette))) {
             const row = byName.get(accent.name);
             if (!row) continue;
             row.value = accent.value;
@@ -105,6 +134,5 @@ export function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): D
             else delete row.values;
         }
     }
-
     return rows;
 }

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

@@ -18,6 +18,9 @@ export * from './adopt';
 export * from './node-classes';
 export * from './empty-image';
 export * from './brand';
+export * from './colour-eval';
+export * from './brand-neutrals';
+export * from './contrast-audit';
 export * from './flavor-tokens';
 export * from './flavor-seed';
 export * from './spring';

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

@@ -121,7 +121,7 @@ export function tokensToDarkVarMap(tokens: ReadonlyArray<DesignTokenLike> | null
 }
 
 const TOKEN_REF = /var\(\s*--iox-([\w-]+)\s*(?:,([^()]*))?\)/g;
-const PLACEHOLDER = /\{\{\s*([\w-]+)\s*\}\}/g;
+const PLACEHOLDER = /\{\{\s*(~?)([\w-]+)\s*\}\}/g;
 
 /** A compiled colour mode — the contract's modes minus `auto`, which is a compile CHOICE, not values. */
 export type ResolvedMode = Exclude<DesignMode, 'auto'>;
@@ -163,6 +163,26 @@ export function resolveTokenValues(
     return out;
 }
 
+/**
+ * Every token's value INSIDE a section wearing `schemeId`, in one mode — what CSS computes there: the
+ * scheme's overrides (`{{token}}` / `{{~token}}` placeholders substituted from the root), every other
+ * row as declared, and `var()` references resolved within the section (the §3c re-declaration rule
+ * makes that the section's own resolution). `default` (or an unknown id) is the root.
+ */
+export function resolveSchemeTokenValues(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    mode: ResolvedMode,
+    schemeId: string,
+): Record<string, string> {
+    const rows = usableTokens(tokens);
+    const set = schemeId === DEFAULT_SCHEME ? undefined : (SPEC_SCHEMES as Readonly<Record<string, { set: Readonly<Record<string, string>> }>>)[schemeId]?.set;
+    if (!set) return resolveTokenValues(rows, mode);
+    const root = resolveTokenValues(rows, mode);
+    const other = resolveTokenValues(rows, mode === DARK ? LIGHT : DARK);
+    const overrides = new Map(schemeEntries(set, root, other));
+    return resolveTokenValues(rows.map(t => ({ name: t.name, value: overrides.get(t.name) ?? modeValue(t, mode) })), LIGHT);
+}
+
 /**
  * `value` with every `var(--iox-…)` replaced by that token's resolved root value in `mode` — what
  * the Style panel's Detach writes, so the node keeps exactly what it showed as a literal. An unknown
@@ -178,20 +198,25 @@ export function resolveTokenReferences(
         resolved[name] ?? (fallback !== undefined ? fallback.trim() : ref));
 }
 
-/** A scheme value with its `{{token}}` placeholders replaced by resolved root values — or null
- *  when a placeholder names a token the set does not have (the declaration is then omitted). */
-function substitute(template: string, resolved: Readonly<Record<string, string>>): string | null {
+type ResolvedValues = Readonly<Record<string, string>>;
+
+/** A scheme value with its placeholders replaced — `{{token}}` by the root's resolved value in this
+ *  mode, `{{~token}}` by its value in the OTHER mode (an inverse section is the other mode's ground,
+ *  DS9) — or null when a placeholder names a token the set does not have (the declaration is then
+ *  omitted). */
+function substitute(template: string, resolved: ResolvedValues, opposite: ResolvedValues): string | null {
     let missing = false;
-    const value = template.replace(PLACEHOLDER, (_, name: string) => {
-        if (!(name in resolved)) missing = true;
-        return resolved[name] ?? '';
+    const value = template.replace(PLACEHOLDER, (_, tilde: string, name: string) => {
+        const from = tilde ? opposite : resolved;
+        if (!(name in from)) missing = true;
+        return from[name] ?? '';
     });
     return missing ? null : value;
 }
 
-const schemeEntries = (set: Readonly<Record<string, string>>, resolved: Readonly<Record<string, string>>) =>
+const schemeEntries = (set: Readonly<Record<string, string>>, resolved: ResolvedValues, opposite: ResolvedValues) =>
     Object.entries(set)
-        .map(([name, template]): [string, string | null] => [name, substitute(template, resolved)])
+        .map(([name, template]): [string, string | null] => [name, substitute(template, resolved, opposite)])
         .filter((e): e is [string, string] => e[1] !== null);
 
 const hasPlaceholder = (value: string) => value.includes('{{');
@@ -209,12 +234,17 @@ const hasPlaceholder = (value: string) => value.includes('{{');
  *   and CSS makes both invalid. The contract writes `{{accent}}` instead — the token's ROOT value,
  *   resolved here at compile time (and again from dark values for the dark twin).
  */
-export function compileSchemeCss(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, scope?: string): string {
+export function compileSchemeCss(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    scope?: string,
+    opposite?: ResolvedValues,
+): string {
     const rows = usableTokens(tokens);
     if (!rows.length) return '';
     const resolved = resolveTokenValues(rows, LIGHT);
+    const other = opposite ?? resolveTokenValues(rows, DARK);
     return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
-        ...schemeEntries(set, resolved),
+        ...schemeEntries(set, resolved, other),
         ...rows.filter(t => !(t.name in set) && t.value.includes(REFERENCE))
             .map((t): [string, string] => [t.name, t.value]),
     ])).filter(Boolean).join('\n');
@@ -231,9 +261,9 @@ function darkSchemeRules(rows: ReadonlyArray<DesignTokenLike>, scope: string | u
     });
     return nonDefaultSchemes().map(([id, set]) => {
         const swapped = Object.fromEntries(Object.entries(set).filter(([, v]) => hasPlaceholder(v)));
-        const lightSwap = new Map(schemeEntries(swapped, light));
+        const lightSwap = new Map(schemeEntries(swapped, light, dark));
         return rule(schemeSelector(id, scope), [
-            ...schemeEntries(swapped, dark).filter(([name, value]) => lightSwap.get(name) !== value),
+            ...schemeEntries(swapped, dark, light).filter(([name, value]) => lightSwap.get(name) !== value),
             ...redeclared.filter(t => !(t.name in set)).map((t): [string, string] => [t.name, darkOf(t) as string]),
         ], '  ');
     });
@@ -249,15 +279,18 @@ export function compileTokenCssBlocks(
     tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
     opts: TokenCssOptions = {},
 ): TokenCssBlocks {
-    const rows = rowsForMode(usableTokens(tokens), opts.mode);
+    const all = usableTokens(tokens);
+    const rows = rowsForMode(all, opts.mode);
     const root = opts.scope ?? ROOT;
+    // A forced mode flattens the rows to ONE mode; a `{{~token}}` still reads the other mode's value.
+    const opposite = resolveTokenValues(all, opts.mode === DARK ? LIGHT : DARK);
     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, [...unset, ...rows.map((t): [string, string] => [t.name, t.value])]),
-        compileSchemeCss(rows, opts.scope),
+        compileSchemeCss(rows, opts.scope, opposite),
         ...ACCESSIBILITY_MEDIA.map(({ query, overrides }) =>
             media(query, [rule(root, presentOverrides(rows, overrides, false), '  ')])),
     ].filter(Boolean).join('\n');

package/styles/iox-design.css

@@ -28,3 +28,19 @@ iox-gallery.iox-es-media[data-iox-empty] > .iox-gallery {
 .iox-es-media[data-iox-empty] .iox-gallery__overlay {
     display: none;
 }
+
+/* What a filled button HOLDS reads its ink (DS9, the contract's `inkScopes`, pinned by
+   ink-scopes.spec.ts). An Icon dropped into a Primary button wore the `icon` style — `icon-color`
+   = accent-text, painted on the accent fill: 1:1 in a Brand section. Inside a button every token a
+   child's colour reads becomes `currentColor` — the button's own ink — so the label and the icon read
+   alike; an author's literal on the child still wins. */
+.iox-es-button-primary,
+.iox-es-button-secondary,
+.iox-es-button-ghost {
+    --iox-icon-color: currentColor;
+    --iox-heading-color: currentColor;
+    --iox-eyebrow-color: currentColor;
+    --iox-link-color: currentColor;
+    --iox-link-hover-color: currentColor;
+    --iox-text-muted: currentColor;
+}

package/styles/iox-forms.css

@@ -101,8 +101,8 @@
  * A Field wearing the `field` element style renders `iox-es iox-es-field`; everything below is
  * scoped to it, so a Field saved before DS2 renders exactly as above whatever tokens the org holds,
  * and seeding an org's tokens never restyles a live legacy form.
- * The first six rules ARE the spec's `fieldClassBaseline`, selectors and values verbatim (pinned by
- * iox-ui's field-baseline spec). Values are bare spec tokens: a marked Field only exists where the
+ * Every rule below IS the spec's `fieldClassBaseline`, selector and values verbatim (pinned by
+ * iox-ui's token-names spec). Values are bare spec tokens: a marked Field only exists where the
  * builder seeded them. */
 .iox-es-field .iox-field__control {
   background: var(--iox-field-bg);
@@ -117,7 +117,7 @@
   transition: border-color var(--iox-dur-base) var(--iox-ease-standard), box-shadow var(--iox-dur-base) var(--iox-ease-standard);
 }
 .iox-es-field .iox-field__control:focus-visible {
-  border-color: var(--iox-accent);
+  border-color: var(--iox-accent-text);
   box-shadow: var(--iox-field-focus);
   outline: none;
 }
@@ -138,6 +138,14 @@
 .iox-es-field.iox-invalid .iox-field__control {
   border-color: var(--iox-danger);
 }
+/* DS9 (contrast audit): the placeholder is themed (the UA's #757575 read 1:1 in a Brand section); the
+   native controls, the focus edge and the switch read `accent-text` — the accent GATED as text on every
+   ground — never the `accent` fill (Pop's orange on its yellow panel: 2.13:1); the off track is
+   `text-muted` under a `bg` thumb (the decorative `line` it wore read 1.06:1). WCAG 1.4.11: 3:1. */
+.iox-es-field .iox-field__control::placeholder {
+  color: var(--iox-text-muted);
+  opacity: 1;
+}
 /* Native-appearance controls (checkbox, radio, range — and the switch, a checkbox) draw themselves:
    the box baseline must not frame them. `:where()` keeps this at the baseline's specificity, so the
    switch rules below still paint the track. */
@@ -145,18 +153,16 @@
   border: none;
   padding: 0;
   background: transparent;
+  accent-color: var(--iox-accent-text);
 }
 .iox-es-field .iox-field__control--switch {
-  background: var(--iox-line);
+  background: var(--iox-text-muted);
   transition: background var(--iox-dur-fast) var(--iox-ease-standard);
 }
 .iox-es-field .iox-field__control--switch::before {
-  background: var(--iox-accent-ink);
+  background: var(--iox-bg);
   transition: transform var(--iox-dur-fast) var(--iox-ease-standard);
 }
 .iox-es-field .iox-field__control--switch:checked {
-  background: var(--iox-accent);
-}
-.iox-es-field .iox-field__control--range {
-  accent-color: var(--iox-accent);
+  background: var(--iox-accent-text);
 }