@ttoss/fsl-theme 1.1.22 → 2.1.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
 
@@ -34,38 +34,39 @@ Components consume only semantic tokens. Core tokens never change between light
 
 One entry per semantic family. Use `vars.*` for typed CSS variable references; use the `semantic.*` path shape below when naming tokens in TypeScript or in discussion.
 
-| Family    | Path shape                                                          | Leaf value              |
-| --------- | ------------------------------------------------------------------- | ----------------------- |
-| colors    | `semantic.colors.{ux}.{role}.{dimension}.{state}`                   | CSS color               |
-| spacing   | `semantic.spacing.inset.{control,surface}.{sm,md,lg}`               | CSS length              |
-|           | `semantic.spacing.gap.{stack,inline}.{xs,sm,md,lg,xl}`              | CSS length              |
-|           | `semantic.spacing.gutter.{page,section}`                            | CSS length / `clamp()`  |
-|           | `semantic.spacing.separation.interactive.min`                       | CSS length              |
-| text      | `semantic.text.{display,headline,title,body,label,code}.{lg,md,sm}` | TextStyle object        |
-| sizing    | `semantic.sizing.hit.{min,base,prominent}`                          | CSS length              |
-|           | `semantic.sizing.icon.{sm,md,lg}`                                   | CSS length              |
-|           | `semantic.sizing.identity.{sm,md,lg,xl}`                            | CSS length              |
-|           | `semantic.sizing.measure.reading`                                   | CSS `ch` / `clamp()`    |
-|           | `semantic.sizing.surface.maxWidth`                                  | CSS length              |
-|           | `semantic.sizing.viewport.{height,width}.full`                      | CSS dvh/dvw             |
-| radii     | `semantic.radii.{control,surface,round}`                            | CSS length              |
-| border    | `semantic.border.divider`                                           | `{width, style}`        |
-|           | `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)    |
-| 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}`    |
-|           | `semantic.motion.transition.{enter,exit}`                           | `{duration, easing}`    |
-| zIndex    | `semantic.zIndex.layer.{base,sticky,overlay,blocking,transient}`    | integer                 |
+| Family    | Path shape                                                       | Leaf value              |
+| --------- | ---------------------------------------------------------------- | ----------------------- |
+| colors    | `semantic.colors.{ux}.{role}.{dimension}.{state}`                | CSS color               |
+| spacing   | `semantic.spacing.inset.{control,surface}.{sm,md,lg}`            | CSS length              |
+|           | `semantic.spacing.gap.{stack,inline}.{xs,sm,md,lg,xl}`           | CSS length              |
+|           | `semantic.spacing.gutter.{page,section}`                         | CSS length / `clamp()`  |
+|           | `semantic.spacing.separation.interactive.min`                    | CSS length              |
+| text      | `semantic.text.{display,headline,title,body,label}.{lg,md,sm}`   | TextStyle object        |
+|           | `semantic.text.code.{md,sm}`                                     | TextStyle object        |
+| sizing    | `semantic.sizing.hit.{min,base,prominent}`                       | CSS length              |
+|           | `semantic.sizing.icon.{sm,md,lg}`                                | CSS length              |
+|           | `semantic.sizing.identity.{sm,md,lg,xl}`                         | CSS length              |
+|           | `semantic.sizing.measure.reading`                                | CSS `ch` / `clamp()`    |
+|           | `semantic.sizing.surface.maxWidth`                               | CSS length              |
+|           | `semantic.sizing.viewport.{height,width}.full`                   | CSS dvh/dvw             |
+| radii     | `semantic.radii.{control,surface,round}`                         | CSS length              |
+| border    | `semantic.border.divider`                                        | `{width, style}`        |
+|           | `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.{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}`    |
+|           | `semantic.motion.transition.{enter,exit}`                        | `{duration, easing}`    |
+| zIndex    | `semantic.zIndex.layer.{base,sticky,overlay,blocking,transient}` | integer                 |
 
 **Colors axes** (`semantic.colors.{ux}.{role}.{dimension}.{state}`):
 
 - `ux` — FSL Entity Kind: `action` · `input` · `navigation` · `feedback` · `informational`
 - `role` — Evaluation: `primary` · `secondary` · `accent` · `muted` · `positive` · `caution` · `negative`
 - `dimension` — `background` · `border` · `text`
-- `state` — `default` · `hover` · `active` · `focused` · `disabled` · `selected` · `pressed`
+- `state` — `default` · `hover` · `active` · `focused` · `disabled` · `selected` · `pressed` · `expanded` · `checked` · `indeterminate` · `current` · `visited` · `droptarget` · `invalid` (legality varies per `ux` — see the colors family spec)
 
 ## Pick a token in 60s
 
@@ -220,7 +221,7 @@ export const App = () => (
 );
 ```
 
-`ThemeProvider` injects CSS Custom Properties via React 19 style hoisting and persists mode to localStorage.
+`ThemeProvider` injects CSS Custom Properties via React 19 style hoisting, persists mode to localStorage, and keeps open tabs in sync via the `storage` event. The react entry point ships with `'use client'`, so it can be imported directly from a Next.js App Router layout.
 
 ### Hooks
 
@@ -242,7 +243,10 @@ import { useResolvedTokens } from '@ttoss/fsl-theme/react';
 
 // Non-CSS environments (React Native, canvas) — resolved raw values
 const resolved = useResolvedTokens();
-// resolved['semantic.colors.action.primary.background.default'] → '#0469E3'
+// resolved['semantic.colors.action.primary.background.default'] → '#020617'
+// ⚠ CSS-coupled tokens (spacing steps, fluid text sizes, hit/viewport sizing —
+// see model.md §8) stay as CSS expressions (var()/calc()/clamp()/cqi) and are
+// not usable outside a CSS engine. Colors and scalar tokens resolve fully.
 ```
 
 ### Consuming tokens
@@ -290,7 +294,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 +354,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
 
@@ -374,16 +380,23 @@ import { getThemeStylesContent } from '@ttoss/fsl-theme/css';
 
 const css = getThemeStylesContent(myTheme);
 // → :root { --tt-* } + :root[data-tt-mode="dark"] { --tt-* (overrides) }
+//   + @media (prefers-color-scheme: dark) fallback for no-JS / pre-hydration
+
+// Fixed light/dark default (dark only via explicit toggle)? Skip the OS fallback:
+const lightFirstCss = getThemeStylesContent(myTheme, undefined, {
+  systemModeFallback: false,
+});
+// <ThemeProvider> / <ThemeHead> derive this automatically from `defaultMode`.
 ```
 
 ## Storybook / micro-frontends
 
-Anchor theme attributes to a specific element instead of `<html>`:
+Anchor theme attributes to a specific element instead of `<html>`. Always pair `root` with a `themeId` — without one, the CSS targets `:root` on `<html>` while the attributes land on the element, and the alternate mode would never apply (a dev warning fires on this combination):
 
 ```tsx
 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>;

package/dist/{Types-BiBa17RL.d.cts → Types-a_sfpbha.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;
   };
 }
 /**
@@ -366,14 +366,18 @@ interface ActionColorStates extends BaseColorStates {
   /** Disclosure trigger or menu button is currently open. Use for buttons that own an open popup, menu, or panel. */
   expanded?: CoreColorRef;
 }
-/** `input` context: adds `checked`, `indeterminate`, `pressed`, `expanded` for form controls.
+/** `input` context: adds `checked`, `indeterminate`, `pressed`, `expanded`,
+ * and `invalid` for form controls.
  *
- * Validation failure is *not* a state — it is an Evaluation (FSL Lexicon §5).
- * Components that fail validation render with the `input.negative.*` role,
- * not with an `invalid` state on `input.primary.*`. This avoids dual
- * representation of the same semantic concept and keeps FSL §7 State Law
- * intact ("States are not free-form"). React Aria's `isInvalid` flag maps
- * to selecting the `negative` role, not to a new state.
+ * Validation doctrine (ADR-017, mirrors `@ttoss/fsl-ui` taxonomy): validation
+ * outcome is a **runtime State** (`invalid`), never an authorial Evaluation —
+ * evaluation lives in the author's pen, state lives in the user's data.
+ * The control itself flips to `input.{role}.*.invalid` when React Aria's
+ * `isInvalid` (or a form library) says so; adjacent *display* parts
+ * (validationMessage, icon) still consume the `input.negative.*` role — they
+ * report valence, the control carries state. The mirror distinction to
+ * Lexicon §10.5 (`negative` ≠ `destructive`) is `invalid` (State) ≠
+ * `negative` (Evaluation) — Lexicon §10.15.
  *
  * Structural Role → token mapping (FSL Lexicon §2): a part declared with
  * Structural Role `validationMessage` consumes `input.negative.text.*` for
@@ -393,6 +397,14 @@ interface InputColorStates extends BaseColorStates {
   pressed?: CoreColorRef;
   /** Combobox / select / disclosure-style input is currently open. */
   expanded?: CoreColorRef;
+  /**
+   * Runtime validation outcome — the control's value failed validation.
+   * Use when React Aria's `isInvalid` (or a form library) asserts failure.
+   * Pair with `input.negative.text.*` on the validationMessage; do not use
+   * the `negative` role on the control itself — that is authorial valence
+   * (Lexicon §10.15).
+   */
+  invalid?: CoreColorRef;
 }
 /** `navigation` context: adds `selected`, `current`, `visited`, `expanded`. */
 interface NavigationColorStates extends BaseColorStates {
@@ -407,10 +419,10 @@ interface NavigationColorStates extends BaseColorStates {
 }
 /** `informational` context: adds `selected`, `visited`, `expanded`.
  *
- * `expanded` covers in-place disclosure on presentational surfaces (accordions,
- * collapsible panels, expandable cards). `Disclosure` Entity Kinds project to
- * `informational` per FSL identity (in-place reveal, not movement across
- * destinations — FSL Lexicon §1). */
+ * `expanded` covers in-place disclosure on presentational surfaces
+ * (accordions, collapsible panels, expandable cards). Note: `Disclosure`
+ * Entity Kinds project to `navigation` (ADR-001); `expanded` here serves
+ * presentational surfaces that disclose without being Disclosure entities. */
 interface InformationalColorStates extends BaseColorStates {
   /** Presentational element is **one of many** and the user picked it (selectable list row, focused card in a deck). */
   selected?: CoreColorRef;
@@ -440,7 +452,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 +599,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 +607,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 +969,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 +1026,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 +1047,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 +1380,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 +1466,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 +1484,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-a_sfpbha.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;
   };
 }
 /**
@@ -366,14 +366,18 @@ interface ActionColorStates extends BaseColorStates {
   /** Disclosure trigger or menu button is currently open. Use for buttons that own an open popup, menu, or panel. */
   expanded?: CoreColorRef;
 }
-/** `input` context: adds `checked`, `indeterminate`, `pressed`, `expanded` for form controls.
+/** `input` context: adds `checked`, `indeterminate`, `pressed`, `expanded`,
+ * and `invalid` for form controls.
  *
- * Validation failure is *not* a state — it is an Evaluation (FSL Lexicon §5).
- * Components that fail validation render with the `input.negative.*` role,
- * not with an `invalid` state on `input.primary.*`. This avoids dual
- * representation of the same semantic concept and keeps FSL §7 State Law
- * intact ("States are not free-form"). React Aria's `isInvalid` flag maps
- * to selecting the `negative` role, not to a new state.
+ * Validation doctrine (ADR-017, mirrors `@ttoss/fsl-ui` taxonomy): validation
+ * outcome is a **runtime State** (`invalid`), never an authorial Evaluation —
+ * evaluation lives in the author's pen, state lives in the user's data.
+ * The control itself flips to `input.{role}.*.invalid` when React Aria's
+ * `isInvalid` (or a form library) says so; adjacent *display* parts
+ * (validationMessage, icon) still consume the `input.negative.*` role — they
+ * report valence, the control carries state. The mirror distinction to
+ * Lexicon §10.5 (`negative` ≠ `destructive`) is `invalid` (State) ≠
+ * `negative` (Evaluation) — Lexicon §10.15.
  *
  * Structural Role → token mapping (FSL Lexicon §2): a part declared with
  * Structural Role `validationMessage` consumes `input.negative.text.*` for
@@ -393,6 +397,14 @@ interface InputColorStates extends BaseColorStates {
   pressed?: CoreColorRef;
   /** Combobox / select / disclosure-style input is currently open. */
   expanded?: CoreColorRef;
+  /**
+   * Runtime validation outcome — the control's value failed validation.
+   * Use when React Aria's `isInvalid` (or a form library) asserts failure.
+   * Pair with `input.negative.text.*` on the validationMessage; do not use
+   * the `negative` role on the control itself — that is authorial valence
+   * (Lexicon §10.15).
+   */
+  invalid?: CoreColorRef;
 }
 /** `navigation` context: adds `selected`, `current`, `visited`, `expanded`. */
 interface NavigationColorStates extends BaseColorStates {
@@ -407,10 +419,10 @@ interface NavigationColorStates extends BaseColorStates {
 }
 /** `informational` context: adds `selected`, `visited`, `expanded`.
  *
- * `expanded` covers in-place disclosure on presentational surfaces (accordions,
- * collapsible panels, expandable cards). `Disclosure` Entity Kinds project to
- * `informational` per FSL identity (in-place reveal, not movement across
- * destinations — FSL Lexicon §1). */
+ * `expanded` covers in-place disclosure on presentational surfaces
+ * (accordions, collapsible panels, expandable cards). Note: `Disclosure`
+ * Entity Kinds project to `navigation` (ADR-001); `expanded` here serves
+ * presentational surfaces that disclose without being Disclosure entities. */
 interface InformationalColorStates extends BaseColorStates {
   /** Presentational element is **one of many** and the user picked it (selectable list row, focused card in a deck). */
   selected?: CoreColorRef;
@@ -440,7 +452,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 +599,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 +607,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 +969,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 +1026,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 +1047,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 +1380,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 +1466,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 +1484,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-DiYlHNG5.mjs → baseBundle-CXdxj_re.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-Bm9LVQ4w.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/{baseBundle-BWbICg4p.cjs → baseBundle-a9LDsqYy.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-B7H0xSVp.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