@ttoss/fsl-theme 1.1.22 → 2.0.0

package/README.md

@@ -10,15 +10,15 @@ pnpm add @ttoss/fsl-theme
 
 ## Entry points
 
-| Import                     | Exports                                                                                                                                                                                         |
-| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@ttoss/fsl-theme`         | `createTheme`, `darkAlternate`, built-in themes (`bruttal`, `corporate`, `oca`, `ventures`), types (`ThemeTokens`, `ThemeBundle`, `SemanticTokens`, `ModeOverride`, `DeepPartial`, `ThemeMode`) |
-| `@ttoss/fsl-theme/react`   | `ThemeProvider`, `ThemeHead`, `ThemeScript`, `ThemeStyles`, `useColorMode`, `useTokens`, `useResolvedTokens`                                                                                    |
-| `@ttoss/fsl-theme/dataviz` | `withDataviz`, `useDatavizTokens`                                                                                                                                                               |
-| `@ttoss/fsl-theme/css`     | `getThemeStylesContent`, `toCssVars`, `toCssVarName`, `toFlatTokens`                                                                                                                            |
-| `@ttoss/fsl-theme/vars`    | `vars`, `buildVarsMap`, type `CssVarsMap`                                                                                                                                                       |
-| `@ttoss/fsl-theme/dtcg`    | `toDTCG` (W3C Design Tokens format)                                                                                                                                                             |
-| `@ttoss/fsl-theme/runtime` | `createThemeRuntime`, `getThemeScriptContent`                                                                                                                                                   |
+| Import                     | Exports                                                                                                                                                                     |
+| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@ttoss/fsl-theme`         | `createTheme`, `baseTheme`, `darkAlternate`, built-in theme (`bruttal`), types (`ThemeTokens`, `ThemeBundle`, `SemanticTokens`, `ModeOverride`, `DeepPartial`, `ThemeMode`) |
+| `@ttoss/fsl-theme/react`   | `ThemeProvider`, `ThemeHead`, `ThemeScript`, `ThemeStyles`, `useColorMode`, `useTokens`, `useResolvedTokens`                                                                |
+| `@ttoss/fsl-theme/dataviz` | `withDataviz`, `useDatavizTokens`                                                                                                                                           |
+| `@ttoss/fsl-theme/css`     | `getThemeStylesContent`, `toCssVars`, `toCssVarName`, `toFlatTokens`                                                                                                        |
+| `@ttoss/fsl-theme/vars`    | `vars`, `buildVarsMap`, type `CssVarsMap`                                                                                                                                   |
+| `@ttoss/fsl-theme/dtcg`    | `toDTCG` (W3C Design Tokens format)                                                                                                                                         |
+| `@ttoss/fsl-theme/runtime` | `createThemeRuntime`, `getThemeScriptContent`                                                                                                                               |
 
 ## Token architecture
 
@@ -53,7 +53,7 @@ One entry per semantic family. Use `vars.*` for typed CSS variable references; u
 |           | `semantic.border.outline.{surface,control,selected}`                | `{width, style}`        |
 | focus     | `semantic.focus.ring`                                               | `{width, style, color}` |
 | elevation | `semantic.elevation.surface.{flat,raised,overlay,blocking}`         | CSS box-shadow          |
-|           | `semantic.elevation.tonal.{flat,raised,overlay,blocking}`           | CSS color (optional)    |
+|           | `semantic.elevation.tonal.{raised,overlay,blocking}`                | CSS color (optional)    |
 | opacity   | `semantic.opacity.{scrim,loading,disabled}`                         | number in (0, 1)        |
 | overlay   | `semantic.overlay.scrim`                                            | CSS color with alpha    |
 | motion    | `semantic.motion.{feedback,emphasis,decorative}`                    | `{duration, easing}`    |
@@ -290,7 +290,9 @@ For one-off custom keys, use `toCssVarName` from `@ttoss/fsl-theme/css` directly
 
 ### React 19 App Router (recommended)
 
-`ThemeProvider` with a `theme` prop uses React 19 style hoisting to inject CSS into `<head>` automatically. Only add `ThemeScript` for flash-prevention:
+`ThemeProvider` with a `theme` prop uses React 19 style hoisting to inject CSS into `<head>` automatically. The injected `<style>` carries a stable `href` (`tt-theme-<themeId|root>`), so multiple providers or a re-render collapse to a single tag instead of duplicating. Only add `ThemeScript` for flash-prevention:
+
+> **React 18:** auto-injection into `<head>` requires React 19 style hoisting. On React 18 the `<ThemeProvider>` `<style>` renders inline where the provider sits — use the `ThemeHead` / `ThemeStyles` path below to place CSS in `<head>` explicitly.
 
 ```tsx
 // app/layout.tsx
@@ -348,7 +350,7 @@ export default function RootLayout({
 }
 ```
 
-> **Warning:** Do not combine `<ThemeHead theme={...}>` with `<ThemeProvider theme={...}>`. Both inject CSS — `ThemeHead` via a plain `<style>` tag and `ThemeProvider` via React 19 style hoisting — resulting in duplicate CSS in the document. Use one or the other.
+> **Warning:** Do not pass `theme` to **both** `<ThemeHead>` and `<ThemeProvider>`. `ThemeHead` injects a plain `<style>`; `ThemeProvider` injects a React-19-hoisted `<style>` — different mechanisms that do **not** dedup against each other, so you get duplicate CSS. Pass `theme` to the head component only; the body `<ThemeProvider>` (no `theme`) manages mode. (Multiple `<ThemeProvider theme={...}>` on React 19 _do_ dedup, via the shared `href`.)
 
 ## Dataviz extension
 

package/dist/{Types-BiBa17RL.d.cts → Types-BkaxtsMv.d.cts}

@@ -42,7 +42,7 @@ interface CoreDataviz {
  *   dataviz.color.scale.diverging.neg3..pos3
  *   dataviz.color.reference.baseline / target
  *   dataviz.color.state.highlight / muted / selected
- *   dataviz.color.status.missing / suppressed / not-applicable
+ *   dataviz.color.status.missing / suppressed / notApplicable
  */
 interface SemanticDatavizColor {
   /**
@@ -82,7 +82,7 @@ interface SemanticDatavizColor {
   status: {
     /** Value is absent or unavailable. */missing: TokenRef; /** Value is withheld for confidentiality or publication rules. */
     suppressed: TokenRef; /** Value is structurally absent (not measured or not applicable). */
-    na: TokenRef;
+    notApplicable: TokenRef;
   };
 }
 /**
@@ -440,7 +440,7 @@ interface FeedbackColorStates {
 interface ColorDimensionOf<S extends BaseColorStates> {
   /** Fills and surface backgrounds. Use for any colored area larger than a line. */
   background?: S;
-  /** Outlines, separators, rings, and other line-color pairings. For line *geometry* (width, style) consume `semantic.borders.*` instead — this dimension is colour only. */
+  /** Outlines, separators, rings, and other line-color pairings. For line *geometry* (width, style) consume `semantic.border.*` instead — this dimension is colour only. */
   border?: S;
   /** Readable foreground — labels, paragraphs, and text-like icons that inherit `currentColor`. */
   text?: S;
@@ -587,7 +587,7 @@ interface SemanticElevation {
    * Tonal overlay tokens — optional surface color treatments paired with shadows
    * to preserve depth perception in dark or heavily-colored themes.
    *
-   * Each token typically resolves to a color overlay (e.g., `color-mix`, rgba surface).
+   * Each token resolves to a color overlay (e.g., `color-mix`, rgba surface).
    * Omit when the product does not use tonal elevation.
    * When present, must cover the same strata that carry visible shadows.
    * @see elevation.md — "Surface + Shadow"
@@ -595,8 +595,8 @@ interface SemanticElevation {
   tonal?: {
     /**
      * Tonal surface treatment paired with `surface.raised`.
-     * Use when the raised stratum needs an additional color overlay (typical in
-     * dark themes where shadow alone is insufficient).
+     * Use when the raised stratum needs an additional color overlay — dark
+     * themes where shadow alone is insufficient.
      * Pair with `surface.raised`; do not use without the matching shadow contract.
      */
     raised: CoreColorRef;
@@ -957,13 +957,13 @@ interface GapStackSteps {
 interface GapInlineSteps {
   /** Visual-only tight grouping (icon + label inside a single target). Never between focusable targets — use `separation.interactive.min`. */
   xs: CoreSpacingRef;
-  /** Inline grouping — same magnitude as `gap.stack.xs`. */
+  /** Tight inline grouping between related inline siblings. */
   sm: CoreSpacingRef;
-  /** Looser inline grouping — same magnitude as `gap.stack.sm`. */
+  /** Default inline grouping — pick this when no other step applies. */
   md: CoreSpacingRef;
-  /** Spacious inline grouping — same magnitude as `gap.stack.md`. */
+  /** Spacious inline grouping. */
   lg: CoreSpacingRef;
-  /** Wide inline grouping — same magnitude as `gap.stack.lg`. */
+  /** Wide inline grouping — the loosest step before a group break. */
   xl: CoreSpacingRef;
 }
 interface SemanticSpacing {
@@ -1014,7 +1014,7 @@ interface SemanticSpacing {
   /**
    * Structural outer padding for page-level and section-level layout regions.
    * `page` and `section` may use a `clamp()` expression with embedded `{token.path}` refs
-   * (e.g. `clamp({core.space.4}, {core.space.6}, {core.space.12})`).
+   * (e.g. `clamp({core.spacing.4}, {core.spacing.6}, {core.spacing.12})`).
    * Typed as `RawValue` to allow both simple refs and responsive clamp expressions.
    */
   gutter: {
@@ -1035,7 +1035,7 @@ interface SemanticSpacing {
   /**
    * Ergonomic separation between independently actionable targets in dense clusters.
    * May use a `clamp()` expression with an embedded `{token.path}` ref
-   * (e.g. `clamp(8px, {core.space.2}, 12px)`).
+   * (e.g. `clamp(8px, {core.spacing.2}, 12px)`).
    */
   separation: {
     interactive: {
@@ -1368,6 +1368,47 @@ interface ThemeTokens {
 interface ModeOverride {
   semantic: DeepPartial<ThemeTokens['semantic']>;
 }
+/**
+ * Machine-readable theme brief — the design intent a theme declares *before*
+ * token values are chosen (theme-authoring.md §"Theme brief"). It is the home
+ * for the `FSL-DESIGN-001..003` gate (posture, density, accessibility target)
+ * so those rules can be validated rather than living only as prose.
+ *
+ * **Orthogonal to tokens.** The brief lives on `ThemeBundle` alongside `base`,
+ * never inside the token tree — DTCG and CSS emitters read `bundle.base`, so a
+ * brief never affects interchange or CSS output. Optional by design: existing
+ * `createTheme` callers stay valid.
+ *
+ * Allowed values mirror theme-authoring.md §"Allowed values".
+ */
+interface ThemeBrief {
+  /** Theme identity name (e.g. `'base'`, `'bruttal'`). */
+  name: string;
+  /** One line on what experience this theme should produce. */
+  purpose?: string;
+  /** Dominant behavioral personality (FSL-DESIGN-001). */
+  primaryPosture: 'calm' | 'productive' | 'technical' | 'expressive' | 'editorial' | 'premium';
+  /** Optional secondary posture; one posture must dominate. */
+  secondaryPosture?: ThemeBrief['primaryPosture'];
+  /** Operational compactness (FSL-DESIGN-002). */
+  densityProfile: 'compact' | 'balanced' | 'comfortable' | 'spacious';
+  /** Reading vs operating vs scanning bias of the interface. */
+  readingMode?: 'reading' | 'operating' | 'scanning' | 'mixed';
+  /** Primary pointer type the hit-target model targets. */
+  pointerProfile?: 'fine' | 'coarse' | 'hybrid';
+  /** Risk profile of adjacent interactions. */
+  interactionRisk?: 'low' | 'medium' | 'high';
+  /** Surface layering strategy. */
+  surfaceModel?: 'flat' | 'lightly-layered' | 'layered' | 'immersive';
+  /** How much brand presence the theme carries. */
+  brandEnergy?: 'quiet' | 'balanced' | 'expressive';
+  /** Non-negotiable accessibility floor (FSL-DESIGN-003). */
+  accessibilityTarget: 'AA' | 'AA+' | 'AAA-like';
+  /** Color-mode support strategy. */
+  colorModeStrategy?: 'light-only' | 'dark-supported' | 'dark-first' | 'adaptive';
+  /** Primary platform the theme is tuned for. */
+  platformBias?: 'web' | 'mobile' | 'desktop' | 'cross-platform';
+}
 /**
  * A theme bundle packages a complete `ThemeTokens` (the base)
  * with an optional semantic-only override for the alternate color mode.
@@ -1413,6 +1454,13 @@ interface ThemeBundle {
    * Only semantic references that differ need to be listed — core tokens are shared.
    */
   alternate?: ModeOverride;
+  /**
+   * Machine-readable design brief (posture, density, accessibility target, …).
+   * Orthogonal to tokens — never serialized into DTCG/CSS. Optional so existing
+   * callers stay valid; carrying one lets `FSL-DESIGN-001..003` be enforced.
+   * @see {@link ThemeBrief}
+   */
+  meta?: ThemeBrief;
 }
 /**
  * The semantic token layer of a theme. This is the **only** part of the token
@@ -1424,4 +1472,4 @@ interface ThemeBundle {
  */
 type SemanticTokens = ThemeTokens['semantic'];
 //#endregion
-export { DeepPartial as a, ThemeTokens as i, SemanticTokens as n, CoreDataviz as o, ThemeBundle as r, SemanticDataviz as s, ModeOverride as t };
+export { ThemeTokens as a, SemanticDataviz as c, ThemeBundle as i, SemanticTokens as n, DeepPartial as o, ThemeBrief as r, CoreDataviz as s, ModeOverride as t };

package/dist/{Types-BiBa17RL.d.mts → Types-BkaxtsMv.d.mts}

@@ -42,7 +42,7 @@ interface CoreDataviz {
  *   dataviz.color.scale.diverging.neg3..pos3
  *   dataviz.color.reference.baseline / target
  *   dataviz.color.state.highlight / muted / selected
- *   dataviz.color.status.missing / suppressed / not-applicable
+ *   dataviz.color.status.missing / suppressed / notApplicable
  */
 interface SemanticDatavizColor {
   /**
@@ -82,7 +82,7 @@ interface SemanticDatavizColor {
   status: {
     /** Value is absent or unavailable. */missing: TokenRef; /** Value is withheld for confidentiality or publication rules. */
     suppressed: TokenRef; /** Value is structurally absent (not measured or not applicable). */
-    na: TokenRef;
+    notApplicable: TokenRef;
   };
 }
 /**
@@ -440,7 +440,7 @@ interface FeedbackColorStates {
 interface ColorDimensionOf<S extends BaseColorStates> {
   /** Fills and surface backgrounds. Use for any colored area larger than a line. */
   background?: S;
-  /** Outlines, separators, rings, and other line-color pairings. For line *geometry* (width, style) consume `semantic.borders.*` instead — this dimension is colour only. */
+  /** Outlines, separators, rings, and other line-color pairings. For line *geometry* (width, style) consume `semantic.border.*` instead — this dimension is colour only. */
   border?: S;
   /** Readable foreground — labels, paragraphs, and text-like icons that inherit `currentColor`. */
   text?: S;
@@ -587,7 +587,7 @@ interface SemanticElevation {
    * Tonal overlay tokens — optional surface color treatments paired with shadows
    * to preserve depth perception in dark or heavily-colored themes.
    *
-   * Each token typically resolves to a color overlay (e.g., `color-mix`, rgba surface).
+   * Each token resolves to a color overlay (e.g., `color-mix`, rgba surface).
    * Omit when the product does not use tonal elevation.
    * When present, must cover the same strata that carry visible shadows.
    * @see elevation.md — "Surface + Shadow"
@@ -595,8 +595,8 @@ interface SemanticElevation {
   tonal?: {
     /**
      * Tonal surface treatment paired with `surface.raised`.
-     * Use when the raised stratum needs an additional color overlay (typical in
-     * dark themes where shadow alone is insufficient).
+     * Use when the raised stratum needs an additional color overlay — dark
+     * themes where shadow alone is insufficient.
      * Pair with `surface.raised`; do not use without the matching shadow contract.
      */
     raised: CoreColorRef;
@@ -957,13 +957,13 @@ interface GapStackSteps {
 interface GapInlineSteps {
   /** Visual-only tight grouping (icon + label inside a single target). Never between focusable targets — use `separation.interactive.min`. */
   xs: CoreSpacingRef;
-  /** Inline grouping — same magnitude as `gap.stack.xs`. */
+  /** Tight inline grouping between related inline siblings. */
   sm: CoreSpacingRef;
-  /** Looser inline grouping — same magnitude as `gap.stack.sm`. */
+  /** Default inline grouping — pick this when no other step applies. */
   md: CoreSpacingRef;
-  /** Spacious inline grouping — same magnitude as `gap.stack.md`. */
+  /** Spacious inline grouping. */
   lg: CoreSpacingRef;
-  /** Wide inline grouping — same magnitude as `gap.stack.lg`. */
+  /** Wide inline grouping — the loosest step before a group break. */
   xl: CoreSpacingRef;
 }
 interface SemanticSpacing {
@@ -1014,7 +1014,7 @@ interface SemanticSpacing {
   /**
    * Structural outer padding for page-level and section-level layout regions.
    * `page` and `section` may use a `clamp()` expression with embedded `{token.path}` refs
-   * (e.g. `clamp({core.space.4}, {core.space.6}, {core.space.12})`).
+   * (e.g. `clamp({core.spacing.4}, {core.spacing.6}, {core.spacing.12})`).
    * Typed as `RawValue` to allow both simple refs and responsive clamp expressions.
    */
   gutter: {
@@ -1035,7 +1035,7 @@ interface SemanticSpacing {
   /**
    * Ergonomic separation between independently actionable targets in dense clusters.
    * May use a `clamp()` expression with an embedded `{token.path}` ref
-   * (e.g. `clamp(8px, {core.space.2}, 12px)`).
+   * (e.g. `clamp(8px, {core.spacing.2}, 12px)`).
    */
   separation: {
     interactive: {
@@ -1368,6 +1368,47 @@ interface ThemeTokens {
 interface ModeOverride {
   semantic: DeepPartial<ThemeTokens['semantic']>;
 }
+/**
+ * Machine-readable theme brief — the design intent a theme declares *before*
+ * token values are chosen (theme-authoring.md §"Theme brief"). It is the home
+ * for the `FSL-DESIGN-001..003` gate (posture, density, accessibility target)
+ * so those rules can be validated rather than living only as prose.
+ *
+ * **Orthogonal to tokens.** The brief lives on `ThemeBundle` alongside `base`,
+ * never inside the token tree — DTCG and CSS emitters read `bundle.base`, so a
+ * brief never affects interchange or CSS output. Optional by design: existing
+ * `createTheme` callers stay valid.
+ *
+ * Allowed values mirror theme-authoring.md §"Allowed values".
+ */
+interface ThemeBrief {
+  /** Theme identity name (e.g. `'base'`, `'bruttal'`). */
+  name: string;
+  /** One line on what experience this theme should produce. */
+  purpose?: string;
+  /** Dominant behavioral personality (FSL-DESIGN-001). */
+  primaryPosture: 'calm' | 'productive' | 'technical' | 'expressive' | 'editorial' | 'premium';
+  /** Optional secondary posture; one posture must dominate. */
+  secondaryPosture?: ThemeBrief['primaryPosture'];
+  /** Operational compactness (FSL-DESIGN-002). */
+  densityProfile: 'compact' | 'balanced' | 'comfortable' | 'spacious';
+  /** Reading vs operating vs scanning bias of the interface. */
+  readingMode?: 'reading' | 'operating' | 'scanning' | 'mixed';
+  /** Primary pointer type the hit-target model targets. */
+  pointerProfile?: 'fine' | 'coarse' | 'hybrid';
+  /** Risk profile of adjacent interactions. */
+  interactionRisk?: 'low' | 'medium' | 'high';
+  /** Surface layering strategy. */
+  surfaceModel?: 'flat' | 'lightly-layered' | 'layered' | 'immersive';
+  /** How much brand presence the theme carries. */
+  brandEnergy?: 'quiet' | 'balanced' | 'expressive';
+  /** Non-negotiable accessibility floor (FSL-DESIGN-003). */
+  accessibilityTarget: 'AA' | 'AA+' | 'AAA-like';
+  /** Color-mode support strategy. */
+  colorModeStrategy?: 'light-only' | 'dark-supported' | 'dark-first' | 'adaptive';
+  /** Primary platform the theme is tuned for. */
+  platformBias?: 'web' | 'mobile' | 'desktop' | 'cross-platform';
+}
 /**
  * A theme bundle packages a complete `ThemeTokens` (the base)
  * with an optional semantic-only override for the alternate color mode.
@@ -1413,6 +1454,13 @@ interface ThemeBundle {
    * Only semantic references that differ need to be listed — core tokens are shared.
    */
   alternate?: ModeOverride;
+  /**
+   * Machine-readable design brief (posture, density, accessibility target, …).
+   * Orthogonal to tokens — never serialized into DTCG/CSS. Optional so existing
+   * callers stay valid; carrying one lets `FSL-DESIGN-001..003` be enforced.
+   * @see {@link ThemeBrief}
+   */
+  meta?: ThemeBrief;
 }
 /**
  * The semantic token layer of a theme. This is the **only** part of the token
@@ -1424,4 +1472,4 @@ interface ThemeBundle {
  */
 type SemanticTokens = ThemeTokens['semantic'];
 //#endregion
-export { DeepPartial as a, ThemeTokens as i, SemanticTokens as n, CoreDataviz as o, ThemeBundle as r, SemanticDataviz as s, ModeOverride as t };
+export { ThemeTokens as a, SemanticDataviz as c, ThemeBundle as i, SemanticTokens as n, DeepPartial as o, ThemeBrief as r, CoreDataviz as s, ModeOverride as t };

package/dist/{baseBundle-BWbICg4p.cjs → baseBundle-DdRSa5mf.cjs}

@@ -1,5 +1,5 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-const require_createTheme = require('./createTheme-BHGc1IFI.cjs');
+const require_createTheme = require('./createTheme--UFgVlEn.cjs');
 
 //#region src/baseBundle.ts
 /**
@@ -10,7 +10,8 @@ const require_createTheme = require('./createTheme-BHGc1IFI.cjs');
 */
 var baseBundle = require_createTheme.createTheme({
   base: require_createTheme.baseTheme,
-  alternate: require_createTheme.darkAlternate
+  alternate: require_createTheme.darkAlternate,
+  brief: require_createTheme.baseBrief
 });
 
 //#endregion

package/dist/{baseBundle-DiYlHNG5.mjs → baseBundle-R7WyjyTw.mjs}

@@ -1,5 +1,5 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { i as darkAlternate, n as createTheme, r as baseTheme } from "./createTheme-C1r5nJco.mjs";
+import { a as darkAlternate, i as baseTheme, n as createTheme, r as baseBrief } from "./createTheme-B6tVIikC.mjs";
 
 //#region src/baseBundle.ts
 /**
@@ -10,7 +10,8 @@ import { i as darkAlternate, n as createTheme, r as baseTheme } from "./createTh
 */
 var baseBundle = createTheme({
   base: baseTheme,
-  alternate: darkAlternate
+  alternate: darkAlternate,
+  brief: baseBrief
 });
 
 //#endregion

package/dist/{createTheme-BHGc1IFI.cjs → createTheme--UFgVlEn.cjs}

@@ -1,5 +1,5 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-const require_helpers = require('./helpers-CIqeJ8yd.cjs');
+const require_helpers = require('./helpers-BU40JvFA.cjs');
 
 //#region src/baseTheme.ts
 /**
@@ -1741,6 +1741,26 @@ var darkAlternate = {
     }
   }
 };
+/**
+* Design brief for the base theme — the recommended default from
+* theme-authoring.md §"Recommended base theme brief". Attached to the base
+* bundle via `createTheme({ brief })`; carries the `FSL-DESIGN-001..003` gate.
+*/
+var baseBrief = {
+  name: "base",
+  purpose: "default built-in foundation for modern product UI",
+  primaryPosture: "productive",
+  secondaryPosture: "calm",
+  densityProfile: "balanced",
+  readingMode: "mixed",
+  pointerProfile: "hybrid",
+  interactionRisk: "medium",
+  surfaceModel: "lightly-layered",
+  brandEnergy: "quiet",
+  accessibilityTarget: "AA+",
+  colorModeStrategy: "dark-supported",
+  platformBias: "web"
+};
 
 //#endregion
 //#region src/roots/validateRefs.ts
@@ -1880,22 +1900,33 @@ var createTheme = ({
   baseMode,
   base,
   overrides,
-  alternate
+  alternate,
+  brief
 } = {}) => {
   const resolvedBase = base ?? parentBundle?.base;
   const resolvedBaseMode = baseMode ?? parentBundle?.baseMode ?? "light";
   const resolvedAlternate = resolveAlternate(alternate, parentBundle);
+  const resolvedMeta = brief ?? parentBundle?.meta;
   return {
     baseMode: resolvedBaseMode,
     base: buildTheme({
       base: resolvedBase,
       overrides
     }),
-    alternate: resolvedAlternate
+    alternate: resolvedAlternate,
+    ...(resolvedMeta ? {
+      meta: resolvedMeta
+    } : {})
   };
 };
 
 //#endregion
+Object.defineProperty(exports, 'baseBrief', {
+  enumerable: true,
+  get: function () {
+    return baseBrief;
+  }
+});
 Object.defineProperty(exports, 'baseTheme', {
   enumerable: true,
   get: function () {

package/dist/{createTheme-C1r5nJco.mjs → createTheme-B6tVIikC.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-Dz7NfNK6.mjs";
+import { a as flattenTheme, r as deepMerge, t as COMPOUND_REF_RE } from "./helpers-BXaKe2s3.mjs";
 
 //#region src/baseTheme.ts
 /**
@@ -1741,6 +1741,26 @@ var darkAlternate = {
     }
   }
 };
+/**
+* Design brief for the base theme — the recommended default from
+* theme-authoring.md §"Recommended base theme brief". Attached to the base
+* bundle via `createTheme({ brief })`; carries the `FSL-DESIGN-001..003` gate.
+*/
+var baseBrief = {
+  name: "base",
+  purpose: "default built-in foundation for modern product UI",
+  primaryPosture: "productive",
+  secondaryPosture: "calm",
+  densityProfile: "balanced",
+  readingMode: "mixed",
+  pointerProfile: "hybrid",
+  interactionRisk: "medium",
+  surfaceModel: "lightly-layered",
+  brandEnergy: "quiet",
+  accessibilityTarget: "AA+",
+  colorModeStrategy: "dark-supported",
+  platformBias: "web"
+};
 
 //#endregion
 //#region src/roots/validateRefs.ts
@@ -1880,20 +1900,25 @@ var createTheme = ({
   baseMode,
   base,
   overrides,
-  alternate
+  alternate,
+  brief
 } = {}) => {
   const resolvedBase = base ?? parentBundle?.base;
   const resolvedBaseMode = baseMode ?? parentBundle?.baseMode ?? "light";
   const resolvedAlternate = resolveAlternate(alternate, parentBundle);
+  const resolvedMeta = brief ?? parentBundle?.meta;
   return {
     baseMode: resolvedBaseMode,
     base: buildTheme({
       base: resolvedBase,
       overrides
     }),
-    alternate: resolvedAlternate
+    alternate: resolvedAlternate,
+    ...(resolvedMeta ? {
+      meta: resolvedMeta
+    } : {})
   };
 };
 
 //#endregion
-export { darkAlternate as i, createTheme as n, baseTheme as r, buildTheme as t };
+export { darkAlternate as a, baseTheme as i, createTheme as n, baseBrief as r, buildTheme as t };

package/dist/css.cjs

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
-const require_helpers = require('./helpers-CIqeJ8yd.cjs');
-const require_toCssVars = require('./toCssVars-DDowz4wU.cjs');
+const require_helpers = require('./helpers-BU40JvFA.cjs');
+const require_toCssVars = require('./toCssVars-BseqmMcT.cjs');
 
 //#region src/css.ts
 /**

package/dist/css.d.cts

@@ -1,5 +1,5 @@
 
-import { i as ThemeTokens, r as ThemeBundle } from "./Types-BiBa17RL.cjs";
+import { a as ThemeTokens, i as ThemeBundle } from "./Types-BkaxtsMv.cjs";
 
 //#region src/roots/helpers.d.ts
 /**

package/dist/css.d.mts

@@ -1,5 +1,5 @@
 
-import { i as ThemeTokens, r as ThemeBundle } from "./Types-BiBa17RL.mjs";
+import { a as ThemeTokens, i as ThemeBundle } from "./Types-BkaxtsMv.mjs";
 
 //#region src/roots/helpers.d.ts
 /**

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-Dz7NfNK6.mjs";
-import { n as toCssVars, t as toCssVarName } from "./toCssVars-CeckLjW1.mjs";
+import { s as toFlatTokens } from "./helpers-BXaKe2s3.mjs";
+import { n as toCssVars, t as toCssVarName } from "./toCssVars-C-9yIZDR.mjs";
 
 //#region src/css.ts
 /**

package/dist/dataviz/index.cjs

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

package/dist/dataviz/index.d.cts

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

package/dist/dataviz/index.d.mts

@@ -1,5 +1,5 @@
 
-import { o as CoreDataviz, r as ThemeBundle, s as SemanticDataviz } from "../Types-BiBa17RL.mjs";
+import { c as SemanticDataviz, i as ThemeBundle, s as CoreDataviz } from "../Types-BkaxtsMv.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-CrgXLR5A.mjs";
+import { n as coreDataviz, r as semanticDataviz, t as withDataviz } from "../withDataviz-BvpZJnFx.mjs";
 import { useTokens } from "../react.mjs";
 
 //#region src/dataviz/useDatavizTokens.ts