@ttoss/fsl-theme 2.0.0 → 2.1.1

package/dist/{createTheme-B6tVIikC.mjs → createTheme-Bm9LVQ4w.mjs}

@@ -1,5 +1,5 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { a as flattenTheme, r as deepMerge, t as COMPOUND_REF_RE } from "./helpers-BXaKe2s3.mjs";
+import { a as flattenTheme, i as flattenObject, r as deepMerge, t as COMPOUND_REF_RE } from "./helpers-BXaKe2s3.mjs";
 
 //#region src/baseTheme.ts
 /**
@@ -66,6 +66,7 @@ var baseTheme = {
         100: "#fee2e2",
         300: "#fca5a5",
         500: "#ef4444",
+        600: "#dc2626",
         700: "#b91c1c",
         900: "#7f1d1d"
       },
@@ -391,7 +392,7 @@ var baseTheme = {
         },
         negative: {
           background: {
-            default: "{core.colors.red.500}",
+            default: "{core.colors.red.600}",
             hover: "{core.colors.red.700}",
             active: "{core.colors.red.900}",
             disabled: "{core.colors.neutral.200}",
@@ -400,7 +401,7 @@ var baseTheme = {
             expanded: "{core.colors.red.700}"
           },
           border: {
-            default: "{core.colors.red.500}",
+            default: "{core.colors.red.600}",
             hover: "{core.colors.red.700}",
             active: "{core.colors.red.900}",
             focused: "{core.colors.red.700}",
@@ -455,7 +456,8 @@ var baseTheme = {
             checked: "{core.colors.brand.500}",
             indeterminate: "{core.colors.brand.300}",
             pressed: "{core.colors.neutral.100}",
-            expanded: "{core.colors.neutral.50}"
+            expanded: "{core.colors.neutral.50}",
+            invalid: "{core.colors.neutral.0}"
           },
           border: {
             default: "{core.colors.neutral.300}",
@@ -467,12 +469,14 @@ var baseTheme = {
             checked: "{core.colors.brand.500}",
             indeterminate: "{core.colors.brand.300}",
             pressed: "{core.colors.neutral.500}",
-            expanded: "{core.colors.brand.500}"
+            expanded: "{core.colors.brand.500}",
+            invalid: "{core.colors.red.600}"
           },
           text: {
             default: "{core.colors.neutral.900}",
             disabled: "{core.colors.neutral.500}",
             checked: "{core.colors.neutral.0}",
+            invalid: "{core.colors.neutral.900}",
             indeterminate: "{core.colors.neutral.900}"
           }
         },
@@ -1355,17 +1359,20 @@ var darkAlternate = {
             selected: "{core.colors.brand.700}",
             droptarget: "{core.colors.neutral.700}",
             pressed: "{core.colors.neutral.500}",
-            expanded: "{core.colors.neutral.500}"
+            expanded: "{core.colors.neutral.500}",
+            invalid: "{core.colors.neutral.700}"
           },
           border: {
             default: "{core.colors.neutral.500}",
             hover: "{core.colors.neutral.300}",
             focused: "{core.colors.brand.500}",
-            disabled: "{core.colors.neutral.700}"
+            disabled: "{core.colors.neutral.700}",
+            invalid: "{core.colors.red.300}"
           },
           text: {
             default: "{core.colors.neutral.0}",
-            disabled: "{core.colors.neutral.500}"
+            disabled: "{core.colors.neutral.500}",
+            invalid: "{core.colors.neutral.0}"
           }
         },
         secondary: {
@@ -1789,10 +1796,17 @@ var levenshtein = (a, b) => {
 * Validate that every `{ref}` in the merged theme points to an existing path.
 * Emits `console.warn` for each broken reference with a "did you mean?" suggestion.
 *
+* `onlyOwnerKeys` restricts which token paths are *checked* (resolution still
+* looks at the whole tree) — used to validate just the leaves an alternate
+* introduces without re-warning refs already reported for the base.
+*
 * **DEV-only** — callers gate this behind `process.env.NODE_ENV !== 'production'`
 * so bundlers tree-shake the entire call in production builds.
 */
-var validateRefs = theme => {
+var validateRefs = (theme, options = {}) => {
+  const {
+    onlyOwnerKeys
+  } = options;
   const {
     core,
     semantic
@@ -1817,6 +1831,7 @@ var validateRefs = theme => {
     return "";
   };
   for (const [ownerKey, value] of Object.entries(all)) {
+    if (onlyOwnerKeys && !onlyOwnerKeys.has(ownerKey)) continue;
     if (typeof value !== "string" || !value.includes("{")) continue;
     let match;
     const re = new RegExp(COMPOUND_REF_RE.source, COMPOUND_REF_RE.flags);
@@ -1835,6 +1850,41 @@ var validateRefs = theme => {
 //#endregion
 //#region src/createTheme.ts
 /**
+* Deep-clone to break shared references between base and result.
+* Tokens are primitives (strings, numbers) — `structuredClone` is safe and
+* more correct than a JSON round-trip (preserves `undefined`, `NaN`, etc.).
+*
+* Falls back to a JSON round-trip when `structuredClone` is unavailable
+* (e.g. Jest's jsdom environment, older embedded runtimes) so importing the
+* package never throws at module-evaluation time. Token trees are plain
+* string/number leaves, so the fallback is lossless for valid themes.
+*/
+var cloneTokens = value => {
+  if (typeof structuredClone === "function") return structuredClone(value);
+  return JSON.parse(JSON.stringify(value));
+};
+/**
+* DEV-only: validate the refs an alternate introduces against the built base.
+* The alternate is authored by hand (semantic-only remaps), so a typo'd
+* dark-mode ref must warn at theme creation instead of silently emitting a
+* broken CSS var in production.
+*
+* Only the leaves the alternate itself provides are checked — base refs were
+* already validated by `buildTheme`, so they would otherwise warn twice.
+*/
+var validateAlternateRefs = ({
+  base,
+  alternate
+}) => {
+  const alternateKeys = new Set(Object.keys(flattenObject(alternate.semantic, "semantic")));
+  validateRefs({
+    core: base.core,
+    semantic: deepMerge(base.semantic, alternate.semantic)
+  }, {
+    onlyOwnerKeys: alternateKeys
+  });
+};
+/**
 * Creates a fully resolved `ThemeTokens` by merging partial overrides into a base.
 * Internal engine — consumers should use `createTheme` which returns `ThemeBundle`.
 *
@@ -1846,13 +1896,28 @@ var buildTheme = ({
 } = {}) => {
   const merged = deepMerge(base, overrides);
   if (process.env.NODE_ENV !== "production") validateRefs(merged);
-  return structuredClone(merged);
+  return cloneTokens(merged);
 };
 var resolveAlternate = (alternate, parentBundle) => {
   if (alternate === null) return void 0;
   if (alternate !== void 0) return alternate;
   return parentBundle?.alternate ?? darkAlternate;
 };
+/** Resolve every `createTheme` input against its `extends` parent + defaults. */
+var resolveBundleInputs = ({
+  parentBundle,
+  baseMode,
+  base,
+  alternate,
+  brief
+}) => {
+  return {
+    resolvedBase: base ?? parentBundle?.base,
+    resolvedBaseMode: baseMode ?? parentBundle?.baseMode ?? "light",
+    resolvedAlternate: resolveAlternate(alternate, parentBundle),
+    resolvedMeta: brief ?? parentBundle?.meta
+  };
+};
 /**
 * Creates a theme bundle with an optional alternate color mode.
 *
@@ -1903,16 +1968,29 @@ var createTheme = ({
   alternate,
   brief
 } = {}) => {
-  const resolvedBase = base ?? parentBundle?.base;
-  const resolvedBaseMode = baseMode ?? parentBundle?.baseMode ?? "light";
-  const resolvedAlternate = resolveAlternate(alternate, parentBundle);
-  const resolvedMeta = brief ?? parentBundle?.meta;
+  const {
+    resolvedBase,
+    resolvedBaseMode,
+    resolvedAlternate,
+    resolvedMeta
+  } = resolveBundleInputs({
+    parentBundle,
+    baseMode,
+    base,
+    alternate,
+    brief
+  });
+  const builtBase = buildTheme({
+    base: resolvedBase,
+    overrides
+  });
+  if (process.env.NODE_ENV !== "production" && resolvedAlternate) validateAlternateRefs({
+    base: builtBase,
+    alternate: resolvedAlternate
+  });
   return {
     baseMode: resolvedBaseMode,
-    base: buildTheme({
-      base: resolvedBase,
-      overrides
-    }),
+    base: builtBase,
     alternate: resolvedAlternate,
     ...(resolvedMeta ? {
       meta: resolvedMeta

package/dist/css.cjs

@@ -3,7 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
 const require_helpers = require('./helpers-BU40JvFA.cjs');
-const require_toCssVars = require('./toCssVars-BseqmMcT.cjs');
+const require_toCssVars = require('./toCssVars-D0BR23cP.cjs');
 
 //#region src/css.ts
 /**
@@ -35,9 +35,10 @@ const require_toCssVars = require('./toCssVars-BseqmMcT.cjs');
 * res.type('text/css').send(getThemeStylesContent(myBundle, 'myTheme'));
 * ```
 */
-var getThemeStylesContent = (bundle, themeId) => {
+var getThemeStylesContent = (bundle, themeId, options) => {
   return require_toCssVars.toCssVars(bundle, {
-    themeId
+    themeId,
+    systemModeFallback: options?.systemModeFallback
   }).toCssString();
 };
 

package/dist/css.d.cts

@@ -1,5 +1,5 @@
 
-import { a as ThemeTokens, i as ThemeBundle } from "./Types-BkaxtsMv.cjs";
+import { a as ThemeTokens, i as ThemeBundle } from "./Types-a_sfpbha.cjs";
 
 //#region src/roots/helpers.d.ts
 /**
@@ -97,6 +97,18 @@ interface BundleCssVarsOptions {
    * multi-theme scenarios (Storybook, micro-frontends).
    */
   themeId?: string;
+  /**
+   * Emit the `@media (prefers-color-scheme)` fallback block so the OS
+   * preference applies before JS runs (and without JS). Only meaningful for
+   * themeId-less bundles. Default `true`.
+   *
+   * Set `false` when the app is deliberately single-default (`defaultMode`
+   * `'light'` or `'dark'` with the alternate reachable only via explicit
+   * toggle) — otherwise dark-OS users would get the alternate on first paint
+   * against the app's configured default. `<ThemeProvider>` / `<ThemeHead>`
+   * derive this automatically from their `defaultMode` prop.
+   */
+  systemModeFallback?: boolean;
 }
 /**
  * Return type of `bundleToCssVars()`.
@@ -163,6 +175,13 @@ declare function toCssVars(bundle: ThemeBundle, options?: BundleCssVarsOptions):
  * res.type('text/css').send(getThemeStylesContent(myBundle, 'myTheme'));
  * ```
  */
-declare const getThemeStylesContent: (bundle: ThemeBundle, themeId?: string) => string;
+declare const getThemeStylesContent: (bundle: ThemeBundle, themeId?: string, options?: {
+  /**
+   * Emit the `@media (prefers-color-scheme)` fallback block (themeId-less
+   * bundles only). Default `true`. Pass `false` for apps whose
+   * `defaultMode` is a fixed `'light'`/`'dark'` rather than `'system'`.
+   */
+  systemModeFallback?: boolean;
+}) => string;
 //#endregion
 export { type BundleCssVarsOptions, type BundleCssVarsResult, type CssVarsOptions, type CssVarsResult, type FlatTokenMap, getThemeStylesContent, toCssVarName, toCssVars, toFlatTokens };

package/dist/css.d.mts

@@ -1,5 +1,5 @@
 
-import { a as ThemeTokens, i as ThemeBundle } from "./Types-BkaxtsMv.mjs";
+import { a as ThemeTokens, i as ThemeBundle } from "./Types-a_sfpbha.mjs";
 
 //#region src/roots/helpers.d.ts
 /**
@@ -97,6 +97,18 @@ interface BundleCssVarsOptions {
    * multi-theme scenarios (Storybook, micro-frontends).
    */
   themeId?: string;
+  /**
+   * Emit the `@media (prefers-color-scheme)` fallback block so the OS
+   * preference applies before JS runs (and without JS). Only meaningful for
+   * themeId-less bundles. Default `true`.
+   *
+   * Set `false` when the app is deliberately single-default (`defaultMode`
+   * `'light'` or `'dark'` with the alternate reachable only via explicit
+   * toggle) — otherwise dark-OS users would get the alternate on first paint
+   * against the app's configured default. `<ThemeProvider>` / `<ThemeHead>`
+   * derive this automatically from their `defaultMode` prop.
+   */
+  systemModeFallback?: boolean;
 }
 /**
  * Return type of `bundleToCssVars()`.
@@ -163,6 +175,13 @@ declare function toCssVars(bundle: ThemeBundle, options?: BundleCssVarsOptions):
  * res.type('text/css').send(getThemeStylesContent(myBundle, 'myTheme'));
  * ```
  */
-declare const getThemeStylesContent: (bundle: ThemeBundle, themeId?: string) => string;
+declare const getThemeStylesContent: (bundle: ThemeBundle, themeId?: string, options?: {
+  /**
+   * Emit the `@media (prefers-color-scheme)` fallback block (themeId-less
+   * bundles only). Default `true`. Pass `false` for apps whose
+   * `defaultMode` is a fixed `'light'`/`'dark'` rather than `'system'`.
+   */
+  systemModeFallback?: boolean;
+}) => string;
 //#endregion
 export { type BundleCssVarsOptions, type BundleCssVarsResult, type CssVarsOptions, type CssVarsResult, type FlatTokenMap, getThemeStylesContent, toCssVarName, toCssVars, toFlatTokens };

package/dist/css.mjs

@@ -1,6 +1,6 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import { s as toFlatTokens } from "./helpers-BXaKe2s3.mjs";
-import { n as toCssVars, t as toCssVarName } from "./toCssVars-C-9yIZDR.mjs";
+import { n as toCssVars, t as toCssVarName } from "./toCssVars-CWTlp9St.mjs";
 
 //#region src/css.ts
 /**
@@ -32,9 +32,10 @@ import { n as toCssVars, t as toCssVarName } from "./toCssVars-C-9yIZDR.mjs";
 * res.type('text/css').send(getThemeStylesContent(myBundle, 'myTheme'));
 * ```
 */
-var getThemeStylesContent = (bundle, themeId) => {
+var getThemeStylesContent = (bundle, themeId, options) => {
   return toCssVars(bundle, {
-    themeId
+    themeId,
+    systemModeFallback: options?.systemModeFallback
   }).toCssString();
 };
 

package/dist/dataviz/index.cjs

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
-const require_react = require('../react-DLB8nrXQ.cjs');
-const require_withDataviz = require('../withDataviz-CYRf4exT.cjs');
+const require_react = require('../react-DQErMGJz.cjs');
+const require_withDataviz = require('../withDataviz-DrUtw8cc.cjs');
 
 //#region src/dataviz/useDatavizTokens.ts
 /**

package/dist/dataviz/index.d.cts

@@ -1,5 +1,5 @@
 
-import { c as SemanticDataviz, i as ThemeBundle, s as CoreDataviz } from "../Types-BkaxtsMv.cjs";
+import { c as SemanticDataviz, i as ThemeBundle, s as CoreDataviz } from "../Types-a_sfpbha.cjs";
 
 //#region src/dataviz/baseTheme.d.ts
 /**

package/dist/dataviz/index.d.mts

@@ -1,5 +1,5 @@
 
-import { c as SemanticDataviz, i as ThemeBundle, s as CoreDataviz } from "../Types-BkaxtsMv.mjs";
+import { c as SemanticDataviz, i as ThemeBundle, s as CoreDataviz } from "../Types-a_sfpbha.mjs";
 
 //#region src/dataviz/baseTheme.d.ts
 /**

package/dist/dataviz/index.mjs

@@ -1,5 +1,5 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { n as coreDataviz, r as semanticDataviz, t as withDataviz } from "../withDataviz-BvpZJnFx.mjs";
+import { n as coreDataviz, r as semanticDataviz, t as withDataviz } from "../withDataviz-Ln3sEwb7.mjs";
 import { useTokens } from "../react.mjs";
 
 //#region src/dataviz/useDatavizTokens.ts

package/dist/dtcg.d.cts

@@ -1,5 +1,5 @@
 
-import { a as ThemeTokens } from "./Types-BkaxtsMv.cjs";
+import { a as ThemeTokens } from "./Types-a_sfpbha.cjs";
 
 //#region src/roots/toDTCG.d.ts
 /**

package/dist/dtcg.d.mts

@@ -1,5 +1,5 @@
 
-import { a as ThemeTokens } from "./Types-BkaxtsMv.mjs";
+import { a as ThemeTokens } from "./Types-a_sfpbha.mjs";
 
 //#region src/roots/toDTCG.d.ts
 /**

package/dist/{index-7YL90Xqs.d.cts → index-BmZQVd3G.d.cts}

@@ -1,5 +1,5 @@
 
-import { a as ThemeTokens, i as ThemeBundle, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-BkaxtsMv.cjs";
+import { a as ThemeTokens, i as ThemeBundle, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-a_sfpbha.cjs";
 //#region src/baseTheme.d.ts
 /**
  * **Foundation** — Neutral baseline theme.

package/dist/{index-BmCTIOzh.d.mts → index-XZsRrMTF.d.mts}

@@ -1,5 +1,5 @@
 
-import { a as ThemeTokens, i as ThemeBundle, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-BkaxtsMv.mjs";
+import { a as ThemeTokens, i as ThemeBundle, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-a_sfpbha.mjs";
 //#region src/baseTheme.d.ts
 /**
  * **Foundation** — Neutral baseline theme.

package/dist/index.cjs

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
-const require_createTheme = require('./createTheme--UFgVlEn.cjs');
+const require_createTheme = require('./createTheme-B7H0xSVp.cjs');
 const require_themes_bruttal = require('./themes/bruttal.cjs');
 exports.baseTheme = require_createTheme.baseTheme;
 exports.bruttal = require_themes_bruttal.bruttal;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 
-import { a as ThemeTokens, i as ThemeBundle, n as SemanticTokens, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-BkaxtsMv.cjs";
-import { i as darkAlternate, n as createTheme, r as baseTheme, t as bruttal } from "./index-7YL90Xqs.cjs";
+import { a as ThemeTokens, i as ThemeBundle, n as SemanticTokens, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-a_sfpbha.cjs";
+import { i as darkAlternate, n as createTheme, r as baseTheme, t as bruttal } from "./index-BmZQVd3G.cjs";
 import { o as ThemeMode } from "./ssrScript-BVysxDws.cjs";
-import { c as ThemeStylesProps, n as ThemeHeadProps } from "./react-Dt7vGAVG.cjs";
+import { c as ThemeStylesProps, n as ThemeHeadProps } from "./react-2D_CNVF2.cjs";
 export { type DeepPartial, type ModeOverride, type SemanticTokens, type ThemeBrief, type ThemeBundle, type ThemeHeadProps, type ThemeMode, type ThemeStylesProps, type ThemeTokens, baseTheme, bruttal, createTheme, darkAlternate };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 
-import { a as ThemeTokens, i as ThemeBundle, n as SemanticTokens, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-BkaxtsMv.mjs";
-import { i as darkAlternate, n as createTheme, r as baseTheme, t as bruttal } from "./index-BmCTIOzh.mjs";
+import { a as ThemeTokens, i as ThemeBundle, n as SemanticTokens, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-a_sfpbha.mjs";
+import { i as darkAlternate, n as createTheme, r as baseTheme, t as bruttal } from "./index-XZsRrMTF.mjs";
 import { o as ThemeMode } from "./ssrScript-BVysxDws.mjs";
-import { c as ThemeStylesProps, n as ThemeHeadProps } from "./react-C8JrZf-b.mjs";
+import { c as ThemeStylesProps, n as ThemeHeadProps } from "./react-BwnHHvJj.mjs";
 export { type DeepPartial, type ModeOverride, type SemanticTokens, type ThemeBrief, type ThemeBundle, type ThemeHeadProps, type ThemeMode, type ThemeStylesProps, type ThemeTokens, baseTheme, bruttal, createTheme, darkAlternate };

package/dist/index.mjs

@@ -1,4 +1,4 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { a as darkAlternate, i as baseTheme, n as createTheme } from "./createTheme-B6tVIikC.mjs";
+import { a as darkAlternate, i as baseTheme, n as createTheme } from "./createTheme-Bm9LVQ4w.mjs";
 import { bruttal } from "./themes/bruttal.mjs";
 export { baseTheme, bruttal, createTheme, darkAlternate };

package/dist/{react-Dt7vGAVG.d.cts → react-2D_CNVF2.d.cts}

@@ -1,9 +1,17 @@
 
-import { i as ThemeBundle, n as SemanticTokens } from "./Types-BkaxtsMv.cjs";
+import { i as ThemeBundle, n as SemanticTokens } from "./Types-a_sfpbha.cjs";
 import { a as ResolvedMode, o as ThemeMode, t as ThemeScriptConfig } from "./ssrScript-BVysxDws.cjs";
 import * as React from "react";
 
 //#region src/react.d.ts
+/**
+ * Accepted shapes for the `root` prop: a concrete element, or a ref object.
+ * Prefer the ref form — refs are populated before layout effects run, so the
+ * runtime attaches directly to the target element with no transient attach
+ * to `<html>` on the first render (the element form is `null` during the
+ * first render when read from `ref.current`).
+ */
+type ThemeRootInput = HTMLElement | React.RefObject<HTMLElement | null>;
 /**
  * Props for the `ThemeProvider` component.
  */
@@ -83,25 +91,32 @@ interface ThemeProviderProps {
   onModeChange?: (mode: ThemeMode, resolvedMode: ResolvedMode) => void;
   /**
    * Root element to anchor `data-tt-theme` / `data-tt-mode` attributes.
-   * Defaults to `document.documentElement`. Pass a container element for
-   * Storybook isolation or micro-frontend use cases.
+   * Defaults to `document.documentElement`. Pass a container for Storybook
+   * isolation or micro-frontend use cases.
    *
-   * Because the element is often `null` on the first render when passed via
-   * `ref.current`, `root` is reactive: the runtime is recreated once when
-   * it transitions from `undefined` to the actual element.
+   * **Must be paired with `themeId`.** Without a `themeId`, the generated CSS
+   * targets `:root` / `:root[data-tt-mode="dark"]` (the `<html>` element),
+   * while the attributes are written to this element — the alternate mode CSS
+   * would never match. A dev-mode warning fires on this combination.
+   *
+   * **Prefer passing the ref object itself** (`root={rootRef}`): refs are
+   * populated before layout effects, so the runtime attaches directly to the
+   * element. Passing `rootRef.current ?? undefined` also works, but the value
+   * is `null` on the first render, causing one transient attach to `<html>`
+   * before the runtime is recreated on the element.
    *
    * @example
    * ```tsx
    * // Storybook decorator — isolates each story from <html>
    * const rootRef = React.useRef<HTMLDivElement>(null);
    * <div ref={rootRef}>
-   *   <ThemeProvider theme={myTheme} root={rootRef.current ?? undefined}>
+   *   <ThemeProvider theme={myTheme} themeId="story" root={rootRef}>
    *     <Story />
    *   </ThemeProvider>
    * </div>
    * ```
    */
-  root?: HTMLElement;
+  root?: ThemeRootInput;
   children: React.ReactNode;
 }
 /**
@@ -134,7 +149,7 @@ declare const ThemeProvider: ({
   onModeChange,
   root,
   children
-}: ThemeProviderProps) => any;
+}: ThemeProviderProps) => import("react/jsx-runtime").JSX.Element;
 /**
  * Access mode state and the mode setter — without subscribing to theme changes.
  *
@@ -178,11 +193,11 @@ declare const useColorMode: () => UseColorModeResult;
  * inline styles produces silently broken rendering:
  *
  * ```tsx
- * // ✗ WRONG — tokens.colors.brand.main is '{core.colors.brand.main}', not '#FF0000'
- * <div style={{ color: tokens.colors.brand.main }} />
+ * // ✗ WRONG — the leaf is '{core.colors.neutral.1000}' (a ref string), not a CSS color
+ * <div style={{ color: tokens.colors.action.primary.text.default }} />
  *
  * // ✓ CSS consumers — use vars:
- * <div style={{ color: 'var(--tt-color-brand-main)' }} />
+ * <div style={{ color: 'var(--tt-colors-action-primary-text-default)' }} />
  *
  * // ✓ Non-CSS consumers (React Native, canvas) — use useResolvedTokens():
  * const resolved = useResolvedTokens();
@@ -197,8 +212,8 @@ declare const useColorMode: () => UseColorModeResult;
  *
  * const Button = () => {
  *   const tokens = useTokens(); // introspection only
- *   // tokens.colors.action.primary.background.default → '{core.colors.brand.500}'
- *   return <button style={{ background: 'var(--tt-action-primary-background-default)' }} />;
+ *   // tokens.colors.action.primary.background.default → '{core.colors.neutral.1000}'
+ *   return <button style={{ background: 'var(--tt-colors-action-primary-background-default)' }} />;
  * };
  * ```
  */
@@ -218,13 +233,21 @@ declare const useTokens: () => SemanticTokens;
  *
  * ```tsx
  * // ✓ CSS (browser)
- * <div style={{ color: 'var(--tt-color-informational-primary-default)' }} />
+ * <div style={{ color: 'var(--tt-colors-informational-primary-text-default)' }} />
  *
  * // ✓ Non-CSS (React Native, canvas)
  * const resolved = useResolvedTokens();
  * <View style={{ backgroundColor: resolved['semantic.colors.action.primary.background.default'] }} />
  * ```
  *
+ * ### ⚠ CSS-coupled tokens stay unresolved
+ * A registered set of dimensional tokens (model.md §8 — spacing steps, fluid
+ * `text.*.fontSize`, `sizing.hit.*`, `sizing.viewport.*`, `sizing.measure.reading`,
+ * `spacing.gutter.*`) carry CSS-only constructs (`var()`, `calc()`, `clamp()`,
+ * `cqi`, `dvh`, `ch`). This hook returns those **as-is** — they are not usable
+ * outside a CSS engine. Colors, opacity, z-index, font weights/leading and
+ * other scalar tokens resolve to plain raw values and are safe everywhere.
+ *
  * Requires `<ThemeProvider theme={...}>`.
  *
  * @example
@@ -276,7 +299,7 @@ declare const ThemeScript: ({
   defaultMode,
   storageKey,
   nonce
-}?: ThemeScriptProps) => any;
+}?: ThemeScriptProps) => import("react/jsx-runtime").JSX.Element;
 /**
  * Props for the `ThemeStyles` component.
  */
@@ -296,6 +319,13 @@ interface ThemeStylesProps {
   themeId?: string;
   /** CSP nonce for the inline style tag. */
   nonce?: string;
+  /**
+   * Emit the `@media (prefers-color-scheme)` fallback block (themeId-less
+   * bundles only). Default `true`. Set `false` when the app's `defaultMode`
+   * is a fixed `'light'`/`'dark'` rather than `'system'` — `<ThemeHead>`
+   * derives this automatically from its `defaultMode`.
+   */
+  systemModeFallback?: boolean;
 }
 /**
  * Renders an inline `<style>` tag with all CSS Custom Properties for a theme
@@ -346,8 +376,9 @@ interface ThemeStylesProps {
 declare const ThemeStyles: ({
   theme,
   themeId,
-  nonce
-}: ThemeStylesProps) => any;
+  nonce,
+  systemModeFallback
+}: ThemeStylesProps) => import("react/jsx-runtime").JSX.Element;
 /**
  * Props for the `ThemeHead` component.
  */
@@ -406,6 +437,6 @@ declare const ThemeHead: ({
   nonce,
   defaultMode,
   storageKey
-}: ThemeHeadProps) => any;
+}: ThemeHeadProps) => import("react/jsx-runtime").JSX.Element;
 //#endregion
 export { ThemeScript as a, ThemeStylesProps as c, useResolvedTokens as d, useTokens as f, ThemeProviderProps as i, UseColorModeResult as l, ThemeHeadProps as n, ThemeScriptProps as o, ThemeProvider as r, ThemeStyles as s, ThemeHead as t, useColorMode as u };