@trinityui/design-system 2.11.0 → 2.13.0

package/dist/tokens.d.ts

@@ -154,6 +154,13 @@ export interface TrinityEasing {
     smooth: string;
     bounce: string;
     elastic: string;
+    /**
+     * Exponential ease-out, `cubic-bezier(0.16, 1, 0.3, 1)`: a fast start that settles softly.
+     * The source of `semanticTokens.motion.easing.emphasized`. Optional, so token sets written
+     * before 2.13.0 still compile (E-32).
+     * @since 2.13.0
+     */
+    expoOut?: string;
 }
 export interface TrinityOpacity {
     0: number;
@@ -259,6 +266,39 @@ export interface TrinityStatusSet {
     success: TrinityStatusColors;
     info: TrinityStatusColors;
 }
+/**
+ * The content color on a solid fill of each status role's `text` color (ADR-03-R7, C-OD-6 A):
+ * the label and icon color of a contained status button, a filled chip or a status badge.
+ *
+ * The Trinity theme maps `status.<x>.text` and `onStatus.<x>` to MUI's `palette.<x>.main` and
+ * `palette.<x>.contrastText`; the CSS package ships them as `--trinity-status-<x>-text` and
+ * `--trinity-on-status-<x>`.
+ *
+ * @since 2.13.0
+ */
+export interface TrinityOnStatusColors {
+    error: string;
+    warning: string;
+    success: string;
+    info: string;
+}
+/**
+ * The statuses of the StatusIndicator catalog (`semanticTokens.colors.indicator`).
+ *
+ * @since 2.13.0
+ */
+export type TrinityIndicatorStatus = 'error' | 'critical' | 'failed' | 'rejected' | 'warning' | 'caution' | 'pending' | 'inProgress' | 'running' | 'success' | 'complete' | 'approved' | 'active' | 'enabled' | 'info' | 'new' | 'updated' | 'neutral' | 'draft' | 'inactive' | 'disabled' | 'cancelled' | 'unknown' | 'beta' | 'experimental';
+/**
+ * One catalog entry: the text (`fg`) on the fill (`bg`), and for light fills an `outline` that
+ * keeps the fill visible on light surfaces.
+ *
+ * @since 2.13.0
+ */
+export interface TrinityIndicatorTokenColor {
+    fg: string;
+    bg: string;
+    outline?: string;
+}
 export interface TrinitySemanticColors {
     brand: TrinityBrandColors;
     text: TrinityTextColors;
@@ -266,6 +306,137 @@ export interface TrinitySemanticColors {
     border: TrinityBorderColors;
     interactive: TrinityInteractiveColors;
     status: TrinityStatusSet;
+    /**
+     * Content colors on a solid status fill (ADR-03-R7). Optional, so a token set written before
+     * 2.13.0 still compiles; the theme falls back to the defaults of the same mode.
+     *
+     * @since 2.13.0
+     */
+    onStatus?: TrinityOnStatusColors;
+    chart: TrinityChartColors;
+    /**
+     * AI color roles (ADR-03, ADR-03-R15). Optional, so a token set written before 2.13.0 still
+     * compiles; the theme falls back to the defaults.
+     *
+     * @since 2.13.0
+     */
+    ai?: TrinityAIColors;
+    /**
+     * The StatusIndicator catalog (E-43+). Optional, so a token set written before 2.13.0 still
+     * compiles; the theme falls back to the defaults. `palette.trinity.indicator` is built from it.
+     *
+     * @since 2.13.0
+     */
+    indicator?: Record<TrinityIndicatorStatus, TrinityIndicatorTokenColor>;
+    /**
+     * The favorite role (ADR-03-R10): the colour of a pinned or favorite mark, such as the filled
+     * star of a starred thread. It references `status.warning.text` (light #B45309, dark #FDE68A),
+     * so an override of that role reaches it unless `favorite` is overridden too, but it is its
+     * own role: its meaning does not change with the status roles. A state glyph, so it needs
+     * 3:1 on its surface (WCAG 1.4.11); the filled icon is the non-colour cue. Optional, so a
+     * token set written before 2.13.0 still compiles.
+     *
+     * @since 2.13.0
+     */
+    favorite?: string;
+}
+/**
+ * Decorative AI presence colors for the voice orb and the composer glow (ADR-03-R11).
+ *
+ * @since 2.13.0
+ */
+export interface TrinityAIPresenceColors {
+    blue: string;
+    violet: string;
+    purple: string;
+    coral: string;
+    base: string;
+}
+/**
+ * The twelve AI color roles (ADR-03, amended by ADR-03-R15), one set per mode.
+ *
+ * - `primary`: AI text and accent lines. Light references `brand.secondary`.
+ * - `primaryFill` and `onPrimaryFill`: a fill under white content, and that content.
+ * - `accent`: the warm AI accent. Light references `brand.accent`.
+ * - `surface`, `border`, `badgeBackground`: light tints derived from `brand.secondary`
+ *   (5%, 20% and 15%), recomputed when `brand.secondary` is overridden.
+ * - `surfaceHover`, `surfaceEmphasis`, `surfaceEmphasisHover`: hover and emphasis tints.
+ * - `typingIndicator`, `focusRing`.
+ *
+ * Three optional sub-groups sit beside them: the decorative `presence` colors, `avatarFill`,
+ * the AIAvatar's gradient stops, and `canvasFill`, the AI start screen's canvas wash.
+ *
+ * Read them in components through `getTrinityPalette(theme).ai` or `useTrinityPalette().ai`.
+ *
+ * @since 2.13.0
+ */
+export interface TrinityAIColors {
+    primary: string;
+    primaryFill: string;
+    onPrimaryFill: string;
+    accent: string;
+    surface: string;
+    surfaceHover: string;
+    surfaceEmphasis: string;
+    surfaceEmphasisHover: string;
+    border: string;
+    badgeBackground: string;
+    typingIndicator: string;
+    focusRing: string;
+    /** Decorative presence colors (ADR-03-R11). */
+    presence?: TrinityAIPresenceColors;
+    /**
+     * The AIAvatar's brand gradient stops, top (`start`) to bottom (`end`), under white content
+     * (`onPrimaryFill`); `gradient.avatar` is built from them. Coral 800 to purple 700 in both
+     * modes (owner decision 2026-10-08). The dark `accent` and `primaryFill` (coral 400, purple
+     * 600) would leave the white icon at 2.5-2.9:1, so the avatar has its own pair. Optional, so a
+     * token set without it falls back to the defaults of the same mode.
+     *
+     * @since 2.13.0
+     */
+    avatarFill?: {
+        start: string;
+        end: string;
+    };
+    /**
+     * The completed share of an AI progress graphic: the completed phase dots of AIChainOfThought's
+     * thought process and the fill of its insight confidence bar (owner mockups 2026-10-08). A
+     * graphic colour, 3:1 or more on the paper, the AI surface and the sunken surface of its mode
+     * (WCAG 1.4.11); never text. Optional, so a token set without it falls back to the default of
+     * the same mode.
+     *
+     * @since 2.13.0
+     */
+    progress?: string;
+    /**
+     * The AI start screen's canvas wash (AIChatWelcome, owner concepts 2026-10-08): a very soft
+     * lavender (`start`) and pink (`end`) that `gradient.canvas` lays over the paper toward the
+     * bottom right. Decorative only: text on it keeps 4.5:1 (light purple 50 and coral 50;
+     * dark 16% purple 700 and 10% coral 800 over the paper). Optional, so a token set without it
+     * falls back to the defaults of the same mode.
+     *
+     * @since 2.13.0
+     */
+    canvasFill?: {
+        start: string;
+        end: string;
+    };
+}
+/**
+ * Chart color roles (categorical, sequential, diverging, grid, axis).
+ *
+ * @since 2.13.0
+ */
+export interface TrinityChartColors {
+    categorical: Record<1 | 2 | 3 | 4 | 5 | 6 | 7 | 8, string>;
+    sequential: Record<1 | 2 | 3 | 4 | 5 | 6, string>;
+    diverging: {
+        negative: string;
+        neutral: string;
+        positive: string;
+    };
+    grid: string;
+    axis: string;
 }
 export interface TrinityTypographyStyle {
     fontSize: string;
@@ -312,6 +483,21 @@ export interface TrinityComponentSpacing {
     gapMd: number;
     gapLg: number;
 }
+/**
+ * Container widths in px for container queries on narrow hosts (E-19, ADR-11 §5): a panel
+ * 320px wide inside a desktop viewport. JavaScript-only, with no CSS custom property, because
+ * a custom property cannot be an `@container` operand (H-08); components read them through
+ * the internal container-query helpers.
+ * @since 2.13.0
+ */
+export interface TrinityContainerQuerySizes {
+    /** The narrowest supported container (320px): everything must work, nothing may scroll sideways. */
+    narrow: number;
+    /** Below this width (360px) footers and toolbars wrap or collapse. */
+    compact: number;
+    /** From this width (600px) a component may use its full desktop layout. */
+    regular: number;
+}
 export interface TrinityLayoutSpacing {
     pagePadding: number;
     sectionGap: number;
@@ -328,6 +514,12 @@ export interface TrinityLayoutSpacing {
     gutter: number;
     /** Content area padding (64px) */
     contentPadding: number;
+    /**
+     * Container widths for container queries (E-19). JavaScript-only: no CSS variable.
+     * Optional, so token sets written before 2.13.0 still compile (E-32).
+     * @since 2.13.0
+     */
+    containerQuery?: TrinityContainerQuerySizes;
 }
 export interface TrinitySemanticSpacing {
     component: TrinityComponentSpacing;
@@ -363,15 +555,67 @@ export interface TrinitySemanticMotionDuration {
     fast: string;
     normal: string;
     slow: string;
+    /**
+     * Long entrances and expansions (400ms), such as an AI panel or a reasoning step opening.
+     * @since 2.13.0
+     */
+    slower?: string;
 }
 export interface TrinitySemanticMotionEasing {
     default: string;
     enter: string;
     exit: string;
+    /**
+     * Emphasized entrance: a fast start that settles softly (`baseTokens.easing.expoOut`).
+     * @since 2.13.0
+     */
+    emphasized?: string;
+    /**
+     * A slight overshoot for playful confirmations (`baseTokens.easing.bounce`). Not for
+     * content that must stay readable while it moves.
+     * @since 2.13.0
+     */
+    overshoot?: string;
+}
+/**
+ * Durations of one cycle of a looping animation. Loops stop under reduced motion with their
+ * state still visible (docs/TOKEN_USAGE_RULES.md, "Motion").
+ * @since 2.13.0
+ */
+export interface TrinitySemanticMotionLoop {
+    /** One turn of a spinner (800ms). */
+    spin: string;
+    /** One cycle of a typing or streaming indicator (1200ms). */
+    typing: string;
+    /** One sweep of a loading shimmer (1500ms). */
+    shimmer: string;
+    /** One cycle of a pulse or breathing indicator (2000ms). */
+    pulse: string;
+}
+/**
+ * Delays between the items of a staggered entrance.
+ * @since 2.13.0
+ */
+export interface TrinitySemanticMotionStagger {
+    /** Dense lists and chips (50ms). */
+    tight: string;
+    /** Cards and list rows (100ms). */
+    normal: string;
 }
 export interface TrinitySemanticMotion {
     duration: TrinitySemanticMotionDuration;
     easing: TrinitySemanticMotionEasing;
+    /**
+     * Looping animation cycles (E-13). Optional, so token sets written before 2.13.0 still
+     * compile (E-32).
+     * @since 2.13.0
+     */
+    loop?: TrinitySemanticMotionLoop;
+    /**
+     * Staggered entrance delays (E-13). Optional, as `loop`.
+     * @since 2.13.0
+     */
+    stagger?: TrinitySemanticMotionStagger;
 }
 /** Overlay effects for interaction states and backdrops */
 export interface TrinityOverlayEffects {
@@ -615,9 +859,25 @@ export interface TrinityPadding {
 export interface TrinityButtonColors {
     background: string;
     backgroundHover: string;
+    /** Optional for compatibility with consumer-authored token sets. */
+    backgroundActive?: string;
     text: string;
     border?: string;
     textHover?: string;
+    /** Optional for compatibility with consumer-authored token sets. */
+    textActive?: string;
+    /** Border on hover, where it differs from the resting border. @since 2.13.0 */
+    borderHover?: string;
+    /** Border while pressed, where it differs from the resting border. @since 2.13.0 */
+    borderActive?: string;
+    /** Fill of a disabled or pending button, where the family has its own. @since 2.13.0 */
+    backgroundDisabled?: string;
+    /** Label of a disabled or pending button, where the family has its own. @since 2.13.0 */
+    textDisabled?: string;
+    /** Border of a disabled or pending button, where the family has its own. @since 2.13.0 */
+    borderDisabled?: string;
+    /** Keyboard focus outline colour, where the family has its own. @since 2.13.0 */
+    focusOutline?: string;
 }
 export interface TrinityButtonTokens {
     height: TrinityComponentSize<number>;
@@ -627,6 +887,18 @@ export interface TrinityButtonTokens {
     primary: TrinityButtonColors;
     secondary: TrinityButtonColors;
     outlined: TrinityButtonColors;
+    /**
+     * The filled button for navy brand surfaces (hero, header, sidebar): white fill, navy label,
+     * coral on hover. The same in light and dark mode, because the navy chrome does not change
+     * with the mode. React: `<Button variant="contained" color="onBrand">`. @since 2.13.0
+     */
+    onBrand?: TrinityButtonColors;
+    /**
+     * The outlined button for navy brand surfaces: white border and label, coral on hover. The
+     * same in light and dark mode. React: `<Button variant="outlined" color="onBrand">`.
+     * @since 2.13.0
+     */
+    onBrandOutlined?: TrinityButtonColors;
 }
 export interface TrinityInputBorderColors {
     default: string;
@@ -714,6 +986,7 @@ export interface TrinityModalTokens {
     padding: number;
     borderRadius: number;
     shadow: string;
+    background?: string;
     backdropOpacity: number;
     width: TrinityModalWidth;
 }
@@ -724,6 +997,11 @@ export interface TrinitySwitchSize {
 export interface TrinitySwitchTrack {
     off: string;
     on: string;
+    /**
+     * The 2px track outline (light gray 300, dark gray 500). Optional so token sets written for
+     * earlier versions stay valid; the theme falls back to the same grays. @since 2.13.0
+     */
+    border?: string;
 }
 export interface TrinitySwitchTokens {
     width: TrinitySwitchSize;
@@ -788,16 +1066,46 @@ export interface TrinityDarkModeTextColors {
     secondary: string;
     tertiary: string;
     disabled: string;
+    /** Text on a light inverse surface while the surrounding application is dark. */
+    inverse?: string;
+    brand?: string;
+    link?: string;
+    linkHover?: string;
+    error?: string;
+    success?: string;
+    warning?: string;
 }
 export interface TrinityDarkModeBackgroundColors {
     primary: string;
     secondary: string;
     tertiary: string;
+    inverse?: string;
+    brandSubtle?: string;
+    accentSubtle?: string;
 }
 export interface TrinityDarkModeBorderColors {
     default: string;
     subtle: string;
     strong: string;
+    focus?: string;
+    error?: string;
+    success?: string;
+}
+/**
+ * Dark-mode surface colors (elevated, sunken, overlay and status surfaces).
+ *
+ * @since 2.13.0
+ */
+export interface TrinityDarkModeSurfaceColors {
+    elevated: string;
+    sunken: string;
+    /** A neutral fill under an icon (ADR-03-R9). @since 2.13.0 */
+    neutralFill?: string;
+    overlay: string;
+    success: string;
+    error: string;
+    warning: string;
+    info: string;
 }
 export interface TrinityDarkModeColors {
     text: TrinityDarkModeTextColors;
@@ -816,9 +1124,128 @@ export interface TrinityDarkModeColors {
         success: TrinityStatusColors;
         info: TrinityStatusColors;
     };
+    /**
+     * Dark content colors on a solid status fill (ADR-03-R7). Optional, so a token set written
+     * before 2.13.0 still compiles.
+     *
+     * @since 2.13.0
+     */
+    onStatus?: TrinityOnStatusColors;
+    /**
+     * The dark favorite role (ADR-03-R10): references the dark `status.warning.text` (#FDE68A).
+     * Optional, so a token set written before 2.13.0 still compiles.
+     *
+     * @since 2.13.0
+     */
+    favorite?: string;
+    indicator?: {
+        inProgress?: Partial<{
+            fg: string;
+            bg: string;
+            outline: string;
+        }>;
+        running?: Partial<{
+            fg: string;
+            bg: string;
+            outline: string;
+        }>;
+        /** @since 2.13.0 The dark info-family fill (ADR-03-R8). */
+        info?: Partial<{
+            fg: string;
+            bg: string;
+            outline: string;
+        }>;
+        /** @since 2.13.0 */
+        new?: Partial<{
+            fg: string;
+            bg: string;
+            outline: string;
+        }>;
+        /** @since 2.13.0 */
+        updated?: Partial<{
+            fg: string;
+            bg: string;
+            outline: string;
+        }>;
+    };
+    chart?: Pick<TrinityChartColors, 'grid' | 'axis'>;
+    /**
+     * Dark AI color roles (ADR-03-R15). Optional, so a token set written before 2.13.0 still
+     * compiles.
+     *
+     * @since 2.13.0
+     */
+    ai?: TrinityAIColors;
+    surface?: TrinityDarkModeSurfaceColors;
+    /**
+     * The avatar text pairs in dark mode (ADR-03-R9): the same as light, because the avatar fills
+     * do not change with the mode. @since 2.13.0
+     */
+    avatar?: {
+        foregrounds?: readonly string[];
+    };
+    focus?: {
+        ring: string;
+        ringOffset: string;
+    };
+    selection?: {
+        background: string;
+        text: string;
+    };
+    switch?: {
+        track: Partial<{
+            off: string;
+            on: string;
+            border: string;
+        }>;
+    };
+    button?: {
+        primary?: Partial<{
+            background: string;
+        }>;
+        secondary?: Partial<{
+            background: string;
+        }>;
+        outlined?: Partial<{
+            border: string;
+            text: string;
+        }>;
+    };
+}
+/**
+ * Dark-mode shadow tokens: the shadow scale, semantic shadows and glows.
+ *
+ * @since 2.13.0
+ */
+export interface TrinityDarkModeShadowTokens {
+    scale: TrinityShadows;
+    semantic: TrinitySemanticShadows;
+    glow: {
+        primary: string;
+        accent: string;
+        info: string;
+    };
+}
+/**
+ * Dark-mode effect tokens: overlays, shadow effects, the focus ring and glow, and state layers.
+ *
+ * `focus.ring` is a box-shadow, like the light `semantic.effects.focus.ring`: the static
+ * stylesheet declares both as `--trinity-focus-ring`, which consumers write into `box-shadow`.
+ *
+ * @since 2.13.0
+ */
+export interface TrinityDarkModeEffectTokens {
+    overlay: TrinityOverlayEffects;
+    shadow: TrinityShadowEffects;
+    focus: Pick<TrinityFocusEffects, 'ring' | 'glow'>;
+    state: TrinityStateEffects;
 }
 export interface TrinityDarkModeTokens {
     colors: TrinityDarkModeColors;
+    /** Optional so consumer-authored legacy token sets remain source-compatible. */
+    shadows?: TrinityDarkModeShadowTokens;
+    /** Optional so consumer-authored legacy token sets remain source-compatible. */
+    effects?: TrinityDarkModeEffectTokens;
 }
 export interface TrinityTokens {
     base: TrinityBaseTokens;
@@ -1042,6 +1469,7 @@ export declare const baseTokens: {
         smooth: string;
         bounce: string;
         elastic: string;
+        expoOut: string;
     };
     opacity: {
         0: number;
@@ -1102,6 +1530,7 @@ export declare const semanticTokens: {
         surface: {
             elevated: string;
             sunken: string;
+            neutralFill: string;
             overlay: string;
             success: string;
             error: string;
@@ -1153,6 +1582,13 @@ export declare const semanticTokens: {
                 border: string;
             };
         };
+        onStatus: {
+            error: string;
+            warning: string;
+            success: string;
+            info: string;
+        };
+        favorite: string;
         /**
          * Status Indicator Colors
          * Semantic colors for StatusIndicator components (dots, badges, chips)
@@ -1264,8 +1700,91 @@ export declare const semanticTokens: {
                 bg: string;
             };
         };
+        chart: {
+            categorical: {
+                1: string;
+                2: string;
+                3: string;
+                4: string;
+                5: string;
+                6: string;
+                7: string;
+                8: string;
+            };
+            sequential: {
+                1: string;
+                2: string;
+                3: string;
+                4: string;
+                5: string;
+                6: string;
+            };
+            diverging: {
+                negative: string;
+                neutral: string;
+                positive: string;
+            };
+            grid: string;
+            axis: string;
+        };
+        ai: {
+            primary: string;
+            primaryFill: string;
+            onPrimaryFill: string;
+            accent: string;
+            surface: string;
+            surfaceHover: string;
+            surfaceEmphasis: string;
+            surfaceEmphasisHover: string;
+            border: string;
+            badgeBackground: string;
+            typingIndicator: string;
+            focusRing: string;
+            presence: {
+                blue: string;
+                violet: string;
+                purple: string;
+                coral: string;
+                base: string;
+            };
+            avatarFill: {
+                start: string;
+                end: string;
+            };
+            progress: string;
+            canvasFill: {
+                start: string;
+                end: string;
+            };
+        };
         avatar: {
+            /**
+             * Solid avatar fills. Not every entry carries white text: render the initials or icon in
+             * the aligned `foregrounds` entry (ADR-03-R9, E-49+). Measured with WCAG relative luminance,
+             * the same in light and dark mode:
+             *
+             * | # | Fill | White | gray[900] | Text |
+             * |---|---|---|---|---|
+             * | 0 | indigo[600] #5F33EB | 6.64:1 | 2.99:1 | white |
+             * | 1 | purple[600] #8D49CE | 5.28:1 | 3.76:1 | white |
+             * | 2 | coral[600] #FF7167 | 2.68:1 | 7.39:1 | gray[900] |
+             * | 3 | azure[600] #239DDD | 3.02:1 | 6.57:1 | gray[900] |
+             * | 4 | navy[700] #30316E | 11.73:1 | 1.69:1 | white |
+             * | 5 | indigo[500] #6739ED | 6.20:1 | 3.20:1 | white |
+             * | 6 | purple[500] #9950D3 | 4.72:1 | 4.20:1 | white |
+             * | 7 | coral[500] #FF796F | 2.55:1 | 7.78:1 | gray[900] |
+             *
+             * The values are unchanged (a token value change is major). A later value change for the
+             * three light fills is a v3.0 candidate.
+             */
             backgrounds: string[];
+            /**
+             * The text or icon colour for each `backgrounds` entry, index for index (ADR-03-R9): every
+             * pair is 4.72:1 or more. Pick a pair by one index, never a background alone.
+             *
+             * @since 2.13.0
+             */
+            foregrounds: readonly string[];
             online: string;
             offline: string;
             busy: string;
@@ -1428,6 +1947,11 @@ export declare const semanticTokens: {
             aiPanelWidth: number;
             gutter: number;
             contentPadding: number;
+            containerQuery: {
+                narrow: number;
+                compact: number;
+                regular: number;
+            };
         };
     };
     borders: {
@@ -1513,11 +2037,24 @@ export declare const semanticTokens: {
             fast: string;
             normal: string;
             slow: string;
+            slower: string;
         };
         easing: {
             default: string;
             enter: string;
             exit: string;
+            emphasized: string;
+            overshoot: string;
+        };
+        loop: {
+            spin: string;
+            typing: string;
+            shimmer: string;
+            pulse: string;
+        };
+        stagger: {
+            tight: string;
+            normal: string;
         };
     };
     effects: {
@@ -1685,11 +2222,13 @@ export declare const semanticTokens: {
     };
 };
 /**
- * Canonical brand colors derived from baseTokens.
+ * Canonical brand colors derived from baseTokens: the single source of brand constants.
  *
- * This provides API compatibility with the legacy `brandColors` export from theme.ts.
- * Components should migrate from `import { brandColors } from '../theme'`
- * to `import { brandColors } from '../tokens'`.
+ * theme.ts exports a view of this object with the legacy shape (the package root and
+ * essentials export that view), so both always hold the same values. Components should
+ * migrate from `import { brandColors } from '../theme'` to `import { brandColors } from '../tokens'`.
+ * These are read-only constants: to rebrand, pass token overrides to createTrinityTheme or
+ * createTrinityThemePreset.
  *
  * MAPPING TABLE:
  * ┌─────────────────────────┬───────────┬──────────────────────────────┐
@@ -1713,6 +2252,9 @@ export declare const semanticTokens: {
  *
  * NOTE: neutral.gray100 naming is misleading - it's actually gray[200] (#E5E7EB).
  * This is preserved for backwards compatibility with theme.ts.
+ *
+ * neutral.darkBg and neutral.darkPaper are deprecated: they are not the dark theme's surfaces
+ * (darkModeTokens.colors.background.primary and .secondary are).
  */
 export declare const brandColors: {
     readonly primary: {
@@ -1738,7 +2280,15 @@ export declare const brandColors: {
         readonly gray700: string;
         readonly gray800: string;
         readonly gray900: string;
+        /**
+         * @deprecated Not the dark theme's page colour. Use `theme.palette.background.default`
+         * (or `palette.trinity.surface`). Removed in v3.0.
+         */
         readonly darkBg: string;
+        /**
+         * @deprecated Not the dark theme's paper colour. Use `theme.palette.background.paper`
+         * (or `palette.trinity.surface.elevated`). Removed in v3.0.
+         */
         readonly darkPaper: string;
     };
 };
@@ -1776,19 +2326,53 @@ export declare const componentTokens: {
         primary: {
             background: string;
             backgroundHover: string;
+            backgroundActive: string;
             text: string;
+            textHover: string;
+            textActive: string;
         };
         secondary: {
             background: string;
             backgroundHover: string;
+            backgroundActive: string;
             text: string;
+            textHover: string;
+            textActive: string;
         };
         outlined: {
             background: string;
             backgroundHover: string;
+            backgroundActive: string;
+            border: string;
+            text: string;
+            textHover: string;
+            textActive: string;
+        };
+        onBrand: {
+            background: string;
+            backgroundHover: string;
+            backgroundActive: string;
+            text: string;
+            textHover: string;
+            textActive: string;
+            backgroundDisabled: string;
+            textDisabled: string;
+            focusOutline: string;
+        };
+        onBrandOutlined: {
+            background: string;
+            backgroundHover: string;
+            backgroundActive: string;
             border: string;
+            borderHover: string;
+            borderActive: string;
             text: string;
             textHover: string;
+            textActive: string;
+            backgroundDisabled: string;
+            textDisabled: string;
+            borderDisabled: string;
+            focusOutline: string;
         };
     };
     input: {
@@ -1902,6 +2486,7 @@ export declare const componentTokens: {
         padding: number;
         borderRadius: number;
         shadow: string;
+        background: string;
         backdropOpacity: number;
         width: {
             small: number;
@@ -1926,6 +2511,7 @@ export declare const componentTokens: {
         track: {
             off: string;
             on: string;
+            border: string;
         };
     };
     navigation: {
@@ -2276,6 +2862,13 @@ export declare const scaleHierarchy: {
         readonly minimum: 44;
         readonly comfortable: 48;
         readonly spacious: 56;
+        /**
+         * The program-wide floor for every pointer target: 24 by 24 CSS pixels, WCAG 2.2 SC 2.5.8
+         * Target Size (Minimum, AA), ratified by DN-12 (2026-10-05). Compact controls reach it
+         * through the shared hit-area recipe (C-40+), which grows the hit area to this size
+         * without changing the visual size. CSS: `--trinity-touch-target-floor`.
+         */
+        readonly floor: 24;
     };
 };
 /**
@@ -2380,7 +2973,7 @@ export declare const spacingHierarchy: {
  */
 /** Get elevation styles for a given level */
 export declare function getElevation(level: keyof typeof elevationHierarchy): {
-    zIndex: 0 | 10 | 1 | 1000 | 1020 | 1040 | 1050 | 1060 | 1070;
+    zIndex: 0 | 1 | 1000 | 10 | 1020 | 1040 | 1050 | 1060 | 1070;
     boxShadow: "none" | "0 1px 2px 0 rgb(0 0 0 / 0.05)" | "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)" | "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)" | "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)" | "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)";
 };
 /** Get typography styles for a given hierarchy */
@@ -2391,19 +2984,26 @@ export declare function getAttentionColor(level: keyof typeof attentionHierarchy
 export declare function getHierarchySpacing(category: 'micro' | 'component' | 'section' | 'layout', size: number): number;
 export declare const darkModeTokens: TrinityDarkModeTokens;
 export declare const darkModeShadows: {
-    none: string;
-    sm: string;
-    base: string;
-    md: string;
-    lg: string;
-    xl: string;
-    '2xl': string;
-    glow: {
+    readonly glow: {
         primary: string;
         accent: string;
         info: string;
     };
+    readonly none: string;
+    readonly sm: string;
+    readonly base: string;
+    readonly md: string;
+    readonly lg: string;
+    readonly xl: string;
+    readonly '2xl': string;
+    readonly inner: string;
 };
+/**
+ * Dark-mode effect tokens (overlays, shadows, focus glow, state layers).
+ *
+ * @since 2.13.0
+ */
+export declare const darkModeEffects: TrinityDarkModeEffectTokens;
 export interface BrandVariant {
     name: string;
     primary: {
@@ -2464,6 +3064,7 @@ export declare function getBrandSemanticTokens(variant: keyof typeof brandVarian
         surface: {
             elevated: string;
             sunken: string;
+            neutralFill: string;
             overlay: string;
             success: string;
             error: string;
@@ -2515,6 +3116,13 @@ export declare function getBrandSemanticTokens(variant: keyof typeof brandVarian
                 border: string;
             };
         };
+        onStatus: {
+            error: string;
+            warning: string;
+            success: string;
+            info: string;
+        };
+        favorite: string;
         /**
          * Status Indicator Colors
          * Semantic colors for StatusIndicator components (dots, badges, chips)
@@ -2626,8 +3234,91 @@ export declare function getBrandSemanticTokens(variant: keyof typeof brandVarian
                 bg: string;
             };
         };
+        chart: {
+            categorical: {
+                1: string;
+                2: string;
+                3: string;
+                4: string;
+                5: string;
+                6: string;
+                7: string;
+                8: string;
+            };
+            sequential: {
+                1: string;
+                2: string;
+                3: string;
+                4: string;
+                5: string;
+                6: string;
+            };
+            diverging: {
+                negative: string;
+                neutral: string;
+                positive: string;
+            };
+            grid: string;
+            axis: string;
+        };
+        ai: {
+            primary: string;
+            primaryFill: string;
+            onPrimaryFill: string;
+            accent: string;
+            surface: string;
+            surfaceHover: string;
+            surfaceEmphasis: string;
+            surfaceEmphasisHover: string;
+            border: string;
+            badgeBackground: string;
+            typingIndicator: string;
+            focusRing: string;
+            presence: {
+                blue: string;
+                violet: string;
+                purple: string;
+                coral: string;
+                base: string;
+            };
+            avatarFill: {
+                start: string;
+                end: string;
+            };
+            progress: string;
+            canvasFill: {
+                start: string;
+                end: string;
+            };
+        };
         avatar: {
+            /**
+             * Solid avatar fills. Not every entry carries white text: render the initials or icon in
+             * the aligned `foregrounds` entry (ADR-03-R9, E-49+). Measured with WCAG relative luminance,
+             * the same in light and dark mode:
+             *
+             * | # | Fill | White | gray[900] | Text |
+             * |---|---|---|---|---|
+             * | 0 | indigo[600] #5F33EB | 6.64:1 | 2.99:1 | white |
+             * | 1 | purple[600] #8D49CE | 5.28:1 | 3.76:1 | white |
+             * | 2 | coral[600] #FF7167 | 2.68:1 | 7.39:1 | gray[900] |
+             * | 3 | azure[600] #239DDD | 3.02:1 | 6.57:1 | gray[900] |
+             * | 4 | navy[700] #30316E | 11.73:1 | 1.69:1 | white |
+             * | 5 | indigo[500] #6739ED | 6.20:1 | 3.20:1 | white |
+             * | 6 | purple[500] #9950D3 | 4.72:1 | 4.20:1 | white |
+             * | 7 | coral[500] #FF796F | 2.55:1 | 7.78:1 | gray[900] |
+             *
+             * The values are unchanged (a token value change is major). A later value change for the
+             * three light fills is a v3.0 candidate.
+             */
             backgrounds: string[];
+            /**
+             * The text or icon colour for each `backgrounds` entry, index for index (ADR-03-R9): every
+             * pair is 4.72:1 or more. Pick a pair by one index, never a background alone.
+             *
+             * @since 2.13.0
+             */
+            foregrounds: readonly string[];
             online: string;
             offline: string;
             busy: string;
@@ -2790,6 +3481,11 @@ export declare function getBrandSemanticTokens(variant: keyof typeof brandVarian
             aiPanelWidth: number;
             gutter: number;
             contentPadding: number;
+            containerQuery: {
+                narrow: number;
+                compact: number;
+                regular: number;
+            };
         };
     };
     borders: {
@@ -2875,11 +3571,24 @@ export declare function getBrandSemanticTokens(variant: keyof typeof brandVarian
             fast: string;
             normal: string;
             slow: string;
+            slower: string;
         };
         easing: {
             default: string;
             enter: string;
             exit: string;
+            emphasized: string;
+            overshoot: string;
+        };
+        loop: {
+            spin: string;
+            typing: string;
+            shimmer: string;
+            pulse: string;
+        };
+        stagger: {
+            tight: string;
+            normal: string;
         };
     };
     effects: {
@@ -3308,6 +4017,13 @@ export declare const hierarchy: {
             readonly minimum: 44;
             readonly comfortable: 48;
             readonly spacious: 56;
+            /**
+             * The program-wide floor for every pointer target: 24 by 24 CSS pixels, WCAG 2.2 SC 2.5.8
+             * Target Size (Minimum, AA), ratified by DN-12 (2026-10-05). Compact controls reach it
+             * through the shared hit-area recipe (C-40+), which grows the hit area to this size
+             * without changing the visual size. CSS: `--trinity-touch-target-floor`.
+             */
+            readonly floor: 24;
         };
     };
     /** Contrast levels */
@@ -3616,6 +4332,7 @@ export declare const tokens: {
             smooth: string;
             bounce: string;
             elastic: string;
+            expoOut: string;
         };
         opacity: {
             0: number;
@@ -3676,6 +4393,7 @@ export declare const tokens: {
             surface: {
                 elevated: string;
                 sunken: string;
+                neutralFill: string;
                 overlay: string;
                 success: string;
                 error: string;
@@ -3727,6 +4445,13 @@ export declare const tokens: {
                     border: string;
                 };
             };
+            onStatus: {
+                error: string;
+                warning: string;
+                success: string;
+                info: string;
+            };
+            favorite: string;
             /**
              * Status Indicator Colors
              * Semantic colors for StatusIndicator components (dots, badges, chips)
@@ -3838,8 +4563,91 @@ export declare const tokens: {
                     bg: string;
                 };
             };
+            chart: {
+                categorical: {
+                    1: string;
+                    2: string;
+                    3: string;
+                    4: string;
+                    5: string;
+                    6: string;
+                    7: string;
+                    8: string;
+                };
+                sequential: {
+                    1: string;
+                    2: string;
+                    3: string;
+                    4: string;
+                    5: string;
+                    6: string;
+                };
+                diverging: {
+                    negative: string;
+                    neutral: string;
+                    positive: string;
+                };
+                grid: string;
+                axis: string;
+            };
+            ai: {
+                primary: string;
+                primaryFill: string;
+                onPrimaryFill: string;
+                accent: string;
+                surface: string;
+                surfaceHover: string;
+                surfaceEmphasis: string;
+                surfaceEmphasisHover: string;
+                border: string;
+                badgeBackground: string;
+                typingIndicator: string;
+                focusRing: string;
+                presence: {
+                    blue: string;
+                    violet: string;
+                    purple: string;
+                    coral: string;
+                    base: string;
+                };
+                avatarFill: {
+                    start: string;
+                    end: string;
+                };
+                progress: string;
+                canvasFill: {
+                    start: string;
+                    end: string;
+                };
+            };
             avatar: {
+                /**
+                 * Solid avatar fills. Not every entry carries white text: render the initials or icon in
+                 * the aligned `foregrounds` entry (ADR-03-R9, E-49+). Measured with WCAG relative luminance,
+                 * the same in light and dark mode:
+                 *
+                 * | # | Fill | White | gray[900] | Text |
+                 * |---|---|---|---|---|
+                 * | 0 | indigo[600] #5F33EB | 6.64:1 | 2.99:1 | white |
+                 * | 1 | purple[600] #8D49CE | 5.28:1 | 3.76:1 | white |
+                 * | 2 | coral[600] #FF7167 | 2.68:1 | 7.39:1 | gray[900] |
+                 * | 3 | azure[600] #239DDD | 3.02:1 | 6.57:1 | gray[900] |
+                 * | 4 | navy[700] #30316E | 11.73:1 | 1.69:1 | white |
+                 * | 5 | indigo[500] #6739ED | 6.20:1 | 3.20:1 | white |
+                 * | 6 | purple[500] #9950D3 | 4.72:1 | 4.20:1 | white |
+                 * | 7 | coral[500] #FF796F | 2.55:1 | 7.78:1 | gray[900] |
+                 *
+                 * The values are unchanged (a token value change is major). A later value change for the
+                 * three light fills is a v3.0 candidate.
+                 */
                 backgrounds: string[];
+                /**
+                 * The text or icon colour for each `backgrounds` entry, index for index (ADR-03-R9): every
+                 * pair is 4.72:1 or more. Pick a pair by one index, never a background alone.
+                 *
+                 * @since 2.13.0
+                 */
+                foregrounds: readonly string[];
                 online: string;
                 offline: string;
                 busy: string;
@@ -4002,6 +4810,11 @@ export declare const tokens: {
                 aiPanelWidth: number;
                 gutter: number;
                 contentPadding: number;
+                containerQuery: {
+                    narrow: number;
+                    compact: number;
+                    regular: number;
+                };
             };
         };
         borders: {
@@ -4087,11 +4900,24 @@ export declare const tokens: {
                 fast: string;
                 normal: string;
                 slow: string;
+                slower: string;
             };
             easing: {
                 default: string;
                 enter: string;
                 exit: string;
+                emphasized: string;
+                overshoot: string;
+            };
+            loop: {
+                spin: string;
+                typing: string;
+                shimmer: string;
+                pulse: string;
+            };
+            stagger: {
+                tight: string;
+                normal: string;
             };
         };
         effects: {
@@ -4288,19 +5114,53 @@ export declare const tokens: {
             primary: {
                 background: string;
                 backgroundHover: string;
+                backgroundActive: string;
                 text: string;
+                textHover: string;
+                textActive: string;
             };
             secondary: {
                 background: string;
                 backgroundHover: string;
+                backgroundActive: string;
                 text: string;
+                textHover: string;
+                textActive: string;
             };
             outlined: {
                 background: string;
                 backgroundHover: string;
+                backgroundActive: string;
+                border: string;
+                text: string;
+                textHover: string;
+                textActive: string;
+            };
+            onBrand: {
+                background: string;
+                backgroundHover: string;
+                backgroundActive: string;
+                text: string;
+                textHover: string;
+                textActive: string;
+                backgroundDisabled: string;
+                textDisabled: string;
+                focusOutline: string;
+            };
+            onBrandOutlined: {
+                background: string;
+                backgroundHover: string;
+                backgroundActive: string;
                 border: string;
+                borderHover: string;
+                borderActive: string;
                 text: string;
                 textHover: string;
+                textActive: string;
+                backgroundDisabled: string;
+                textDisabled: string;
+                borderDisabled: string;
+                focusOutline: string;
             };
         };
         input: {
@@ -4414,6 +5274,7 @@ export declare const tokens: {
             padding: number;
             borderRadius: number;
             shadow: string;
+            background: string;
             backdropOpacity: number;
             width: {
                 small: number;
@@ -4438,6 +5299,7 @@ export declare const tokens: {
             track: {
                 off: string;
                 on: string;
+                border: string;
             };
         };
         navigation: {
@@ -4739,6 +5601,13 @@ export declare const tokens: {
                 readonly minimum: 44;
                 readonly comfortable: 48;
                 readonly spacious: 56;
+                /**
+                 * The program-wide floor for every pointer target: 24 by 24 CSS pixels, WCAG 2.2 SC 2.5.8
+                 * Target Size (Minimum, AA), ratified by DN-12 (2026-10-05). Compact controls reach it
+                 * through the shared hit-area recipe (C-40+), which grows the hit area to this size
+                 * without changing the visual size. CSS: `--trinity-touch-target-floor`.
+                 */
+                readonly floor: 24;
             };
         };
         /** Contrast levels */