@ttoss/fsl-theme 1.1.21 → 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}`    |
@@ -164,9 +164,9 @@ Find the CSS property you are setting, then follow the branch to the leaf.
 
 ## Per-family specs
 
-Full grammar rules, decision matrices, and anti-patterns live in the family specs. Each file follows the pattern `02-families/{family}.md`:
+Full grammar rules, decision matrices, and anti-patterns live in the family specs. Each file follows the pattern `families/{family}.md`:
 
-[colors](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/colors.md) · [spacing](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/spacing.md) · [typography](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/typography.md) · [sizing](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/sizing.md) · [radii](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/radii.md) · [borders](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/borders.md) · [elevation](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/elevation.md) · [opacity](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/opacity.md) · [motion](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/motion.md) · [z-index](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/z-index.md) · [breakpoints](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/01-design-system/02-design-tokens/02-families/breakpoints.md)
+[colors](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/colors.md) · [spacing](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/spacing.md) · [typography](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/typography.md) · [sizing](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/sizing.md) · [radii](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/radii.md) · [borders](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/borders.md) · [elevation](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/elevation.md) · [opacity](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/opacity.md) · [motion](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/motion.md) · [z-index](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/z-index.md) · [breakpoints](https://github.com/ttoss/ttoss/blob/main/docs/website/docs/design/design-system/design-tokens/families/breakpoints.md)
 
 ## createTheme
 
@@ -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-BXvPJYzj.cjs → baseBundle-DdRSa5mf.cjs}

@@ -1,5 +1,5 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-const require_createTheme = require('./createTheme-JOu16Shb.cjs');
+const require_createTheme = require('./createTheme--UFgVlEn.cjs');
 
 //#region src/baseBundle.ts
 /**
@@ -10,7 +10,8 @@ const require_createTheme = require('./createTheme-JOu16Shb.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-BLvD8XVS.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-DzLnsknT.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-JOu16Shb.cjs → createTheme--UFgVlEn.cjs}

@@ -1,5 +1,5 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-const require_helpers = require('./helpers-C29fy-Ad.cjs');
+const require_helpers = require('./helpers-BU40JvFA.cjs');
 
 //#region src/baseTheme.ts
 /**
@@ -7,6 +7,33 @@ const require_helpers = require('./helpers-C29fy-Ad.cjs');
 *
 * System fonts, gray palette, and balanced proportions. Serves as the
 * canonical base that all other themes extend via `createTheme`.
+*
+* ## Theme brief
+*
+* Every value in this file is chosen so that the resolved bundle satisfies
+* this brief. Changes that contradict the brief belong in a different theme,
+* not in `baseTheme`.
+*
+* ```yaml
+* 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
+* ```
+*
+* Intended feel: practical, calm, modern, trustworthy, easy to extend.
+* Avoided feel: flashy, ornamental, cramped, fragile, overly branded.
+*
+* @see /docs/website/docs/design/design-system/design-tokens/theme-authoring.md#recommended-base-theme-brief
 */
 var baseTheme = {
   core: {
@@ -1077,23 +1104,23 @@ var baseTheme = {
     spacing: {
       inset: {
         control: {
-          sm: "{core.spacing.2}",
-          md: "{core.spacing.3}",
-          lg: "{core.spacing.4}"
-        },
-        surface: {
           sm: "{core.spacing.3}",
           md: "{core.spacing.4}",
           lg: "{core.spacing.6}"
+        },
+        surface: {
+          sm: "{core.spacing.4}",
+          md: "{core.spacing.6}",
+          lg: "{core.spacing.8}"
         }
       },
       gap: {
         stack: {
           xs: "{core.spacing.2}",
-          sm: "{core.spacing.3}",
-          md: "{core.spacing.4}",
-          lg: "{core.spacing.6}",
-          xl: "{core.spacing.8}"
+          sm: "{core.spacing.4}",
+          md: "{core.spacing.6}",
+          lg: "{core.spacing.8}",
+          xl: "{core.spacing.12}"
         },
         inline: {
           xs: "{core.spacing.1}",
@@ -1104,12 +1131,12 @@ var baseTheme = {
         }
       },
       gutter: {
-        page: "clamp({core.spacing.4}, {core.spacing.6}, {core.spacing.12})",
-        section: "clamp({core.spacing.3}, {core.spacing.4}, {core.spacing.12})"
+        page: "clamp({core.spacing.6}, {core.spacing.12}, {core.spacing.16})",
+        section: "clamp({core.spacing.4}, {core.spacing.8}, {core.spacing.16})"
       },
       separation: {
         interactive: {
-          min: "clamp(8px, {core.spacing.2}, 12px)"
+          min: "clamp(8px, {core.spacing.3}, 16px)"
         }
       }
     },
@@ -1714,6 +1741,96 @@ 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
+/**
+* Compute the Levenshtein edit distance between two strings.
+* Used exclusively by `validateRefs` to power "did you mean?" suggestions.
+*/
+var levenshtein = (a, b) => {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({
+    length: m + 1
+  }, () => {
+    return Array.from({
+      length: n + 1
+    }, () => {
+      return 0;
+    });
+  });
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) for (let j = 1; j <= n; j++) dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+  return dp[m][n];
+};
+/**
+* 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.
+*
+* **DEV-only** — callers gate this behind `process.env.NODE_ENV !== 'production'`
+* so bundlers tree-shake the entire call in production builds.
+*/
+var validateRefs = theme => {
+  const {
+    core,
+    semantic
+  } = require_helpers.flattenTheme(theme);
+  const all = {
+    ...core,
+    ...semantic
+  };
+  const allKeys = Object.keys(all);
+  const findSuggestion = (refPath, candidates) => {
+    if (candidates.length === 0) return "";
+    let bestDist = Infinity;
+    let bestKey = "";
+    for (const candidate of candidates) {
+      const dist = levenshtein(refPath, candidate);
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestKey = candidate;
+      }
+    }
+    if (bestDist <= Math.ceil(refPath.length * .4)) return `\n   Did you mean '{${bestKey}}'?`;
+    return "";
+  };
+  for (const [ownerKey, value] of Object.entries(all)) {
+    if (typeof value !== "string" || !value.includes("{")) continue;
+    let match;
+    const re = new RegExp(require_helpers.COMPOUND_REF_RE.source, require_helpers.COMPOUND_REF_RE.flags);
+    while ((match = re.exec(value)) !== null) {
+      const refPath = match[1];
+      if (all[refPath] !== void 0) continue;
+      const prefix = refPath.split(".")[0];
+      const suggestion = findSuggestion(refPath, allKeys.filter(k => {
+        return k.startsWith(prefix + ".");
+      }));
+      console.warn(`[fsl-theme] Invalid token reference '{${refPath}}' at path '${ownerKey}'.${suggestion}`);
+    }
+  }
+};
 
 //#endregion
 //#region src/createTheme.ts
@@ -1728,7 +1845,7 @@ var buildTheme = ({
   overrides = {}
 } = {}) => {
   const merged = require_helpers.deepMerge(base, overrides);
-  if (process.env.NODE_ENV !== "production") require_helpers.validateRefs(merged);
+  if (process.env.NODE_ENV !== "production") validateRefs(merged);
   return structuredClone(merged);
 };
 var resolveAlternate = (alternate, parentBundle) => {
@@ -1783,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 () {