@ttoss/fsl-theme 2.0.0 → 2.1.0

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-Drr-QSuX.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-BwsjWKmo.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-C8JrZf-b.d.mts → react-BwsjWKmo.d.mts}

@@ -1,9 +1,17 @@
 
-import { i as ThemeBundle, n as SemanticTokens } from "./Types-BkaxtsMv.mjs";
+import { i as ThemeBundle, n as SemanticTokens } from "./Types-a_sfpbha.mjs";
 import { a as ResolvedMode, o as ThemeMode, t as ThemeScriptConfig } from "./ssrScript-BVysxDws.mjs";
 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;
 }
 /**
@@ -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
@@ -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,7 +376,8 @@ interface ThemeStylesProps {
 declare const ThemeStyles: ({
   theme,
   themeId,
-  nonce
+  nonce,
+  systemModeFallback
 }: ThemeStylesProps) => any;
 /**
  * Props for the `ThemeHead` component.