@motion-proto/live-tokens 0.47.1 → 0.48.0

package/.claude/skills/live-tokens-adjust-shape-space/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: live-tokens-adjust-shape-space
+description: Adjust corner radius, padding, gap, and border width across live-tokens components by moving each token alias along the shipped scales. Use when the user asks for pill or capsule buttons, rounded, rounder, sharp, sharper, square corners, softer, harder, a bigger or smaller corner radius, thicker or thinner borders, or talks about spacing and padding. Make the buttons pill shaped, give the cards sharp corners, make the windows sharper, make the UI softer, space it out, tighter, denser, more compact, airier, more breathing room. Changes shape and space aliases per component, never color, fonts, or tokens.css. Not for editing a single token (use the editor) or for color (see live-tokens-generate-theme).
+---
+
+# Adjusting shape and space
+
+You translate the request into a small ops file; the CLI resolves each matching alias on its token ladder, writes the result into each component's unsaved buffer, and prints a report card. Never hand-edit the data tree.
+
+## Workflow
+
+1. Write the ops file to a temp path (not the project tree), e.g. `/tmp/adjust-ops.json`.
+2. Run `npx live-tokens adjust /tmp/adjust-ops.json`. It writes `component-configs/<id>/_working.json` for every component the ops change, which is the buffer the page already runs. `--dry-run` prints the report without writing.
+3. Read the report card: every changed alias old → new, plus skips (raw value, off the ladder, already at the ladder end, pill preserved). Exit 1 means the run was rejected; the message names the offending op or the missing input, so fix it and re-run.
+4. Tell the user to reload the app and look. Offer the inverse op as the undo, and say the edit is unsaved until they save the open theme.
+
+Each run reads the LIVE config (buffer, else the open theme, else the shipped default), so "a bit more" and "back one" compound naturally.
+
+## The ops file
+
+Global, relative:
+
+```json
+{ "ops": [{ "kind": "radius", "shift": 1 }, { "kind": "padding", "shift": 1 }, { "kind": "gap", "shift": 1 }] }
+```
+
+Targeted, absolute:
+
+```json
+{ "ops": [{ "target": "button", "kind": "radius", "set": "--radius-full" }] }
+```
+
+- `name`: ignored. Buffers are fixed slots, so a name names no file, and the CLI says it dropped one. Leave it out.
+- `target` (optional): a component id (the folder names under `src/live-tokens/data/component-configs/`). A named component targets its id: "windows" or "modals" is `dialog`, "cards" is `card`, "tabs" is `tabbar`; an unknown target is a hard error. "The UI", "everything", or no noun at all means global, so omit it.
+- `kind`: `radius | padding | gap | border-width`.
+- `set` or `shift`, exactly one of the two. `set` takes an existing token on that kind's ladder. `shift` is a whole number of steps, clamped at the ladder ends.
+- `full` (radius shifts only): admits `--radius-full` as the ladder's top rung. `set` plus `full` is an error, so a pill request is `set: "--radius-full"` with no `full` flag.
+
+## Idioms
+
+| Request | Ops |
+|---|---|
+| pill, capsule | radius `set: "--radius-full"` |
+| sharp, square corners | radius `set: "--radius-none"`, or `--radius-sm` for "mostly sharp" |
+| rounded (a named component) | radius `shift: 2` |
+| softer, rounder (global) | radius `shift: 1` to `2`, no `full` |
+| harder, sharper | radius `shift: -1` to `-2` |
+| increase the radius, less round, more round | radius `shift: 1` or `-1` with `"full": true`, so repeated pushes reach pill and a pill can come back down |
+| space it out, airier, breathing room | padding and gap `shift: 1` |
+| tighter, denser, more compact | padding and gap `shift: -1` |
+| thicker, thinner borders | border-width `shift: 1` or `-1` |
+
+Magnitude words: "slightly" or "a bit" is 1 step, unqualified is 1 to 2, "much", "way", or "really" is 2 to 3. Mood words often mean both axes: "softer" is rounder plus airier, "compact" is tighter padding plus smaller gaps.
+
+## Ladders
+
+Radius runs `none, sm, md, lg, xl, 2xl, 3xl, 4xl`, with `full` as the gated ninth rung. Space (padding and gap) is the editor picker's subset: `0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 48`, so every written value stays re-editable by hand. Border width is the full `--border-width-*` scale. `set` values must be on the ladder (`--space-64` is rejected); an alias sitting off the subset snaps to the nearest rung when shifted, and the report marks a snap that lands against the requested direction.
+
+## Scope
+
+Every value written is an existing token; nothing new is minted. `tokens.css`, saved themes, colors, and fonts are never touched, so any theme composes with any shape state. An adjustment is an unsaved edit: Save the open theme in the editor to keep it, and Adopt to ship it. Both stay human actions.
+
+## Verify
+
+- The CLI exits 0 and the report card lists the changes you expected, with no surprising skips.
+- The app (dev server running) shows the new shape on each changed component after a reload.
+- `component-configs/<id>/_working.json` exists for every component the report listed. That buffer is the whole change: it stays until the open theme is saved or another theme is loaded.
+- To revert, run the inverse ops, or load a theme in the Theme panel to discard every unsaved edit.

package/.claude/skills/live-tokens-create-component/SKILL.md

@@ -552,7 +552,7 @@ It enforces the file layout, the `:global(:root)` block, token-suffix vocabulary
 1. Registration resolves to a real `sourceFile` and a non-empty schema.
 2. Schema variables are unique within the component.
 3. Every editable token (excluding `hidden: true`, `kind: 'gradient'`, and padding-side suffixes) is declared in the runtime `<style>` block.
-4. Every editable token is seeded in the production-pointed config under `src/live-tokens/data/component-configs/<id>/`.
+4. Every editable token is seeded in `src/live-tokens/data/component-configs/<id>/default.json`.
 5. `setComponentAlias` round-trips the alias through the slice.
 
 A new first-party component is auto-covered the moment it lands in `builtInRegistry` — `npm test` will fail if any of the five checks miss. For a consumer-authored component, mirror this pattern in your own test suite if you want the same drift protection (the same test logic works against any `registerComponent` registration; iterate `getComponentRegistryEntries()` after your `main.ts` has run).
@@ -564,6 +564,6 @@ Finally navigate to `/live-tokens/components` and confirm the runtime behaviours
 - [ ] The new component appears in the nav rail under the **CUSTOM** group (system entries above, custom below the labeled divider).
 - [ ] Token rows render. Color pickers, radius selectors, font selectors all work.
 - [ ] Linked-block (if your component has linked siblings): shared rows appear with the link toggle. Changing the linked value broadcasts across every variant.
-- [ ] First save creates `component-configs/<id>/default.json`. Subsequent saves write `_active.json` plus any named files.
+- [ ] `component-configs/<id>/default.json` is derived from the `:global(:root)` block at boot. Save writes `_working.json`, the unsaved buffer the open theme captures; Save As also writes a named preset.
 - [ ] Reset returns each variable to its `:global(:root)` default.
 - [ ] Boot validation is clean (no warnings about the component being missing from the server scan, or about disk-vs-registry drift).

package/.claude/skills/live-tokens-generate-theme/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: live-tokens-generate-theme
+description: Generate a complete live-tokens color theme from a natural-language mood brief by choosing 10 OKLCH seeds and running the packaged generator, which enforces AA contrast automatically. Use when the user asks for a color theme, color scheme, or palette by mood, vibe, season, holiday, or hue — make me a bright and cheerful theme, give me a dark and moody night theme, a St. Patrick's Day theme with green and gold, a Christmas theme, a red-based theme, make it warmer, more contrast, a calmer palette. Changes color assignments only, never fonts. Not for editing a single token (use the editor) or building pages (see live-tokens-build-page).
+---
+
+# Generating a theme from a mood brief
+
+You translate the brief into 10 OKLCH seed colors plus a scheme; the CLI does everything else (curve assembly, AA contrast enforcement with auto-correction, writing the theme, opening it). Never hand-author theme JSON and never edit the data tree directly. Seeds in, valid theme out.
+
+## Workflow
+
+1. Translate the brief into a seed file using the framework below. Write it to a temp path (not the project tree), e.g. `/tmp/theme-brief.json`.
+2. Run `npx live-tokens generate-theme /tmp/theme-brief.json`. It writes `themes/<slug>.json`, opens that theme, and prints a contrast report card. Exit 1 means unmet floors.
+3. Read the report. Auto-corrections are fine (the engine adjusted text curves to hit the floors). Unmet floors mean the seeds themselves are unworkable; each failure line says which seed to adjust (usually raise the seed's lightness or cut chroma). Fix the brief and re-run — same name, same file, it overwrites.
+4. Tell the user to look at the running app. Offer refinements ("warmer", "more contrast", "less saturated") as seed adjustments to the same brief, re-run.
+
+Flags: `--dry-run` prints the report without writing; `--no-activate` writes the theme without opening it. Opening a theme never changes what the site ships: only Adopt, in the editor, does that.
+
+Warn once per session when iterating: regeneration replaces the whole color state of that theme, including any manual palette tweaks made in the editor after the last generation.
+
+## The brief
+
+```json
+{
+  "name": "Spring Meadow",
+  "scheme": "light",
+  "seeds": {
+    "Brand":     { "l": 0.62, "c": 0.17, "h": 145 },
+    "Accent":    { "l": 0.80, "c": 0.15, "h": 95 },
+    "Special":   { "l": 0.60, "c": 0.19, "h": 300 },
+    "Canvas":    { "l": 0.97, "c": 0.01, "h": 120 },
+    "Neutral":   { "l": 0.55, "c": 0.012, "h": 140 },
+    "Alternate": { "l": 0.58, "c": 0.009, "h": 60 },
+    "Info":      { "l": 0.60, "c": 0.15, "h": 255 },
+    "Success":   { "l": 0.60, "c": 0.16, "h": 150 },
+    "Warning":   { "l": 0.75, "c": 0.15, "h": 85 },
+    "Danger":    { "l": 0.58, "c": 0.20, "h": 25 }
+  },
+  "harmony": { "mode": "analogous" }
+}
+```
+
+All 10 seeds are required. A seed may also be a `"#rrggbb"` hex string (converted for you). OKLCH: `l` 0–1 perceptual lightness, `c` chroma (0 grey, ~0.37 max), `h` hue degrees. `name` becomes the theme file slug, tidied to lowercase with hyphens and stripped of any leading underscore (those names are reserved); `"default"` is refused (protected package theme). `harmony` is an optional record of your reasoning; the seeds are ground truth. `canvasGradient` is an optional boolean — see "The canvas sky" below before setting it.
+
+Roles: **Brand** is the dominant chromatic identity; **Accent** the supporting color; **Special** the rare expressive tertiary; **Canvas** is the page background verbatim; **Neutral** drives all neutral surfaces and body text; **Alternate** is the second near-grey family; the four status colors are conventional signals.
+
+## Chroma budget: color is inversely proportional to area
+
+| Tier | Palettes | Chroma |
+|---|---|---|
+| Ground (~60% of every screen) | Canvas, Neutral, Alternate | C 0.005–0.03 |
+| Dominant chromatic (~30%) | Brand | C 0.10–0.20 |
+| Garnish (~10%) | Accent, Special | may exceed Brand; at most one at full saturation |
+| Conditional | Info, Success, Warning, Danger | C 0.12–0.19 |
+
+A good theme reads as 3–4 hue families on screen, never 10. Neutral and Alternate stay near-grey, tinted toward the theme (Neutral near Brand's hue; Alternate offset +15–60° or as a warm/cool counterpoint), never pure C = 0.
+
+## Per-role bands
+
+| Seed | Light scheme | Dark scheme | Hue |
+|---|---|---|---|
+| Canvas | L 0.92–0.98, C 0.02–0.06 (see below) | L 0.15–0.28, C 0.01–0.05 | brand hue or its harmony slot |
+| Neutral / Alternate | L ≈ 0.55, C 0.008–0.02 | same | see chroma budget |
+| Brand | L 0.45–0.62, C 0.12–0.20 | L 0.70–0.83, C cut by ~⅓ | the brief's identity hue |
+| Accent | harmony slot, or ΔL ≥ 0.25 from Brand when the mode collapses hue distance | lighten/desaturate like Brand | harmony slot |
+| Special | most expressive; default = Brand hue +60° at ~65% of Brand's C | same transform | harmony slot |
+| Info | shared status L (0.55–0.65 light) | lighten like Brand | H 230–260 |
+| Success | shared status L | same | H 140–155 |
+| Warning | L ≥ 0.75 (vivid yellow must be light) | same | H 70–90 |
+| Danger | shared status L, C 0.15–0.20 | same | H 20–30 |
+
+- **The canvas carries the theme's identity — commit to it.** The page background is the largest area on screen and the strongest differentiator between themes; a timid canvas makes every theme look the same. Below C ≈ 0.015 at L ≥ 0.95 a tint is imperceptible: that near-white is a deliberate choice for clean/minimal briefs, never the default. Three escalating levels of commitment, matched to the brief:
+  1. *Tinted paper* (most UI briefs): a tint you can actually see — C 0.02–0.06, dropping L to 0.92–0.95 where the hue needs room.
+  2. *Colored ground* (expressive briefs): L 0.85–0.92 at C 0.05–0.10 — the page is unmistakably mint, parchment, sky.
+  3. *Full-color ground* (holiday and statement briefs): the canvas IS the theme color — a red Christmas page (0.40–0.48, C 0.12–0.16, H 25) with green and gold on it, an orange Halloween page. Keep canvas L ≤ ~0.48 or ≥ ~0.85 so text has somewhere to go; the contrast gate enforces legibility either way. A saturated background is a legitimate choice, not something to correct.
+- **Gamut note for light canvases**: blue tints cap very low at high L (H 264 at L 0.95 barely reaches C 0.03) — for a blue-leaning canvas, lower L instead of fighting the ceiling; yellow/green/cream hues tint generously at high L.
+- **When generating a set of themes, make the canvases pairwise distinct.** Any two Canvas seeds should differ noticeably in hue (at visible chroma) or in L. Two light themes both near (0.97, 0.01, anything) read as the same theme with different buttons. Dark canvases differentiate the same way: deep indigo, plum, and near-black violet are three different nights.
+- **Dark scheme is a transform, not just a dark Canvas**: every chromatic seed lightens to L ≈ 0.75–0.85 and drops about a third of its chroma. Saturated color vibrates on dark grounds.
+- **Equal lightness = equal weight**: give the four statuses one shared L; do the same for Brand vs Accent when they should balance.
+- Status hues never rotate with the harmony; only their L/C adapt to the mood.
+
+## Mood dials
+
+Empirically: pleasantness rises with lightness (strongly) and saturation (weakly); energy/arousal rises with saturation; drama/dominance rises with dark + saturated.
+
+| Brief says | Dials |
+|---|---|
+| cheerful, bright, playful | light scheme; Brand/Accent L 0.7–0.9, C 0.15–0.22; warm hues 40–140 (yellow is the strongest joy hue) |
+| calm, serene, soft | light scheme; C 0.03–0.08 on everything chromatic; cool hues 140–260 |
+| energetic, bold | C ≥ 0.18 at L 0.55–0.65; red/orange/magenta |
+| dark, moody, dramatic, luxurious | dark scheme; Canvas L 0.15–0.25; purple, deep blue, crimson; keep working accents light per the dark transform, reserve dark-saturated color for one or two moments |
+| professional, trustworthy | blue 230–265, C 0.08–0.15; everything else muted |
+| warm / cool | hues 20–110 (plus pink 290–360) / hues 140–290 |
+
+Avoid mid-lightness yellow-green (H 100–120 at L 0.5–0.7, C ≈ 0.1) unless the brief asks for olive/toxic.
+
+## Gamut guardrails (don't request impossible seeds)
+
+- Dark saturated yellow does not exist: H 90 at L 0.4 caps at C ≈ 0.08 and reads olive. Vivid yellow needs L ≥ 0.8. Brown = dark low-chroma orange.
+- Vivid light blue does not exist: H 264 at L 0.9 caps at C ≈ 0.05. Rich blue lives at L 0.40–0.55.
+- Teal/sky cap at C ≈ 0.15; a "vivid teal" is C 0.13–0.15.
+- Peak chroma anchors: red H20 C 0.25 @ L 0.63; orange H60 C 0.18 @ L 0.76; yellow H90 C 0.18 @ L 0.86; green H140 C 0.28 @ L 0.88; blue H264 C 0.28 @ L 0.50; magenta H320 C 0.31 @ L 0.65.
+
+The engine gamut-clamps regardless; these rules keep your *intent* achievable rather than silently muted.
+
+## Choosing the harmony mode
+
+Modes and hue offsets from Brand: complementary +180; split-complementary +150/+210; triadic +120/+240; tetradic +60/+180/+240; square +90 steps; compound +30/+180/+210; analogous ±30; monochromatic same hue.
+
+- Vague or single-adjective brief → monochromatic or analogous; differentiate Accent from Brand by L/C, not hue. Polished-UI default: Accent = Brand's hue at ~45% chroma, Special = +60° at ~65% chroma.
+- Brief names two colors → measure their hue gap and pick the matching mode (green + gold ≈ 60–90° → analogous/compound).
+- Drama or maximum contrast → complementary/triadic/tetradic; then never pair max-chroma text with a near-black ground; tone one side down.
+
+## The canvas sky (optional page-background gradient)
+
+The brief may set `"canvasGradient": true` to render the page background as a
+vertical gradient built from the Canvas ramp. The engine picks the stops itself
+(two ramp steps from the Canvas anchor on the scheme's safe side), so the
+choice you make is only *whether*, never *how*.
+
+Default **off**. Turn it on only when the brief evokes atmosphere: sky, night,
+dusk, dawn, sunset, glow, candlelight, underwater, depth — or when the user
+asks for a gradient outright. Keep it off for crisp, clean, flat, minimal, or
+corporate briefs, and whenever in doubt. Most themes should not have one; a sky
+that appears on every generated theme stops meaning anything. When you enable
+it, say why in one sentence when reporting back ("night brief → canvas sky").
+
+A sky needs a committed canvas: when the Canvas seed anchors at the ramp edge
+(near-white light canvas, near-black dark one) there is no room on the safe
+side and the engine skips the sky, saying so in the report. An atmospheric
+brief that wants one should already be at canvas commitment level 2–3.
+
+## Named themes (canonical OKLCH anchors)
+
+Holiday briefs are statement briefs — default to commitment level 2–3 above, not cream. The named colors go on the *ground*, not just the buttons.
+
+- **Christmas**: red (0.53, 0.21, 22) + green (0.46, 0.11, 155) + gold (0.77, 0.14, 91). Strongest form: a full red canvas (0.42, 0.14, 25) with green Brand and gold Accent on it (dark scheme). Softer form: evergreen canvas (0.35, 0.07, 160) or deep cream (0.95, 0.04, 85). Never a 50/50 red-green split — one owns the ground, the other highlights.
+- **Halloween**: pumpkin (0.70, 0.20, 46) + purple (0.51, 0.21, 313) + poison green (0.73, 0.20, 137). Strongest form: an orange canvas (0.45, 0.13, 55) with violet and poison-green accents; alternative: near-black violet canvas with pumpkin Brand. Dark scheme either way.
+- **St. Patrick's**: green (0.51, 0.13, 152) Brand, gold Accent, white/beige neutrals.
+- **Ocean**: deep blue (0.35, 0.08, 237) vs aqua (0.78, 0.12, 214); H 180–240.
+- **Sunset**: hues 90 → 320 through red, L falling 0.85 → 0.40.
+- **Autumn / Fall**: leaves and dry grass — canvas warm tan/parchment (0.87, 0.06, 80), rust Brand (0.55, 0.15, 40), golden Accent (0.75, 0.15, 85), moss/olive Special (0.55, 0.10, 120), warm brown neutrals H 50–70. Deep red H 25 welcome. **Spring**: pastels L 0.85–0.95, C 0.04–0.10, greens 130–150 / pinks 0–20, mint canvas.
+
+## Scope
+
+Fonts are never touched (they carry forward from the live look, as do shadows and component aliases). Swatch gradients (`--gradient-1..4`) carry forward when user-tuned; if they are absent or still stock, the engine rebuilds them from the new theme's families — you never author them. Radius is out of scope for generation. Shipping the theme stays a human action: Adopt, in the editor.
+
+## Verify
+
+- The CLI exits 0 and the report card shows every check ✓ (auto-corrected is fine).
+- The app (dev server running) shows the new theme after a reload; the editor's Theme panel names it.
+- If the user wants the previous look back, the CLI output names the theme that was open; load it from the Theme panel.

package/CHANGELOG.md

@@ -1,5 +1,275 @@
 # Changelog
 
+## 0.48.0 — Themes are documents
+
+### Added
+
+- **Loading is preview first.** Picking a theme in the Load window paints
+  it on the page while the window stays open: switch between looks freely,
+  then Save to keep one or Cancel to return to exactly what you had,
+  unsaved edits included. The preview is paint only; nothing touches disk
+  until Save. A "Colors and type only. Keep my shapes" toggle previews and
+  loads just a theme's palette and fonts over your current component
+  shapes, and your own saved colors-and-type files appear in the same list
+  under a badge, where that mode is implied.
+
+- **One Theme panel.** The editor's separate colors-and-type and theme
+  managers merge into a single panel: one identity, Save, Save As, Load,
+  Import, Export. Colors & Type and a Components drift count appear as
+  read-only parts inside it, the way a component shows its parts. The seven
+  presets live in this panel's Load list and nowhere else. Save captures the
+  look on screen, the colors and type you have been editing included, so
+  there is no separate save first.
+
+- **Adopt ships the whole look.** Production state and the Adopt action
+  live on the Theme panel's root card: one action saves the open theme and
+  publishes it, colors and type plus every component it carries, with one
+  CSS regeneration. Component editors hold their own unsaved state, which
+  the panel cannot write, so Save and Adopt both say how many components are
+  waiting on their own editors before they run.
+
+- **`generate-theme` turns a mood brief into a complete theme.** `npx
+  live-tokens generate-theme <brief.json>` takes ten OKLCH seeds plus a
+  scheme, assembles the full curve set, enforces AA contrast with automatic
+  correction rounds, writes `themes/<slug>.json`, and opens it. The bundled
+  `live-tokens-generate-theme` skill translates natural-language briefs
+  ("dark and moody night theme", "St. Patrick's Day with green and gold")
+  into seeds. Seven preset themes generated this way ship in the package:
+  Autumn, Halloween, Midnight Study, Ocean, Royal Velvet, Spring Meadow,
+  Sunset.
+
+- **`adjust` moves shape and space along the token scales.** `npx
+  live-tokens adjust <ops.json>` shifts or sets every matching radius,
+  padding, gap, and border-width alias across component configs: relative
+  shifts preserve the cross-component hierarchy, `--radius-full` is a
+  gated rung so a global "softer" never silently turns the UI into
+  capsules, and spacing moves along the editor picker's 12-step subset so
+  every written value stays hand-editable. The result lands in each
+  component's unsaved buffer, so save the open theme to keep it. The bundled
+  `live-tokens-adjust-shape-space` skill maps "make the buttons pill
+  shaped", "make the UI softer", "space it out" onto ops files.
+
+- **Gradients travel with the theme.** The `--gradient-N` swatch tokens
+  round-trip through colors-and-type files as a structured `gradients` field:
+  the editable type, angle, and stops, not just the rendered CSS strings, which
+  stay in `cssVariables` as a projection for production. Loading restores your
+  tuned gradients; files saved before the field existed keep the stock set they
+  rendered. `generate-theme` carries tuned gradients forward and rebuilds stock
+  ones from the new theme's color families.
+
+- **Themes are encapsulated.** A theme now carries its whole look by value
+  (`schemaVersion: 3`): its full colors and type plus a copy of every
+  non-default component config. Deleting any colors-and-type or component
+  file never breaks a saved theme, and the import/export bundle is the same
+  format as the file on disk. Existing pointer themes migrate on first
+  dev-server start, resolving and embedding what they reference.
+
+- **The seven presets ship as full example looks.** One theme per preset
+  embeds its colors and type plus a distinct shape personality and a Google
+  Fonts pairing: Halloween goes fully square with heavy borders and Mystery
+  Quest, Midnight Study pairs sharp windows and round buttons with EB
+  Garamond, and no two presets share a corner-radius and spacing profile or
+  a font family. Load one to try the complete look, load Motion Proto to
+  come back. `npm run generate:preset-themes` regenerates all seven from the
+  component defaults.
+
+### Changed
+
+- **Themes are documents; the working set is a buffer. (breaking)** A theme file
+  is the whole look, `themes/_active.json` names the one the editor has open,
+  and `themes/_production.json` names the one your site ships. Anything not yet
+  saved into a theme lives in one reserved slot per layer, `_working.json`, and
+  a slot exists only where the look sits off the shipped default, so a new
+  project has none. The per-layer `_active.json` / `_production.json` pointer
+  files, about fifty in a full tree, are retired, and applying a theme no longer
+  writes a copy of it under its own slug. The files that piled up, one set per
+  theme sampled, go with the mechanism that made them.
+
+- **Trying a theme no longer publishes it. (breaking)** Loading a theme used to
+  set production in the same step, so sampling the presets rewrote
+  `tokens.generated.css` behind your back. Loading now opens the theme and does
+  nothing else. Adopt is the only action that changes what your site ships.
+
+- **A component ships with its theme. (breaking)** Production is one saved theme
+  rather than a mix of per-slice pointers, so a component editor's Adopt saves
+  and publishes the open theme, that component with it. The per-slice promote
+  door is gone.
+
+- **Existing projects need one `npx live-tokens migrate`.** It starts with the
+  directories: a project last opened on 0.47.1 or earlier keeps its colors and
+  type in `data/themes/` and its whole looks in `data/manifests/`, so the
+  migration moves `themes/` to `colors-and-type/` and `manifests/` to `themes/`
+  before reading a single file. Then it heals what is inside. It reads what the
+  retired pointers resolved to and records it as the production theme, keeps
+  live state that had drifted from the open theme as a buffer, deletes the
+  copies a saved theme already carries, and clears the pointer files. A file
+  matching no theme is yours and is kept; the effective production output never
+  changes without being written down as `themes/recovered-production.json`, so
+  that file appearing is the normal outcome when your live look had drifted from
+  the production pointers, not an error. `--check` prints the whole plan,
+  renames included. Until you run it the dev server leaves the data directory
+  alone: it writes nothing, rebuilds no CSS, refuses the editor's save doors,
+  and prints what to run. Restart it afterwards.
+
+  Two things to finish by hand. Token references that the migration repaired
+  reach `tokens.generated.css` on the next save and adopt, not at migration
+  time, so re-save your theme (make any edit, or Save As over it) and adopt it
+  once. And a `.gitignore` entry for `data/themes/_backups/` or
+  `data/manifests/_backups/` now names the wrong directory: any old backups move
+  with their directory, so repath the entry to `data/colors-and-type/_backups/`
+  or drop it.
+
+- **`npm update` will not bring you here.** Pre-1.0 a caret range pins the
+  minor, so `^0.47.1` never resolves to 0.48.0. Ask for it by name: `npm
+  install @motion-proto/live-tokens@0.48.0`.
+
+- **Re-copy the bundled skills.** `npx live-tokens setup-claude` copies the
+  Claude Code skills into your repo's `.claude/skills/`. That copy is a copy: it
+  does not follow the package, and a stale one describes CLIs and files this
+  release changed. Run the command again after upgrading, with `--force` to
+  overwrite.
+
+- **The REST surface, before and after.** For anyone who proxies, mocks or
+  scripts `/api/live-tokens/*`. A door retired in place answers 405, so a caller
+  that still holds one gets an answer it can read. The `/manifests/*` paths are
+  not retired in place: they are gone, and the middleware passes them through to
+  your app like any unclaimed URL.
+
+  | Before, through 0.47.1 | Now |
+  | --- | --- |
+  | `/themes`, `/themes/:name` (colors and type) | `/colors-and-type`, `/colors-and-type/:name` |
+  | `GET /themes/active`, `PUT /themes/active` | `GET /colors-and-type/active`; writes go to `PUT /colors-and-type/working` |
+  | `GET`/`PUT /themes/production` (colors and type) | `/colors-and-type/production`, 405 on every method |
+  | `PUT /component-configs/:comp/active` | `PUT /component-configs/:comp/working` |
+  | `GET`/`PUT /component-configs/:comp/production` | 405 on every method: a component ships with its theme |
+  | `/manifests`, `/manifests/:name`, `/manifests/:name/apply`, `/manifests/:name/export`, `/manifests/import` | the same shapes under `/themes` |
+  | `GET`/`PUT /manifests/active` | `GET`/`PUT /themes/active` |
+  | new | `PUT /production`: adopt the open theme, the only door that publishes |
+  | new | `GET /themes/production`: the whole theme your site ships |
+  | new | `GET`/`PUT`/`DELETE /colors-and-type/working` and `/component-configs/:comp/working` |
+
+- **Public API. (breaking)** `setActiveFile`, `setProductionFile`,
+  `getProductionInfo`, the `ProductionInfo` type and the `activeFileName` store
+  leave with the per-layer pointers they drove. `getProductionTheme`,
+  `writeWorkingColorsAndType`, the `LiveSource` type and the `openThemeSlug`
+  store arrive.
+
+- **CLIs follow the model.** `generate-theme` writes `themes/<slug>.json` and
+  opens it, instead of writing a colors-and-type file and flipping pointers at
+  it. `adjust` writes each touched component's buffer; its `--no-activate` flag
+  named files that no longer exist, so it is rejected with what to do instead.
+  `live-tokens migrate` runs the data heal alongside the tokens.css migrations.
+
+- **One Theme panel, one save and load surface.** The editor sidebar holds a
+  single Theme panel: Save, Save As, Load with preview, Import, Export, the
+  production state and Adopt at the root, with Colors & Type and Components
+  as read-only parts under it. Colors and type stops being a file the user
+  manages: no list, no Save, no Save As, no lifecycle of its own. It names
+  the two faces the page is showing, and no working file name appears
+  anywhere in the panel.
+
+- **Load can take colors and type alone.** "Colors and type only. Keep my
+  shapes." in the Load window previews and applies just the palette and the
+  fonts, leaving every component setting as it is. Older colors and type
+  files are listed there too, marked, and picking one is always that
+  narrower load. `GET /colors-and-type` marks each file `isPackage`, so a
+  local copy of a shipped preset stays reachable while the presets
+  themselves are offered once, as whole themes.
+
+- **The Default theme is written and regenerated at boot.** It is a full set
+  derived from the package default colors and type and each component's
+  `:global(:root)` defaults, rewritten whenever the derived content drifts
+  and restored if deleted outside the file manager. The package no longer
+  ships the file; a consumer's boot always materializes a current local
+  copy.
+
+- **Almost everything is deletable.** Colors-and-type and component files are
+  presets now, so nothing live points at one and any of them can go. Deleting
+  the theme you have open is legal too: the buffer survives its document, so
+  the look on screen stays, and open heals to the shipped version if one
+  shadows it, otherwise to Default. Three refusals remain, each about
+  something a delete would break: the protected `default` name, the theme in
+  production, and a shipped file with no local copy.
+
+- **Load applies the complete look.** Loading a theme opens it: its embedded
+  copies fill the working buffer and components it does not carry go back to
+  their defaults. Components that are not installed are skipped and reported
+  instead of silently ignored.
+
+- **"Manifest" retires; a theme is the whole look.** The file that carries a
+  complete look is a **theme**, and the colors-and-typography layer inside it
+  is **Colors & Type**. Every surface follows: `data/manifests/` →
+  `data/themes/` and the old `data/themes/` → `data/colors-and-type/`;
+  `/api/live-tokens/manifests/*` → `/api/live-tokens/themes/*` and the old
+  `/api/live-tokens/themes/*` → `/api/live-tokens/colors-and-type/*`; the
+  public exports `listManifests`, `applyManifest`, `saveAsManifest` and their
+  siblings become `listThemes`, `applyTheme`, `saveAsTheme`; `npm run
+  generate:preset-manifests` and `collapse:manifest` become
+  `generate:preset-themes` and `collapse:theme`. The manifest family never
+  shipped, and the routes ship as a matched client and server pair, so no
+  compatibility shim exists anywhere. The one key a consumer must act on is
+  below.
+
+- **Config keys follow the vocabulary.** `themesDir` now names the whole-look
+  directory, the meaning `manifestsDir` used to carry; the new
+  `colorsAndTypeDir` names the colors-and-typography directory that
+  `themesDir` used to name. A consumer that set `themesDir` in
+  `live-tokens.config.json` before this release must rename it to
+  `colorsAndTypeDir`.
+
+- **A theme file is `schemaVersion: 3`.** The embedded key `theme` becomes
+  `colorsAndType`. The boot migration carries a v1 pointer file or a v2
+  encapsulated file to v3 in one pass. Export writes `kind: "theme-bundle"`
+  at that version; the `manifest-bundle` kind every release through 0.47.1
+  wrote is still imported, and only at its own v1, so a crossed pair stays
+  rejected.
+
+### Fixed
+
+- **Dead shape and space keys dropped from every colors-and-type file**
+  (colors-and-type schema version 4): the `--badge-trait-*`,
+  `--sectiondivider-padding`, and `--dialog-{primary,secondary}-*` shape keys
+  had no consumers since their components were restructured; a migration
+  removes them from `cssVariables`.
+
+- **Line-height references follow the scale that was renamed under them**
+  (colors-and-type schema version 5, component-config schema version 21):
+  0.41.0 reshaped `--line-height-{xs..xl}` into leading vocabulary in
+  `tokens.css`, but nothing carried a saved file's references across, so every
+  one of them pointed at a token that no longer existed. Both layers now migrate
+  on load, a colors-and-type file's `cssVariables` and a component config's
+  alias values alike: `xs` to `none`, `sm` to `tighter`, `md` to `normal`, `lg`
+  to `relaxed`. The retired 2.0 slot (`xl`) lands on `relaxed`, the nearest
+  surviving step, which is a visible change to any line that used it.
+
+- **A colors-and-type file left among the themes is refused, not read as a
+  theme.** Both kinds carry a `schemaVersion` and the sequences overlap, so one
+  parsed as a current theme whose colors resolved to the package default: it
+  listed as a theme that painted the shipped look, and the boot migration
+  rewrote it, taking the palette with it. Every door that reads a theme off disk
+  now checks the shape, answers 422, and leaves the file alone.
+
+- **Adopting while a shipped theme is active records the adoption.** The
+  adopt path used to return success while writing nothing when the active
+  theme resolved from the package; it now forks the theme locally,
+  shadow-and-restore style.
+
+- **Orphan component-config directories removed** (`detailnav`, `stateditor`,
+  `slotprobe`, `floatingtokentags`): no shipped component reads them.
+
+- **`collapse-theme-to-default` no longer drops `harmonyAxes`** or coerces a
+  missing `fontStacks` to an empty object when baking a theme into the
+  shipped defaults.
+
+### Known limitations
+
+- **Production freshness resets on reload.** Nothing on disk records when the
+  last bake happened, so the editor tracks it for the session. Save a theme
+  after adopting it and the panel reads "out of sync" until you adopt again,
+  which is right; reload the page and it reads "in production" again while the
+  baked CSS is a version behind. Adopt when in doubt, it costs nothing to
+  repeat.
+
 ## 0.47.1 — Straightened curves
 
 ### Fixed