@ttoss/fsl-theme 1.1.13 → 1.1.15

package/dist/Types-BiBa17RL.d.cts

@@ -0,0 +1,1427 @@
+
+//#region src/dataviz/Types.d.ts
+type Scale1To8 = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+type Scale1To7 = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+type Scale1To6 = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Core data visualization token tree.
+ *
+ * Contains non-color encoding primitives only.
+ * Color tokens are sourced directly from `core.colors.*` — no separate dataviz
+ * color palette is needed. Semantic dataviz color tokens reference `core.colors.*`.
+ *
+ * Placed at `theme.core.dataviz` — optional extension of `ThemeTokens`.
+ */
+interface CoreDataviz {
+  /** Mark shapes for categorical differentiation (e.g. 'circle', 'square'). */
+  shape: Record<Scale1To8, RawValue>;
+  /** Fill patterns for area/region differentiation (e.g. 'diagonal-stripes'). */
+  pattern: Record<Scale1To6, RawValue>;
+  /** Stroke dash patterns as SVG-compatible dash-array strings. */
+  stroke: {
+    solid: RawValue;
+    dashed: RawValue;
+    dotted: RawValue;
+  };
+  /**
+   * Analytical opacity primitives.
+   * Distinct from foundation opacity — used as encoding channels, not UI effects.
+   */
+  opacity: {
+    /** Geographic/spatial context reduction behind overlays. */context: NumericValue; /** De-emphasis of non-highlighted data marks. */
+    muted: NumericValue; /** Visual signal of estimated or uncertain data. */
+    uncertainty: NumericValue;
+  };
+}
+/**
+ * Semantic categorical and scale color roles.
+ *
+ * Paths (in code: semantic.dataviz.color.*):
+ *   dataviz.color.series.1..8
+ *   dataviz.color.scale.sequential.1..7
+ *   dataviz.color.scale.diverging.neg3..pos3
+ *   dataviz.color.reference.baseline / target
+ *   dataviz.color.state.highlight / muted / selected
+ *   dataviz.color.status.missing / suppressed / not-applicable
+ */
+interface SemanticDatavizColor {
+  /**
+   * Categorical series identity — 8 named, unordered roles.
+   * Use for nominal categories, named series, distinct groups.
+   */
+  series: Record<Scale1To8, TokenRef>;
+  scale: {
+    /**
+     * Ordered magnitude — 7 steps from low (1) to high (7).
+     * Use for quantitative ranges and progressive intensity.
+     */
+    sequential: Record<Scale1To7, TokenRef>;
+    /**
+     * Midpoint comparison — 7 named positions around a true center.
+     * Only use when the data has a meaningful midpoint (zero, baseline, target).
+     */
+    diverging: {
+      neg3: TokenRef;
+      neg2: TokenRef;
+      neg1: TokenRef; /** Neutral midpoint class. */
+      neutral: TokenRef;
+      pos1: TokenRef;
+      pos2: TokenRef;
+      pos3: TokenRef;
+    };
+  };
+  reference: {
+    /** Color for a baseline or reference level (e.g. average, goal). */baseline: TokenRef; /** Color for a target or objective line. */
+    target: TokenRef;
+  };
+  state: {
+    /** Emphasized / highlighted data mark. */highlight: TokenRef; /** De-emphasized / non-highlighted data mark. */
+    muted: TokenRef; /** User-selected or actively focused data mark. */
+    selected: TokenRef;
+  };
+  status: {
+    /** Value is absent or unavailable. */missing: TokenRef; /** Value is withheld for confidentiality or publication rules. */
+    suppressed: TokenRef; /** Value is structurally absent (not measured or not applicable). */
+    na: TokenRef;
+  };
+}
+/**
+ * Semantic non-color encoding roles.
+ *
+ * Paths: dataviz.encoding.*
+ */
+interface SemanticDatavizEncoding {
+  shape: {
+    /** Series identity through mark shape — use for redundant differentiation. */series: Record<Scale1To8, TokenRef>;
+  };
+  pattern: {
+    /** Series identity through fill texture — use for filled marks and overlays. */series: Record<Scale1To6, TokenRef>;
+  };
+  stroke: {
+    /** Stroke style for analytical reference guides or baselines. */reference: TokenRef; /** Stroke style for projected or forward-looking data segments. */
+    forecast: TokenRef; /** Stroke style for uncertain or estimated bounds. */
+    uncertainty: TokenRef;
+  };
+  opacity: {
+    /** Opacity for contextual elements behind overlay data. */context: TokenRef; /** Opacity for de-emphasized (non-highlighted) data marks. */
+    muted: TokenRef; /** Opacity for representing estimated or uncertain data visually. */
+    uncertainty: TokenRef;
+  };
+}
+/**
+ * Semantic geospatial overlay roles.
+ *
+ * Defines only the contextual relationship between overlays and geography.
+ * Geospatial overlays use `dataviz.color.*` and `dataviz.encoding.*` for
+ * analytical meaning — these tokens cover only spatial context.
+ *
+ * Paths: dataviz.geo.*
+ */
+interface SemanticDatavizGeo {
+  context: {
+    /** Reduced background wash for geographic base layer. */muted: TokenRef; /** Color for supportive boundary lines (region outlines, coastlines). */
+    boundary: TokenRef; /** Color for contextual geographic labels (city names, region labels). */
+    label: TokenRef;
+  };
+  state: {
+    /** Fill or stroke for a spatially selected region. */selection: TokenRef; /** Fill or stroke for spatially focused region (keyboard / pointer focus). */
+    focus: TokenRef;
+  };
+}
+/**
+ * Full semantic data visualization token tree.
+ *
+ * Placed at `theme.semantic.dataviz` — optional extension of `ThemeTokens`.
+ * This is the **public API** of the Data Visualization extension.
+ * Components and patterns must consume only these tokens.
+ */
+interface SemanticDataviz {
+  color: SemanticDatavizColor;
+  encoding: SemanticDatavizEncoding;
+  geo: SemanticDatavizGeo;
+}
+//#endregion
+//#region src/families/primitives.d.ts
+/** A raw CSS value (color hex, px, clamp expression, etc.) */
+type RawValue = string;
+/** A numeric raw value (font weight, opacity, line-height, z-index, etc.) */
+type NumericValue = number;
+/**
+ * A reference to a core token, expressed as `{token.path}`.
+ *
+ * Optionally narrowed to a path prefix family for autocomplete and typo
+ * catching at high-leverage positions. Defaults to `string` — fully open —
+ * which preserves the original (untyped-path) behavior for any external code
+ * importing `TokenRef` directly.
+ *
+ * Narrowed aliases cover every semantic family. The only remaining open
+ * `TokenRef` is `SemanticFocus.ring.color`, which intentionally references a
+ * `semantic.*` path rather than a `core.*` one.
+ *
+ * @example
+ * ```ts
+ * // open — accepts any '{...}' string
+ * const ref: TokenRef = '{core.colors.brand.500}';
+ *
+ * // narrowed — '{core.spacing.|' autocompletes; '{core.colorz.…}' errors
+ * const gap: TokenRef<`core.spacing.${string}`> = '{core.spacing.4}';
+ * ```
+ */
+type TokenRef<TPath extends string = string> = `{${TPath}}`;
+/** Reference into the `core.colors.*` namespace. */
+type CoreColorRef = TokenRef<`core.colors.${string}`>;
+/** Reference into the `core.spacing.*` namespace. */
+type CoreSpacingRef = TokenRef<`core.spacing.${string}`>;
+/** Reference into the `core.sizing.*` namespace. */
+type CoreSizingRef = TokenRef<`core.sizing.${string}`>;
+/** Reference into the `core.font.scale.*` namespace (responsive size ramp). */
+type CoreFontScaleRef = TokenRef<`core.font.scale.${string}`>;
+/** Reference into the `core.font.*` namespace (family, weight, leading, tracking, optical, numeric). */
+type CoreFontRef = TokenRef<`core.font.${string}`>;
+/** Reference into the `core.elevation.*` namespace. */
+type CoreElevationRef = TokenRef<`core.elevation.${string}`>;
+/** Reference into the `core.radii.*` namespace. */
+type CoreRadiiRef = TokenRef<`core.radii.${string}`>;
+/** Reference into the `core.border.*` namespace (width and style sub-families). */
+type CoreBorderRef = TokenRef<`core.border.${string}`>;
+/** Reference into the `core.opacity.*` namespace. */
+type CoreOpacityRef = TokenRef<`core.opacity.${string}`>;
+/** Reference into the `core.motion.*` namespace (duration and easing sub-families). */
+type CoreMotionRef = TokenRef<`core.motion.${string}`>;
+/** Reference into the `core.zIndex.*` namespace. */
+type CoreZIndexRef = TokenRef<`core.zIndex.${string}`>;
+/**
+ * Recursive partial type. Every nested property becomes optional,
+ * enabling selective overrides at any depth.
+ */
+type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+//#endregion
+//#region src/families/borders.d.ts
+/**
+ * Core line widths — intent-free primitives.
+ * `selected` and `focused` must resolve to a width strictly greater than `default`.
+ * Never reference these directly from components — use semantic border tokens.
+ */
+interface CoreBorderWidths {
+  none: RawValue;
+  default: RawValue;
+  selected: RawValue;
+  focused: RawValue;
+}
+/**
+ * Core line styles — intent-free primitives.
+ * Default to `solid`; use `dashed` or `dotted` only when the pattern truly requires it.
+ */
+interface CoreBorderStyles {
+  solid: RawValue;
+  dashed: RawValue;
+  dotted: RawValue;
+  none: RawValue;
+}
+/** Intent-free line primitives — width and style only. */
+interface CoreBorder {
+  width: CoreBorderWidths;
+  style: CoreBorderStyles;
+}
+/**
+ * Shared shape for every semantic line contract: width + style references only.
+ * Color is never part of this contract — pair with semantic color tokens.
+ * @see SemanticColors — for border color tokens per UX context.
+ */
+interface SemanticBorderOutline {
+  width: CoreBorderRef;
+  style: CoreBorderRef;
+}
+/**
+ * Semantic line contracts — the stable API consumed by components.
+ *
+ * Four canonical contracts (borders.md §Canonical semantic set):
+ * @see borders.md
+ * - `divider`           — structural separator between content groups
+ * - `outline.surface`   — boundary of containing surfaces (cards, panels, dialogs)
+ * - `outline.control`   — boundary of interactive controls (buttons, inputs, toggles)
+ * - `outline.selected`  — stronger-thickness indicator for selected/current state
+ *
+ * Rules:
+ * - Components consume these tokens only — never `core.border.*` directly.
+ * - `outline.selected` must resolve to a width strictly greater than `outline.{surface,control}`.
+ * - Color meaning stays in the color system; these tokens define geometry only.
+ * - Do not add component-specific tokens (`border.input`, `border.card`, etc.).
+ *
+ * @adr ADR-011 — `outline.selected` lives inside `outline.*` (shape grouping); `focus.ring` stays separate (accessibility contract + color field).
+ */
+interface SemanticBorder {
+  /**
+   * Structural separator between content groups (low emphasis).
+   * Use when splitting list rows, sections, toolbar regions, or grouped fields
+   * — anywhere the line *separates* without enclosing.
+   * Pair with a low-emphasis color (`informational.muted.border.default`); do
+   * not use to enclose a surface or control — those are `outline.surface` /
+   * `outline.control`.
+   */
+  divider: SemanticBorderOutline;
+  outline: {
+    /**
+     * Boundary of a containing surface (card, panel, dialog, menu, grouped region).
+     * Use when the element *contains* other content and needs a visible edge.
+     * Pair with `informational.{role}.border.{state}` colors and (optionally)
+     * `semantic.elevation.surface.*`; do not use for interactive controls — those
+     * are `outline.control`.
+     */
+    surface: SemanticBorderOutline;
+    /**
+     * Boundary of an interactive control (button, input, toggle, chip, segmented item).
+     * Use when the element is interactive and needs a visible edge at rest.
+     * Pair with `{ux}.{role}.border.{state}` colors per FSL UX context; do not
+     * use for containing surfaces — those are `outline.surface`.
+     */
+    control: SemanticBorderOutline;
+    /**
+     * Stronger-thickness boundary expressing selected / current state.
+     * Use when selection or current-item status is communicated by line weight
+     * (active tab, selected row, chosen card).
+     * Resolves to a width strictly greater than `outline.{surface,control}`. Do
+     * not use for keyboard focus — that is `semantic.focus.ring`.
+     */
+    selected: SemanticBorderOutline;
+  };
+}
+//#endregion
+//#region src/families/breakpoints.d.ts
+interface CoreBreakpoints {
+  sm: RawValue;
+  md: RawValue;
+  lg: RawValue;
+  xl: RawValue;
+  '2xl': RawValue;
+}
+//#endregion
+//#region src/families/colors.d.ts
+/**
+ * Unified color scale steps (0–1000).
+ * Themes may use any subset; step 500 is always required as the canonical mid-point.
+ */
+type CoreColorStep = 0 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 1000;
+/**
+ * Palette scale — partial record over CoreColorStep with 500 required.
+ * Sparse palettes (100/300/500/700/900) and dense palettes (0–1000) both conform.
+ */
+type CoreColorScale = Partial<Record<CoreColorStep, RawValue>> & {
+  500: RawValue;
+};
+/**
+ * Core color tokens — intent-free palette primitives.
+ *
+ * Rules:
+ * - Core names define palette families and scale positions, never usage.
+ * - No semantic naming (no `danger`, `warning`, `link`, `surface`, etc.).
+ * - No mode naming (core values are immutable across modes).
+ * - No component naming (no `cardBg`, `inputBorder`, etc.).
+ *
+ * @see colors.md
+ */
+interface CoreColors {
+  /** Primary brand identity color scale. */
+  brand: CoreColorScale;
+  /**
+   * Zero-saturation anchor scale (greyscale/slate).
+   * Provides surfaces, text contrast, dividers, and subdued UI.
+   * Named `neutral` by convention — not a semantic role, purely a palette family.
+   * Use step 0 for white-end and step 1000 for black-end.
+   */
+  neutral: CoreColorScale;
+  /**
+   * Open hue families. Themes define which they need (red, green, yellow, blue, etc.).
+   * No fixed set is required beyond `brand` and `neutral`.
+   */
+  [hue: string]: CoreColorScale;
+}
+/** Base interaction states — available in every UX context.
+ *  `selected` is NOT included here — it is added only by the UX contexts
+ *  where set-membership semantics apply (input, navigation, informational).
+ *  Action context uses `pressed` for toggle state instead (FSL Lexicon §7).
+ */
+interface BaseColorStates {
+  /** Resting / base state. The colour rendered when no other state asserts. */
+  default: CoreColorRef;
+  /** Pointer is currently over the element. Do not use for keyboard focus — that is `focused`. */
+  hover?: CoreColorRef;
+  /** Pointer or key is currently *down* on the element — transient, lasts only while held. Releases back to `default` / `hover`. Do not use for persistent toggle state — that is `pressed`. */
+  active?: CoreColorRef;
+  /** Element has keyboard or programmatic focus. Pair with `semantic.focus.ring.color` when no `{ux}.{role}` context applies. */
+  focused?: CoreColorRef;
+  /** Element is non-interactive. Carries the contrast guarantees that `semantic.opacity.disabled` cannot — prefer this for controls and text over opacity. */
+  disabled?: CoreColorRef;
+  /**
+   * Valid drag-and-drop destination during an active drag (FSL Lexicon §7).
+   * Applies wherever drop-target semantics are valid: file inputs, collection rows,
+   * informational surfaces, and any other entity that accepts dropped items.
+   */
+  droptarget?: CoreColorRef;
+}
+/** `action` context: adds `pressed` for toggle controls and `expanded` for disclosure triggers and open menus. */
+interface ActionColorStates extends BaseColorStates {
+  /** Toggle button is currently engaged — *persistent*, not transient. Use for toolbar toggles ("Bold" pressed). Do not confuse with `active` (the brief moment of clicking). */
+  pressed?: CoreColorRef;
+  /** Disclosure trigger or menu button is currently open. Use for buttons that own an open popup, menu, or panel. */
+  expanded?: CoreColorRef;
+}
+/** `input` context: adds `checked`, `indeterminate`, `pressed`, `expanded` for form controls.
+ *
+ * Validation failure is *not* a state — it is an Evaluation (FSL Lexicon §5).
+ * Components that fail validation render with the `input.negative.*` role,
+ * not with an `invalid` state on `input.primary.*`. This avoids dual
+ * representation of the same semantic concept and keeps FSL §7 State Law
+ * intact ("States are not free-form"). React Aria's `isInvalid` flag maps
+ * to selecting the `negative` role, not to a new state.
+ *
+ * Structural Role → token mapping (FSL Lexicon §2): a part declared with
+ * Structural Role `validationMessage` consumes `input.negative.text.*` for
+ * its text dimension (and `input.negative.{background,border}.*` if it
+ * carries those dimensions). `validationMessage` is anatomy (which part);
+ * `input.negative.*` is the visual contract (which value). The same
+ * Evaluation token lawfully serves multiple Structural Roles — this is the
+ * intended single-source semantics, not duplication. */
+interface InputColorStates extends BaseColorStates {
+  /** Element is **one of many** in a set and the user picked it (segment in a segmented control, picker option). Do not use for two-state controls — those are `checked`. */
+  selected?: CoreColorRef;
+  /** **Two-state control** that is currently on — checkbox, radio, switch. Do not use for selection from a set — that is `selected`. */
+  checked?: CoreColorRef;
+  /** Boolean control in a mixed / unknown state — e.g. parent checkbox over partially-checked children. */
+  indeterminate?: CoreColorRef;
+  /** Persistent engaged state of a toggle-style input (e.g. a switch rendered as a button). See `ActionColorStates.pressed` for the disambiguation against `active`. */
+  pressed?: CoreColorRef;
+  /** Combobox / select / disclosure-style input is currently open. */
+  expanded?: CoreColorRef;
+}
+/** `navigation` context: adds `selected`, `current`, `visited`, `expanded`. */
+interface NavigationColorStates extends BaseColorStates {
+  /** Tab / item is **one of many** in the set and the user picked it. May coexist with `current` when the selected item also represents the live route. */
+  selected?: CoreColorRef;
+  /** Element is the user's **current location** in the navigation set — active route, current step in a wizard. Do not use for set-membership without a routing meaning — that is `selected`. */
+  current?: CoreColorRef;
+  /** Link points to a URL the user has visited. */
+  visited?: CoreColorRef;
+  /** Disclosure-style nav item (collapsible section, expandable submenu) is currently open. */
+  expanded?: CoreColorRef;
+}
+/** `informational` context: adds `selected`, `visited`, `expanded`.
+ *
+ * `expanded` covers in-place disclosure on presentational surfaces (accordions,
+ * collapsible panels, expandable cards). `Disclosure` Entity Kinds project to
+ * `informational` per FSL identity (in-place reveal, not movement across
+ * destinations — FSL Lexicon §1). */
+interface InformationalColorStates extends BaseColorStates {
+  /** Presentational element is **one of many** and the user picked it (selectable list row, focused card in a deck). */
+  selected?: CoreColorRef;
+  /** Visited link rendered inside informational content. */
+  visited?: CoreColorRef;
+  /** Accordion / collapsible panel / `<details>` is currently open — in-place reveal (FSL Lexicon §1). */
+  expanded?: CoreColorRef;
+}
+/**
+ * `feedback` context state set — feedback components are not interactive triggers (FSL §7).
+ * Legal states: `default`, `focused` (focusable wrapper or close button), `disabled`.
+ * `hover`, `active`, `selected`, `pressed`, `expanded`, `droptarget` are illegal.
+ */
+interface FeedbackColorStates {
+  /** Resting / base state. The colour rendered when no other state asserts. */
+  default: CoreColorRef;
+  /** Element has keyboard or programmatic focus — e.g. a focusable close button inside the feedback component. */
+  focused?: CoreColorRef;
+  /** Element is non-interactive. Prefer this over `opacity.disabled` for controls and text that carry colour contrast guarantees. */
+  disabled?: CoreColorRef;
+}
+/**
+ * Color dimensions for a given UX context.
+ * Each dimension is optional — components choose which they consume.
+ * (e.g. a text link uses only `text`; a ghost button uses `text` + `border`)
+ */
+interface ColorDimensionOf<S extends BaseColorStates> {
+  /** Fills and surface backgrounds. Use for any colored area larger than a line. */
+  background?: S;
+  /** Outlines, separators, rings, and other line-color pairings. For line *geometry* (width, style) consume `semantic.borders.*` instead — this dimension is colour only. */
+  border?: S;
+  /** Readable foreground — labels, paragraphs, and text-like icons that inherit `currentColor`. */
+  text?: S;
+}
+/** `action`: triggers actions or changes state. Roles: primary | secondary | accent | muted | negative */
+interface ActionColorRoles {
+  /** The single most important action on the view. Only one `primary` per `{ux}` per view — if two compete, the loser is `secondary`. */
+  primary: ColorDimensionOf<ActionColorStates>;
+  /** Alternative action that coexists with the primary one. Use when two actions share the surface and neither dominates. */
+  secondary: ColorDimensionOf<ActionColorStates>;
+  /** Highlighted action that draws attention without being the main path ("Try the new…" promo button). */
+  accent: ColorDimensionOf<ActionColorStates>;
+  /** Low-priority action — helper button, optional control, dismiss / cancel ghost. */
+  muted: ColorDimensionOf<ActionColorStates>;
+  /** Action whose intent is adverse: failure, invalid result, or destructive consequence (delete, cancel paid plan). Outcome (success / warning) lives in `feedback.*`, not here. */
+  negative: ColorDimensionOf<ActionColorStates>;
+}
+/** `input`: data entry, selection, form controls. Roles: primary | secondary | muted | positive | caution | negative */
+interface InputColorRoles {
+  /** Default input role — the brand-influenced active style for the canonical control on the form. */
+  primary: ColorDimensionOf<InputColorStates>;
+  /** Alternative input role coexisting with `primary` — e.g. a secondary search field on the same surface. */
+  secondary: ColorDimensionOf<InputColorStates>;
+  /** Low-priority input — quiet text field, ghost search, optional metadata input. */
+  muted: ColorDimensionOf<InputColorStates>;
+  /** Input whose value reports success / completion / validity confirmed (e.g. "available" username field after async check). */
+  positive: ColorDimensionOf<InputColorStates>;
+  /** Input whose value carries risk that needs attention but does not block submission. */
+  caution: ColorDimensionOf<InputColorStates>;
+  /** Input whose value failed validation — maps from React Aria `isInvalid`. Validation failure is *not* a state on `primary`; it selects this role (FSL Lexicon §5). */
+  negative: ColorDimensionOf<InputColorStates>;
+}
+/** `navigation`: movement and orientation. Roles: primary | secondary | accent | muted */
+interface NavigationColorRoles {
+  /** The dominant navigation surface on the view — main top nav, primary sidebar. */
+  primary: ColorDimensionOf<NavigationColorStates>;
+  /** Secondary navigation that coexists with the primary one — sub-nav, in-page tabs. */
+  secondary: ColorDimensionOf<NavigationColorStates>;
+  /** Highlighted nav item that draws attention without being the main path — "What's new", featured destination. */
+  accent: ColorDimensionOf<NavigationColorStates>;
+  /** Low-priority nav — footer links, breadcrumb separators, optional sub-items. */
+  muted: ColorDimensionOf<NavigationColorStates>;
+}
+/** `feedback`: reactive system/user-result messages. Roles: primary | muted | positive | caution | negative */
+interface FeedbackColorRoles {
+  /** Neutral / informational feedback that carries no valence — "Auto-saved", "Connected". */
+  primary: ColorDimensionOf<FeedbackColorStates>;
+  /** Quiet feedback that should not steal attention — inline hints, low-priority status text. */
+  muted: ColorDimensionOf<FeedbackColorStates>;
+  /** Feedback reporting success, completion, or validity confirmed. */
+  positive: ColorDimensionOf<FeedbackColorStates>;
+  /** Feedback reporting risk that needs attention but does not block the user. */
+  caution: ColorDimensionOf<FeedbackColorStates>;
+  /** Feedback reporting failure or an invalid system state. */
+  negative: ColorDimensionOf<FeedbackColorStates>;
+}
+/** `informational`: informational surfaces and readable content. Roles: primary | secondary | accent | muted | positive | caution | negative */
+interface InformationalColorRoles {
+  /** Dominant content / surface on the view — page background, main panel, the card the user is reading. */
+  primary: ColorDimensionOf<InformationalColorStates>;
+  /** Supporting content / surface coexisting with `primary` — sidebar panel, secondary card. */
+  secondary: ColorDimensionOf<InformationalColorStates>;
+  /** Highlighted content that draws attention without being the main path — featured callout, promo tile. */
+  accent: ColorDimensionOf<InformationalColorStates>;
+  /** Low-priority content — helper text, dividers, captions, metadata. */
+  muted: ColorDimensionOf<InformationalColorStates>;
+  /** Informational surface or text reporting success / completion (e.g. "All up to date" empty state). */
+  positive: ColorDimensionOf<InformationalColorStates>;
+  /** Informational surface or text carrying caution — warning panel, advisory note. */
+  caution: ColorDimensionOf<InformationalColorStates>;
+  /** Informational surface or text reporting failure or invalid state — error empty state, broken-state panel. */
+  negative: ColorDimensionOf<InformationalColorStates>;
+}
+/**
+ * Semantic colour API — the only colour contract components consume.
+ *
+ * Pick the UX context by asking *what kind of UI is this?* (colors.md §"UX contexts in 60 seconds"):
+ * is the user about to **act**, **type**, **move**, **hear back**, or just **see / contain** something?
+ *
+ * Token grammar: `{ux}.{role}.{dimension}.{state}`. Legal combinations are
+ * enforced by the type system; see colors.md §Legal Combinations.
+ *
+ * @see colors.md
+ */
+interface SemanticColors {
+  /** Anything the user **triggers** — buttons, toggles, menu items, action icons. Pick when the user is about to *act*. */
+  action: ActionColorRoles;
+  /** Anything the user **enters or selects data into** — text fields, selects, checkboxes, radios. Pick when the user is about to *type / pick a value*. */
+  input: InputColorRoles;
+  /** Anything that **moves the user** between views or sections — links, tabs, breadcrumbs, pagination. Pick when the user is about to *go somewhere*. */
+  navigation: NavigationColorRoles;
+  /** Surfaces that **report the outcome** of an action or system event — toasts, alerts, banners, inline validation. Pick when the system is *reporting back*. */
+  feedback: FeedbackColorRoles;
+  /**
+   * **Presentational surfaces** — hold, group, layer, frame, or display content; never drive a transaction.
+   * Body text, page backgrounds, cards, panels, dialogs, dividers, list rows, accordions.
+   * Interactivity is not a tiebreaker: a focusable Card or expandable accordion is still `informational` —
+   * its purpose is presentational. Focusability is covered by `semantic.focus.ring.*`; disclosure by the `expanded` state.
+   */
+  informational: InformationalColorRoles;
+}
+//#endregion
+//#region src/families/elevation.d.ts
+/**
+ * Open shadow recipe ramp — themes define as many levels as needed.
+ * Every key referenced by a semantic token must resolve to a defined entry here.
+ */
+type CoreElevationLevels = Record<string, RawValue>;
+/**
+ * Core elevation primitives — shadow recipe ramps.
+ *
+ * - `level`    — base recipes (standard opacity), used by default in light themes
+ * - `emphatic` — high-opacity recipes for surfaces needing stronger depth contrast
+ *               (e.g., on dark or heavily-colored backgrounds)
+ *
+ * Both ramps are open `Record<string, RawValue>` — themes define as many levels as
+ * needed. Every key referenced by a semantic token must be defined here.
+ *
+ * Future expansion (non-breaking): add optional sibling ramps as needed.
+ * @see elevation.md
+ */
+interface CoreElevation {
+  /** Base shadow recipes — standard opacity, light-surface defaults. */
+  level: CoreElevationLevels;
+  /**
+   * High-opacity shadow recipes for surfaces needing stronger depth contrast.
+   * Mode-agnostic: expresses shadow weight, not a mode label.
+   * Themes include this ramp when a dark alternate requires higher-opacity recipes.
+   */
+  emphatic?: CoreElevationLevels;
+}
+interface SemanticElevation {
+  /**
+   * Shadow-based surface strata — the primary depth contract.
+   * Maps each stratum to a shadow recipe (core elevation reference).
+   */
+  surface: {
+    /** Surfaces flush with the page */flat: CoreElevationRef; /** Cards and panels */
+    raised: CoreElevationRef; /** Dropdowns, popovers, floating surfaces */
+    overlay: CoreElevationRef; /** Dialogs and blocking sheets */
+    blocking: CoreElevationRef;
+  };
+  /**
+   * Tonal overlay tokens — optional surface color treatments paired with shadows
+   * to preserve depth perception in dark or heavily-colored themes.
+   *
+   * Each token typically resolves to a color overlay (e.g., `color-mix`, rgba surface).
+   * Omit when the product does not use tonal elevation.
+   * When present, must cover the same strata that carry visible shadows.
+   * @see elevation.md — "Surface + Shadow"
+   */
+  tonal?: {
+    /**
+     * Tonal surface treatment paired with `surface.raised`.
+     * Use when the raised stratum needs an additional color overlay (typical in
+     * dark themes where shadow alone is insufficient).
+     * Pair with `surface.raised`; do not use without the matching shadow contract.
+     */
+    raised: CoreColorRef;
+    /**
+     * Tonal surface treatment paired with `surface.overlay`.
+     * Use when the overlay stratum (dropdowns, popovers) needs reinforced
+     * tonal lift over the page beneath.
+     * Pair with `surface.overlay`; resolves to a stronger overlay than `tonal.raised`.
+     */
+    overlay: CoreColorRef;
+    /**
+     * Tonal surface treatment paired with `surface.blocking`.
+     * Use when the blocking stratum (dialogs, sheets) needs the strongest
+     * tonal separation from the page beneath the scrim.
+     * Pair with `surface.blocking` and `semantic.overlay.scrim`; resolves to
+     * the strongest tonal overlay in the contract.
+     */
+    blocking: CoreColorRef;
+  };
+}
+//#endregion
+//#region src/families/focus.d.ts
+interface SemanticFocus {
+  ring: SemanticBorderOutline & {
+    /**
+     * System-wide focus ring colour — cross-cutting infrastructure (model.md §6).
+     *
+     * Use this when the component has no obvious FSL Entity Kind
+     * (focusable Card, profile chip, custom widget). For components with a clear
+     * `{ux}`, prefer `{ux}.{role}.border.focused` instead.
+     *
+     * Must reference a semantic token so mode overrides remap it automatically.
+     */
+    color: TokenRef<`semantic.${string}`>;
+  };
+}
+//#endregion
+//#region src/families/motion.d.ts
+interface CoreMotionDurations {
+  none: RawValue;
+  xs: RawValue;
+  sm: RawValue;
+  md: RawValue;
+  lg: RawValue;
+  xl: RawValue;
+}
+interface CoreMotionEasings {
+  standard: RawValue;
+  enter: RawValue;
+  exit: RawValue;
+  linear: RawValue;
+}
+/** Core motion primitives — duration steps and easing curves. Components consume only semantic motion tokens. */
+interface CoreMotion {
+  duration: CoreMotionDurations;
+  easing: CoreMotionEasings;
+}
+/** A duration + easing pair that fully specifies motion for one use-case. */
+interface SemanticMotionSpec {
+  duration: CoreMotionRef;
+  easing: CoreMotionRef;
+}
+interface SemanticMotion {
+  /**
+   * Immediate response to a discrete user input on a single element.
+   * Use when animating hover, press, toggle, or small confirmation tweaks
+   * (color/scale/opacity changes on the element itself).
+   * Do not use for elements entering or leaving the layout — those are
+   * `transition.enter` / `transition.exit`.
+   */
+  feedback: SemanticMotionSpec;
+  transition: {
+    /**
+     * Element appearing into rest position (overlay, surface, revealed content).
+     * Use when an element transitions *from* hidden/absent *to* visible.
+     * Pair with `transition.exit` on the inverse phase; do not use for the
+     * resting element's response to input — that is `feedback`.
+     */
+    enter: SemanticMotionSpec;
+    /**
+     * Element leaving rest position (overlay closing, content dismissing).
+     * Use when an element transitions *from* visible *to* hidden/absent.
+     * Symmetric counterpart of `transition.enter`; the exit phase is shorter
+     * by default to keep dismissal feeling responsive.
+     */
+    exit: SemanticMotionSpec;
+  };
+  /**
+   * Attention-drawing motion for a relevant in-place change.
+   * Use when the user must notice that something changed (status update,
+   * value reconciliation, error appearing on a field).
+   * Stronger than `feedback`; do not use for routine state changes — that is
+   * `feedback`. May collapse to minimal motion in static themes.
+   */
+  emphasis: SemanticMotionSpec;
+  /**
+   * Ambient, non-essential motion (loops, parallax, idle flourishes).
+   * Use only when motion is never required for understanding the UI.
+   * Always disabled by default in static or reduced-motion themes; do not use
+   * for any motion the user must perceive to operate the interface.
+   */
+  decorative: SemanticMotionSpec;
+}
+//#endregion
+//#region src/families/opacity.d.ts
+/** Intent-free opacity scale. Components must use `SemanticOpacity` — never this directly.
+ * Invariant: `0 ≤ 25 ≤ 50 ≤ 75 ≤ 100`, all in `[0, 1]`, no two adjacent steps equal. */
+interface CoreOpacity {
+  100: NumericValue;
+  75: NumericValue;
+  50: NumericValue;
+  25: NumericValue;
+  0: NumericValue;
+}
+/** Stable opacity contracts for components. Each must resolve to `(0, 1)` exclusive.
+ *
+ * Opacity is a whole-element modifier — never a substitute for a semantic
+ * color, state, or hierarchy token (opacity.md §"What Opacity Should Not Do").
+ * If only one dimension (background, text, border) should become translucent,
+ * use a semantic color with alpha instead.
+ */
+interface SemanticOpacity {
+  /**
+   * Backdrop dimming for a blocking foreground layer.
+   * Use when rendering the layer that sits *behind* a modal, dialog, drawer, or sheet
+   * to attenuate the page underneath.
+   * Pair with `semantic.overlay.scrim` (the colored backdrop fill); do not use on the
+   * foreground surface itself — that surface stays fully opaque.
+   */
+  scrim: CoreOpacityRef;
+  /**
+   * De-emphasis veil for content during in-flight asynchronous work.
+   * Use when content must remain visible (so the user keeps spatial context) while a
+   * fetch / mutation / long task is pending.
+   * Do not use for permanent disabled state — that is `disabled`. Remove the moment
+   * the work resolves.
+   */
+  loading: CoreOpacityRef;
+  /**
+   * Dimming for image-like media in a disabled state (avatars, thumbnails, illustrations).
+   * Use when the disabled element has no semantic color contract that can carry the state
+   * (i.e. it is a visual asset, not a control).
+   * Do not use for disabled controls or text — those consume `{ux}.{role}.{dimension}.disabled`
+   * color tokens, which carry the contrast guarantees opacity cannot.
+   */
+  disabled: CoreOpacityRef;
+}
+//#endregion
+//#region src/families/overlay.d.ts
+interface SemanticOverlay {
+  /** Modal backdrop color — full CSS color including alpha. */
+  scrim: RawValue;
+}
+//#endregion
+//#region src/families/radii.d.ts
+/**
+ * Core radius scale — intent-free corner curvature primitives.
+ * Ordered: none < sm < md < lg < xl << full.
+ *
+ * **Never reference core radii directly from components.**
+ * Components consume only semantic radii (`radii.control`, `radii.surface`, `radii.round`).
+ */
+interface CoreRadii {
+  none: RawValue;
+  sm: RawValue;
+  md: RawValue;
+  lg: RawValue;
+  xl: RawValue;
+  /**
+   * Fully-rounded intent (`9999px`).
+   * Expresses shape intent — perfect circles still depend on element dimensions.
+   */
+  full: RawValue;
+}
+/**
+ * Semantic radius contracts — stable shape API consumed by components.
+ *
+ * Pick by structural role:
+ * - `control`  → interactive element (button, input, toggle, chip)
+ * - `surface`  → containing surface (card, panel, dialog, menu)
+ * - `round`    → explicitly fully-rounded shape intent (pill, capsule, avatar)
+ *
+ * @see radii.md — Decision Matrix and Rules of Engagement.
+ */
+interface SemanticRadii {
+  /** Radius for interactive controls and touchable UI elements. */
+  control: CoreRadiiRef;
+  /** Radius for surfaces that contain or group content. */
+  surface: CoreRadiiRef;
+  /** Full-round shape intent for pills, capsules, and circular affordances. */
+  round: CoreRadiiRef;
+}
+//#endregion
+//#region src/families/sizing.d.ts
+type CoreSizeRampUI = Record<1 | 2 | 3 | 4 | 5 | 6 | 7 | 8, RawValue>;
+type CoreSizeRampLayout = Record<1 | 2 | 3 | 4 | 5 | 6, RawValue>;
+interface CoreSizeRelative {
+  em: RawValue;
+  rem: RawValue;
+}
+interface CoreSizeBehavior {
+  auto: RawValue;
+  full: RawValue;
+  fit: RawValue;
+  min: RawValue;
+  max: RawValue;
+}
+interface CoreSizeViewport {
+  height: {
+    full: RawValue;
+  };
+  width: {
+    full: RawValue;
+  };
+}
+/** Three-step hit target size ramp (min / base / prominent). */
+interface CoreSizeHitScale {
+  min: RawValue;
+  base: RawValue;
+  prominent: RawValue;
+}
+/**
+ * Hit target sizes split by pointer type.
+ * `toCssVars` automatically injects the `coarse` values under `@media (any-pointer: coarse)`.
+ */
+interface CoreSizeHit {
+  /** Fine pointer (mouse/trackpad) hit targets */
+  fine: CoreSizeHitScale;
+  /** Coarse pointer (touch) hit targets */
+  coarse: CoreSizeHitScale;
+}
+interface CoreSizing {
+  ramp: {
+    ui: CoreSizeRampUI;
+    layout: CoreSizeRampLayout;
+  };
+  relative: CoreSizeRelative;
+  behavior: CoreSizeBehavior;
+  viewport: CoreSizeViewport;
+  hit: CoreSizeHit;
+}
+interface SemanticSizing {
+  /**
+   * Ergonomic hit targets. Each token resolves to the **fine-pointer** value.
+   * The CSS output layer (`toCssVars`) automatically injects coarse-pointer
+   * overrides inside `@media (any-pointer: coarse)` — no component code needed.
+   *
+   * Fine-pointer values (`core.sizing.hit.fine.*`) may use `clamp(floor, preferred, max)`
+   * where `floor` is a fixed `Npx` ergonomic minimum — this guarantees accessibility
+   * while allowing themes to express density preferences (e.g. via the rem scale).
+   * Coarse-pointer values (`core.sizing.hit.coarse.*`) are always fixed `px`.
+   */
+  hit: {
+    /** Minimum interactive area for small / secondary targets (icon-only buttons, toolbar items). Enforce via `min-width` / `min-height`; not a visual size. */min: CoreSizingRef; /** Default interactive area for standard buttons, inputs, and toggles. Pick when no other step applies. */
+    base: CoreSizingRef; /** Prominent interactive area for high-emphasis or low-density targets (CTAs, dialog actions). */
+    prominent: CoreSizingRef;
+  };
+  /**
+   * Visual glyph dimensions. Set on the icon element itself; never used to
+   * gate the hit target that wraps it (that is `hit.*`).
+   */
+  icon: {
+    /** Compact glyph — dense UI, inline indicators, list-row icons. */sm: CoreSizingRef; /** Default glyph — pick this when no other step applies. */
+    md: CoreSizingRef; /** Prominent glyph — emphasis or feature icons. */
+    lg: CoreSizingRef;
+  };
+  /**
+   * Visual identity object dimensions (avatars, profile photos, brand marks,
+   * entity logos). Carries the *visual* size only — the surrounding hit target,
+   * if any, is sized via `hit.*`.
+   */
+  identity: {
+    /** Compact identity — list rows, dense lists, mention chips. */sm: CoreSizingRef; /** Default identity — toolbar, navigation, standard avatar slots. */
+    md: CoreSizingRef; /** Prominent identity — profile cards, feature surfaces. */
+    lg: CoreSizingRef; /** Hero identity — landing surfaces, brand-leading sections. */
+    xl: CoreSizingRef;
+  };
+  measure: {
+    /**
+     * Typed as `RawValue` by design: `ch` units cannot be expressed as a core
+     * token reference. Override with a validated character-based `clamp()`
+     * expression only — never px or rem.
+     */
+    reading: RawValue;
+  };
+  surface: {
+    /**
+     * Maximum width of a structural surface (page shell, content column,
+     * card / panel / dialog wrapper).
+     * Use as `max-width` on the *outer* surface wrapper.
+     * Pair with `gutter.page` for inline padding; do not use for line-length
+     * readability — that is `measure.reading`.
+     */
+    maxWidth: CoreSizingRef;
+  };
+  viewport: {
+    height: {
+      /**
+       * Full-height layouts using dynamic viewport units (`100dvh`).
+       * Use intentionally — only when a region must occupy the full viewport
+       * height (app shells, full-screen modals, mobile splash regions).
+       * Do not use `100vh` directly — dynamic units handle mobile chrome correctly.
+       */
+      full: CoreSizingRef;
+    };
+    width: {
+      /**
+       * Full-width layouts using dynamic viewport units (`100dvw`).
+       * Use intentionally — only when a region must span the full viewport
+       * width (full-bleed banners, edge-to-edge surfaces).
+       * Do not use `100vw` directly — dynamic units avoid scrollbar overflow.
+       */
+      full: CoreSizingRef;
+    };
+  };
+}
+//#endregion
+//#region src/families/spacing.d.ts
+interface CoreSpacingEngine {
+  /** Responsive base unit — container-first clamp formula */
+  unit: RawValue;
+  /** Optional container-aware variant */
+  unitCq?: RawValue;
+}
+interface CoreSpacingSteps {
+  /** Responsive engine primitives — internal, not for direct component use */
+  engine: CoreSpacingEngine;
+  0: RawValue;
+  1: RawValue;
+  2: RawValue;
+  3: RawValue;
+  4: RawValue;
+  6: RawValue;
+  8: RawValue;
+  12: RawValue;
+  16: RawValue;
+}
+interface InsetSteps {
+  /** Compact step — tight controls / dense surfaces. */
+  sm: CoreSpacingRef;
+  /** Default step — standard controls and surfaces. Pick this when no other step applies. */
+  md: CoreSpacingRef;
+  /** Roomy step — prominent controls / spacious surfaces. */
+  lg: CoreSpacingRef;
+}
+interface GapStackSteps {
+  /** Tight vertical rhythm — micro-clusters within a single field. */
+  xs: CoreSpacingRef;
+  /** Medium vertical rhythm — sibling lines inside a form group. */
+  sm: CoreSpacingRef;
+  /** Default vertical rhythm — pick this when no other step applies. */
+  md: CoreSpacingRef;
+  /** Roomy vertical rhythm — separating distinct content clusters within a surface. */
+  lg: CoreSpacingRef;
+  /** Section-level rhythm — separating major sections of a page. */
+  xl: CoreSpacingRef;
+}
+interface GapInlineSteps {
+  /** Visual-only tight grouping (icon + label inside a single target). Never between focusable targets — use `separation.interactive.min`. */
+  xs: CoreSpacingRef;
+  /** Inline grouping — same magnitude as `gap.stack.xs`. */
+  sm: CoreSpacingRef;
+  /** Looser inline grouping — same magnitude as `gap.stack.sm`. */
+  md: CoreSpacingRef;
+  /** Spacious inline grouping — same magnitude as `gap.stack.md`. */
+  lg: CoreSpacingRef;
+  /** Wide inline grouping — same magnitude as `gap.stack.lg`. */
+  xl: CoreSpacingRef;
+}
+interface SemanticSpacing {
+  /**
+   * Internal padding *inside* an element (CSS `padding`).
+   * Use when the spacing lives between an element's edge and its own content;
+   * never for the distance between siblings — that is `gap.*`.
+   */
+  inset: {
+    /**
+     * Padding inside an interactive control (button, input, chip, toggle).
+     * Use on elements with a hit target and a single inner content cluster.
+     * Pair with `inset.surface` on the containing surface; do not use for
+     * containing surfaces — those are `inset.surface`.
+     */
+    control: InsetSteps;
+    /**
+     * Padding inside a containing surface (card, panel, dialog, menu, section).
+     * Use on elements that *contain* other content blocks and need a margin
+     * between their edge and the inner cluster.
+     * Must be ≥ `inset.control` at the same step (validation rule); do not use
+     * for the inner controls themselves — those are `inset.control`.
+     */
+    surface: InsetSteps;
+  };
+  /**
+   * Distance *between* siblings (CSS `gap` on Flex/Grid containers).
+   * Use when laying out a sequence of sibling elements; never for internal
+   * padding (that is `inset.*`) and never for page/section structural padding
+   * (that is `gutter.*`).
+   */
+  gap: {
+    /**
+     * Vertical rhythm between stacked siblings (column layouts, lists, form fields).
+     * Use when items flow along the block axis and rhythm carries hierarchy.
+     * Pair with `gap.inline` for horizontal groupings; do not use for items
+     * arranged along the inline axis — those are `gap.inline`.
+     */
+    stack: GapStackSteps;
+    /**
+     * Horizontal grouping between inline siblings (icon + label, toolbar items, chip rows).
+     * Use when items flow along the inline axis as a visual group.
+     * `gap.inline.xs` is *visual-only* — never use it between independently
+     * focusable interactive targets (use `separation.interactive.min` instead).
+     */
+    inline: GapInlineSteps;
+  };
+  /**
+   * Structural outer padding for page-level and section-level layout regions.
+   * `page` and `section` may use a `clamp()` expression with embedded `{token.path}` refs
+   * (e.g. `clamp({core.space.4}, {core.space.6}, {core.space.12})`).
+   * Typed as `RawValue` to allow both simple refs and responsive clamp expressions.
+   */
+  gutter: {
+    /**
+     * Outer padding bounding the page's content column.
+     * Use as inline padding on the top-level page container.
+     * Bounded `clamp()` contract by spec; do not use for inner sections — that
+     * is `gutter.section`.
+     */
+    page: RawValue;
+    /**
+     * Outer padding separating a section's content from its parent's gutter.
+     * Use on inner section wrappers nested inside a `gutter.page` container.
+     * Bounded `clamp()` contract by spec; resolves tighter than `gutter.page`.
+     */
+    section: RawValue;
+  };
+  /**
+   * Ergonomic separation between independently actionable targets in dense clusters.
+   * May use a `clamp()` expression with an embedded `{token.path}` ref
+   * (e.g. `clamp(8px, {core.space.2}, 12px)`).
+   */
+  separation: {
+    interactive: {
+      /**
+       * Minimum gap between adjacent interactive targets (toolbar buttons,
+       * paginator arrows, segmented controls, dense menu items).
+       * Use only between elements the user can click/tap/focus independently.
+       * Do not use for visual-only groupings — that is `gap.inline.xs`.
+       */
+      min: RawValue;
+    };
+  };
+}
+//#endregion
+//#region src/families/typography.d.ts
+interface CoreFontFamilies {
+  sans: RawValue;
+  mono: RawValue;
+  serif?: RawValue;
+}
+interface CoreFontWeights {
+  regular: NumericValue;
+  medium: NumericValue;
+  semibold: NumericValue;
+  bold: NumericValue;
+}
+interface CoreFontLeading {
+  tight: NumericValue;
+  snug: NumericValue;
+  normal: NumericValue;
+  relaxed: NumericValue;
+}
+interface CoreFontTracking {
+  tight: RawValue;
+  normal: RawValue;
+  wide: RawValue;
+}
+/**
+ * Core font optical sizing primitives — exhaustive enumeration of the CSS
+ * `font-optical-sizing` property values. Closed set by spec, not by choice.
+ *
+ * Mapping (token → CSS keyword):
+ * - `auto` → `auto`  (let the UA opt into optical sizing for variable fonts)
+ * - `none` → `none`  (disable optical adjustments)
+ *
+ * The wrapper exists to satisfy the `CoreFontRef` invariant of `TextStyle`
+ * (semantic styles reference core tokens only) and to register entries in the
+ * CSS variable pipeline — not to enable per-theme variation, which the CSS
+ * spec does not permit.
+ */
+interface CoreFontOptical {
+  auto: RawValue;
+  none: RawValue;
+}
+/**
+ * Core font numeric variant primitives — figure shape, alignment, and special glyph
+ * features exposed by the CSS `font-variant-numeric` property.
+ *
+ * The set covers the standalone keyword values of the CSS spec; combinations
+ * (e.g. `tabular-nums slashed-zero`) are composed at the consumer site by
+ * concatenating these values, not encoded as additional tokens.
+ *
+ * Mapping (token → CSS keyword):
+ * - `proportional` → `proportional-nums`  (default figure widths)
+ * - `tabular`      → `tabular-nums`       (uniform-width figures; dashboards, tables)
+ * - `lining`       → `lining-nums`        (cap-height figures)
+ * - `oldstyle`     → `oldstyle-nums`      (text-figure variants for body copy)
+ * - `slashedZero`  → `slashed-zero`       (zero disambiguation; financial/code contexts)
+ * - `ordinal`      → `ordinal`            (1st, 2nd, 3rd ordinal markers)
+ * - `normal`       → `normal`             (reset to UA defaults)
+ *
+ * The wrapper exists to satisfy the `CoreFontRef` invariant of `TextStyle`
+ * (semantic styles reference core tokens only) and to register entries in the
+ * CSS variable pipeline — not to enable per-theme variation of the keyword
+ * values themselves, which are fixed by the CSS spec.
+ */
+interface CoreFontNumeric {
+  proportional: RawValue;
+  tabular: RawValue;
+  lining: RawValue;
+  oldstyle: RawValue;
+  slashedZero: RawValue;
+  ordinal: RawValue;
+  normal: RawValue;
+}
+type RampScale6 = Record<1 | 2 | 3 | 4 | 5 | 6, RawValue>;
+/**
+ * Responsive font size scale — text and display size ramps.
+ * Both ramps use `clamp()` expressions with container query units (cqi) as the
+ * preferred fluid step, with viewport-safe fallbacks emitted by `toCssVars`.
+ */
+interface CoreFontScale {
+  /** Body text, labels, and dense UI typography */
+  text: RampScale6;
+  /** Headings, titles, and high-hierarchy display text */
+  display: RampScale6;
+}
+/** Core font primitive set — family, weight, leading (line height), tracking (letter spacing), optical sizing, numeric variant references, and the responsive size scale. */
+interface CoreFont {
+  family: CoreFontFamilies;
+  weight: CoreFontWeights;
+  leading: CoreFontLeading;
+  tracking: CoreFontTracking;
+  optical: CoreFontOptical;
+  numeric: CoreFontNumeric;
+  /** Responsive font size scale. @see CoreFontScale */
+  scale: CoreFontScale;
+}
+/** Composite text style — groups 5–7 font token references that define a single typographic role. References core tokens only. */
+interface TextStyle {
+  fontFamily: CoreFontRef;
+  fontSize: CoreFontScaleRef;
+  fontWeight: CoreFontRef;
+  lineHeight: CoreFontRef;
+  letterSpacing: CoreFontRef;
+  fontOpticalSizing?: CoreFontRef;
+  fontVariantNumeric?: CoreFontRef;
+}
+/**
+ * Three-step size scale within a single text family.
+ * Step is the *relative* hierarchy inside the family — never an absolute size.
+ * Same step across families is not interchangeable: `display.md` and `body.md`
+ * share only the step name, not the role.
+ */
+interface TextStyleLgMdSm {
+  /** Largest step of this family — strongest hierarchy *within* the family. Use for the most prominent instance of this role on the surface. */
+  lg: TextStyle;
+  /** Default step of this family — the unmarked choice. Use unless the surface explicitly calls for `lg` or `sm`. */
+  md: TextStyle;
+  /** Smallest step of this family — compact / dense usage. Use when space is constrained or when the text is secondary within the role. */
+  sm: TextStyle;
+}
+/**
+ * Two-step size scale (no `lg`) for families where a hero step is not meaningful.
+ * @see TextStyleLgMdSm — for the rationale of step semantics.
+ */
+interface TextStyleMdSm {
+  /** Default step of this family — the unmarked choice. */
+  md: TextStyle;
+  /** Smallest step of this family — compact / dense usage. */
+  sm: TextStyle;
+}
+/**
+ * Semantic text styles — the only typography API consumed by components.
+ *
+ * Family is the typographic *role* (where in the interface this text sits);
+ * step (`lg`/`md`/`sm`) is the relative size *within* the role. The pair
+ * `family × step` selects one composite style; never mix `display.sm` with
+ * `headline.lg` to "shrink a display" — pick the family whose role matches.
+ *
+ * HTML semantics (`h1…h6`, `p`, `label`) and visual style are decoupled —
+ * `as="h2"` carries document structure; `text.title.md` carries appearance.
+ *
+ * @see typography.md — Text Families table.
+ */
+interface SemanticText {
+  /**
+   * High-impact hero text — landing surfaces and prominent page headers.
+   * Use sparingly; reserved for the single most important text on a page.
+   * Pair with `headline` for the next hierarchy step; do not use for section
+   * headings inside content — those are `headline`.
+   */
+  display: TextStyleLgMdSm;
+  /**
+   * Section or page headings that structure scanning of the document.
+   * Use for the primary headings inside content (page title, major section breaks).
+   * Below `display` in hierarchy, above `title`. Do not use for surface chrome
+   * (card / panel / dialog headers) — those are `title`.
+   */
+  headline: TextStyleLgMdSm;
+  /**
+   * Titles for *surfaces* — cards, panels, dialogs, sheets, menus, structured sections.
+   * Use as the heading of a contained surface, not the heading of a content section.
+   * Pair with `body` / `label` inside the same surface; do not use for top-level
+   * page or document headings — those are `headline` / `display`.
+   */
+  title: TextStyleLgMdSm;
+  /**
+   * Default reading text — paragraphs, descriptions, long-form content.
+   * Use for any text the user will *read* rather than *scan* or *select*.
+   * Optimized for readability; do not use for short UI strings or labels —
+   * those are `label`.
+   */
+  body: TextStyleLgMdSm;
+  /**
+   * Short UI strings — field labels, button text, badges, metadata, captions.
+   * Use for compact, scan-only text that names or describes adjacent UI.
+   * Do not use for prose the user must read in sequence — that is `body`.
+   */
+  label: TextStyleLgMdSm;
+  /**
+   * Monospaced text for code snippets, logs, identifiers, or technical data.
+   * Use whenever the text must align by character cell or distinguish similar
+   * glyphs (`Il1O0`).
+   * Do not use for UI strings that merely *look* technical — that is `body` or `label`.
+   */
+  code: TextStyleMdSm;
+}
+//#endregion
+//#region src/families/z-index.d.ts
+/**
+ * Intent-free z-index level scale. Components must use `SemanticZIndex` — never this directly.
+ * Ordering invariant (strictly ascending): `level.0 < level.1 < level.2 < level.3 < level.4`.
+ * `level.0` must be ≥ 0. Adjacent levels must differ by ≥ 10.
+ */
+type CoreZIndexLevels = Record<0 | 1 | 2 | 3 | 4, NumericValue>;
+interface CoreZIndex {
+  level: CoreZIndexLevels;
+}
+/**
+ * Stable application strata consumed by components. Top-layer browser elements
+ * (modal dialogs / popovers promoted by the platform) are out of scope.
+ *
+ * Tokens express *cross-component layer relationships* only — never local
+ * layering inside a single component, never visual depth (that is `elevation`).
+ * Stratum picked must match the element's *blocking behaviour* and *persistence*,
+ * not its component name (no `z.dropdown`, `z.toast`, etc.).
+ */
+interface SemanticZIndex {
+  layer: {
+    /**
+     * Page content in normal document flow.
+     * Use when the element participates in the default application stratum and
+     * has no claim above sibling content.
+     * Do not use to "reset" stacking inside a component — local layering is
+     * the component's own concern.
+     */
+    base: CoreZIndexRef;
+    /**
+     * Anchored bars that follow scroll while staying inside the app stack.
+     * Use when building sticky headers, sticky navigation, or persistent
+     * anchored toolbars.
+     * Pair with `position: sticky`; do not use for non-anchored floating
+     * surfaces — those are `overlay`.
+     */
+    sticky: CoreZIndexRef;
+    /**
+     * Non-blocking floating surfaces above sticky and base content.
+     * Use when building dropdowns, menus, popovers, or floating panels that
+     * the user can dismiss by interacting elsewhere.
+     * Do not use for surfaces that block the page behind them — those are
+     * `blocking`.
+     */
+    overlay: CoreZIndexRef;
+    /**
+     * Surfaces that sit above other overlays and prevent interaction behind them.
+     * Use when building dialogs, sheets, or blocking drawers paired with a scrim.
+     * Pair with `semantic.overlay.scrim` and `semantic.opacity.scrim`; do not
+     * use for non-blocking floating panels — those are `overlay`.
+     */
+    blocking: CoreZIndexRef;
+    /**
+     * Highest application-controlled stratum before the browser top layer.
+     * Use when building transient notifications that must surface above any
+     * other app stratum (toasts, tooltip-like transient overlays).
+     * Do not use for persistent UI — `transient` implies the element is
+     * short-lived and self-dismissing.
+     */
+    transient: CoreZIndexRef;
+  };
+}
+//#endregion
+//#region src/Types.d.ts
+/**
+ * Full ttoss Design Tokens Theme contract.
+ *
+ * Two layers:
+ *   - `core`     — raw primitives and responsive engines (immutable across modes)
+ *   - `semantic` — stable aliases consumed by components (remapped per mode)
+ *
+ * Extensions are optional properties inside `core` and `semantic`.
+ * When present they follow the same `core → semantic` contract.
+ */
+interface ThemeTokens {
+  core: {
+    colors: CoreColors;
+    elevation: CoreElevation;
+    font: CoreFont;
+    spacing: CoreSpacingSteps;
+    sizing: CoreSizing;
+    radii: CoreRadii;
+    border: CoreBorder;
+    opacity: CoreOpacity;
+    motion: CoreMotion;
+    zIndex: CoreZIndex; /** Viewport threshold scale. Core-only — no semantic layer. @see CoreBreakpoints */
+    breakpoints: CoreBreakpoints;
+    /**
+     * Data Visualization extension — analytical color palettes and non-color
+     * encoding primitives. Optional: omit when the theme does not support dataviz.
+     */
+    dataviz?: CoreDataviz;
+  };
+  semantic: {
+    colors: SemanticColors;
+    elevation: SemanticElevation;
+    text: SemanticText;
+    spacing: SemanticSpacing;
+    sizing: SemanticSizing;
+    radii: SemanticRadii;
+    border: SemanticBorder;
+    focus: SemanticFocus;
+    overlay: SemanticOverlay;
+    opacity: SemanticOpacity;
+    motion: SemanticMotion;
+    zIndex: SemanticZIndex;
+    /**
+     * Data Visualization extension — semantic roles for analytical color,
+     * non-color encodings, and geospatial overlays.
+     * Optional: omit when the theme does not support dataviz.
+     *
+     * This is the **public API** of the dataviz extension.
+     * Components consume these tokens; never `core.dataviz.*` directly.
+     */
+    dataviz?: SemanticDataviz;
+  };
+}
+/**
+ * Semantic-only overrides for the alternate color mode.
+ *
+ * Core tokens are immutable across modes. Only semantic token references
+ * may change — remapping to different core tokens for the alternate mode.
+ *
+ * Uses `DeepPartial`: every nested key is optional. Omitting a key inherits
+ * the value from the base theme (see `deepMerge` in `roots/helpers.ts`,
+ * which treats `undefined` and absent keys identically). An alternate
+ * supplies only the leaves that differ from the base.
+ *
+ * @see {@link modes.md} — "Modes remap semantic references, not core values."
+ */
+interface ModeOverride {
+  semantic: DeepPartial<ThemeTokens['semantic']>;
+}
+/**
+ * A theme bundle packages a complete `ThemeTokens` (the base)
+ * with an optional semantic-only override for the alternate color mode.
+ *
+ * - `baseMode` declares which mode the `base` theme represents.
+ * - `alternate` remaps only semantic token references that differ in the
+ *   opposite mode. Core token values stay immutable.
+ *
+ * **Why only two modes?** `prefers-color-scheme` is binary (`light` / `dark`);
+ * that is the only axis `ThemeBundle` addresses. High-contrast, reduced-motion,
+ * and coarse-pointer are orthogonal CSS `@media` axes — they are handled by
+ * the dedicated blocks emitted by `toCssVars` and are not additional modes.
+ * Proposals to generalize to `Record<ModeName, ModeOverride>` conflate these
+ * independent axes and should be rejected.
+ *
+ * When no `alternate` is provided, the theme is single-mode.
+ *
+ * @example
+ * ```ts
+ * const bundle: ThemeBundle = {
+ *   baseMode: 'light',
+ *   base: baseTheme,
+ *   alternate: {
+ *     semantic: {
+ *       colors: {
+ *         informational: { primary: { background: { default: '{core.colors.neutral.900}' } } },
+ *       },
+ *     },
+ *   },
+ * };
+ * ```
+ */
+interface ThemeBundle {
+  /**
+   * Which color mode the `base` theme represents.
+   * Constrained to `'light' | 'dark'` because `prefers-color-scheme` is binary.
+   */
+  baseMode: 'light' | 'dark';
+  /** Complete theme for the base mode. */
+  base: ThemeTokens;
+  /**
+   * Semantic remapping overrides for the opposite mode.
+   * Only semantic references that differ need to be listed — core tokens are shared.
+   */
+  alternate?: ModeOverride;
+}
+/**
+ * The semantic token layer of a theme. This is the **only** part of the token
+ * system that components should consume — never `core.*` tokens directly.
+ *
+ * Obtain via `useTokens()` inside a `<ThemeProvider theme={...}>`.
+ *
+ * @see {@link useTokens}
+ */
+type SemanticTokens = ThemeTokens['semantic'];
+//#endregion
+export { DeepPartial as a, ThemeTokens as i, SemanticTokens as n, CoreDataviz as o, ThemeBundle as r, SemanticDataviz as s, ModeOverride as t };