@vectoriox/iox-ui 5.10.0 → 5.12.0

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

@@ -1,6 +1,6 @@
 import { deriveAccentTokens } from './brand';
 import { cssString } from './fonts';
-import { FLAVOR_SPEC } from './flavor-spec.generated';
+import { SPEC_AXES } from './flavor-spec.generated';
 import {
     DesignChoices, DesignTokenRow, FlavorPackV2, FlavorSpecToken, flavorSourceStamp, USER_TOKEN_SOURCE,
 } from './design-token.model';
@@ -70,7 +70,7 @@ export function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): D
     const pair = pack.pairs.find(p => p.id === choices.pairId) ?? pack.pairs[0];
     for (const [name, value] of Object.entries(pair?.tokens ?? {})) set(name, value);
 
-    const axes = FLAVOR_SPEC.axes;
+    const axes = SPEC_AXES;
     for (const [name, value] of [
         ...axisValues(axes.shapes, choices.shape),
         ...axisValues(axes.densities, choices.density),
@@ -86,7 +86,11 @@ export function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): D
 
     if (choices.seed && choices.seed.toLowerCase() !== pack.seed.toLowerCase()) {
         const bg = byName.get('bg');
-        for (const accent of deriveAccentTokens(choices.seed, { bg: bg?.value ?? '', bgDark: bg?.values?.dark })) {
+        const 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,
+        })) {
             const row = byName.get(accent.name);
             if (!row) continue;
             row.value = accent.value;

package/src/design-core/flavor.ts

@@ -1,18 +1,11 @@
-import { styleKeyToKebab } from './css-names';
 import { DesignTokenGroup, DesignTokenTier, DesignTokenType } from './design-token.model';
 
 /**
- * Flavors (flavors-and-theming-plan.md, F1): the design language a studio launches with,
- * expressed as data. THE invariant — a flavor never writes a literal into a node; it writes
- * tokens, and element defaults that REFERENCE tokens. To that end a pack's `defaults` map
- * holds TOKEN NAMES, not CSS values: the resolver builds `var(--iox-<name>, <packValue>)`,
- * so smuggling a literal in is impossible by construction, and the validator only has to
- * check that every referenced token exists.
- *
- * The fallback is the bootstrap: until F2 seeds the org's `designtokens` rows, no `--iox-*`
- * var is defined anywhere, and `var(--iox-radius-control, 4px)` must still paint identically
- * in the builder canvas and the SSR page. Once tokens ARE seeded (or re-themed), the var wins
- * over the fallback everywhere — which is exactly the §3 propagation story.
+ * 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.
  */
 
 export interface FlavorTokenDef {
@@ -32,82 +25,24 @@ export interface FlavorPack {
     label: string;
     blurb: string;
     tokens: FlavorTokenDef[];
-    /** type → styleTrait → TOKEN NAME (never a CSS value — see the module header). */
-    defaults: Record<string, Record<string, string>>;
     /** F2: the accent's hue rotation (degrees in OKLab) from the brand seed — a pack opinion. */
     accentHueDeg?: number;
 }
 
-/** trait → `var(--iox-<token>, <packValue>)` for one node type. Unknown type → {}. */
-export function resolveFlavorDefaults(
-    type: string,
-    pack: FlavorPack | null | undefined,
-): Record<string, string> {
-    const map = pack?.defaults?.[type];
-    if (!map) return {};
-    const byName = new Map((pack!.tokens ?? []).map(t => [t.name, t.value]));
-    const out: Record<string, string> = {};
-    for (const [trait, tokenName] of Object.entries(map)) {
-        const fallback = byName.get(tokenName);
-        if (fallback === undefined) continue;   // validator fails the build; runtime stays safe
-        out[trait] = `var(--iox-${tokenName}, ${fallback})`;
-    }
-    return out;
-}
-
-/**
- * The ENGINE's half of the cascade: kebab `prop: var(…)` declarations for every pack default
- * the node's persisted styleProps does NOT set. Appended beside renderDefaultDeclarations —
- * same guard-on-undefined discipline, so a node saved post-F1 (var already serialised via the
- * builder's trait defaults) is untouched, and a legacy node picks the pack default up at
- * render time. Node styleProps always wins.
- */
-export function flavorDefaultDeclarations(
-    type: string,
-    styleProps: Record<string, any> | null | undefined,
-    pack: FlavorPack | null | undefined,
-): string[] {
-    const sp = styleProps ?? {};
-    const out: string[] = [];
-    for (const [trait, value] of Object.entries(resolveFlavorDefaults(type, pack))) {
-        if (sp[trait] === undefined) out.push(`${styleKeyToKebab(trait)}: ${value}`);
-    }
-    return out;
-}
-
-/**
- * The CI gate (flavors plan §10 C4): a pack may only name types and traits that exist in the
- * live component registry, and tokens it defines itself. Returns human-readable errors; a
- * consumer spec feeds it the REAL registry and asserts [].
- */
-export function validateFlavorPack(
-    pack: FlavorPack,
-    knownTraitsByType: Record<string, ReadonlySet<string> | string[]>,
-): string[] {
+/** A pack's own sanity: every token row names itself and carries a value. Returns errors. */
+export function validateFlavorPack(pack: FlavorPack): string[] {
     const errors: string[] = [];
-    const tokenNames = new Set((pack.tokens ?? []).map(t => t.name));
     for (const t of pack.tokens ?? []) {
         if (!t.name) errors.push(`${pack.id}: token with empty name`);
         if (!t.value) errors.push(`${pack.id}: token "${t.name}" has no value`);
     }
-    for (const [type, traits] of Object.entries(pack.defaults ?? {})) {
-        const known = knownTraitsByType[type];
-        if (!known) { errors.push(`${pack.id}: unknown component type "${type}"`); continue; }
-        const knownSet = known instanceof Set ? known : new Set(known);
-        for (const [trait, tokenName] of Object.entries(traits)) {
-            if (!knownSet.has(trait)) errors.push(`${pack.id}: "${type}" has no style trait "${trait}"`);
-            if (!tokenNames.has(tokenName)) errors.push(`${pack.id}: "${type}.${trait}" references undefined token "${tokenName}"`);
-            if (/[:(]|^#|\d/.test(tokenName)) errors.push(`${pack.id}: "${type}.${trait}" must name a token, not a value ("${tokenName}")`);
-        }
-    }
     return errors;
 }
 
 /**
- * Swiss — the default pack (flavors plan §8: "the flavor that can never embarrass anyone").
- * Deliberately SMALL at F1: radius + control padding on the clickables, surface radius on Card.
- * Colour, type and motion arrive with the brand step (F2) — a colour default here would repaint
- * legacy pages before anyone chose anything.
+ * 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`.
  */
 export const SWISS_FLAVOR: FlavorPack = {
     id: 'swiss',
@@ -120,18 +55,6 @@ export const SWISS_FLAVOR: FlavorPack = {
         { name: 'space-control', value: '10px 18px', type: 'spacing', group: 'space' },
         { name: 'space-stack', value: '12px', type: 'spacing', group: 'space' },
     ],
-    defaults: {
-        Button: { borderRadius: 'radius-control', padding: 'space-control' },
-        ButtonBlock: { borderRadius: 'radius-control', padding: 'space-control' },
-        Card: { borderRadius: 'radius-surface' },
-    },
-    // F2: Swiss turns the seed toward a cool counterpoint. NOTE deliberately: the brand tokens
-    // deriveBrandTokens() emits are SEEDED per org — they do not join `defaults` here, because a
-    // colour default repaints legacy nodes whose saved styleProps lack the key (the engine fills
-    // missing keys from config defaults). Coloured element defaults are a Swiss v2 upgrade
-    // decision (§10 C2), taken with the picker in front of the author — never a side effect.
+    // F2: Swiss turns the seed toward a cool counterpoint.
     accentHueDeg: 150,
 };
-
-/** What both renderers use until F2 lets an org choose. */
-export const DEFAULT_FLAVOR: FlavorPack = SWISS_FLAVOR;

package/src/design-core/fonts.ts

@@ -1,4 +1,4 @@
-import { FLAVOR_SPEC } from './flavor-spec.generated';
+import { SPEC_FONTS } from './flavor-spec.generated';
 import { DesignTokenLike } from './token-css';
 
 /**
@@ -7,7 +7,7 @@ import { DesignTokenLike } from './token-css';
  */
 
 /** Family name → Google Fonts css2 `family=` id. Replaces the engine's private GOOGLE_FONTS map. */
-export const FONT_CATALOG: Readonly<Record<string, string>> = FLAVOR_SPEC.fonts;
+export const FONT_CATALOG: Readonly<Record<string, string>> = SPEC_FONTS;
 
 export type FontFormat = 'woff2' | 'woff' | 'truetype' | 'opentype';
 export type FontStyle = 'normal' | 'italic';
@@ -30,9 +30,19 @@ const MIN_WEIGHT = 100;
 const MAX_WEIGHT = 900;
 const FONT_FORMATS: ReadonlyArray<FontFormat> = ['woff2', 'woff', 'truetype', 'opentype'];
 
-/** A CSS string literal, single-quoted, with `\` and `'` escaped and line breaks dropped. */
+/**
+ * A CSS string literal, single-quoted: `\` and `'` escaped, line breaks and NUL dropped, and `<` /
+ * `>` hex-escaped (`\3c `) — the face CSS is inlined into a `<style>` by the SSR engine, where an
+ * uploaded family named `</style><script>` would otherwise close the element.
+ */
 export function cssString(value: string): string {
-    return `'${String(value).replace(/[\r\n\f]/g, '').replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+    const body = String(value)
+        .replace(/[\r\n\f\0]/g, '')
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/</g, '\\3c ')
+        .replace(/>/g, '\\3e ');
+    return `'${body}'`;
 }
 
 const clampWeight = (w: unknown): number => {

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

@@ -13,6 +13,7 @@ export * from './design-token.model';
 export * from './css-names';
 export * from './token-css';
 export * from './flavor';
+export * from './element-styles';
 export * from './brand';
 export * from './flavor-tokens';
 export * from './flavor-seed';

package/src/design-core/spring.ts

@@ -3,7 +3,8 @@
  * generator (`build-spec.mjs` `spring()`) uses to write `springs.lively`, so a spring computed at
  * runtime is byte-identical to the one in the contract.
  *
- * `stiffness` is k (ω₀ = √k), `damping` the ratio ζ (< 1 under-damped, ≥ 1 critically damped).
+ * `stiffness` is k (ω₀ = √k), `damping` the ratio ζ: < 1 under-damped, = 1 critically damped,
+ * > 1 over-damped. Both must be positive and finite — a zero or negative spring never settles.
  * Duration = the last instant the curve is more than 0.1% away from rest, rounded up to 10ms.
  */
 const SETTLE_TOLERANCE = 0.001;
@@ -13,20 +14,31 @@ const SAMPLES = 40;
 const DECIMALS = 4;
 const ROUND_TO_MS = 10;
 
+/** Displacement from rest → target (0 → 1) of a unit-mass spring released at rest. */
+function springPosition(w0: number, damping: number): (t: number) => number {
+    if (damping < 1) {
+        const wd = w0 * Math.sqrt(1 - damping * damping);
+        return t => 1 - Math.exp(-damping * w0 * t) * (Math.cos(wd * t) + ((damping * w0) / wd) * Math.sin(wd * t));
+    }
+    if (damping === 1) return t => 1 - Math.exp(-w0 * t) * (1 + w0 * t);
+    // Over-damped: two real, negative roots. Written with exponentials of the roots, not cosh/sinh,
+    // which overflow for a stiff, heavily damped spring well inside the settle horizon.
+    const root = w0 * Math.sqrt(damping * damping - 1);
+    const r1 = -damping * w0 + root;
+    const r2 = -damping * w0 - root;
+    return t => 1 - (r2 * Math.exp(r1 * t) - r1 * Math.exp(r2 * t)) / (r2 - r1);
+}
+
 export interface LinearSpring {
     easing: string;
     duration: string;
 }
 
 export function springToLinear(stiffness: number, damping: number): LinearSpring {
-    const w0 = Math.sqrt(stiffness);
-    const x = (t: number): number => {
-        if (damping < 1) {
-            const wd = w0 * Math.sqrt(1 - damping * damping);
-            return 1 - Math.exp(-damping * w0 * t) * (Math.cos(wd * t) + ((damping * w0) / wd) * Math.sin(wd * t));
-        }
-        return 1 - Math.exp(-w0 * t) * (1 + w0 * t);
-    };
+    if (!(Number.isFinite(stiffness) && stiffness > 0) || !(Number.isFinite(damping) && damping > 0)) {
+        throw new RangeError(`springToLinear: stiffness and damping must be > 0 (got ${stiffness}, ${damping})`);
+    }
+    const x = springPosition(Math.sqrt(stiffness), damping);
     let settle = 0;
     for (let t = 0; t < SETTLE_HORIZON_S; t += SETTLE_STEP_S) if (Math.abs(1 - x(t)) > SETTLE_TOLERANCE) settle = t;
     const durationMs = Math.ceil((settle * 1000) / ROUND_TO_MS) * ROUND_TO_MS;

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

@@ -1,4 +1,5 @@
-import { FLAVOR_SPEC } from './flavor-spec.generated';
+import { DesignMode } from './design-token.model';
+import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
 
 /**
  * Design-token → CSS compilation, shared by BOTH renderers (flavors F0, design-system DS1).
@@ -40,24 +41,11 @@ export interface TokenCssBlocks {
     dark: string;
 }
 
-/** What `prefers-reduced-motion: reduce` collapses — movement and duration, never colour. */
-export const REDUCED_MOTION_OVERRIDES: Readonly<Record<string, string>> = {
-    'dur-fast': '0ms',
-    'dur-base': '0ms',
-    'dur-slow': '0ms',
-    'hover-lift': '0px',
-    'button-hover-x': '0px',
-    'button-hover-y': '0px',
-    'card-hover-x': '0px',
-    'card-lift': '0px',
-};
+/** What `prefers-reduced-motion: reduce` collapses — the contract's complete list (`a11y.reducedMotion`). */
+export const REDUCED_MOTION_OVERRIDES: Readonly<Record<string, string>> = SPEC_A11Y.reducedMotion;
 
-/** What `prefers-reduced-transparency: reduce` makes solid — every glass surface, in one block. */
-export const REDUCED_TRANSPARENCY_OVERRIDES: Readonly<Record<string, string>> = {
-    'surface-glass': 'var(--iox-surface)',
-    'surface-glass-strong': 'var(--iox-surface)',
-    'blur-surface': 'none',
-};
+/** What `prefers-reduced-transparency: reduce` makes solid — the contract's `a11y.reducedTransparency`. */
+export const REDUCED_TRANSPARENCY_OVERRIDES: Readonly<Record<string, string>> = SPEC_A11Y.reducedTransparency;
 
 const ROOT = ':root';
 const DEFAULT_SCHEME = 'default';
@@ -95,7 +83,7 @@ const schemeSelector = (id: string, scope?: string) =>
     scope ? `${scope} .iox-scheme-${id}` : `.iox-scheme-${id}`;
 
 const nonDefaultSchemes = (): ReadonlyArray<[string, Readonly<Record<string, string>>]> =>
-    Object.entries(FLAVOR_SPEC.schemes)
+    Object.entries(SPEC_SCHEMES)
         .filter(([id]) => id !== DEFAULT_SCHEME)
         .map(([id, scheme]) => [id, scheme.set as Readonly<Record<string, string>>]);
 
@@ -116,32 +104,113 @@ export function tokensToDarkVarMap(tokens: ReadonlyArray<DesignTokenLike> | null
     return map;
 }
 
+const TOKEN_REF = /var\(\s*--iox-([\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'>;
+const LIGHT: ResolvedMode = 'light';
+const DARK: ResolvedMode = 'dark';
+
+const modeValue = (t: DesignTokenLike, mode: ResolvedMode): string => (mode === DARK ? darkOf(t) ?? t.value : t.value);
+
+/** 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(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    mode: ResolvedMode = LIGHT,
+): Record<string, string> {
+    const raw = new Map(usableTokens(tokens).map(t => [t.name, modeValue(t, mode)]));
+    const out: Record<string, string> = {};
+    const resolve = (name: string, trail: ReadonlySet<string>): string | null => {
+        if (name in out) return out[name];
+        const value = raw.get(name);
+        if (value === undefined || trail.has(name)) return null;
+        const next = new Set(trail).add(name);
+        return value.replace(TOKEN_REF, (ref, inner: string, fallback?: string) =>
+            resolve(inner, next) ?? (fallback !== undefined ? fallback.trim() : ref));
+    };
+    for (const name of raw.keys()) {
+        const value = resolve(name, new Set());
+        if (value !== null) out[name] = value;
+    }
+    return out;
+}
+
 /**
- * Section colour schemes (design-system plan §3c). ⚠️ Custom properties resolve where they are
- * DECLARED: `--iox-card-bg: var(--iox-surface)` declared on `:root` keeps `:root`'s surface
- * inside `.iox-scheme-inverse`. So each scheme block carries the spec's overrides PLUS every other
- * token whose value references a token, re-declared verbatim — re-resolving it in the section.
+ * `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
+ * token falls back to its declared fallback, else stays as written.
+ */
+export function resolveTokenReferences(
+    value: string,
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    mode: ResolvedMode = LIGHT,
+): string {
+    const resolved = resolveTokenValues(tokens, mode);
+    return value.replace(TOKEN_REF, (ref, name: string, fallback?: string) =>
+        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 {
+    let missing = false;
+    const value = template.replace(PLACEHOLDER, (_, name: string) => {
+        if (!(name in resolved)) missing = true;
+        return resolved[name] ?? '';
+    });
+    return missing ? null : value;
+}
+
+const schemeEntries = (set: Readonly<Record<string, string>>, resolved: Readonly<Record<string, string>>) =>
+    Object.entries(set)
+        .map(([name, template]): [string, string | null] => [name, substitute(template, resolved)])
+        .filter((e): e is [string, string] => e[1] !== null);
+
+const hasPlaceholder = (value: string) => value.includes('{{');
+
+/**
+ * Section colour schemes (design-system plan §3c). Two rules, both about WHERE a custom property
+ * resolves:
+ *
+ * - ⚠️ Custom properties resolve where they are DECLARED: `--iox-card-bg: var(--iox-surface)`
+ *   declared on `:root` keeps `:root`'s surface inside `.iox-scheme-inverse`. So each scheme block
+ *   carries the spec's overrides PLUS every other token whose value references a token,
+ *   re-declared verbatim — re-resolving it in the section.
+ * - ⚠️ A scheme that SWAPS two tokens (Brand: accent ⇄ accent-ink) cannot write them as `var()`:
+ *   on one element `accent: var(--iox-accent-ink)` + `accent-ink: var(--iox-accent)` is a cycle,
+ *   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 {
     const rows = usableTokens(tokens);
     if (!rows.length) return '';
+    const resolved = resolveTokenValues(rows, LIGHT);
     return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
-        ...Object.entries(set),
+        ...schemeEntries(set, resolved),
         ...rows.filter(t => !(t.name in set) && t.value.includes(REFERENCE))
             .map((t): [string, string] => [t.name, t.value]),
     ])).filter(Boolean).join('\n');
 }
 
-/** The dark twin of the re-declaration rule: a re-declared token with a dark value would
- *  otherwise pin the LIGHT value inside the section once the visitor is in dark mode. */
+/** The dark twin of both scheme rules: a re-declared token with a dark value would otherwise pin
+ *  the LIGHT value inside the section, and a `{{token}}` swap was resolved from LIGHT values. */
 function darkSchemeRules(rows: ReadonlyArray<DesignTokenLike>, scope: string | undefined): string[] {
+    const light = resolveTokenValues(rows, LIGHT);
+    const dark = resolveTokenValues(rows, DARK);
     const redeclared = rows.filter(t => {
-        const dark = darkOf(t);
-        return dark !== null && (t.value.includes(REFERENCE) || dark.includes(REFERENCE));
+        const d = darkOf(t);
+        return d !== null && (t.value.includes(REFERENCE) || d.includes(REFERENCE));
+    });
+    return nonDefaultSchemes().map(([id, set]) => {
+        const swapped = Object.fromEntries(Object.entries(set).filter(([, v]) => hasPlaceholder(v)));
+        const lightSwap = new Map(schemeEntries(swapped, light));
+        return rule(schemeSelector(id, scope), [
+            ...schemeEntries(swapped, dark).filter(([name, value]) => lightSwap.get(name) !== value),
+            ...redeclared.filter(t => !(t.name in set)).map((t): [string, string] => [t.name, darkOf(t) as string]),
+        ], '  ');
     });
-    return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), redeclared
-        .filter(t => !(t.name in set))
-        .map((t): [string, string] => [t.name, darkOf(t) as string]), '  '));
 }
 
 function presentOverrides(rows: ReadonlyArray<DesignTokenLike>, overrides: Readonly<Record<string, string>>,

package/styles/iox-forms.css

@@ -49,6 +49,57 @@
 .iox-field__error   { margin: 4px 0 0; }
 .iox-submit         { font: inherit; border: none; cursor: pointer; }
 
+/* ── Visual baseline — EXACTLY the spec's `fieldClassBaseline` (design-system plan DS2) ──────────
+ * Every value is a token, so a re-theme restyles every form with no page write. Each var() carries
+ * today's value as its fallback (trap T6) — `inherit` where the structural rule above inherits, the
+ * engine reset's `0` for padding, and `revert` (the UA default, which is what rendered before) for
+ * everything nothing declared — so an org whose tokens are not seeded renders as it did.
+ * Two spec values are bare keywords and cannot fall back: `border-style: solid` (the UA inset
+ * border becomes solid) and the focus ring's `outline: none`, whose box-shadow therefore falls back
+ * to a visible system-colour ring rather than to nothing. */
+.iox-field__control {
+  background: var(--iox-field-bg, revert);
+  color: var(--iox-field-ink, inherit);
+  border-width: var(--iox-field-border-width, revert);
+  border-style: solid;
+  border-color: var(--iox-field-border, revert);
+  border-radius: var(--iox-field-radius, revert);
+  padding: var(--iox-field-pad, 0);
+  font-family: var(--iox-font-body, inherit);
+  font-size: var(--iox-size-body, inherit);
+  transition: border-color var(--iox-dur-base, 0s) var(--iox-ease-standard, ease), box-shadow var(--iox-dur-base, 0s) var(--iox-ease-standard, ease);
+}
+.iox-field__control:focus-visible {
+  border-color: var(--iox-accent, revert);
+  box-shadow: var(--iox-field-focus, 0 0 0 2px Highlight);
+  outline: none;
+}
+.iox-field__label {
+  font-family: var(--iox-font-body, inherit);
+  font-size: var(--iox-field-label-size, inherit);
+  font-weight: var(--iox-field-label-weight, inherit);
+  color: var(--iox-text, inherit);
+}
+.iox-field__help {
+  font-size: var(--iox-size-small, inherit);
+  color: var(--iox-text-muted, inherit);
+}
+.iox-field__error {
+  font-size: var(--iox-size-small, inherit);
+  color: var(--iox-danger, inherit);
+}
+.iox-invalid .iox-field__control {
+  border-color: var(--iox-danger, revert);
+}
+/* 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. */
+.iox-field__control:where([type='checkbox'], [type='radio'], [type='range']) {
+  border: none;
+  padding: 0;
+  background: transparent;
+}
+
 /* Visually hidden, still announced — a label may be hidden, never deleted. */
 .iox-field__label--hidden {
     position: absolute; width: 1px; height: 1px; margin: -1px;
@@ -65,7 +116,7 @@
   background: var(--iox-line, #d8d4d1);
   position: relative;
   cursor: pointer;
-  transition: background 150ms ease-out;
+  transition: background var(--iox-dur-fast, 150ms) var(--iox-ease-standard, ease-out);
   flex-shrink: 0;
 }
 .iox-field__control--switch::before {
@@ -76,11 +127,11 @@
   width: 16px;
   height: 16px;
   border-radius: 999px;
-  background: #ffffff;
-  transition: transform 150ms ease-out;
+  background: var(--iox-accent-ink, #ffffff);
+  transition: transform var(--iox-dur-fast, 150ms) var(--iox-ease-standard, ease-out);
 }
 .iox-field__control--switch:checked {
-  background: var(--iox-brand-500, #1f1d1b);
+  background: var(--iox-accent, var(--iox-brand-500, #1f1d1b));
 }
 .iox-field__control--switch:checked::before {
   transform: translateX(16px);
@@ -92,5 +143,5 @@
 /* ── range (control='range') ── */
 .iox-field__control--range {
   width: 100%;
-  accent-color: var(--iox-brand-500, #1f1d1b);
+  accent-color: var(--iox-accent, var(--iox-brand-500, #1f1d1b));
 }