@app-studio/components 0.10.17 → 0.10.19

package/docs/README.md

@@ -12,6 +12,7 @@ build with the same public API.
 - **[Component Development](./component-development/guide.md)** — Building and contributing components (including `.native.tsx` siblings)
 - **[API Integration](./api-integration.md)** — Backend integration patterns
 - **[Design System](./design-system/theming.md)** — Theming and styling guidelines
+- **[Generating a Design-System Config](./design-system/design-system.md)** — Step-by-step recipe (for agents) to author a new brand config that works in light + dark
 
 ### Specialized Documentation
 - **[ADK Components](../README-ADK.md)** — Agent Development Kit integration

package/docs/app-studio/Theming.md

@@ -487,3 +487,10 @@ Each palette has these shades: `50, 100, 200, 300, 400, 500, 600, 700, 800, 900`
 - **Dark Mode**: Uses `defaultDarkPalette` and `defaultDarkColors`
 - Colors automatically switch based on `themeMode` unless using `light.*` or `dark.*` prefix
 - Color values are inverted for dark mode (e.g., `color-white` becomes black in dark mode)
+
+### Making a theme slot adaptive vs constant
+The value you assign to a theme slot decides whether it follows the mode or stays fixed:
+- **Constant** — a literal value (`primary: '#2563eb'`) is emitted as-is and never changes between modes. Use for brand identity.
+- **Adaptive** — a token reference (`text: 'color-black'`, `canvas: 'color-white'`) is emitted as `var(--color-…)` and **flips with the mode** (`color-black` → white in dark). Use for structural neutrals.
+
+This is the foundation of the design-system layer's "one config, both modes" rule — see [docs/design-system/theming.md §2.1](../design-system/theming.md#21-one-config-both-modes--the-adaptive-rule).

package/docs/design-system/component-library.md

@@ -105,21 +105,31 @@ Switching brand at runtime is just a state update of the `config` (or `configId`
 ### 3.2 `theme` (11 semantic colors — the single source of truth)
 ```jsonc
 {
+  // Brand identity — raw hex → stays constant in light AND dark
   "primary":     "#ff385c",
-  "secondary":   "#222222",
-  "success":     "#428bff",
-  "warning":     "#460479",
-  "error":       "#c13515",
-  "canvas":      "#ffffff",
-  "surface":     "#f7f7f7",
-  "text":        "#222222",
-  "muted":       "#6a6a6a",
-  "border":      "#dddddd",
-  "onPrimary":   "#ffffff"
+  "secondary":   "#7c3aed",
+  "success":     "#16a34a",
+  "warning":     "#d97706",
+  "error":       "#dc2626",
+  "onPrimary":   "#ffffff",
+
+  // Structural neutrals — color-* token → flips automatically with the mode
+  "canvas":      "color-white",    // white in light, black in dark
+  "surface":     "color-gray-50",  // near-white in light, near-black in dark
+  "text":        "color-black",    // black in light, white in dark
+  "muted":       "color-gray-500", // readable mid-grey in both
+  "border":      "color-gray-200"  // light hairline → dark hairline
 }
 ```
 
-`theme` is the **only** place hex values for those eleven roles should live. Everything else — `tokens.colors[]`, `components.*.views`, page-level inline styles — should reference them via `theme-*` token strings. That's the contract: change one hex in `theme.primary` and every button, badge, focus ring, link, and brand snapshot updates across the design-system page.
+`theme` is the **only** place these eleven roles are defined. Everything else — `tokens.colors[]`, `components.*.views`, page-level inline styles — references them via `theme-*` token strings. Change one value here and every button, badge, focus ring, link, and surface updates across the design-system page.
+
+The **form of each value** decides its light/dark behaviour — this is the heart of the adaptive system ([theming.md §2.1](./theming.md#21-one-config-both-modes--the-adaptive-rule)):
+
+- **Raw hex** (`"#ff385c"`) → constant across modes. Use for brand slots: `primary`, `secondary`, `success`, `warning`, `error`, `onPrimary`.
+- **`color-*` token** (`"color-black"`) → flips automatically. Use for structural neutrals: `canvas`, `surface`, `text`, `muted`, `border`.
+
+This is why one config serves both modes: the brand colours stay put while the neutrals invert. Do **not** hand-author a second dark config, and do **not** put a constant dark hex in `text`/`canvas` — that's what breaks a "light" brand the moment the user toggles to dark.
 
 ### 3.3 `tokens` (raw extracted material)
 ```jsonc
@@ -486,6 +496,11 @@ Use these inside bespoke page-level compositions (brand snapshots, tier-pricing
 
 ## 6. Authoring a config for a new brand
 
+> **For a focused, copy-paste recipe (especially for AI agents), use the
+> dedicated guide: [design-system.md](./design-system.md).** It walks the five
+> sections in order with the coherence rules, a validation checklist, and an
+> anti-pattern table. The summary below remains the quick reference.
+
 A config is a JSON file under [src/design-system/configs/](../../src/design-system/configs/). To add `mybrand`:
 
 1. **Create `mybrand.json`** with all five sections (`metadata`, `theme`, `tokens`, `components`, `personality`). Use an existing config as a template — `airbnb.json` (light) or `linear.json` (dark) are the cleanest references.
@@ -618,9 +633,9 @@ If a brand source HTML/page exists ([§9.10](#910-when-a-source-html-exists)), e
 
 ### 9.2 Decision flow (the 7 ordered steps)
 
-1. **Pick the primary hex.** One color. Everything else is derived.
-2. **Pick appearance.** Light brands → `canvas: '#ffffff'-ish`. Dark brands → `canvas: '#000-#0d0d0d'`.
-3. **Build the 11 theme slots** following [§9.3](#93-theme-palette-recipe).
+1. **Pick the primary hex.** One color. Everything else is derived. It must read on **both** a white and a black canvas (it stays constant across modes — see step 3).
+2. **Pick the default appearance** (`light` or `dark`). This only sets which mode the config *opens in* — you do **not** hand-pick a canvas/text hex per mode; the neutrals adapt automatically.
+3. **Build the 11 theme slots** following [§9.3](#93-theme-palette-recipe): brand slots as **hex** (constant), neutral slots (`canvas`, `surface`, `text`, `muted`, `border`) as **`color-*` tokens** (auto-flip). One config, both modes.
 4. **Pick the typography fingerprint** from [§9.4](#94-typography-fingerprints) and assemble `tokens.typography` + `metadata.googleFontLinks`.
 5. **Pick the personality archetype** from [§9.5](#95-personality-archetypes); copy its block; tweak `signatureMotif` and `voice` to fit the brand.
 6. **Fill `components.*` defaults** following the component patterns in [§9.7](#97-component-config-patterns). Use `theme-*` tokens, **never hex**.
@@ -628,26 +643,38 @@ If a brand source HTML/page exists ([§9.10](#910-when-a-source-html-exists)), e
 
 ### 9.3 Theme palette recipe (the 11 slots)
 
-| Slot          | What it paints                                              | Construction rule                                                                                       |
-|---------------|-------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| `primary`     | CTA backgrounds, links, focus rings, active tabs            | The signature hex.                                                                                      |
-| `secondary`   | Secondary CTAs, hovers, accent emphasis                     | A *related* hue (analogous or lighter tint of primary), not a clash. Lift L by ~10–15% from primary.    |
-| `success`     | Positive states, "operational" indicators                   | Green family — pick a green that survives next to `primary` without vibrating. ~`#27a644`–`#1DB954`.    |
-| `warning`     | Cautions, "degraded" indicators                             | Amber/orange (`#f59e0b`-ish) for most; some brands repurpose a brand color (Linear uses a desaturated indigo). |
-| `error`       | Destructive actions, "outage" indicators                    | Red family (`#c13515`–`#ef4444`). Coinbase / Stripe / Airbnb tune this toward their primary's temperature. |
-| `canvas`      | Page background                                             | Light brands: `#ffffff`–`#fafafa`. Dark brands: `#000000`–`#0d0d0d`. Choose the extreme — half-tones look amateur. |
-| `surface`     | Cards, popovers, raised regions                             | Canvas ± 4–8% lightness. Light: `#f5f5f7`-ish. Dark: `#1a1b1d`-ish. **Must be visually distinct from canvas.** |
-| `text`        | Body copy                                                   | Light: near-black (`#111`–`#222`). Dark: near-white (`#f7f8f8`).                                        |
-| `muted`       | Secondary copy, captions, placeholder text                  | Same hue as `text`, ~55–65% opacity. Hex like `#6a6a6a` (light) / `#8a8f98` (dark).                     |
-| `border`      | Dividers, card outlines, input borders                      | Very low-contrast against canvas. Light: `#e5e5e7`-ish. Dark: `#23252a`-ish.                            |
-| `onPrimary`   | Text *on top of* `primary` (filled-button label)            | Maximum contrast vs `primary`. ~99% of brands use `#ffffff`. Use `#000` only when `primary` is light (yellow, mint, pale gold). |
-
-> **Contrast invariants** the LLM must check before outputting:
-> - `text` vs `canvas`: WCAG AA at minimum (contrast ratio ≥ 4.5:1).
+Each slot is either **constant** (a raw `hex` — brand identity, identical in light and dark) or **adaptive** (a `color-*` token — flips automatically with the mode). Author both groups in one config and the dark theme is derived for free ([theming.md §2.1](./theming.md#21-one-config-both-modes--the-adaptive-rule)). **Do not author a second dark config.**
+
+**Brand slots — write a `hex`, stays constant in both modes:**
+
+| Slot        | What it paints                                   | Construction rule                                                                                              |
+|-------------|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| `primary`   | CTA backgrounds, links, focus rings, active tabs | The signature hex. Must clear **≥ 3:1 on both white and black** — it never flips, so it has to read in dark too. |
+| `secondary` | Secondary CTAs, hovers, accent emphasis          | A *related* hue (analogous or lighter tint of primary), not a clash. **Not body ink** — ink is `text`.          |
+| `success`   | Positive / "operational" states                  | Green family that survives next to `primary` without vibrating. ~`#16a34a`–`#1DB954`.                          |
+| `warning`   | Cautions / "degraded" states                     | Amber/orange (`#d97706`-ish); some brands repurpose a brand hue (Linear uses a desaturated indigo).            |
+| `error`     | Destructive / "outage" states                    | Red family (`#dc2626`–`#ef4444`). Coinbase / Stripe / Airbnb tune this toward their primary's temperature.     |
+| `onPrimary` | Ink *on top of* `primary` (filled-button label)  | Max contrast vs `primary`. ~99% use `#ffffff`; `#000` only when `primary` is light (yellow, mint, pale gold).   |
+
+**Neutral slots — write a `color-*` token, flips with the mode:**
+
+| Slot      | What it paints                          | Recommended token → what it becomes in dark                                            |
+|-----------|-----------------------------------------|-----------------------------------------------------------------------------------------|
+| `canvas`  | Page background                         | `color-white` → black. (Want off-white instead of pure white? `color-gray-50`.)         |
+| `surface` | Cards, popovers, raised regions         | `color-gray-50` (or `color-gray-100`) → near-black. Must stay distinct from `canvas`.    |
+| `text`    | Body copy                              | `color-black` → white. (Softer ink: `color-gray-900`.)                                   |
+| `muted`   | Secondary copy, captions, placeholders  | `color-gray-500` → a readable mid-grey in both modes.                                    |
+| `border`  | Dividers, outlines, input borders       | `color-gray-200` → dark hairline. (Stronger: `color-gray-300`.)                          |
+
+> **Tint the neutrals for brand character** while keeping auto-flip: swap the grey family — `color-slate-*` (cool), `color-stone-*` (warm), `color-zinc-*`, `color-neutral-*`. Pick **one** family and use it for all five neutral slots so they stay coherent.
+
+> **Contrast invariants** to verify in **both** light and dark (the default `color-gray-*` ramp passes these by construction — re-check only if you hand-pick shades or tint the family):
+> - `text` vs `canvas`: WCAG AA (≥ 4.5:1).
 > - `onPrimary` vs `primary`: WCAG AA (≥ 4.5:1).
-> - `surface` vs `canvas`: distinguishable when adjacent (ratio ≥ 1.1:1 — purely perceptual).
-> - `border` vs `surface`: visible but subtle (ratio 1.2–1.6:1).
-> - `muted` vs `canvas`: legible but recessive (ratio ≥ 3:1).
+> - `primary` vs `canvas`: ≥ 3:1 on **both** white and black (primary doesn't flip).
+> - `surface` vs `canvas`: distinguishable when adjacent (≥ 1.1:1).
+> - `border` vs `surface`: visible but subtle (1.2–1.6:1).
+> - `muted` vs `canvas`: legible but recessive (≥ 3:1).
 
 ### 9.4 Typography fingerprints
 
@@ -743,12 +770,12 @@ Save this as `src/design-system/configs/<brandid>.json`, replace every `___` pla
     "success":   "#___",
     "warning":   "#___",
     "error":     "#___",
-    "canvas":    "#___",
-    "surface":   "#___",
-    "text":      "#___",
-    "muted":     "#___",
-    "border":    "#___",
-    "onPrimary": "#ffffff"
+    "onPrimary": "#ffffff",
+    "canvas":    "color-white",
+    "surface":   "color-gray-50",
+    "text":      "color-black",
+    "muted":     "color-gray-500",
+    "border":    "color-gray-200"
   },
   "tokens": {
     "rawCssVars": {},
@@ -837,9 +864,16 @@ Run this list against the output before declaring done:
 - [ ] `label.color` is **absent** on `checkbox`/`radio`/`switch`/`input`/`textarea`/`select` ([§7.2](#72-strip-labelcolor-from-brand-component-configs)).
 - [ ] Every font family in `components.*.views.*.fontFamily` matches `tokens.typography.fontFamily`.
 
-**Contrast & legibility**
+**Light/dark adaptivity** (so one config serves both modes — [theming.md §2.1](./theming.md#21-one-config-both-modes--the-adaptive-rule))
+- [ ] Neutral slots `canvas`, `surface`, `text`, `muted`, `border` are **`color-*` token references**, not raw hex — so they flip with the theme mode.
+- [ ] Brand slots `primary`, `secondary`, `success`, `warning`, `error`, `onPrimary` are **raw hex** — constant across modes.
+- [ ] The five neutral slots all use **one** grey family (`color-gray-*`, or one tint family) — not mixed.
+- [ ] Components reference `theme-text` / `theme-muted` for body ink — **never** a constant brand slot like `theme-secondary` (which would stay dark on a dark canvas).
+
+**Contrast & legibility** (verify in **both** light and dark)
 - [ ] `text` vs `canvas` ≥ 4.5:1.
 - [ ] `onPrimary` vs `primary` ≥ 4.5:1.
+- [ ] `primary` ≥ 3:1 against **both** `color-white` and `color-black` (it doesn't flip).
 - [ ] `surface` ≠ `canvas` (visually distinguishable).
 - [ ] `muted` vs `canvas` ≥ 3:1.
 
@@ -871,7 +905,8 @@ To anchor the playbook, here's how it applies end-to-end to a fictional brand: *
 1. **Primary hex**: `#00d4ff` (electric cyan — owns the "speed/transit" lane without colliding with Tesla blue).
 2. **Appearance**: `dark` (premium-technical brands default dark).
 3. **Theme** (built per [§9.3](#93-theme-palette-recipe)):
-   - `primary #00d4ff`, `secondary #00a4cc` (darker analog), `success #00d68f`, `warning #ffb547`, `error #ff5757`, `canvas #050608`, `surface #0f1115`, `text #f0f3f5`, `muted #6e7681`, `border #1f242b`, `onPrimary #001218` (dark on cyan for AA contrast).
+   - Brand (hex, constant): `primary #00d4ff`, `secondary #00a4cc` (darker analog), `success #00d68f`, `warning #ffb547`, `error #ff5757`, `onPrimary #001218` (dark ink on cyan for AA). `primary` reads on both white and black ✓.
+   - Neutrals (`color-*` tokens, adaptive): `canvas color-white`, `surface color-gray-50`, `text color-black`, `muted color-gray-500`, `border color-gray-200`. With `defaultAppearance: "dark"` the config **opens** with a near-black canvas + light ink, and still works if the user toggles to light. *(If a brand truly needs exact, bespoke dark-only neutrals — e.g. a glass `#0f1115` surface — pin those as hex instead, accepting they won't flip.)*
 4. **Typography**: *Modern-Mono-Hybrid* — body `Inter`, mono `JetBrains Mono`, plus `googleFontLinks` for both.
 5. **Personality**: *Dev-Editorial* archetype, but tune `signatureMotif: '→'`, `accentTreatment: 'glow'`, `voice: 'velocity-precision'`.
 6. **Components**: from the starter template; replace generic `Inter` with the chosen family; `tabs.activeTab` underline style (`backgroundColor: "transparent"`); `button.color: "theme-primary"`.
@@ -887,7 +922,8 @@ The output is a config that *renders correctly* and *unmistakably reads as Hyper
 - Provider & hooks: [src/design-system/DesignSystemProvider.tsx](../../src/design-system/DesignSystemProvider.tsx)
 - Types (incl. `BrandPersonality`): [src/design-system/types.ts](../../src/design-system/types.ts)
 - Merge utilities: [src/design-system/utils.ts](../../src/design-system/utils.ts) — `deepMerge` (skips top-level `undefined`/`null`; recurses only when both sides are plain objects, so React-element props stay reference-only and don't trigger cycles), `getDesignSystemComponentProps` (runs `stripNullsDeep` so the schema's `null` placeholders never reach the merge — see [§3.6](#36-uniform-schema-across-configs)), `mergeDesignSystemComponentProps`, `normalizeDesignSystemComponentProps`
-- 15 brand configs: [src/design-system/configs/](../../src/design-system/configs/) — fully tokenized; all `components.*.views.*` colors are `theme-*` references
+- Default adaptive config: [src/design-system/configs/default.json](../../src/design-system/configs/default.json) — the brand-neutral fallback; brand slots are hex (constant), neutral slots are `color-*` tokens (auto-flip), so it renders correctly in light **and** dark. The reference implementation of [theming.md §2.1](./theming.md#21-one-config-both-modes--the-adaptive-rule).
+- 15 brand configs: [src/design-system/configs/](../../src/design-system/configs/) — fully tokenized; all `components.*.views.*` colors are `theme-*` references. (These are brand *snapshots* and currently pin their neutral slots as hex for their native appearance — convert a slot to a `color-*` token per §2.1 to make that brand adapt.)
 - Live showcase: [src/pages/designSystem.page.tsx](../../src/pages/designSystem.page.tsx) — ergonomic patterns for `componentRadius`, `getPersonality`, `personality*` helpers, `BrandSnapshotSample`, `PaletteFrame`
 - Theming primer (token vocabulary): [docs/design-system/theming.md](./theming.md)
 - Wider conventions: [docs/conventions.md](../conventions.md)

package/docs/design-system/llm-design-system.md

@@ -0,0 +1,426 @@
+# Generating a Design-System Config — Agent Guide
+
+This is a **prescriptive recipe** for an AI agent (or a human) to generate a new
+brand design-system config from scratch. Follow it top to bottom and you will
+produce a single JSON file that renders correctly in **both light and dark
+mode** across every component — with **no component code changes** and **no
+light/dark branching**.
+
+> **Mental model.** A config is *data*. Components are *dumb consumers* — they
+> read tokens and do their job, nothing more. All the intelligence lives in the
+> **shape of the values you choose**. Get the tokens right and dark mode,
+> contrast, and brand identity all fall out automatically.
+
+If you want the deep "how the resolver works" reference, read
+[theming.md](./theming.md). This doc is the **build instructions**; theming.md
+is the **physics**.
+
+---
+
+## 0. TL;DR — the five rules that make a config coherent
+
+1. **Stay vs adapt is decided by the value's *form*.**
+   - **Raw hex** (`"#2563eb"`) → **constant** in both modes. Use for brand identity.
+   - **`color-*` token** (`"color-black"`) → **flips** automatically. Use for structural neutrals.
+2. **Brand colors are FILLS, not foreground.** `theme-primary` paints a
+   background and pairs with `theme-onPrimary` ink. **Never** use `theme-primary`
+   as the text/border color of something sitting directly on a surface — for a
+   black/white brand it collides with the surface and vanishes.
+3. **Surface-contrasting foreground uses neutrals.** Body text, borders,
+   dividers, helper text → `theme-text` / `theme-muted` / `theme-border` (or the
+   `color-*` neutrals). These flip with the surface, so they stay readable on any
+   brand in any mode.
+4. **`primary` and `onPrimary` must use the *same form*.** Both hex, or both
+   `color-*`. That keeps the fill and its ink flipping together (or staying
+   together) so the label never disappears.
+5. **Never put a token into a raw inline `style={{}}` or a gradient string.** The
+   resolver only runs on component **props**. Tokens in raw CSS silently break
+   (fine for hex, invisible for `color-*`). This rule is about *consuming* configs;
+   you don't hit it while authoring one, but it's why neutrals must be tokens.
+
+Everything below is an expansion of these five rules.
+
+---
+
+## 1. What you are producing
+
+- **One file:** `src/design-system/configs/<brand>.json`.
+- **One registration line** in `src/design-system/configs/index.ts`.
+
+The fastest correct path is: **copy `default.json`, then change values** — its
+structure is already coherent. Do not invent a new shape.
+
+```bash
+cp src/design-system/configs/default.json src/design-system/configs/<brand>.json
+```
+
+The file has exactly five top-level keys, in this order:
+
+```jsonc
+{
+  "metadata":   { ... },   // identity + fonts
+  "theme":      { ... },   // the 11 semantic color slots  ← the heart of the config
+  "tokens":     { ... },   // typography, spacing, radii, shadows (mostly tooling)
+  "components": { ... },   // per-component slot overrides
+  "personality":{ ... }    // non-color brand cues (shape, weight, density, motif)
+}
+```
+
+The TypeScript contract is [`DesignSystemConfig`](../../src/design-system/types.ts) —
+keep it valid against that.
+
+---
+
+## 2. `metadata`
+
+```jsonc
+"metadata": {
+  "id": "acme",                                  // unique kebab id; MUST match the filename and the index.ts key
+  "label": "Acme",                               // human label shown in the showcase switcher
+  "sourcePath": "",                              // optional reference URL/path; "" is fine
+  "sourceTitle": "Acme brand system (light + dark)",
+  "defaultAppearance": "light",                  // which mode the brand opens in: "light" | "dark"
+  "googleFontLinks": [                           // REQUIRED if typography.fontFamily names a web font
+    "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap"
+  ]
+}
+```
+
+- `defaultAppearance` only sets the **opening** mode — the config still works in
+  both. Pick the mode that flatters the brand (e.g. SpaceX → `dark`).
+- **Every font family referenced in `tokens.typography` must be loaded** via
+  `googleFontLinks`, or it silently falls back to the next family in the stack.
+
+---
+
+## 3. `theme` — the 11 slots (the part that matters most)
+
+Eleven slots. Each is either a **constant hex** or an **adaptive `color-*`
+token**. This single block serves light *and* dark — you never write a second
+config.
+
+```jsonc
+"theme": {
+  "primary":   "#2563eb",        // hex → CONSTANT brand color (CTAs, links, focus)
+  "secondary": "#7c3aed",        // hex → CONSTANT accent
+  "success":   "#16a34a",        // hex → CONSTANT
+  "warning":   "#d97706",        // hex → CONSTANT
+  "error":     "#dc2626",        // hex → CONSTANT
+  "onPrimary": "#ffffff",        // hex → CONSTANT ink that sits on `primary`
+
+  "canvas":    "color-white",    // token → ADAPTS: white in light, black in dark
+  "surface":   "color-gray-50",  // token → ADAPTS: near-white → near-black
+  "text":      "color-black",    // token → ADAPTS: black in light, white in dark
+  "muted":     "color-gray-500", // token → ADAPTS: readable mid-grey in both
+  "border":    "color-gray-200"  // token → ADAPTS: hairline in both
+}
+```
+
+### 3.1 The decision table
+
+| Slot | Role | Form | Why |
+|------|------|------|-----|
+| `primary` | Brand CTA / link / focus | **hex** | Brand identity, same in both modes |
+| `secondary` | Supporting accent | **hex** | Same |
+| `success` / `warning` / `error` | Status accents | **hex** | Same |
+| `onPrimary` | Ink on top of `primary` | **hex** | Contrast for the primary fill |
+| `canvas` | Page background | **`color-*`** | Must flip to go dark |
+| `surface` | Card / elevated background | **`color-*`** | Must flip |
+| `text` | Primary ink / body copy | **`color-*`** | Must flip to stay readable |
+| `muted` | Secondary ink (captions, helper) | **`color-*`** | Must flip |
+| `border` | Hairlines, dividers, control borders | **`color-*`** | Must flip |
+
+### 3.2 Hard constraints (verify these)
+
+- **`primary` and `onPrimary` use the same form.** Both hex (typical), or both
+  `color-*`. Never mix — a hex fill with a flipping ink (or vice-versa) loses its
+  label in one mode.
+- **`onPrimary` actually contrasts `primary`.** ≥ 4.5:1. Usually `#ffffff` for a
+  mid/dark `primary`; use `#000000` for a light/vivid `primary` (e.g. a bright
+  green or yellow).
+- **`primary` reads on *both* `canvas` colors.** Since `primary` doesn't flip, a
+  hue chosen only for white can wash out on black. Aim for ≥ 3:1 against **both**
+  white and black. Most mid-tone brand colors pass; very light or very dark ones
+  don't (see monochrome brands, §3.3).
+- **Body ink is never a brand slot.** Use `text` / `muted` for copy. A constant
+  dark `secondary` used as text becomes invisible on a dark canvas.
+
+### 3.3 Monochrome / black-or-white brands (Nike, Vercel, Uber, SpaceX…)
+
+A brand whose primary *is* black or white is the one case the form rule has to be
+applied deliberately. Two valid strategies — pick one and be consistent:
+
+| Strategy | `primary` | `onPrimary` | Result |
+|----------|-----------|-------------|--------|
+| **A — Constant brand (recommended)** | `"#111111"` (hex) | `"#ffffff"` (hex) | CTA stays the **same** black/white in both modes. Brand-stable. |
+| **B — Adaptive monochrome (authentic Vercel/Linear)** | `"color-black"` | `"color-white"` | CTA **inverts**: black-on-light, white-on-dark. |
+
+- Either way, **both forms match** (A = both hex, B = both `color-*`) — that's
+  rule 4.
+- **Do not** then reuse `primary` for outline/ghost foreground or icons — on the
+  matching surface it disappears. For those, use `theme-text` (which flips with
+  the surface) or a chromatic `secondary`. This is the bug that makes an "outline
+  badge" vanish on the dark card.
+
+### 3.4 Give neutrals character without breaking the flip
+
+Swap the grey *family* — the shade still inverts, only the hue changes:
+
+- `color-slate-*` (cool blue-grey), `color-stone-*` (warm), `color-zinc-*`,
+  `color-neutral-*`.
+
+```jsonc
+"surface": "color-slate-50", "muted": "color-slate-500", "border": "color-slate-200"
+```
+
+**Valid shades:** `50, 100, 200, 300, 400, 500, 600, 700, 800, 900` only.
+`920` / `950` / `960` etc. are **not valid** and will fail to resolve.
+
+---
+
+## 4. `tokens`
+
+Mostly typography (functional) plus documentation/tooling arrays.
+
+```jsonc
+"tokens": {
+  "rawCssVars": { "primary": "#2563eb", "secondary": "#7c3aed", ... },  // descriptive mirror of brand hexes
+  "colors": [ { "name": "primary", "value": "#2563eb", "role": "primary" }, ... ], // descriptive
+  "typography": {
+    "fontFamily": "'Inter', system-ui, -apple-system, sans-serif",       // FUNCTIONAL — used by components
+    "monoFamily": "ui-monospace, 'SF Mono', Menlo, monospace",
+    "fontSizes":   ["12px","13px","14px","16px","18px","22px","28px","36px","48px","64px"],
+    "fontWeights": ["400","500","600","700","800"],
+    "lineHeights": ["1.0","1.1","1.2","1.4","1.5","1.6"]
+  },
+  "spacing": ["2px","4px","8px","12px","16px","24px","32px","48px","64px"],  // 4px grid, documentation
+  "radii":   ["2px","4px","6px","8px","12px","16px","9999px"],               // documentation
+  "shadows": [                                                                // lightest first; components pick by index
+    "0 1px 2px rgba(0,0,0,0.04)",
+    "0 4px 12px rgba(0,0,0,0.08)",
+    "0 12px 32px rgba(0,0,0,0.12)"
+  ]
+}
+```
+
+- **`typography.fontFamily` / `monoFamily` are the only fields components read at
+  runtime.** Always end the stack with a system fallback (`system-ui`,
+  `sans-serif`) so a missing web font degrades gracefully. List any web font in
+  `metadata.googleFontLinks`.
+- `rawCssVars`, `colors`, and the `spacing` / `radii` / `shadows` arrays are
+  reference/tooling material — keep them consistent with the brand but they don't
+  drive rendering on their own.
+
+---
+
+## 5. `components` — per-slot overrides
+
+Each component has a top-level config (variant/size/shape) plus a `views` map of
+named slots. Use overrides to apply the brand's **shape, font, and accent
+tokens** — **not** to re-specify colors a component already handles correctly.
+
+**The token-role rule for every slot:**
+
+| What the slot paints | Use | Examples |
+|----------------------|-----|----------|
+| A **filled** element's background + its ink | `theme-primary` + `theme-onPrimary` | filled badge/button, checkbox `_checked`, radio `dot`, slider `progress`, progress `bar` |
+| A **surface** background | `theme-surface` / `theme-canvas` or a `color-*` neutral | card/input/table/accordion container |
+| A **border / divider** | `theme-border` or `color-gray-200` | container borders, separators, table lines |
+| **Body / heading ink** on a surface | `theme-text` or `color-black`, or `"inherit"` | titles, cell text, labels |
+| **Secondary ink** | `theme-muted` or `color-gray-500` | helper text, captions, descriptions |
+| A **brand-colored accent foreground** | `theme-primary` **only for chromatic brands** | active-tab label, link, alert icon |
+
+> **The trap:** using `theme-primary` for *foreground on a surface* (an outline
+> border, a link, an active-tab label) looks great for a blue brand and
+> **disappears** for a black/white brand, because their `primary` equals the
+> surface in one mode. If the brand is monochrome, switch those to `theme-text`
+> or `theme-secondary`.
+
+Example — a button override that changes only shape/typography and keeps the
+correct fill tokens:
+
+```jsonc
+"button": {
+  "variant": "filled", "size": "md", "shape": "rounded",
+  "color": "theme-primary", "textColor": "theme-onPrimary",
+  "views": {
+    "container": {
+      "borderRadius": 8,
+      "fontFamily": "'Inter', system-ui, sans-serif",
+      "fontWeight": 600,
+      "borderColor": "theme-primary",
+      "letterSpacing": "-0.01em"
+    }
+  }
+}
+```
+
+**Do not lock `label.color`** on form controls (Checkbox, Radio, Switch,
+FieldLabel, StatusIndicator, Table cells). Omit it so the component's `inherit`
+default carries the surrounding ink — see
+[component-library.md §7.2](./component-library.md).
+
+The complete slot map for all 22 overridable components is the
+[`default.json`](../../src/design-system/configs/default.json) you copied —
+treat it as the canonical template and change values slot-by-slot. The component
+name list and slot types are in [types.ts](../../src/design-system/types.ts)
+(`DesignSystemComponentName`).
+
+---
+
+## 6. `personality` — non-color brand cues
+
+Pages and composition helpers read these for brand character that 11 colors can't
+express. Keep it; tune the values.
+
+```jsonc
+"personality": {
+  "cornerStyle": "soft",        // "sharp" | "soft" | "pill"
+  "typeWeight": "regular",      // "light" | "regular" | "bold" | "black"
+  "typeCase": "normal",         // "normal" | "uppercase"
+  "typeStyle": "normal",        // "normal" | "italic"
+  "letterSpacing": "-0.01em",
+  "accentTreatment": "flat",    // "flat" | "gradient" | "stripe" | "glow" | "halftone"
+  "signatureMotif": "●",        // a glyph used as a brand tick/bullet
+  "density": "comfortable",     // "tight" | "comfortable" | "spacious"
+  "surfaceTone": "paper",       // "paper" | "glass" | "matte" | "mono"
+  "cardRadius": 12, "pillRadius": 9999, "badgeRadius": 6,
+  "voice": "neutral-clear"      // free-text descriptor used to pick brand copy
+}
+```
+
+Match these to the brand: Nike → `cornerStyle: "sharp"`, `typeCase: "uppercase"`,
+`typeWeight: "black"`; Revolut/Spotify → `cornerStyle: "pill"`.
+
+---
+
+## 7. Register the config
+
+Add two lines to [`src/design-system/configs/index.ts`](../../src/design-system/configs/index.ts):
+
+```ts
+import acme from './acme.json';            // 1. import
+
+export const designSystemConfigs = {
+  // ...
+  acme: acme as DesignSystemConfig,        // 2. register (key MUST equal metadata.id)
+};
+```
+
+That makes it available as `configId="acme"` and adds it to the showcase
+switcher. Use it anywhere:
+
+```tsx
+<DesignSystemProvider configId="acme">
+  <App />
+</DesignSystemProvider>
+```
+
+---
+
+## 8. Validation checklist (self-check before you finish)
+
+Run through every item — these map 1:1 to the failure modes this system has hit:
+
+- [ ] **JSON is valid** and matches `DesignSystemConfig` (5 top-level keys).
+- [ ] `metadata.id` === filename === `index.ts` key.
+- [ ] **`canvas`, `surface`, `text`, `muted`, `border` are `color-*` tokens** (they MUST flip).
+- [ ] **`primary`, `secondary`, `success`, `warning`, `error`, `onPrimary` are hex** (constant) — *unless* you chose monochrome Strategy B for `primary`/`onPrimary` (then both are `color-*`).
+- [ ] **`primary` and `onPrimary` use the same form.**
+- [ ] `onPrimary` contrasts `primary` ≥ 4.5:1.
+- [ ] `primary` reads ≥ 3:1 on **both** white and black.
+- [ ] **No `color-*` shade outside `50…900`.** No `920/950/960`.
+- [ ] **No brand slot used as body ink**; body uses `text` / `muted`.
+- [ ] **No `theme-primary` used as foreground-on-surface for a monochrome brand** (use `theme-text` / `theme-secondary`).
+- [ ] Every font in `typography` is listed in `metadata.googleFontLinks`; the stack ends in a system fallback.
+- [ ] `label.color` is **omitted** on form-control overrides (let `inherit` work).
+- [ ] Registered in `index.ts`.
+- [ ] **Eyeball both modes** in the showcase — toggle light/dark and confirm: no invisible text, no white-on-white, no vanished outlines, filled CTAs keep readable labels.
+
+---
+
+## 9. Anti-patterns (do NOT do these)
+
+| ❌ Anti-pattern | Why it breaks | ✅ Instead |
+|----------------|---------------|-----------|
+| `"text": "#111111"` | Frozen dark ink → invisible on dark canvas | `"text": "color-black"` |
+| `"canvas": "#ffffff"` | Frozen white page → never goes dark | `"canvas": "color-white"` |
+| `"primary": "color-blue-600"` for a chromatic brand | Brand color shifts between modes unexpectedly | `"primary": "#2563eb"` (hex, constant) |
+| `primary` hex + `onPrimary` `"color-white"` | Mismatched forms → label flips off the fill | Same form for both |
+| `theme-primary` as outline/link color on a **black** brand | Collides with the surface, vanishes | `theme-text` or `theme-secondary` |
+| Writing a separate `<brand>.dark.json` | Unnecessary; dark is derived | One config, adaptive tokens |
+| Adding `appearance === 'dark' ? … : …` anywhere | The system flips for you via tokens | Use the right token form |
+| `color-gray-950` | Invalid shade | `color-gray-900` |
+
+---
+
+## 10. Minimal valid template (copy, then fill in)
+
+```jsonc
+{
+  "metadata": {
+    "id": "acme", "label": "Acme", "sourcePath": "",
+    "sourceTitle": "Acme brand system (light + dark)",
+    "defaultAppearance": "light",
+    "googleFontLinks": ["https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap"]
+  },
+  "theme": {
+    "primary": "#2563eb", "secondary": "#7c3aed",
+    "success": "#16a34a", "warning": "#d97706", "error": "#dc2626",
+    "onPrimary": "#ffffff",
+    "canvas": "color-white", "surface": "color-gray-50",
+    "text": "color-black", "muted": "color-gray-500", "border": "color-gray-200"
+  },
+  "tokens": {
+    "rawCssVars": { "primary": "#2563eb", "secondary": "#7c3aed", "success": "#16a34a", "warning": "#d97706", "error": "#dc2626" },
+    "colors": [
+      { "name": "primary", "value": "#2563eb", "role": "primary" },
+      { "name": "secondary", "value": "#7c3aed", "role": "secondary" }
+    ],
+    "typography": {
+      "fontFamily": "'Inter', system-ui, -apple-system, sans-serif",
+      "monoFamily": "ui-monospace, 'SF Mono', Menlo, monospace",
+      "fontSizes": ["12px","13px","14px","16px","18px","22px","28px","36px","48px","64px"],
+      "fontWeights": ["400","500","600","700","800"],
+      "lineHeights": ["1.0","1.1","1.2","1.4","1.5","1.6"]
+    },
+    "spacing": ["2px","4px","8px","12px","16px","24px","32px","48px","64px"],
+    "radii": ["2px","4px","6px","8px","12px","16px","9999px"],
+    "shadows": ["0 1px 2px rgba(0,0,0,0.04)","0 4px 12px rgba(0,0,0,0.08)","0 12px 32px rgba(0,0,0,0.12)"]
+  },
+  "components": {
+    "button": {
+      "variant": "filled", "size": "md", "shape": "rounded",
+      "color": "theme-primary", "textColor": "theme-onPrimary",
+      "views": { "container": { "borderRadius": 8, "fontWeight": 600, "borderColor": "theme-primary" } }
+    },
+    "card": {
+      "variant": "outlined", "shape": "rounded",
+      "views": {
+        "container": { "backgroundColor": "color-gray-50", "borderColor": "color-gray-200", "color": "color-black", "borderRadius": 12 },
+        "header": { "color": "color-black", "borderColor": "color-gray-200" },
+        "content": { "color": "color-gray-500" }
+      }
+    }
+  },
+  "personality": {
+    "cornerStyle": "soft", "typeWeight": "regular", "typeCase": "normal", "typeStyle": "normal",
+    "letterSpacing": "-0.01em", "accentTreatment": "flat", "signatureMotif": "●",
+    "density": "comfortable", "surfaceTone": "paper",
+    "cardRadius": 12, "pillRadius": 9999, "badgeRadius": 6, "voice": "neutral-clear"
+  }
+}
+```
+
+> Start from the **full** [`default.json`](../../src/design-system/configs/default.json)
+> (all 22 component overrides), not this minimal one, unless you have a reason to
+> omit components — missing components simply fall back to library defaults.
+
+---
+
+## See also
+
+- [theming.md](./theming.md) — how the token resolver and CSS-variable flip work.
+- [component-library.md](./component-library.md) — authoring components against the system.
+- [types.ts](../../src/design-system/types.ts) — the `DesignSystemConfig` contract.
+- [configs/](../../src/design-system/configs/) — 15 shipped brand configs to learn from.