@sonata-innovations/fiber-fbre 3.1.0 → 3.2.0

package/README.md

@@ -226,7 +226,7 @@ import type {
 Flow
 ├── uuid: string
 ├── metadata: { name?, description?, ...}
-├── config?: { mode?, theme?: { color?, darkMode?, style? }, navigation?: { transition?, allowInvalidTransition? }, controls?: { show?, layout?, showStepper? }, summary? }
+├── config?: { mode?, theme?: { color?, colorScheme?, style?, background?, surface?, text?, border?, radius?, fontFamily?, error?, success?, warning? }, navigation?: { transition?, allowInvalidTransition? }, controls?: { show?, layout?, showStepper? }, summary? }
 └── screens: FlowScreen[]
     ├── uuid: string
     ├── label?: string
@@ -407,42 +407,111 @@ const flow = {
 
 ## Theming
 
-FBRE uses CSS custom properties. Override on the container:
+FBRE's appearance is driven entirely by CSS custom properties (the `--fbre-*` tokens). There are two independent axes — **`style`** controls the *shape* (borders vs. underlines, fills, spacing; set via `theme.style`), and the **palette** controls the *colors*. This section is a complete reference for the palette.
 
-```css
-.fbre-container {
-  --fbre-theme-color: #1976d2;
-  --fbre-theme-light: #e3f2fd;
-  --fbre-theme-dark: #1565c0;
-  --fbre-error: #d32f2f;
-  --fbre-text: #212121;
-  --fbre-text-secondary: #666;
-  --fbre-border: #ccc;
-  --fbre-bg: #fff;
-  --fbre-radius: 4px;
-  --fbre-font: "Segoe UI", system-ui, sans-serif;
-}
+Palette values resolve through four layers, each overriding the one above, so you only specify what you want to change:
+
+```
+1.  Light defaults                  base.css                       (lowest)
+2.  Preset:  colorScheme: "dark"    base.css [data-mode="dark"]
+3.  Knobs:   theme.{surface,text…}  inline custom properties
+4.  Raw CSS: your own --fbre-* rules your stylesheet               (highest)
+```
+
+### Color scheme (presets)
+
+`theme.colorScheme` (`"light"` default | `"dark"`) seeds the **entire** token set with a coherent light or dark palette and sets `data-mode` on the container. Set it on the `theme` prop or in the flow config (the prop takes precedence):
+
+```tsx
+<FBRE flow={myFlow} theme={{ colorScheme: "dark" }} onFlowComplete={handleComplete} />
 ```
 
-`theme.color` from `flow.config.theme.color` is applied automatically via inline style.
+> Replaces the former `darkMode: boolean`: `darkMode: true` → `colorScheme: "dark"`, `darkMode: false`/absent → `colorScheme: "light"`. There is no runtime fallback — migrate stored flows before upgrading.
 
-### Dark Mode
+### Theme knobs
 
-Enable dark mode via the `theme` prop or config:
+Layer brand colors on top of the preset with the `theme` palette knobs. Each knob sets its primary `--fbre-*` token **plus the tokens derived from it** (e.g. `surface` also drives the input fills and hover/alt surfaces, via mode-aware `color-mix`). Any subset may be set; unset knobs fall through to the preset.
 
 ```tsx
-// Via theme prop (takes precedence)
-<FBRE flow={myFlow} theme={{ darkMode: true }} onFlowComplete={handleComplete} />
+<FBRE
+  flow={myFlow}
+  theme={{
+    colorScheme: "dark",
+    color: "#bcd3cd",       // accent
+    background: "#1a2a3a",  // form ground
+    surface: "#243244",     // input fills / cards
+    text: "#e8ede9",
+    border: "#2e4158",
+    radius: "3px",
+    fontFamily: '"Inter", system-ui, sans-serif',
+  }}
+  onFlowComplete={handleComplete}
+/>
+```
 
-// Via flow config
-const flow = {
-  ...myFlow,
-  config: { ...myFlow.config, theme: { darkMode: true } }
-};
-<FBRE flow={flow} onFlowComplete={handleComplete} />
+| Knob | Primary token | Also derives |
+| --- | --- | --- |
+| `color` | `--fbre-theme-color` | light/dark accent tints |
+| `background` | `--fbre-bg` | — |
+| `surface` | `--fbre-surface` | input fills, hover/alt/subtle surfaces, control surface |
+| `text` | `--fbre-text` | secondary/placeholder/disabled, label |
+| `border` | `--fbre-border` | hover/light/subtle |
+| `radius` | `--fbre-radius` | — |
+| `fontFamily` | `--fbre-font` | — |
+| `error` / `success` / `warning` | `--fbre-{error,success,warning}` | their `-bg` / `-border` (and `error-light`) |
+
+### Raw CSS (escape hatch)
+
+For tokens not exposed as a knob (e.g. `--fbre-star-filled`, `--fbre-shadow-color`) — or for surgical control — override the `--fbre-*` variables directly. Scope to your wrapper so you out-specify the engine defaults regardless of load order:
+
+```css
+.my-form-wrapper .fbre-container {
+  --fbre-surface: #243244;
+  --fbre-star-filled: #bcd3cd;
+}
 ```
 
-Dark mode applies `data-mode="dark"` on the container and overrides all CSS custom properties with a dark palette. Custom `theme.color` values are preserved — the inline style takes precedence over the dark mode default.
+Knobs are inline (highest specificity among engine-supplied values), so a knob and a raw rule on the *same* token: the knob wins unless your selector is also high-specificity. Use knobs for the common palette, raw CSS for the long tail.
+
+### Token catalog
+
+Every themeable value, with light/dark preset defaults. Tokens marked **(derived)** are produced from a knob when it's set; you can also set any of them raw.
+
+**Accent** — `--fbre-theme-color` (`#1976d2` / `#42a5f5`, knob `color`), `--fbre-theme-light` (`#e3f2fd` / `#1a2332`, derived), `--fbre-theme-dark` (`#1565c0` / `#1e88e5`, derived), `--fbre-on-primary` (`#fff` / `#fff`).
+
+**Ground & surfaces**
+
+| Token | Light | Dark | Knob |
+| --- | --- | --- | --- |
+| `--fbre-bg` | `#fff` | `#121212` | `background` |
+| `--fbre-surface` | `#fff` | `#1e1e1e` | `surface` |
+| `--fbre-surface-hover` | `#f5f5f5` | `#2a2a2a` | (derived) |
+| `--fbre-surface-alt` | `#e0e0e0` | `#333` | (derived) |
+| `--fbre-surface-subtle` | `#e8e8e8` | `#2a2a2a` | (derived) |
+| `--fbre-control-surface` | `#fff` | `#e0e0e0` | (derived) |
+| `--fbre-input-bg` | `var(--fbre-surface)` | `var(--fbre-surface)` | (derived) |
+| `--fbre-input-bg-focus` | `var(--fbre-bg)` | `var(--fbre-bg)` | (derived) |
+
+**Text** — `--fbre-text` (`#212121` / `#e0e0e0`, knob `text`), `--fbre-text-secondary` (`#666` / `#9e9e9e`, derived), `--fbre-text-placeholder` (`#aaa` / `#666`, derived), `--fbre-text-disabled` (`#bbb` / `#555`, derived), `--fbre-label` (`var(--fbre-text-secondary)`, derived).
+
+**Borders** — `--fbre-border` (`#ccc` / `#444`, knob `border`), `--fbre-border-hover` (`#999` / `#666`, derived), `--fbre-border-light` (`#ddd` / `#444`, derived), `--fbre-border-subtle` (`#eee` / `#333`, derived).
+
+**State colors**
+
+| Token | Light | Dark | Knob |
+| --- | --- | --- | --- |
+| `--fbre-error` | `#d32f2f` | `#ef5350` | `error` |
+| `--fbre-error-light` | `#fdecea` | `#2c1b1b` | (derived) |
+| `--fbre-success` | `#2d6a28` | `#a8e6a0` | `success` |
+| `--fbre-success-bg` | `#ddffda` | `#1a3318` | (derived) |
+| `--fbre-success-border` | `#b8e6b4` | `#2d5a28` | (derived) |
+| `--fbre-warning` | `#7a5900` | `#ffe082` | `warning` |
+| `--fbre-warning-bg` | `#fff8e1` | `#332b00` | (derived) |
+| `--fbre-warning-border` | `#ffe082` | `#665500` | (derived) |
+
+**Controls (no knob — set raw)** — `--fbre-toggle-track` (`#ccc` / `#555`), `--fbre-star-empty` (`#ddd` / `#444`), `--fbre-star-filled` (`#ffc107` / `#ffca28`), `--fbre-slider-track` (`#ddd` / `#444`), `--fbre-shadow-color` (`rgba(0,0,0,.12)` / `rgba(0,0,0,.4)`).
+
+**Shape & motion** — `--fbre-radius` (`4px`, knob `radius`), `--fbre-font` (`"Segoe UI", system-ui, sans-serif`, knob `fontFamily`), `--fbre-layout-gap` (`4px`, varies by style), `--fbre-transition-duration` (`250ms`), `--fbre-transition-easing` (`cubic-bezier(0.4, 0, 0.2, 1)`).
 
 ### Screen Transitions