@vectoriox/iox-ui 5.9.0 → 5.11.0

package/index.d.ts

@@ -5,6 +5,7 @@ import { Observable } from 'rxjs';
 import * as i3 from '@angular/platform-browser/animations';
 import Lenis from 'lenis';
 import * as i2 from '@angular/common';
+export * from '@vectoriox/iox-ui/design-core';
 
 declare class ViewPositionDirective implements AfterViewInit {
     private _elr;
@@ -1313,8 +1314,6 @@ declare class IoxComponentRegistryService {
  * `1vh` / `1vw` fallbacks restore native browser behaviour.
  */
 declare function rewriteViewportUnits(value: string): string;
-/** camelCase style key → kebab-case CSS property. */
-declare function styleKeyToKebab(key: string): string;
 /**
  * Style props a type's render-default fully REPLACES. Emitting them would produce a dead
  * declaration that is immediately overridden in the same rule (e.g. an Icon's serialised
@@ -1497,115 +1496,6 @@ declare const PART_CLASS_NAMES: Record<string, Record<string, string>>;
  *  Undefined when the type declares no such part (or no parts at all). */
 declare function partClassName(type: string, partKey: string): string | undefined;
 
-/**
- * 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.
- */
-interface FlavorTokenDef {
-    name: string;
-    value: string;
-    /** Dark-scheme override, seeded into DesignToken.values.dark at F2. */
-    values?: {
-        dark?: string;
-    };
-    type?: 'color' | 'spacing' | 'size' | 'font' | 'other';
-    /** Tokens-panel grouping (flavors plan §10 C5). */
-    group?: 'colour' | 'type' | 'space' | 'radius' | 'shadow' | 'motion';
-}
-interface FlavorPack {
-    id: string;
-    /** Bumped when the pack's values change; seeding stamps `flavor:<id>@<version>` as DesignToken.source. */
-    version: number;
-    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 → {}. */
-declare function resolveFlavorDefaults(type: string, pack: FlavorPack | null | undefined): Record<string, string>;
-/**
- * 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.
- */
-declare function flavorDefaultDeclarations(type: string, styleProps: Record<string, any> | null | undefined, pack: FlavorPack | null | undefined): string[];
-/**
- * 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 [].
- */
-declare function validateFlavorPack(pack: FlavorPack, knownTraitsByType: Record<string, ReadonlySet<string> | string[]>): string[];
-/**
- * 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.
- */
-declare const SWISS_FLAVOR: FlavorPack;
-/** What both renderers use until F2 lets an org choose. */
-declare const DEFAULT_FLAVOR: FlavorPack;
-
-/**
- * BRAND DERIVATION (flavors plan §6, F2): one colour in, an asserted accessible ramp out.
- *
- * Competitors ask for a palette of five and hope; we ask for ONE seed and compute the rest so
- * that contrast is a TEST, not a promise. WCAG 2 ratios are the gate (every guarantee below is
- * unit-asserted across seeds); APCA is exposed as the picker's quality read-out only.
- *
- * Colour math is OKLab (perceptually even lightness — the ramp steps LOOK even), hand-rolled
- * from the published matrices because this module must stay dependency-free: it runs in the
- * builder, the engine and (later) the generator's Node service.
- */
-interface Rgb {
-    r: number;
-    g: number;
-    b: number;
-}
-interface OkLab {
-    L: number;
-    a: number;
-    b: number;
-}
-declare function parseHexColor(hex: string): Rgb | null;
-declare function toHexColor(c: Rgb): string;
-declare function rgbToOklab(c: Rgb): OkLab;
-declare function oklabToRgb(c: OkLab): Rgb;
-declare function relativeLuminance(c: Rgb): number;
-/** WCAG 2 contrast ratio between two colours (order-independent), 1..21. */
-declare function wcagContrastRatio(a: string | Rgb, b: string | Rgb): number;
-/**
- * APCA-W3 lightness contrast Lc (0.0.98G-4g constants), text-on-background and signed:
- * positive for dark-on-light, negative for light-on-dark; |Lc| ≈ 106–108 at the extremes.
- * Shown in the picker as the perceptual read-out; never used as the pass/fail gate here.
- */
-declare function apcaLc(text: string | Rgb, bg: string | Rgb): number;
-/**
- * The derived brand tokens (plan §6's table, every row asserted in brand.spec.ts):
- * `brand-50…900` (monotonic OKLab lightness, gamut-safe) · `brandInk` (black or white, ≥4.5 on
- * brand-500 — brand-500's lightness is nudged when neither side clears it) · `surface`/`ink`/
- * `inkMuted` (seed-tinted neutrals, ≥7:1 / ≥4.5:1 on surface) · `line` (the LIGHTEST neutral that
- * still clears 3:1 on surface) · `accent` (pack-rotated hue, ≥4.5:1 on surface) — with dark-scheme
- * values for the neutral family riding `values.dark`.
- *
- * Throws on an unparseable seed: callers (the picker) validate; a silent fallback here would
- * launch a studio into a palette nobody chose.
- */
-declare function deriveBrandTokens(seed: string, pack: FlavorPack): FlavorTokenDef[];
-
 /** Trait names whose value Swiper reads per breakpoint. Anything else is config-wide. */
 declare const SWIPER_RESPONSIVE_TRAITS: readonly string[];
 /** `{ [minWidth]: { slidesPerView, … } }` — Swiper's own `breakpoints` shape. */
@@ -1631,44 +1521,6 @@ declare function buildSwiperBreakpoints(inputs: InputMap | null | undefined, res
  */
 declare function mergeSwiperBreakpoints(derived: SwiperBreakpointMap, advancedJson: string | null | undefined): SwiperBreakpointMap | undefined;
 
-/**
- * Design-token → CSS compilation, shared by BOTH renderers (flavors plan F0).
- *
- * A token row is `{ name, value }` plus, since F0, an optional per-scheme override:
- * `values.dark`. The shape exists NOW — before any dark-mode UI — because retrofitting it
- * later means rewriting every org's `designtokens` collection (flavors plan §10 C3).
- *
- * ⚠️ The appended-last contract: the dark block REDEFINES custom properties under
- * `@media (prefers-color-scheme: dark)`. Per the responsive-breakpoints A3 lesson, every
- * consumer appends it AFTER all of its base rules — the engine pushes it after the page's
- * css blocks, the builder registry keeps it as its last token rule. Custom properties are
- * order-insensitive against node rules, but keeping one ordering rule for every @media
- * block in the product is cheaper than remembering which ones are exempt.
- */
-/** The transport-agnostic token row. `source` marks seeded rows (`flavor:<id>@<ver>`). */
-interface DesignTokenLike {
-    name: string;
-    value: string;
-    /** Per-scheme overrides. Only `dark` exists today; absent means the base value everywhere. */
-    values?: {
-        dark?: string;
-    };
-    type?: string;
-    source?: string;
-}
-/** `{ 'iox-brand': '#2f6f62', … }` — the builder registry's input shape for base values. */
-declare function tokensToVarMap(tokens: ReadonlyArray<DesignTokenLike> | null | undefined): Record<string, string>;
-/** Only the tokens that carry a dark override, as `{ 'iox-name': darkValue }`. */
-declare function tokensToDarkVarMap(tokens: ReadonlyArray<DesignTokenLike> | null | undefined): Record<string, string>;
-/**
- * The two CSS blocks a renderer emits. `base` goes FIRST (before node rules), `dark` goes
- * LAST (after every base rule); either may be '' when there is nothing to say.
- */
-declare function compileTokenCss(tokens: ReadonlyArray<DesignTokenLike> | null | undefined): {
-    base: string;
-    dark: string;
-};
-
 /**
  * page-style — the ONE compiler that turns a page's style settings into CSS.
  *
@@ -2838,5 +2690,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_FLAVOR, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SWISS_FLAVOR, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, apcaLc, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, compileTokenCss, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, deriveBrandTokens, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, flavorDefaultDeclarations, getByPath, getSeoValue, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, oklabToRgb, parentBreakpoint, parseHexColor, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, relativeLuminance, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveFlavorDefaults, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, rgbToOklab, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, stripSuppressedProps, styleKeyToKebab, toHexColor, tokensToDarkVarMap, tokensToVarMap, validateFlavorPack, variableAliases, variableItemsFrom, wcagContrastRatio, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
-export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, DesignTokenLike, FlavorPack, FlavorTokenDef, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OkLab, OverrideBreakpoint, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, Rgb, RouteContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };
+export { AOSService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, getByPath, getSeoValue, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, stripSuppressedProps, variableAliases, variableItemsFrom, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
+export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.9.0",
+  "version": "5.11.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -27,6 +27,10 @@
       "types": "./consent-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-consent-core.mjs"
     },
+    "./design-core": {
+      "types": "./design-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-design-core.mjs"
+    },
     "./forms-core": {
       "types": "./forms-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-forms-core.mjs"

package/src/design-core/brand.ts

@@ -0,0 +1,335 @@
+import { FlavorPack, FlavorTokenDef } from './flavor';
+
+/**
+ * BRAND DERIVATION (flavors plan §6, F2): one colour in, an asserted accessible ramp out.
+ *
+ * Competitors ask for a palette of five and hope; we ask for ONE seed and compute the rest so
+ * that contrast is a TEST, not a promise. WCAG 2 ratios are the gate (every guarantee below is
+ * unit-asserted across seeds); APCA is exposed as the picker's quality read-out only.
+ *
+ * Colour math is OKLab (perceptually even lightness — the ramp steps LOOK even), hand-rolled
+ * from the published matrices because this module must stay dependency-free: it runs in the
+ * builder, the engine and (later) the generator's Node service.
+ */
+
+// ── sRGB ⇄ OKLab ─────────────────────────────────────────────────────────────
+
+export interface Rgb { r: number; g: number; b: number; }        // 0..1
+export interface OkLab { L: number; a: number; b: number; }
+
+export function parseHexColor(hex: string): Rgb | null {
+    const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec((hex ?? '').trim());
+    if (!m) return null;
+    let h = m[1];
+    if (h.length === 3) h = h.split('').map(c => c + c).join('');
+    const n = parseInt(h, 16);
+    return { r: ((n >> 16) & 255) / 255, g: ((n >> 8) & 255) / 255, b: (n & 255) / 255 };
+}
+
+export function toHexColor(c: Rgb): string {
+    const q = (v: number) => Math.round(Math.min(1, Math.max(0, v)) * 255).toString(16).padStart(2, '0');
+    return `#${q(c.r)}${q(c.g)}${q(c.b)}`;
+}
+
+const srgbToLinear = (v: number) => (v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
+const linearToSrgb = (v: number) => (v <= 0.0031308 ? v * 12.92 : 1.055 * Math.pow(v, 1 / 2.4) - 0.055);
+
+export function rgbToOklab(c: Rgb): OkLab {
+    const r = srgbToLinear(c.r), g = srgbToLinear(c.g), b = srgbToLinear(c.b);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    return {
+        L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+    };
+}
+
+export function oklabToRgb(c: OkLab): Rgb {
+    const l = Math.pow(c.L + 0.3963377774 * c.a + 0.2158037573 * c.b, 3);
+    const m = Math.pow(c.L - 0.1055613458 * c.a - 0.0638541728 * c.b, 3);
+    const s = Math.pow(c.L - 0.0894841775 * c.a - 1.291485548 * c.b, 3);
+    return {
+        r: linearToSrgb(+4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+        g: linearToSrgb(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+        b: linearToSrgb(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+    };
+}
+
+const inGamut = (c: Rgb) => [c.r, c.g, c.b].every(v => v >= -1e-6 && v <= 1 + 1e-6);
+
+/** The OKLab colour at (L, hue, chroma), chroma reduced until it fits sRGB. */
+function atLightness(L: number, hueA: number, hueB: number, chroma: number): Rgb {
+    const len = Math.hypot(hueA, hueB) || 1;
+    const ua = hueA / len, ub = hueB / len;
+    let c = chroma;
+    for (let i = 0; i < 24; i++) {
+        const rgb = oklabToRgb({ L, a: ua * c, b: ub * c });
+        if (inGamut(rgb)) return rgb;
+        c *= 0.82;
+    }
+    return oklabToRgb({ L, a: 0, b: 0 });
+}
+
+// ── WCAG 2 (the gate) ────────────────────────────────────────────────────────
+
+export function relativeLuminance(c: Rgb): number {
+    return 0.2126 * srgbToLinear(c.r) + 0.7152 * srgbToLinear(c.g) + 0.0722 * srgbToLinear(c.b);
+}
+
+/** WCAG 2 contrast ratio between two colours (order-independent), 1..21. */
+export function wcagContrastRatio(a: string | Rgb, b: string | Rgb): number {
+    const ca = typeof a === 'string' ? parseHexColor(a) : a;
+    const cb = typeof b === 'string' ? parseHexColor(b) : b;
+    if (!ca || !cb) return 1;
+    const la = relativeLuminance(ca), lb = relativeLuminance(cb);
+    const [hi, lo] = la >= lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+
+// ── APCA (the read-out — WCAG 2 stays the gate) ─────────────────────────────
+
+/**
+ * APCA-W3 lightness contrast Lc (0.0.98G-4g constants), text-on-background and signed:
+ * positive for dark-on-light, negative for light-on-dark; |Lc| ≈ 106–108 at the extremes.
+ * Shown in the picker as the perceptual read-out; never used as the pass/fail gate here.
+ */
+export function apcaLc(text: string | Rgb, bg: string | Rgb): number {
+    const toY = (c: Rgb) =>
+        0.2126729 * Math.pow(c.r, 2.4) + 0.7151522 * Math.pow(c.g, 2.4) + 0.072175 * Math.pow(c.b, 2.4);
+    const clamp = (y: number) => (y < 0.022 ? y + Math.pow(0.022 - y, 1.414) : y);
+    const ct = typeof text === 'string' ? parseHexColor(text) : text;
+    const cb = typeof bg === 'string' ? parseHexColor(bg) : bg;
+    if (!ct || !cb) return 0;
+    const yTxt = clamp(toY(ct)), yBg = clamp(toY(cb));
+    let lc: number;
+    if (yBg > yTxt) lc = (Math.pow(yBg, 0.56) - Math.pow(yTxt, 0.57)) * 1.14;
+    else lc = (Math.pow(yBg, 0.65) - Math.pow(yTxt, 0.62)) * 1.14;
+    if (Math.abs(lc) < 0.1) return 0;
+    return Math.round((lc > 0 ? lc - 0.027 : lc + 0.027) * 1000) / 10;
+}
+
+// ── The ramp ─────────────────────────────────────────────────────────────────
+
+/** Fixed, perceptually even lightness ladder for brand-50 … brand-900. */
+const RAMP_STEPS: ReadonlyArray<{ step: number; L: number; chromaScale: number }> = [
+    { step: 50, L: 0.97, chromaScale: 0.22 },
+    { step: 100, L: 0.93, chromaScale: 0.42 },
+    { step: 200, L: 0.86, chromaScale: 0.66 },
+    { step: 300, L: 0.78, chromaScale: 0.85 },
+    { step: 400, L: 0.70, chromaScale: 0.96 },
+    { step: 500, L: 0.62, chromaScale: 1.0 },
+    { step: 600, L: 0.53, chromaScale: 0.96 },
+    { step: 700, L: 0.45, chromaScale: 0.88 },
+    { step: 800, L: 0.36, chromaScale: 0.76 },
+    { step: 900, L: 0.27, chromaScale: 0.62 },
+];
+
+const BLACK: Rgb = { r: 0, g: 0, b: 0 };
+const WHITE: Rgb = { r: 1, g: 1, b: 1 };
+
+/** Snap to the 8-bit hex the token will actually carry — contrast is judged on WHAT SHIPS.
+ *  (The first version searched in float space and hex rounding landed 6.9596 where 7 was owed.) */
+const quant = (c: Rgb): Rgb => parseHexColor(toHexColor(c))!;
+
+/** Binary-search an OKLab lightness so `contrast(colour, against) ≥ ratio`, darkening-or-lightening. */
+function atContrast(against: Rgb, ratio: number, hueA: number, hueB: number, chroma: number, darker: boolean): Rgb {
+    let lo = darker ? 0 : rgbToOklab(against).L;
+    let hi = darker ? rgbToOklab(against).L : 1;
+    let best = quant(atLightness(darker ? 0.18 : 0.92, hueA, hueB, chroma));
+    for (let i = 0; i < 28; i++) {
+        const mid = (lo + hi) / 2;
+        const candidate = quant(atLightness(mid, hueA, hueB, chroma));
+        if (wcagContrastRatio(candidate, against) >= ratio) {
+            best = candidate;
+            if (darker) lo = mid; else hi = mid; // pull back toward `against`: the LOWEST passing step
+        } else {
+            if (darker) hi = mid; else lo = mid;
+        }
+    }
+    return best;
+}
+
+/**
+ * The derived brand tokens (plan §6's table, every row asserted in brand.spec.ts):
+ * `brand-50…900` (monotonic OKLab lightness, gamut-safe) · `brandInk` (black or white, ≥4.5 on
+ * brand-500 — brand-500's lightness is nudged when neither side clears it) · `surface`/`ink`/
+ * `inkMuted` (seed-tinted neutrals, ≥7:1 / ≥4.5:1 on surface) · `line` (the LIGHTEST neutral that
+ * still clears 3:1 on surface) · `accent` (pack-rotated hue, ≥4.5:1 on surface) — with dark-scheme
+ * values for the neutral family riding `values.dark`.
+ *
+ * Throws on an unparseable seed: callers (the picker) validate; a silent fallback here would
+ * launch a studio into a palette nobody chose.
+ */
+export function deriveBrandTokens(seed: string, pack: Pick<FlavorPack, 'accentHueDeg'>): FlavorTokenDef[] {
+    const seedRgb = parseHexColor(seed);
+    if (!seedRgb) throw new TypeError(`deriveBrandTokens: not a colour: "${seed}"`);
+    const lab = rgbToOklab(seedRgb);
+    const chroma = Math.hypot(lab.a, lab.b);
+    const ua = chroma > 1e-6 ? lab.a : 0.0, ub = chroma > 1e-6 ? lab.b : 1e-6; // grey seeds: keep a stable (arbitrary) hue axis
+    const baseChroma = Math.max(chroma, 0.02); // near-grey seeds still get a usable, quiet ramp
+
+    const token = (name: string, value: string, dark?: string): FlavorTokenDef =>
+        ({ name, value, ...(dark ? { values: { dark } } : {}), type: 'color', group: 'colour' });
+
+    // 1 — the ramp
+    const ramp = RAMP_STEPS.map(({ step, L, chromaScale }) =>
+        ({ step, rgb: atLightness(L, ua, ub, baseChroma * chromaScale) }));
+
+    // 2 — brandInk on brand-500, nudging 500 (within its neighbours) when neither ink clears 4.5
+    let five = ramp.find(r => r.step === 500)!;
+    five.rgb = quant(five.rgb);
+    const inkFor = (bg: Rgb) => (wcagContrastRatio(WHITE, bg) >= wcagContrastRatio(BLACK, bg) ? WHITE : BLACK);
+    for (let i = 0; i < 40 && wcagContrastRatio(inkFor(five.rgb), five.rgb) < 4.5; i++) {
+        const L = rgbToOklab(five.rgb).L;
+        // Mid tones can fail both inks — walk toward whichever side is already winning, but
+        // never past the neighbouring steps: the ramp's monotonic lightness is a guarantee.
+        const towardDark = wcagContrastRatio(WHITE, five.rgb) >= wcagContrastRatio(BLACK, five.rgb);
+        const next = Math.min(0.695, Math.max(0.545, L + (towardDark ? -0.012 : 0.012)));
+        if (next === L) break;
+        five.rgb = quant(atLightness(next, ua, ub, baseChroma));
+    }
+    const brandInk = inkFor(five.rgb);
+
+    // 3 — the neutral family, faintly tinted by the seed hue. Surfaces are quantized FIRST:
+    // every later guarantee is measured against the hex that ships, not a float ideal.
+    const tint = 0.006;
+    const surface = quant(atLightness(0.985, ua, ub, tint));
+    const surfaceDark = quant(atLightness(0.145, ua, ub, tint * 1.5));
+    const ink = atContrast(surface, 7, ua, ub, tint * 2, true);
+    const inkDark = atContrast(surfaceDark, 7, ua, ub, tint * 2, false);
+    const inkMuted = atContrast(surface, 4.5, ua, ub, tint * 2, true);
+    const inkMutedDark = atContrast(surfaceDark, 4.5, ua, ub, tint * 2, false);
+    const line = atContrast(surface, 3, ua, ub, tint, true);
+    const lineDark = atContrast(surfaceDark, 3, ua, ub, tint, false);
+
+    // 4 — the accent: pack-defined hue rotation from the seed, readable on surface
+    const rot = ((pack.accentHueDeg ?? 150) * Math.PI) / 180;
+    const ra = ua * Math.cos(rot) - ub * Math.sin(rot);
+    const rb = ua * Math.sin(rot) + ub * Math.cos(rot);
+    const accent = atContrast(surface, 4.5, ra, rb, Math.max(baseChroma, 0.06), true);
+
+    return [
+        ...ramp.map(({ step, rgb }) => token(`brand-${step}`, toHexColor(rgb))),
+        token('brandInk', toHexColor(brandInk)),
+        token('surface', toHexColor(surface), toHexColor(surfaceDark)),
+        token('ink', toHexColor(ink), toHexColor(inkDark)),
+        token('inkMuted', toHexColor(inkMuted), toHexColor(inkMutedDark)),
+        token('line', toHexColor(line), toHexColor(lineDark)),
+        token('accent', toHexColor(accent)),
+    ];
+}
+
+// ── The design-system accent quartet (design-system plan §3e) ────────────────
+
+/** WCAG 2 AA for body text — the gate every quartet pair is held to. */
+export const WCAG_AA_TEXT = 4.5;
+
+export const ACCENT_TOKEN_NAMES = [
+    'accent', 'accent-ink', 'accent-hover', 'accent-text', 'inverse-accent', 'inverse-accent-ink',
+] as const;
+export type AccentTokenName = (typeof ACCENT_TOKEN_NAMES)[number];
+
+/** The backgrounds the accent must read on, light and (optionally) dark. Without an inverse
+ *  background the inverse pair is not derived — the pack's own stays. */
+export interface AccentBackgrounds {
+    bg: string;
+    bgDark?: string;
+    inverseBg?: string;
+    inverseBgDark?: string;
+}
+
+const RAMP_ORDER = RAMP_STEPS.map(s => s.step);
+const WHITE_HEX = toHexColor(WHITE);
+const BLACK_HEX = toHexColor(BLACK);
+const passesText = (fg: string, bg: string) => wcagContrastRatio(fg, bg) >= WCAG_AA_TEXT;
+const bestInkHex = (bg: string) =>
+    (wcagContrastRatio(WHITE_HEX, bg) >= wcagContrastRatio(BLACK_HEX, bg) ? WHITE_HEX : BLACK_HEX);
+
+/**
+ * The quartet a seed different from the pack's own becomes, built ON `deriveBrandTokens` (its
+ * ramp and its WCAG-gated `brandInk`) — never a second colour model:
+ *
+ * - `accent` = brand-500 (already nudged until `brandInk` clears 4.5:1 on it), `accent-ink` = brandInk
+ * - `accent-hover` = the neighbouring step AWAY from the ink, so ink-on-hover only gains contrast
+ * - `accent-text` = the first step from 500 toward the far end that clears 4.5:1 on `bg`
+ * - dark: the first of brand-300/200/400 an ink clears 4.5:1 on, the same hover rule, and
+ *   `accent-text` = the first light step that clears 4.5:1 on `bgDark`
+ *
+ * - `inverse-accent` = the first step from 500 toward the end that reads on `inverseBg` clearing
+ *   4.5:1 on it; `inverse-accent-ink` = the higher-contrast of `brandInk` and the OPPOSITE ramp end
+ *   (the spec's `brandSeed` rule). A step whose best ink still misses 4.5:1 is passed over, so the
+ *   pair is a guarantee rather than a hope. Dark: the same against `inverseBgDark`.
+ *
+ * Every pair (ink/accent, ink/hover, text/bg, inverse ink/inverse accent, inverse accent/inverse
+ * bg) is asserted ≥ 4.5:1 across packs and seeds in `flavor-tokens.spec.ts`.
+ */
+export function deriveAccentTokens(
+    seed: string,
+    against: AccentBackgrounds,
+    pack: Pick<FlavorPack, 'accentHueDeg'> = {},
+): FlavorTokenDef[] {
+    const derived = deriveBrandTokens(seed, pack);
+    const hexOf = (name: string) => derived.find(t => t.name === name)!.value;
+    const step = (n: number) => hexOf(`brand-${n}`);
+
+    const hoverFor = (accentStep: number, ink: string): string => {
+        const i = RAMP_ORDER.indexOf(accentStep) + (ink === WHITE_HEX ? 1 : -1);
+        const candidate = RAMP_ORDER[i] !== undefined ? step(RAMP_ORDER[i]) : null;
+        return candidate && passesText(ink, candidate) ? candidate : step(accentStep);
+    };
+    const firstOn = (steps: number[], bg: string) => step(steps.find(n => passesText(step(n), bg)) ?? steps[steps.length - 1]);
+
+    const ink = hexOf('brandInk');
+    const light = {
+        accent: step(500),
+        ink,
+        hover: hoverFor(500, ink),
+        text: firstOn([500, 600, 700, 800, 900], against.bg),
+    };
+
+    const dark = against.bgDark ? (() => {
+        const darkStep = [300, 200, 400].find(n => passesText(bestInkHex(step(n)), step(n))) ?? 300;
+        const darkInk = bestInkHex(step(darkStep));
+        return {
+            accent: step(darkStep),
+            ink: darkInk,
+            hover: hoverFor(darkStep, darkInk),
+            text: firstOn([300, 200, 100, 50], against.bgDark),
+        };
+    })() : null;
+
+    const inverseOn = (inverseBg: string) => {
+        const toward = wcagContrastRatio(step(RAMP_ORDER[0]), inverseBg) >= wcagContrastRatio(step(RAMP_ORDER[RAMP_ORDER.length - 1]), inverseBg)
+            ? -1 : 1;
+        const walk = RAMP_ORDER.filter(n => (toward < 0 ? n <= 500 : n >= 500));
+        if (toward < 0) walk.reverse();
+        const rampEnd = step(toward < 0 ? RAMP_ORDER[RAMP_ORDER.length - 1] : RAMP_ORDER[0]);
+        const inkOn = (fill: string) =>
+            (wcagContrastRatio(ink, fill) >= wcagContrastRatio(rampEnd, fill) ? ink : rampEnd);
+        for (const n of walk) {
+            const fill = step(n);
+            if (passesText(fill, inverseBg) && passesText(inkOn(fill), fill)) return { accent: fill, ink: inkOn(fill) };
+        }
+        const fill = step(walk[walk.length - 1]);
+        return { accent: fill, ink: passesText(inkOn(fill), fill) ? inkOn(fill) : bestInkHex(fill) };
+    };
+    const inverse = against.inverseBg ? inverseOn(against.inverseBg) : null;
+    const inverseDark = against.inverseBg && against.inverseBgDark ? inverseOn(against.inverseBgDark) : null;
+
+    const row = (name: AccentTokenName, value: string, darkValue?: string): FlavorTokenDef => ({
+        name, value, type: 'color', group: 'colour', tier: 'semantic',
+        ...(darkValue ? { values: { dark: darkValue } } : {}),
+    });
+    return [
+        row('accent', light.accent, dark?.accent),
+        row('accent-ink', light.ink, dark?.ink),
+        row('accent-hover', light.hover, dark?.hover),
+        row('accent-text', light.text, dark?.text),
+        ...(inverse ? [
+            row('inverse-accent', inverse.accent, inverseDark?.accent),
+            row('inverse-accent-ink', inverse.ink, inverseDark?.ink),
+        ] : []),
+    ];
+}

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

@@ -0,0 +1,4 @@
+/** camelCase style key → kebab CSS property (`borderRadius` → `border-radius`). */
+export function styleKeyToKebab(key: string): string {
+    return key.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
+}