@ttoss/fsl-theme 1.1.12 → 1.1.14

package/dist/{esm/chunk-SE5Z52RE.js → createTheme-BLNYztZU.mjs}

@@ -1,14 +1,15 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { __name, deepMerge, validateRefs } from "./chunk-WVQSTQD5.js";
+import { c as validateRefs, r as deepMerge } from "./helpers-CaswNJMy.mjs";
 
-// src/baseTheme.ts
-var baseTheme = {
-  // ==========================================================================
-  // CORE TOKENS — raw primitives and responsive engines
-  // ==========================================================================
+//#region src/baseTheme.ts
+/**
+* **Foundation** — Neutral baseline theme.
+*
+* System fonts, gray palette, and balanced proportions. Serves as the
+* canonical base that all other themes extend via `createTheme`.
+*/
+const baseTheme = {
   core: {
-    // -- Colors -------------------------------------------------------------
-    // Core colors are intent-free primitives. Scale positions only.
     colors: {
       brand: {
         50: "#eff6ff",
@@ -84,7 +85,6 @@ var baseTheme = {
         900: "#831843"
       }
     },
-    // -- Elevation ----------------------------------------------------------
     elevation: {
       level: {
         0: "none",
@@ -93,7 +93,6 @@ var baseTheme = {
         3: "0 8px 16px rgba(0,0,0,0.10), 0 4px 8px rgba(0,0,0,0.08)",
         4: "0 16px 32px rgba(0,0,0,0.14), 0 8px 16px rgba(0,0,0,0.10)"
       },
-      // High-opacity recipes — stronger depth contrast for dark or heavily-colored surfaces
       emphatic: {
         0: "none",
         1: "0 1px 2px rgba(0,0,0,0.20), 0 1px 1px rgba(0,0,0,0.14)",
@@ -102,12 +101,11 @@ var baseTheme = {
         4: "0 16px 32px rgba(0,0,0,0.34), 0 8px 16px rgba(0,0,0,0.28)"
       }
     },
-    // -- Font Primitives ----------------------------------------------------
     font: {
       family: {
-        sans: 'ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial, "Apple Color Emoji", "Segoe UI Emoji"',
-        serif: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
-        mono: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace'
+        sans: "ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial, \"Apple Color Emoji\", \"Segoe UI Emoji\"",
+        serif: "ui-serif, Georgia, Cambria, \"Times New Roman\", Times, serif",
+        mono: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", \"Courier New\", monospace"
       },
       weight: {
         regular: 400,
@@ -139,7 +137,6 @@ var baseTheme = {
         ordinal: "ordinal",
         normal: "normal"
       },
-      // -- Font Size Scale (Responsive Engine) --------------------------------
       scale: {
         text: {
           1: "clamp(12px, calc(0.6cqi + 10px), 14px)",
@@ -159,23 +156,6 @@ var baseTheme = {
         }
       }
     },
-    // -- Spacing (Responsive Engine) ----------------------------------------
-    // Tuned for medium-high density (mouse-first). The engine caps at 6px
-    // — above that, button paddings compound with hit floors and produce
-    // visually heavy controls (>48px desktop) that fight modern UI rhythm
-    // (Material 40px, GitHub 32–40px, Bootstrap 38px). Touch density is
-    // restored automatically via `@media (any-pointer: coarse)` overrides.
-    //
-    // CSS-coupled tokens (registered in model.md §8 → "CSS-coupled core
-    // tokens"):
-    //   • `engine.unit` — fluid primitive (`clamp()` + `cqi`); viewport
-    //     fallback emitted by `toCssVars`.
-    //   • steps 1..16 — cascade-preserving aliases that reference
-    //     `--tt-core-spacing-engine-unit` directly so the engine stays a
-    //     single point of override. Replacing `var()` with a token ref
-    //     would inline `clamp(...cqi...)` into every step and inflate the
-    //     `@supports (width: 1cqi)` block. Non-CSS consumers receive the
-    //     unresolved expression — see model.md §8.
     spacing: {
       engine: {
         unit: "clamp(4px, 0.25cqi + 3px, 6px)"
@@ -190,7 +170,6 @@ var baseTheme = {
       12: "calc(12 * var(--tt-core-spacing-engine-unit))",
       16: "calc(16 * var(--tt-core-spacing-engine-unit))"
     },
-    // -- Sizing (Responsive Engine) -----------------------------------------
     sizing: {
       ramp: {
         ui: {
@@ -232,20 +211,11 @@ var baseTheme = {
         }
       },
       hit: {
-        // Fine: clamp(floor, preferred, max) — floor is the fixed ergonomic
-        // minimum; preferred scales with rem so user font-size preferences
-        // (accessibility) are respected. Caps tuned to medium-high density:
-        //   min  32px → secondary / icon-only / dense list controls
-        //   base 40px → default button (Material 40, GitHub 40, Tailwind 40)
-        //   prominent 48px → hero CTAs and primary form submits
-        // 24px WCAG 2.2 minimum is well exceeded at every step.
         fine: {
           min: "clamp(28px, 1.75rem, 32px)",
           base: "clamp(32px, 2rem, 40px)",
           prominent: "clamp(40px, 2.5rem, 48px)"
         },
-        // Coarse: always fixed px — touch ergonomics require predictable,
-        // reliable targets (Apple HIG 44px floor, Material 48dp default).
         coarse: {
           min: "32px",
           base: "48px",
@@ -253,7 +223,6 @@ var baseTheme = {
         }
       }
     },
-    // -- Radii --------------------------------------------------------------
     radii: {
       none: "0px",
       sm: "4px",
@@ -262,7 +231,6 @@ var baseTheme = {
       xl: "16px",
       full: "9999px"
     },
-    // -- Borders ------------------------------------------------------------
     border: {
       width: {
         none: "0px",
@@ -277,15 +245,13 @@ var baseTheme = {
         none: "none"
       }
     },
-    // -- Opacity ------------------------------------------------------------
     opacity: {
       100: 1,
-      75: 0.75,
-      50: 0.5,
-      25: 0.25,
+      75: .75,
+      50: .5,
+      25: .25,
       0: 0
     },
-    // -- Motion -------------------------------------------------------------
     motion: {
       duration: {
         none: "0ms",
@@ -302,7 +268,6 @@ var baseTheme = {
         linear: "linear"
       }
     },
-    // -- Z-Index ------------------------------------------------------------
     zIndex: {
       level: {
         0: 0,
@@ -312,7 +277,6 @@ var baseTheme = {
         4: 400
       }
     },
-    // -- Breakpoints --------------------------------------------------------
     breakpoints: {
       sm: "30rem",
       md: "48rem",
@@ -321,31 +285,10 @@ var baseTheme = {
       "2xl": "96rem"
     }
   },
-  // ==========================================================================
-  // SEMANTIC TOKENS — stable aliases consumed by components
-  //
-  // Semantic tokens reference core tokens only.
-  // No raw values are allowed in this layer.
-  // ==========================================================================
   semantic: {
-    // -- Colors -------------------------------------------------------------
-    // Grammar: {ux}.{role}.{dimension}.{state?}
-    // Components consume semantic colors only. Core colors are never referenced directly.
     colors: {
-      // Grammar: {ux}.{role}.{dimension}.{state?}
-      // States are only defined when they produce a VALUE DIFFERENT from the
-      // default state in that dimension. Hover/active/focused/selected/current
-      // that resolve to the same color as default are intentionally omitted —
-      // a token that looks identical to default is semantically invisible.
-      //
-      // Checked pairs enforced by the distinguishability test:
-      //   hover, active, focused, selected, current → must differ from default
-      // Other states (disabled, droptarget, pressed, expanded, checked,
-      //   indeterminate, visited) may match default when semantically justified.
       action: {
         primary: {
-          // neutral.1000 (black) background — authoritative, neutral primary action.
-          // Contrast: neutral.0 text on neutral.1000 → ~20:1 ✓ ; neutral.700 hover → ~12:1 ✓
           background: {
             default: "{core.colors.neutral.1000}",
             hover: "{core.colors.neutral.900}",
@@ -367,12 +310,10 @@ var baseTheme = {
           text: {
             default: "{core.colors.neutral.0}",
             disabled: "{core.colors.neutral.500}",
-            // On droptarget background (neutral.100 = light), dark text is required
             droptarget: "{core.colors.neutral.900}"
           }
         },
         secondary: {
-          // neutral.100 background, neutral.300 border, neutral.900 text
           background: {
             default: "{core.colors.neutral.200}",
             hover: "{core.colors.neutral.300}",
@@ -397,9 +338,6 @@ var baseTheme = {
           }
         },
         accent: {
-          // brand.500 background — vivid blue that draws attention in the UI.
-          // Contrast: neutral.0 text on brand.500 (#0469e3) → ~5.7:1 ✓ AA
-          // All interactive states darken further → neutral.0 text remains valid.
           background: {
             default: "{core.colors.brand.500}",
             hover: "{core.colors.brand.700}",
@@ -419,14 +357,12 @@ var baseTheme = {
             expanded: "{core.colors.brand.700}"
           },
           text: {
-            // brand.500 is dark enough — neutral.0 meets ≥ 4.5:1 AA on all states
             default: "{core.colors.neutral.0}",
             disabled: "{core.colors.neutral.500}",
             droptarget: "{core.colors.neutral.900}"
           }
         },
         negative: {
-          // red.500 background, red.500 border, neutral.0 text
           background: {
             default: "{core.colors.red.500}",
             hover: "{core.colors.red.700}",
@@ -452,7 +388,6 @@ var baseTheme = {
           }
         },
         muted: {
-          // neutral.0 background, neutral.200 border, neutral.700 text
           background: {
             default: "{core.colors.neutral.0}",
             hover: "{core.colors.neutral.50}",
@@ -483,7 +418,6 @@ var baseTheme = {
       },
       input: {
         primary: {
-          // neutral.0 background, neutral.300 border, neutral.900 text
           background: {
             default: "{core.colors.neutral.0}",
             hover: "{core.colors.neutral.50}",
@@ -512,13 +446,9 @@ var baseTheme = {
             default: "{core.colors.neutral.900}",
             disabled: "{core.colors.neutral.500}",
             checked: "{core.colors.neutral.0}",
-            // brand.300 (indeterminate bg) is light — use dark text for contrast
             indeterminate: "{core.colors.neutral.900}"
           }
         },
-        // Lower-emphasis input field (inline editors, filter pills, optional fields).
-        // Mirrors primary controls but uses a lighter chrome — default border is
-        // neutral.200 (vs primary's neutral.300) so it recedes until interacted with.
         secondary: {
           background: {
             default: "{core.colors.neutral.0}",
@@ -555,7 +485,6 @@ var baseTheme = {
           background: {
             default: "{core.colors.red.100}",
             disabled: "{core.colors.neutral.100}",
-            // red.700 (not red.500) so neutral.0 text meets 4.5:1 AA contrast
             checked: "{core.colors.red.700}",
             indeterminate: "{core.colors.red.300}"
           },
@@ -578,7 +507,6 @@ var baseTheme = {
           background: {
             default: "{core.colors.green.100}",
             disabled: "{core.colors.neutral.100}",
-            // green.700 (not green.500) so neutral.0 text meets 4.5:1 AA contrast
             checked: "{core.colors.green.700}",
             indeterminate: "{core.colors.green.300}"
           },
@@ -616,7 +544,6 @@ var baseTheme = {
           text: {
             default: "{core.colors.yellow.900}",
             disabled: "{core.colors.neutral.500}",
-            // yellow.500 is light — dark text required for 4.5:1 AA
             checked: "{core.colors.neutral.900}"
           }
         },
@@ -695,7 +622,6 @@ var baseTheme = {
             default: "{core.colors.neutral.700}",
             active: "{core.colors.neutral.900}",
             disabled: "{core.colors.neutral.500}",
-            // neutral.700 (not neutral.500) to meet 4.5:1 AA on neutral.100 background
             visited: "{core.colors.neutral.700}"
           }
         },
@@ -781,15 +707,11 @@ var baseTheme = {
           }
         },
         accent: {
-          // brand.400 bg — louder than primary (brand.500). Outlined/tinted card accent.
-          // Follows filled pattern for selected, rest stays light.
           background: {
             default: "{core.colors.brand.50}",
             hover: "{core.colors.brand.100}",
             active: "{core.colors.brand.200}",
             disabled: "{core.colors.neutral.100}",
-            // selected uses brand.500 (not brand.400) so neutral.0 text meets
-            // AA Normal (≥ 4.5:1). brand.400 on white fails the normal threshold.
             selected: "{core.colors.brand.500}"
           },
           border: {
@@ -805,16 +727,12 @@ var baseTheme = {
             hover: "{core.colors.brand.900}",
             active: "{core.colors.brand.900}",
             disabled: "{core.colors.neutral.500}",
-            // selected uses filled bg (brand.500) — neutral.0 meets 4.5:1
             selected: "{core.colors.neutral.0}",
             visited: "{core.colors.brand.700}"
           }
         }
       },
       feedback: {
-        // Feedback is informational — surfaces show state, not interactions.
-        // Legal states: default | focused (close button or focusable wrapper) | disabled.
-        // hover, active, selected, pressed, expanded are absent: FSL §7.
         primary: {
           background: {
             default: "{core.colors.neutral.50}"
@@ -883,8 +801,6 @@ var baseTheme = {
       },
       navigation: {
         primary: {
-          // Inline link on light surfaces: transparent bg, brand text underline.
-          // Contrast: brand.700 (#034da6) on neutral.0 (#ffffff) → ~9.5:1 ✓
           background: {
             default: "{core.colors.neutral.0}",
             hover: "{core.colors.neutral.50}",
@@ -909,7 +825,6 @@ var baseTheme = {
           }
         },
         secondary: {
-          // Light nav: neutral.50 background, neutral.200 border, neutral.700 text
           background: {
             default: "{core.colors.neutral.50}",
             hover: "{core.colors.neutral.100}",
@@ -941,8 +856,6 @@ var baseTheme = {
           }
         },
         accent: {
-          // Brand accent nav: brand.50 background with brand border — louder than secondary.
-          // Targeted use: highlighted/featured nav items.
           background: {
             default: "{core.colors.brand.50}",
             hover: "{core.colors.brand.100}",
@@ -965,7 +878,6 @@ var baseTheme = {
             default: "{core.colors.brand.700}",
             hover: "{core.colors.brand.900}",
             disabled: "{core.colors.neutral.500}",
-            // selected/current use brand.700 bg — neutral.0 meets ≥ 4.5:1
             selected: "{core.colors.neutral.0}",
             current: "{core.colors.neutral.0}",
             visited: "{core.colors.brand.500}",
@@ -973,8 +885,6 @@ var baseTheme = {
           }
         },
         muted: {
-          // Subdued nav: transparent / neutral.100 background, none border, neutral.500 text.
-          // Used for secondary nav items, breadcrumbs, or inactive sidebar links.
           background: {
             default: "{core.colors.neutral.0}",
             hover: "{core.colors.neutral.50}",
@@ -1006,8 +916,6 @@ var baseTheme = {
         }
       }
     },
-    // -- Elevation ----------------------------------------------------------
-    // Grammar: elevation.surface.{stratum}
     elevation: {
       surface: {
         flat: "{core.elevation.level.0}",
@@ -1016,8 +924,6 @@ var baseTheme = {
         blocking: "{core.elevation.level.4}"
       }
     },
-    // -- Typography ---------------------------------------------------------
-    // Grammar: text.{family}.{step}
     text: {
       display: {
         lg: {
@@ -1168,22 +1074,13 @@ var baseTheme = {
         }
       }
     },
-    // -- Spacing ------------------------------------------------------------
-    // Grammar: {pattern}.{context}.{step?}
     spacing: {
       inset: {
-        // Mapped to the documented defaults from spacing.md. Medium-high
-        // density is delivered by `core.sizing.hit.fine.*` (40px base)
-        // combined with the spacing engine clamp — not by tightening
-        // inset.control, which previously caused cramped vertical padding
-        // (~4px) when content grew beyond `min-height: hit.base`.
         control: {
           sm: "{core.spacing.2}",
           md: "{core.spacing.3}",
           lg: "{core.spacing.4}"
         },
-        // Surfaces breathe more than controls; the invariant
-        // inset.surface.X ≥ inset.control.X is preserved.
         surface: {
           sm: "{core.spacing.3}",
           md: "{core.spacing.4}",
@@ -1216,8 +1113,6 @@ var baseTheme = {
         }
       }
     },
-    // -- Sizing -------------------------------------------------------------
-    // Grammar: {family}.{stepOrProperty}
     sizing: {
       hit: {
         min: "{core.sizing.hit.fine.min}",
@@ -1250,13 +1145,11 @@ var baseTheme = {
         }
       }
     },
-    // -- Radii --------------------------------------------------------------
     radii: {
       control: "{core.radii.md}",
       surface: "{core.radii.lg}",
       round: "{core.radii.full}"
     },
-    // -- Borders ------------------------------------------------------------
     border: {
       divider: {
         width: "{core.border.width.default}",
@@ -1277,31 +1170,21 @@ var baseTheme = {
         }
       }
     },
-    // -- Focus --------------------------------------------------------------
     focus: {
       ring: {
         width: "{core.border.width.focused}",
         style: "{core.border.style.solid}",
-        // References the semantic accent focused border so mode overrides
-        // remap focus color automatically (e.g. brand.300 in dark mode).
         color: "{semantic.colors.action.accent.border.focused}"
       }
     },
-    // -- Overlay ------------------------------------------------------------
     overlay: {
-      // Full modal backdrop color. Alpha is sourced from semantic.opacity.scrim
-      // so both tokens stay in sync across themes and modes.
-      // RawValue rationale: rgba() composing a token ref cannot be expressed
-      // as a single TokenRef — see model.md §8 RawValue inventory.
       scrim: "rgba(0, 0, 0, {semantic.opacity.scrim})"
     },
-    // -- Opacity ------------------------------------------------------------
     opacity: {
       scrim: "{core.opacity.50}",
       loading: "{core.opacity.50}",
       disabled: "{core.opacity.50}"
     },
-    // -- Motion -------------------------------------------------------------
     motion: {
       feedback: {
         duration: "{core.motion.duration.sm}",
@@ -1326,7 +1209,6 @@ var baseTheme = {
         easing: "{core.motion.easing.linear}"
       }
     },
-    // -- Z-Index ------------------------------------------------------------
     zIndex: {
       layer: {
         base: "{core.zIndex.level.0}",
@@ -1338,13 +1220,11 @@ var baseTheme = {
     }
   }
 };
-var darkAlternate = {
+const darkAlternate = {
   semantic: {
     colors: {
       action: {
         primary: {
-          // White button on dark surface — inverted authority for dark contexts.
-          // Contrast: neutral.900 text on neutral.0 → ~19:1 ✓
           background: {
             default: "{core.colors.neutral.0}",
             hover: "{core.colors.neutral.100}",
@@ -1364,7 +1244,6 @@ var darkAlternate = {
           text: {
             default: "{core.colors.neutral.900}",
             disabled: "{core.colors.neutral.500}",
-            // droptarget bg is now neutral.700 (dark) — neutral.0 required for contrast
             droptarget: "{core.colors.neutral.0}"
           }
         },
@@ -1407,15 +1286,12 @@ var darkAlternate = {
           text: {
             default: "{core.colors.neutral.50}",
             disabled: "{core.colors.neutral.500}",
-            // neutral.900 text on neutral.700 dark bg → ~3:1 — fails WCAG AA
             hover: "{core.colors.neutral.0}",
             active: "{core.colors.neutral.0}",
             pressed: "{core.colors.neutral.0}",
             expanded: "{core.colors.neutral.0}"
           }
         },
-        // negative: red.500 bg/border + neutral.0 text remain valid on dark
-        // pages (vivid destructive colour). Only state-specific overrides.
         negative: {
           background: {
             disabled: "{core.colors.neutral.700}",
@@ -1425,12 +1301,9 @@ var darkAlternate = {
             disabled: "{core.colors.neutral.700}"
           },
           text: {
-            // droptarget bg is now neutral.700 (dark) — neutral.0 required for contrast
             droptarget: "{core.colors.neutral.0}"
           }
         },
-        // accent: brand.500 bg/border + neutral.0 text remain valid on dark
-        // surface. Only remap states that use light-mode fills that fail on dark.
         accent: {
           background: {
             disabled: "{core.colors.neutral.700}",
@@ -1468,8 +1341,6 @@ var darkAlternate = {
             disabled: "{core.colors.neutral.500}"
           }
         },
-        // input.secondary: lower-emphasis field, matches primary dark values since both
-        // render on a dark page. base neutral.0 default fails on dark — full override.
         secondary: {
           background: {
             default: "{core.colors.neutral.700}",
@@ -1567,7 +1438,6 @@ var darkAlternate = {
           },
           text: {
             default: "{core.colors.neutral.0}",
-            // neutral.700 on neutral.900 dark bg → ~2:1 — fails WCAG AA
             visited: "{core.colors.neutral.300}"
           }
         },
@@ -1586,9 +1456,7 @@ var darkAlternate = {
           },
           text: {
             default: "{core.colors.neutral.50}",
-            // neutral.900 on neutral.700 dark bg → ~3:1 — fails WCAG AA
             active: "{core.colors.neutral.0}",
-            // neutral.700 on neutral.700 → 1:1 — invisible
             visited: "{core.colors.neutral.300}"
           }
         },
@@ -1642,7 +1510,6 @@ var darkAlternate = {
             default: "{core.colors.red.300}"
           }
         },
-        // Full remap: base brand.50/100/200 backgrounds are near-white and fail on dark pages.
         accent: {
           background: {
             default: "{core.colors.brand.900}",
@@ -1654,13 +1521,11 @@ var darkAlternate = {
             default: "{core.colors.brand.300}",
             hover: "{core.colors.brand.400}",
             active: "{core.colors.brand.400}",
-            // brand.100 for focused — must differ from default (brand.300) for state distinguishability
             focused: "{core.colors.brand.100}",
             disabled: "{core.colors.neutral.700}",
             selected: "{core.colors.brand.400}"
           },
           text: {
-            // brand.700 on neutral.900 bg → ~1.3:1 — invisible; use brand.300
             default: "{core.colors.brand.300}",
             hover: "{core.colors.brand.100}",
             active: "{core.colors.brand.100}",
@@ -1726,17 +1591,7 @@ var darkAlternate = {
         }
       },
       navigation: {
-        // Stacked-surface separation in dark mode.
-        // The page background and informational.primary.background.default both
-        // resolve to neutral.900 here. Per the prescribed pattern (see
-        // colors.md → "Stacking informational surfaces"), separation is paid in
-        // elevation + border + theme-side step displacement, never in colour.
-        // navigation.primary applies (3): hover/active/current/expanded shift to
-        // neutral.700 so a nav item reads as a distinct affordance against the
-        // page surface even with no elevation of its own.
         primary: {
-          // Inline link on dark surfaces: transparent bg, brand.300 text.
-          // Contrast: brand.300 (#60a5fa) on neutral.900 (#0f172a) → ~6.8:1 ✓
           background: {
             default: "{core.colors.neutral.900}",
             hover: "{core.colors.neutral.700}",
@@ -1860,23 +1715,70 @@ var darkAlternate = {
   }
 };
 
-// src/createTheme.ts
-var buildTheme = /* @__PURE__ */__name(({
+//#endregion
+//#region src/createTheme.ts
+/**
+* Creates a fully resolved `ThemeTokens` by merging partial overrides into a base.
+* Internal engine — consumers should use `createTheme` which returns `ThemeBundle`.
+*
+* @internal
+*/
+const buildTheme = ({
   base = baseTheme,
   overrides = {}
 } = {}) => {
   const merged = deepMerge(base, overrides);
-  if (process.env.NODE_ENV !== "production") {
-    validateRefs(merged);
-  }
+  if (process.env.NODE_ENV !== "production") validateRefs(merged);
   return structuredClone(merged);
-}, "buildTheme");
-var resolveAlternate = /* @__PURE__ */__name((alternate, parentBundle) => {
+};
+const resolveAlternate = (alternate, parentBundle) => {
   if (alternate === null) return void 0;
   if (alternate !== void 0) return alternate;
   return parentBundle?.alternate ?? darkAlternate;
-}, "resolveAlternate");
-var createTheme = /* @__PURE__ */__name(({
+};
+/**
+* Creates a theme bundle with an optional alternate color mode.
+*
+* The `extends` param is the idiomatic way to build on a built-in theme:
+* it inherits the base tokens **and** the dark-mode alternate automatically.
+*
+* @param params.extends - Parent bundle to inherit from. `base`, `baseMode`, and
+*   `alternate` default to the parent's values when this is provided.
+* @param params.baseMode - Which mode the base represents. Defaults to `'light'`.
+* @param params.base - Base theme to extend. Defaults to `extends.base` or `baseTheme`.
+* @param params.overrides - Brand overrides applied to the base theme.
+* @param params.alternate - Semantic remapping overrides for the opposite color mode.
+*   Defaults to `darkAlternate` (built-in dark mode) when neither `alternate` nor
+*   `extends` is provided. Inherits from `extends.alternate` when `extends` is given.
+*   Pass `null` to explicitly opt out of any alternate (single-mode theme).
+*   Core tokens are immutable — only semantic references change between modes.
+*
+* @example
+* ```ts
+* // Path A — default foundation (light base + dark alternate included)
+* const myTheme = createTheme();
+* <ThemeProvider theme={myTheme} />
+*
+* // Path B — custom brand overrides (dark mode still included)
+* const myTheme = createTheme({
+*   overrides: { core: { colors: { brand: { 500: '#FF0000' } } } },
+* });
+*
+* // Path C — custom semantic dark alternate
+* const myTheme = createTheme({
+*   overrides: { core: { colors: { brand: { 500: '#FF0000' } } } },
+*   alternate: {
+*     semantic: {
+*       colors: { informational: { primary: { background: { default: '{core.colors.neutral.900}' } } } },
+*     },
+*   },
+* });
+*
+* // Path D — single-mode theme (no dark alternate)
+* const myTheme = createTheme({ alternate: null });
+* ```
+*/
+const createTheme = ({
   extends: parentBundle,
   baseMode,
   base,
@@ -1894,5 +1796,7 @@ var createTheme = /* @__PURE__ */__name(({
     }),
     alternate: resolvedAlternate
   };
-}, "createTheme");
-export { baseTheme, darkAlternate, buildTheme, createTheme };
+};
+
+//#endregion
+export { darkAlternate as i, createTheme as n, baseTheme as r, buildTheme as t };