@ttoss/fsl-theme 1.1.11

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { T as ThemeTokens, M as ModeOverride, a as ThemeBundle, D as DeepPartial } from './Types-6tR0_2Ss.js';
+export { S as SemanticTokens } from './Types-6tR0_2Ss.js';
+export { ThemeHeadProps, ThemeStylesProps } from './react.js';
+export { ThemeMode } from './runtime-entry.js';
+export { bruttal } from './themes/bruttal.js';
+export { corporate } from './themes/corporate.js';
+export { oca } from './themes/oca.js';
+export { ventures } from './themes/ventures.js';
+import 'react/jsx-runtime';
+import 'react';
+
+/**
+ * **Foundation** — Neutral baseline theme.
+ *
+ * System fonts, gray palette, and balanced proportions. Serves as the
+ * canonical base that all other themes extend via `createTheme`.
+ */
+declare const baseTheme: ThemeTokens;
+declare const darkAlternate: ModeOverride;
+
+/**
+ * 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 });
+ * ```
+ */
+declare const createTheme: ({ extends: parentBundle, baseMode, base, overrides, alternate, }?: {
+    /**
+     * Parent bundle to inherit from. `base`, `baseMode`, and `alternate` all
+     * default to the parent's values — including dark-mode inheritance.
+     *
+     * `extends` is a reserved word in JS — destructured as `parentBundle`
+     * in the implementation.
+     */
+    extends?: ThemeBundle;
+    /** Which mode the base represents. Defaults to `extends.baseMode` or `'light'`. */
+    baseMode?: "light" | "dark";
+    /** Base theme to extend. Defaults to `extends.base` or `baseTheme`. */
+    base?: ThemeTokens;
+    /** Brand overrides applied to the base theme. */
+    overrides?: DeepPartial<ThemeTokens>;
+    /**
+     * Semantic remapping overrides for the opposite mode.
+     * Defaults to `darkAlternate` when not provided (and no `extends`).
+     * Pass `null` to opt out of any alternate (single-mode theme).
+     */
+    alternate?: ModeOverride | null;
+}) => ThemeBundle;
+
+export { DeepPartial, ModeOverride, ThemeBundle, ThemeTokens, baseTheme, createTheme, darkAlternate };

package/dist/react.d.ts

@@ -0,0 +1,346 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import { ThemeMode, ResolvedMode, ThemeScriptConfig } from './runtime-entry.js';
+import { a as ThemeBundle, S as SemanticTokens } from './Types-6tR0_2Ss.js';
+
+/**
+ * Props for the `ThemeProvider` component.
+ */
+interface ThemeProviderProps {
+    /** Mode to use when no persisted value is found. Only read on initial mount. @default 'system' */
+    defaultMode?: ThemeMode;
+    /** localStorage key for persistence. Only read on initial mount. @default 'tt-theme' */
+    storageKey?: string;
+    /**
+     * Theme identifier written to `data-tt-theme`. Reactive — changing this
+     * prop recreates the runtime and rewrites the attribute so the browser
+     * matches the scoped CSS (e.g. `[data-tt-theme="<id>"]`). Provide only
+     * for MFE / multi-theme CSS scoping (Storybook toolbar, runtime theme swap).
+     */
+    themeId?: string;
+    /**
+     * The theme bundle for the app — the canonical 1-theme / 2-mode model.
+     *
+     * Passing `theme` enables `useTokens()` and `useResolvedTokens()` for all
+     * descendants, and automatically injects the CSS Custom Properties `<style>`
+     * tag into the document head (React 19 hoisting).
+     *
+     * @example
+     * ```tsx
+     * import { createTheme } from '@ttoss/fsl-theme';
+     * import { ThemeProvider } from '@ttoss/fsl-theme/react';
+     *
+     * const myTheme = createTheme();
+     *
+     * <ThemeProvider theme={myTheme}>
+     *   <App />
+     * </ThemeProvider>
+     * ```
+     */
+    theme?: ThemeBundle;
+    /**
+     * Called after each mode transition. Does **not** fire on initial mount —
+     * only on subsequent user-triggered or system-triggered mode changes.
+     *
+     * Receives both `mode` (user intent: `'light' | 'dark' | 'system'`) and
+     * `resolvedMode` (actual: `'light' | 'dark'`), covering all integration
+     * needs in one callback.
+     *
+     * @example
+     * ```tsx
+     * <ThemeProvider
+     *   theme={myTheme}
+     *   onModeChange={(mode, resolvedMode) => {
+     *     analytics.track('modeChanged', { mode, resolvedMode });
+     *   }}
+     * >
+     * ```
+     */
+    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.
+     *
+     * 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.
+     *
+     * @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}>
+     *     <Story />
+     *   </ThemeProvider>
+     * </div>
+     * ```
+     */
+    root?: HTMLElement;
+    children: React.ReactNode;
+}
+/**
+ * React provider that manages theme switching via `createThemeRuntime`.
+ *
+ * Applies `data-tt-theme` and `data-tt-mode` on `<html>` (or `root`),
+ * persists to localStorage, and listens to system color scheme changes.
+ * When `theme` is provided, automatically injects CSS Custom Properties into
+ * the document `<head>` via React 19 style hoisting.
+ *
+ * @example
+ * ```tsx
+ * import { ThemeProvider } from '@ttoss/fsl-theme/react';
+ * import { createTheme } from '@ttoss/fsl-theme';
+ *
+ * const myTheme = createTheme();
+ *
+ * export const App = () => (
+ *   <ThemeProvider theme={myTheme}>
+ *     <YourApp />
+ *   </ThemeProvider>
+ * );
+ * ```
+ */
+declare const ThemeProvider: ({ defaultMode, storageKey, theme, themeId, onModeChange, root, children, }: ThemeProviderProps) => react_jsx_runtime.JSX.Element;
+/**
+ * Access mode state and the mode setter — without subscribing to theme changes.
+ *
+ * Consumers of `useColorMode()` only re-render on mode transitions, never on
+ * `themeId` changes. Use this for components that only need dark/light toggling
+ * (e.g. a sun/moon icon button) to avoid unnecessary re-renders.
+ *
+ * Must be used within a `<ThemeProvider>`.
+ *
+ * @example
+ * ```tsx
+ * import { useColorMode } from '@ttoss/fsl-theme/react';
+ *
+ * const DarkModeToggle = () => {
+ *   const { resolvedMode, setMode } = useColorMode();
+ *   return (
+ *     <button onClick={() => setMode(resolvedMode === 'dark' ? 'light' : 'dark')}>
+ *       {resolvedMode === 'dark' ? '☀️' : '🌙'}
+ *     </button>
+ *   );
+ * };
+ * ```
+ */
+interface UseColorModeResult {
+    mode: ThemeMode;
+    resolvedMode: ResolvedMode;
+    setMode: (mode: ThemeMode) => void;
+}
+declare const useColorMode: () => UseColorModeResult;
+/**
+ * Access the current theme's **semantic tokens only** — the structural tree
+ * with **unresolved** `TokenRef` values (e.g. `'{core.colors.brand.500}'`).
+ *
+ * ### Primary use cases
+ * - Introspection and devtools
+ * - Token path comparison (e.g. checking which tokens differ between themes)
+ * - Passing to `createTheme` calls
+ *
+ * ### ✗ Do not use for styling
+ * `TokenRef` values are reference strings, not CSS values. Using them in
+ * 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 }} />
+ *
+ * // ✓ CSS consumers — use vars:
+ * <div style={{ color: 'var(--tt-color-brand-main)' }} />
+ *
+ * // ✓ Non-CSS consumers (React Native, canvas) — use useResolvedTokens():
+ * const resolved = useResolvedTokens();
+ * <View style={{ backgroundColor: resolved['semantic.colors.action.primary.background.default'] }} />
+ * ```
+ *
+ * Requires `<ThemeProvider theme={...}>`.
+ *
+ * @example
+ * ```tsx
+ * import { useTokens } from '@ttoss/fsl-theme/react';
+ *
+ * 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)' }} />;
+ * };
+ * ```
+ */
+declare const useTokens: () => SemanticTokens;
+/**
+ * Access fully resolved token values as a flat `Record<string, string | number>`.
+ *
+ * All `{ref}` indirections are resolved to their final raw values — hex colors,
+ * px sizes, unitless numbers, etc. Keys use `semantic.*` dot-path notation.
+ *
+ * ### When to use
+ * Use in non-CSS environments where CSS custom properties (`var()`) are not
+ * available: React Native, canvas renderers, PDF generation, test assertions.
+ *
+ * ### ✗ Do not use for CSS rendering
+ * CSS consumers should use `vars.*` instead for zero-JS rendering:
+ *
+ * ```tsx
+ * // ✓ CSS (browser)
+ * <div style={{ color: 'var(--tt-color-informational-primary-default)' }} />
+ *
+ * // ✓ Non-CSS (React Native, canvas)
+ * const resolved = useResolvedTokens();
+ * <View style={{ backgroundColor: resolved['semantic.colors.action.primary.background.default'] }} />
+ * ```
+ *
+ * Requires `<ThemeProvider theme={...}>`.
+ *
+ * @example
+ * ```tsx
+ * import { useResolvedTokens } from '@ttoss/fsl-theme/react';
+ *
+ * const ReactNativeButton = () => {
+ *   const resolved = useResolvedTokens();
+ *   return (
+ *     <View style={{ backgroundColor: resolved['semantic.colors.action.primary.background.default'] }}>
+ *       <Text>Click</Text>
+ *     </View>
+ *   );
+ * };
+ * ```
+ */
+declare const useResolvedTokens: () => Record<string, string | number>;
+/**
+ * Props for the `ThemeScript` component.
+ */
+interface ThemeScriptProps extends ThemeScriptConfig {
+    /** CSP nonce for the inline script. */
+    nonce?: string;
+}
+/**
+ * Renders an inline `<script>` that prevents theme flash on SSR/SSG.
+ *
+ * Place in the `<head>` before stylesheets.
+ *
+ * @example
+ * ```tsx
+ * // Next.js app/layout.tsx
+ * import { ThemeScript } from '@ttoss/fsl-theme/react';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html lang="en">
+ *       <head>
+ *         <ThemeScript defaultTheme="bruttal" />
+ *       </head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare const ThemeScript: ({ defaultTheme, defaultMode, storageKey, nonce, }?: ThemeScriptProps) => react_jsx_runtime.JSX.Element;
+/**
+ * Props for the `ThemeStyles` component.
+ */
+interface ThemeStylesProps {
+    /** The theme bundle to generate CSS for. */
+    theme: ThemeBundle;
+    /**
+     * Theme identifier for CSS scoping (`[data-tt-theme="<themeId>"]`).
+     *
+     * **Omit in the canonical 1-theme model** — CSS targets `:root` and the
+     * alternate mode selector becomes `:root[data-tt-mode="dark"]`. No theme
+     * name repetition required.
+     *
+     * Pass `themeId` only for multi-theme scenarios (Storybook, micro-frontends,
+     * apps with visual theme switching).
+     */
+    themeId?: string;
+    /** CSP nonce for the inline style tag. */
+    nonce?: string;
+}
+/**
+ * Renders an inline `<style>` tag with all CSS Custom Properties for a theme
+ * bundle — including coarse-pointer, reduced-motion, and container query
+ * progressive enhancement blocks.
+ *
+ * Use as an escape hatch for SSR frameworks that need explicit `<head>` style
+ * injection. In most React apps, `<ThemeProvider theme={...}>` already injects
+ * styles automatically via React 19 style hoisting — no `<ThemeStyles>` needed.
+ *
+ * `dangerouslySetInnerHTML` is safe: content comes exclusively from
+ * `toCssVars()` (a pure internal function) — no user input is interpolated.
+ *
+ * @example
+ * ```tsx
+ * // SSR escape hatch — no themeId needed for canonical 1-theme model
+ * import { ThemeScript, ThemeStyles } from '@ttoss/fsl-theme/react';
+ * import { createTheme } from '@ttoss/fsl-theme';
+ *
+ * const myTheme = createTheme();
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html lang="en">
+ *       <head>
+ *         <ThemeScript />
+ *         <ThemeStyles theme={myTheme} />
+ *       </head>
+ *       <body>
+ *         <ThemeProvider theme={myTheme}>{children}</ThemeProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multi-theme: explicit themeId for CSS scoping
+ * <ThemeStyles theme={brandA} themeId="brand-a" />
+ * <ThemeStyles theme={brandB} themeId="brand-b" />
+ * ```
+ */
+declare const ThemeStyles: ({ theme, themeId, nonce }: ThemeStylesProps) => react_jsx_runtime.JSX.Element;
+/**
+ * Props for the `ThemeHead` component.
+ */
+interface ThemeHeadProps extends ThemeStylesProps {
+    /** Mode to use when no persisted value is found. @default 'system' */
+    defaultMode?: ThemeMode;
+    /** localStorage key for persistence. Must match `ThemeProvider`'s `storageKey`. @default 'tt-theme' */
+    storageKey?: string;
+}
+/**
+ * Convenience component that renders both `<ThemeScript>` and `<ThemeStyles>`
+ * in a single line — the complete SSR `<head>` setup for flash-free theming.
+ *
+ * Use in SSR frameworks (Next.js, Remix) where you need explicit `<head>`
+ * injection. In CSR apps, `<ThemeProvider theme={...}>` handles everything.
+ *
+ * @example
+ * ```tsx
+ * // Next.js app/layout.tsx
+ * import { ThemeHead, ThemeProvider } from '@ttoss/fsl-theme/react';
+ * import { createTheme } from '@ttoss/fsl-theme';
+ *
+ * const myTheme = createTheme();
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html lang="en">
+ *       <head>
+ *         <ThemeHead theme={myTheme} />
+ *       </head>
+ *       <body>
+ *         <ThemeProvider theme={myTheme}>{children}</ThemeProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare const ThemeHead: ({ theme, themeId, nonce, defaultMode, storageKey, }: ThemeHeadProps) => react_jsx_runtime.JSX.Element;
+
+export { ResolvedMode, ThemeHead, type ThemeHeadProps, ThemeMode, ThemeProvider, type ThemeProviderProps, ThemeScript, type ThemeScriptProps, ThemeStyles, type ThemeStylesProps, type UseColorModeResult, useColorMode, useResolvedTokens, useTokens };

package/dist/runtime-entry.d.ts

@@ -0,0 +1,95 @@
+declare const DATA_THEME_ATTR = "data-tt-theme";
+declare const DATA_MODE_ATTR = "data-tt-mode";
+/**
+ * Theme mode. `'system'` delegates to the OS `prefers-color-scheme` preference.
+ */
+type ThemeMode = 'light' | 'dark' | 'system';
+/**
+ * Resolved mode — always `'light'` or `'dark'` (never `'system'`).
+ */
+type ResolvedMode = 'light' | 'dark';
+/**
+ * Snapshot of the current theme state.
+ */
+interface ThemeState {
+    mode: ThemeMode;
+    resolvedMode: ResolvedMode;
+}
+/**
+ * Configuration for `createThemeRuntime()`.
+ */
+interface ThemeRuntimeConfig {
+    /** Theme identifier written to `data-tt-theme`. Provide only for MFE / multi-theme CSS scoping. When omitted, `data-tt-theme` is not written to the DOM. */
+    defaultTheme?: string;
+    /** Mode to use when no persisted value is found. @default 'system' */
+    defaultMode?: ThemeMode;
+    /** localStorage key for persistence. @default 'tt-theme' */
+    storageKey?: string;
+    /** Root element to apply data attributes to. @default document.documentElement */
+    root?: HTMLElement;
+}
+/**
+ * Public API returned by `createThemeRuntime()`.
+ */
+interface ThemeRuntime {
+    getState: () => ThemeState;
+    setMode: (mode: ThemeMode) => void;
+    subscribe: (listener: (state: ThemeState) => void) => () => void;
+    destroy: () => void;
+}
+/**
+ * Creates a framework-agnostic runtime that manages theme switching.
+ *
+ * - Sets `data-tt-mode` (and `data-tt-theme` when `defaultTheme` is provided) attributes on the root element.
+ * - Updates `style.colorScheme` for native dark/light UI.
+ * - Persists `{ mode }` to localStorage.
+ * - Listens to `prefers-color-scheme` media query when mode is `'system'`.
+ * - Pub/sub pattern for state changes.
+ *
+ * @example
+ * ```ts
+ * const runtime = createThemeRuntime({ defaultMode: 'dark' });
+ * runtime.setMode('system');
+ * const unsub = runtime.subscribe(console.log);
+ * runtime.destroy();
+ * ```
+ */
+declare const createThemeRuntime: (config?: ThemeRuntimeConfig) => ThemeRuntime;
+
+/**
+ * Configuration for the SSR bootstrap script.
+ */
+interface ThemeScriptConfig {
+    /** Theme identifier written to `data-tt-theme`. When omitted, `data-tt-theme` is not written. */
+    defaultTheme?: string;
+    /** Mode to use when no persisted value is found. @default 'system' */
+    defaultMode?: ThemeMode;
+    /** localStorage key. Must match the runtime's `storageKey`. @default 'tt-theme' */
+    storageKey?: string;
+}
+/**
+ * Returns self-contained JavaScript code that prevents theme flash on SSR/SSG.
+ *
+ * Insert the returned string into an inline `<script>` tag in the `<head>`,
+ * before any stylesheets or the app bundle.
+ *
+ * @example
+ * ```tsx
+ * // Next.js app/layout.tsx
+ * import { getThemeScriptContent } from '@ttoss/fsl-theme/runtime';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html lang="en">
+ *       <head>
+ *         <script dangerouslySetInnerHTML={{ __html: getThemeScriptContent() }} />
+ *       </head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare const getThemeScriptContent: (config?: ThemeScriptConfig) => string;
+
+export { DATA_MODE_ATTR, DATA_THEME_ATTR, type ResolvedMode, type ThemeMode, type ThemeRuntime, type ThemeRuntimeConfig, type ThemeScriptConfig, type ThemeState, createThemeRuntime, getThemeScriptContent };

package/dist/themes/bruttal.d.ts

@@ -0,0 +1,5 @@
+import { a as ThemeBundle } from '../Types-6tR0_2Ss.js';
+
+declare const bruttal: ThemeBundle;
+
+export { bruttal };

package/dist/themes/corporate.d.ts

@@ -0,0 +1,5 @@
+import { a as ThemeBundle } from '../Types-6tR0_2Ss.js';
+
+declare const corporate: ThemeBundle;
+
+export { corporate };

package/dist/themes/oca.d.ts

@@ -0,0 +1,5 @@
+import { a as ThemeBundle } from '../Types-6tR0_2Ss.js';
+
+declare const oca: ThemeBundle;
+
+export { oca };

package/dist/themes/ventures.d.ts

@@ -0,0 +1,5 @@
+import { a as ThemeBundle } from '../Types-6tR0_2Ss.js';
+
+declare const ventures: ThemeBundle;
+
+export { ventures };

package/dist/vars.d.ts

@@ -0,0 +1,127 @@
+import { T as ThemeTokens, S as SemanticTokens } from './Types-6tR0_2Ss.js';
+
+/**
+ * Transforms a token-tree type into an identical structure where every leaf
+ * value becomes `string` (a CSS `var(--tt-*)` reference).
+ *
+ * Keys starting with `$` (e.g. `$deprecated`) are excluded — they are
+ * metadata, not consumable tokens.
+ *
+ * Optional keys in the source type remain optional in the mapped type, so
+ * theme extensions such as `dataviz?` are typed as `CssVarsMap<...> | undefined`
+ * and TypeScript will require callers to guard against `undefined` before
+ * accessing their members.
+ *
+ * @example
+ * ```ts
+ * type Colors = { action: { primary: { background: { default: TokenRef } } } };
+ * type ColorVars = CssVarsMap<Colors>;
+ * // → { action: { primary: { background: { default: string } } } }
+ * ```
+ */
+type CssVarsMap<T> = {
+    [K in keyof T as K extends `$${string}` ? never : K]: NonNullable<T[K]> extends string | number ? string : undefined extends T[K] ? CssVarsMap<NonNullable<T[K]>> | undefined : CssVarsMap<NonNullable<T[K]>>;
+};
+/**
+ * Build a deeply-nested CSS var-reference map from a theme's semantic layer.
+ *
+ * Walks `theme.semantic` recursively and replaces every leaf value with the
+ * corresponding `var(--tt-*)` CSS custom property reference. The resulting
+ * object has the exact same shape as `theme.semantic` but with `string` leaves.
+ *
+ * Keys starting with `$` are skipped (deprecation metadata).
+ *
+ * @example
+ * ```ts
+ * import { buildVarsMap } from './roots/toVars';
+ * import { baseTheme } from './baseTheme';
+ *
+ * const vars = buildVarsMap(baseTheme);
+ * vars.colors.action.primary.background.default
+ * // → 'var(--tt-action-primary-background-default)'
+ * ```
+ */
+declare const buildVarsMap: (theme: ThemeTokens) => CssVarsMap<ThemeTokens["semantic"]>;
+
+/**
+ * Static map of all semantic tokens as typed CSS `var(--tt-*)` references.
+ *
+ * Every leaf value is a CSS Custom Property reference string — zero runtime
+ * overhead, full autocomplete, structural parity with `SemanticTokens`.
+ *
+ * The var names are stable across themes and modes: only the values behind
+ * the CSS vars change when the theme or mode switches. Components reference
+ * the vars; CSS (generated by `toCssVars`) carries the values.
+ *
+ * ## Usage with Ark UI / CSS-in-JS
+ *
+ * ```tsx
+ * import { vars } from '@ttoss/fsl-theme/vars';
+ *
+ * <Button style={{ background: vars.colors.action.primary.background.default }} />
+ * // → background: 'var(--tt-action-primary-background-default)'
+ * ```
+ *
+ * ## Usage in CSS / CSS Modules
+ *
+ * ```css
+ * .button {
+ *   background: var(--tt-action-primary-background-default);
+ *   color: var(--tt-action-primary-text-default);
+ * }
+ * ```
+ *
+ * (For plain CSS you can use the var names directly — `vars` is most valuable
+ * when you need TypeScript autocomplete in inline styles or CSS-in-JS.)
+ *
+ * ## Usage in Tailwind plugins / PostCSS
+ *
+ * ```ts
+ * import { toCssVarName } from '@ttoss/fsl-theme/css';
+ * // toCssVarName gives you the raw CSS property name without `var()`.
+ * ```
+ *
+ * ## Limitations
+ *
+ * `vars` reflects the semantic token shape of the **default theme**. If your
+ * project extends `SemanticTokens` with custom token families (e.g. a
+ * `dataviz` palette, project-specific component tokens), those extra leaves
+ * won't appear on this export.
+ *
+ * ### Typed extension recipe
+ *
+ * Build your own typed vars object using the public `buildVarsMap` helper
+ * together with `CssVarsMap`:
+ *
+ * ```ts
+ * // my-theme.ts
+ * import { createTheme, type SemanticTokens } from '@ttoss/fsl-theme';
+ * import { buildVarsMap, type CssVarsMap } from '@ttoss/fsl-theme/vars';
+ *
+ * // 1. Extend the semantic shape structurally.
+ * type MySemanticTokens = SemanticTokens & {
+ *   colors: SemanticTokens['colors'] & {
+ *     brandX: { primary: { default: string } };
+ *   };
+ * };
+ *
+ * const myTheme = createTheme({ ... });
+ *
+ * // 2. Build a typed mirror of the extended shape.
+ * export const myVars: CssVarsMap<MySemanticTokens> =
+ *   buildVarsMap(myTheme.base) as CssVarsMap<MySemanticTokens>;
+ *
+ * myVars.colors.brandX.primary.default;
+ * // → 'var(--tt-colors-brandx-primary-default)'
+ * ```
+ *
+ * For one-off custom keys where the extra structure is trivial, use
+ * `toCssVarName` from `'@ttoss/fsl-theme/css'` to construct individual var
+ * references without declaring a full extended type.
+ *
+ * @see {@link toCssVarName}        — for raw CSS property names (without `var()`)
+ * @see {@link useResolvedTokens}  — for resolved raw values in non-CSS environments (React Native, canvas, PDF)
+ */
+declare const vars: CssVarsMap<SemanticTokens>;
+
+export { type CssVarsMap, buildVarsMap, vars };