@motion-proto/live-tokens 0.47.0 → 0.48.0

package/README.md

@@ -8,12 +8,13 @@ A foundational design system for quickly styling and building Svelte + Vite micr
 
 - **Real-time token editing.** Pick a color, drag a hue slider, retype a font size — the page repaints on every input event via CSS-variable writes. No reload, no save-and-refresh, no build step. Works across colors, typography, spacing, radii, shadows, motion, palettes, and gradients.
 - **Real-time component editing.** Each of ~24 shipped Svelte components (Button, Input, Card, Dialog, Badge, Callout, Table, Tooltip, Toggle, TabBar, SegmentedControl, RadioButton, MenuSelect, ProgressBar, CornerBadge, SectionDivider, CollapsibleSection, Notification, Image, ImageLightbox, CodeSnippet, SideNavigation, and more) declares its own design-token aliases in a `:global(:root)` block. Rewire any alias from a per-component picker and see that component update everywhere it's used — live, on your real pages, not in a Storybook sandbox.
-- **Theme editor** (`/live-tokens/editor` route, dev-only) — the home of real-time token editing. Save themes to disk as JSON, promote one to "production" to bake it into a static `tokens.css` for the build.
+- **Theme editor** (`/live-tokens/editor` route, dev-only) — the home of real-time token editing. Save themes to disk as JSON, then Adopt one to bake it into static CSS for the build.
 - **Per-component editor** (`/live-tokens/components` route, dev-only) — the home of real-time component-alias editing. Pick token aliases per component without writing CSS.
 - **Live editor overlay** — pins to the top-right of every dev page. Opens the editor in a side panel or floating window so you edit *on the page you're styling*, not in a separate tab. Includes a "Page Source" button that opens the current page's `.svelte` file in VS Code.
-- **Manifests** — a manifest captures a whole site configuration as one portable artifact: the theme in one slot, every component in its own slot, each holding either the shipped default or a custom file. Export it as a bundle and import it into another project to restore the full styling in one step.
-- **Vite plugin** — hosts the `/api/live-tokens/{themes,component-configs,manifests}/*` routes that persist your edits to disk as you make them. The single namespace keeps live-tokens' routes from colliding with anything your app serves under `/api`.
-- **Claude Code skill suite** — three bundled skills so you can drive the package in plain English. `build-page` composes pages from the shipped components. `pick-component` decides between confusing pairs (TabBar vs SegmentedControl, Card vs CollapsibleSection). `create-component` authors a new editable component against the project's naming, state-model, and import rules. One command to install all three: `npx @motion-proto/live-tokens setup-claude`. See [Claude Code skills](#claude-code-skills) below.
+- **Themes** — a theme is a whole look in one file: colors and type plus a config for every component you changed, held by value. In the editor this is the Theme panel, with Colors & Type and Components as its parts. Themes are documents: loading one opens it, filling the editor's working buffer and returning every component it does not carry to its default, and nothing your site ships changes until you Adopt. A narrower load takes the colors and type alone and leaves your shapes. Export one and import it into another project to restore the full styling in one step.
+- **Seven example looks** — Autumn, Halloween, Midnight Study, Ocean, Royal Velvet, Spring Meadow and Sunset each ship as a full theme: preset colors and type plus a shape personality of radius, padding, gap and border-width aliases. Each preset also names its own Google Fonts pairing, one display family and one body family, so a look carries type as well as colour and shape. They need no local files, so Load one to try a whole look on your own pages and load Motion Proto to come back. Saving over a preset writes a local copy that shadows the shipped one; delete that copy and the shipped version returns.
+- **Vite plugin** — hosts the `/api/live-tokens/{colors-and-type,component-configs,themes}/*` routes the editor reads and saves through. The single namespace keeps live-tokens' routes from colliding with anything your app serves under `/api`.
+- **Claude Code skill suite** — five bundled skills so you can drive the package in plain English. `build-page` composes pages from the shipped components. `pick-component` decides between confusing pairs (TabBar vs SegmentedControl, Card vs CollapsibleSection). `create-component` authors a new editable component against the project's naming, state-model, and import rules. `generate-theme` turns a mood brief ("bright and cheerful", "dark night theme") into a complete AA-checked color theme. `adjust-shape-space` turns "make the buttons pill shaped" or "space it out" into new radius, padding, gap, and border-width aliases. One command to install them all: `npx @motion-proto/live-tokens setup-claude`. See [Claude Code skills](#claude-code-skills) below.
 
 ## Quick install
 
@@ -42,14 +43,20 @@ export default defineConfig({
 ```
 
 The `themeFileApi` plugin:
-- Seeds `src/live-tokens/data/themes/` with a default theme on first dev-server start.
+- Resolves the `default` colors and type from the installed package, so you start on the shipped defaults without a local copy.
 - Discovers components at `src/components/*.svelte` (and `src/system/components/*.svelte` for back-compat) and seeds `src/live-tokens/data/component-configs/{comp}/default.json` from each component's `:global(:root)` block.
+- Writes `src/live-tokens/data/themes/default.json` on dev-server start: the Default theme, derived from the shipped colors and type and those component defaults, and regenerated whenever they change. It is protected, so the editor never deletes it and an outside deletion heals on the next start.
+- Bakes `tokens.generated.css` from the production theme at startup, so a fresh checkout builds against the look you shipped.
 - Hosts the `/api/live-tokens/*` routes the editor uses to save and load themes + per-component configs.
 - Auto-injects `__PROJECT_ROOT__` for the overlay's "Page Source" link and `__LIVE_TOKENS_API_BASE__` so the client uses whatever `apiBase` you configured.
 
+A project last opened on 0.47.1 or earlier still keeps its colors and type in `themes/` and its whole looks in `manifests/`, the names 0.48 reassigned. The plugin recognises that layout, writes nothing at all, and says so. `npx live-tokens migrate` moves `themes/` to `colors-and-type/` and `manifests/` to `themes/`, then heals what is inside: it reads what the retired per-layer `_active.json` / `_production.json` pointers resolved to, records it as the production theme, and clears them. Restart the dev server afterwards.
+
 ### Where data lands — and how to move it
 
-By default, the plugin reads and writes under one folder: `src/live-tokens/data/`. Inside that folder live three subdirectories — `themes/`, `manifests/`, `component-configs/` — each owned by the plugin.
+By default, the plugin reads and writes under one folder: `src/live-tokens/data/`. Inside that folder live three subdirectories — `colors-and-type/`, `themes/`, `component-configs/` — each owned by the plugin.
+
+`themes/` holds the documents: one file per whole look, plus `_active.json` naming the one the editor has open and `_production.json` naming the one your site ships. `colors-and-type/` and `component-configs/{comp}/` hold each layer's `default.json` baseline, any preset you save by name, and the `_working.json` buffer for edits you have not saved into a theme. A buffer exists only where the look sits off the shipped default, so a new project has none.
 
 To move them, create a `live-tokens.config.json` at your project root:
 
@@ -59,17 +66,19 @@ To move them, create a `live-tokens.config.json` at your project root:
 }
 ```
 
-All four keys are optional. `dataDir` is the headline knob — it relocates all three subfolders at once. The per-folder overrides exist for unusual layouts (e.g. a monorepo where themes are shared across packages but component-configs aren't):
+All four keys are optional. `dataDir` is the headline knob — it relocates all three subfolders at once. The per-folder overrides exist for unusual layouts (e.g. a monorepo where colors and type are shared across packages but component-configs aren't):
 
 ```json
 {
   "dataDir": "src/live-tokens/data",
-  "themesDir": "../shared/themes",
+  "colorsAndTypeDir": "../shared/colors-and-type",
   "componentConfigsDir": "src/live-tokens/data/component-configs",
-  "manifestsDir": "src/live-tokens/data/manifests"
+  "themesDir": "src/live-tokens/data/themes"
 }
 ```
 
+`colorsAndTypeDir` holds the colors-and-type files; `themesDir` holds the whole-look themes.
+
 Resolution order, per folder: explicit `themeFileApi(opts)` argument > matching key in `live-tokens.config.json` > `<dataDir>/<sub>`. The dev server reads the file once at startup — restart vite to pick up changes.
 
 ### Bootstrap in `main.ts`
@@ -204,8 +213,8 @@ import '@motion-proto/live-tokens/app/fonts.css';  // optional: Fraunces + Manro
 ```
 
 …or copy `node_modules/@motion-proto/live-tokens/src/system/styles/tokens.css` into
-your project and edit. The editor will seed `themes/default.json` on first
-run and you can promote your edits back into the file.
+your project and edit. It stays hand-authored: the editor writes what you Adopt
+into the sidecar `tokens.generated.css`, never back into `tokens.css`.
 
 ## Consuming live-tokens from scratch
 
@@ -269,8 +278,8 @@ src/
   system/styles/tokens.css        # vendored Layer-1 tokens — committed
   live-tokens/data/               # editor state — committed
     tokens.generated.css          #   editor output
-    themes/ manifests/ component-configs/
-    **/_backups/                  #   gitignored (local-only snapshots)
+    themes/                       #   one file per whole look, plus the two pointers
+    colors-and-type/ component-configs/
 vite.config.ts                    # svelte({ preprocess: vitePreprocess() }) + themeFileApi
 svelte.config.js                  # vitePreprocess()
 ```
@@ -279,7 +288,7 @@ Conventions that make this work:
 
 - **Vendor `tokens.css` into `src/` and commit it.** Point `themeFileApi({ tokensCssPath })` at that file, not at one inside `node_modules`. The dev server writes your edits there; a copy under `node_modules` is wiped on every `npm install`.
 - **All editable state lives under `src/` and is committed** — `tokens.css`, `tokens.generated.css`, and everything in `live-tokens/data/`. This is the invariant that makes upgrades safe: `npm install` only ever touches `node_modules` + `package.json` + the lockfile, never your `src/`.
-- **`_backups/` is gitignored.** The dev server snapshots a file before overwriting it; those snapshots are local working state, not source.
+- **Nothing is backed up for you.** The dev server keeps no snapshots, so git is the safety net: commit a theme you care about before editing over it.
 - **Preprocess with `vitePreprocess()`** (bundled in `@sveltejs/vite-plugin-svelte`), keeping `sass` installed for the components' `scss`. No `svelte-preprocess`, no `legacy-peer-deps` `.npmrc` — the dependency tree resolves cleanly on its own (since 0.19.1).
 - **Import only from the public surface** — `@motion-proto/live-tokens`, `/components/*`, `/vite-plugin`, `/app/*`.
 
@@ -311,13 +320,15 @@ The component appears in the `/live-tokens/components` page under a **CUSTOM** g
 
 ## Claude Code skills
 
-The package ships a suite of Claude Code skills that encode the project's conventions so Claude can drive the package in plain English. They cover the three jobs the README itself can't carry well: deciding which shipped component fits a need, composing a page from the catalogue, and (for the long-tail case) authoring a new editable component. Each skill auto-triggers from natural-language requests — no slash commands. (Plain `npm install` plus the README handle first-time setup.)
+The package ships a suite of Claude Code skills that encode the project's conventions so Claude can drive the package in plain English. They cover the jobs the README itself can't carry well: deciding which shipped component fits a need, composing a page from the catalogue, generating a color theme from a mood brief, adjusting shape and space from plain language, and (for the long-tail case) authoring a new editable component. Each skill auto-triggers from natural-language requests — no slash commands. (Plain `npm install` plus the README handle first-time setup.)
 
 | Skill                          | Triggers on                                                          | What it knows                                                                                                                  |
 |--------------------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
 | `live-tokens-build-page`       | "build a pricing page using live-tokens components"                  | shipped-component catalogue, column grid, `pageSources` registration, token-only styling rule                                   |
 | `live-tokens-pick-component`   | "what's the difference between TabBar and SegmentedControl?"         | decision tables for each confusable family (selection, container, messaging, on/off); when to author a new one instead         |
 | `live-tokens-create-component` | "author a new Toggle component for my live-tokens project"           | runtime + editor + `registerComponent()` recipe, naming scheme, state model, public-imports rule, verification checklist        |
+| `live-tokens-generate-theme`   | "make me a bright and cheerful color theme"                          | mood → OKLCH seed framework (chroma budget, per-role bands, gamut guardrails, holiday palettes); drives `npx live-tokens generate-theme`, which enforces AA contrast |
+| `live-tokens-adjust-shape-space` | "make the buttons pill shaped", "space it out"                     | shape and space idioms (pill, sharper, softer, tighter, airier) → radius/padding/gap/border-width ops; drives `npx live-tokens adjust`, which moves aliases along the shipped token scales |
 
 ### Install
 
@@ -345,8 +356,8 @@ It enforces the file layout, `:global(:root)` block, token-suffix vocabulary, th
 
 ## How the editor ships changes to prod
 
-1. Edit in `/live-tokens/editor` or `/live-tokens/components`. Saves write to `<dataDir>/themes/{name}.json` and `<dataDir>/component-configs/{comp}/{name}.json`.
-2. Promote a theme to "production." Its variables are written into `tokens.generated.css` next to your authored `tokens.css`.
+1. Edit in `/live-tokens/editor` or `/live-tokens/components`. Your edits sit in the working buffer (`_working.json`); **Save** in the Theme panel captures that buffer into the open theme at `<dataDir>/themes/{name}.json`.
+2. **Adopt** the theme. It becomes the production theme, and its variables are baked into `tokens.generated.css` next to your authored `tokens.css`. Nothing else writes that file, so trying a look never changes what you ship.
 3. `npm run build` bundles both as plain CSS. No editor code, no JSON lookups, no dev surfaces ship to prod.
 
 ## File ownership — what the plugin writes
@@ -362,19 +373,19 @@ Knowing which files the plugin touches matters when upgrading the package or wor
 
 It never writes to your project root, your `src/` outside the data folder, or anywhere else.
 
-**At dev-server startup, the plugin only fills gaps — it never overwrites authored files:**
+**At dev-server startup, the plugin fills gaps and refreshes its own derived files — it never overwrites authored ones:**
 
-- `<dataDir>/themes/default.json` — written **only if missing**.
-- `<dataDir>/themes/_active.json` and `_production.json` — written **only if missing**.
-- `<dataDir>/component-configs/{comp}/_active.json` and `_production.json` — same: only if missing.
+- `<dataDir>/themes/default.json` — the derived Default theme, regenerated when the shipped colors and type or a component default changes.
+- `<dataDir>/themes/_active.json` and `_production.json` — written **only if missing**, and healed when they name a theme that no longer resolves.
 - `<dataDir>/component-configs/{comp}/default.json` — regenerated from the component's `:global(:root)` block **only when the `.svelte` source is newer than the existing default**. This file is a build artifact of the source; don't hand-edit it.
+- `<tokensCssPath sibling>/tokens.generated.css` — rebaked from the production theme, so a fresh checkout builds against the look you shipped.
 
-**At dev-time editor actions, these files get rewritten by your explicit save/promote:**
+**At dev-time editor actions, these files get rewritten by what you do:**
 
-- `<dataDir>/themes/{name}.json` — every save in the editor.
-- `<tokensCssPath sibling>/tokens.generated.css` — fully regenerated when you save or promote the production theme.
-- `<tokensCssPath sibling>/fonts.css` — same rule: regenerated from the theme's font sources.
-- `<dataDir>/component-configs/{comp}/{name}.json` — every save of a per-component config.
+- `<dataDir>/colors-and-type/_working.json` and `<dataDir>/component-configs/{comp}/_working.json` — the buffer, written as you save each part of the look and cleared when a theme you open does not carry it.
+- `<dataDir>/themes/{name}.json` — every Save and Save As in the Theme panel.
+- `<dataDir>/colors-and-type/{name}.json` and `<dataDir>/component-configs/{comp}/{name}.json` — only when you save a preset by name. Nothing machine-written lands among them.
+- `<tokensCssPath sibling>/tokens.generated.css` and `fonts.css` — regenerated from the production theme when you Adopt.
 
 The developer-authored `tokens.css` itself is **never written** by the plugin — it holds defaults you're free to hand-edit. The editor's overrides land in the sidecar `tokens.generated.css`, which the package imports immediately after `tokens.css`.
 

package/bin/adjust.mjs

@@ -0,0 +1,254 @@
+// `live-tokens adjust` worker.
+//
+// Reads an ops file (JSON), applies it to every component's LIVE config via the
+// compiled engine (dist-plugin/adjust — the CLI never imports TS sources), and
+// writes the result into that component's `_working.json` buffer: the same slot
+// the editor's own edits land in, so an adjustment is an unsaved edit the user
+// saves into a theme when they want to keep it. `default.json`, named preset
+// files, themes, colors and type, and tokens.css are never touched.
+
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const ENGINE = resolve(pkgRoot, 'dist-plugin/adjust/index.js');
+const packageThemesDir = join(pkgRoot, 'src/live-tokens/data/themes');
+
+const SOURCE_LABELS = {
+  working: 'your unsaved edits',
+  theme: 'the open theme',
+  default: 'the shipped default',
+};
+
+const SKIP_LABELS = [
+  ['raw-value', 'raw value, not a token'],
+  ['off-ladder', 'off the ladder'],
+  ['clamped', 'already at the ladder end'],
+  ['pill-preserved', 'pill preserved (pass "full": true to move it)'],
+];
+
+async function loadEngine() {
+  if (!existsSync(ENGINE)) {
+    throw new Error(
+      `adjust engine not found at ${relative(process.cwd(), ENGINE)}. ` +
+        `Build the plugin first (npm run build:plugin).`,
+    );
+  }
+  return import(ENGINE);
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function readJsonIfExists(path) {
+  return existsSync(path) ? readJson(path) : null;
+}
+
+function numericRung(token) {
+  const match = /-(\d+)$/.exec(token);
+  return match ? Number(match[1]) : null;
+}
+
+/** Net direction the ops asked for on this alias. An explicit `set` owns the
+ *  value outright, so it reports no direction. */
+function requestedDirection(ops, matchesKind, component, variable) {
+  let total = 0;
+  for (const op of ops) {
+    if (op.target !== undefined && op.target !== component) continue;
+    if (!matchesKind(variable, op.kind)) continue;
+    if (op.shift === undefined) return 0;
+    total += op.shift;
+  }
+  return Math.sign(total);
+}
+
+/** A shift can land below where it started: an off-subset value (`--space-64`)
+ *  snaps to its nearest writable rung first. Those changes are marked, never
+ *  listed as an ordinary shift. */
+function opposesShift(ops, matchesKind, component, change) {
+  const from = numericRung(change.from);
+  const to = numericRung(change.to);
+  if (from === null || to === null) return false;
+  const direction = requestedDirection(ops, matchesKind, component, change.variable);
+  return direction !== 0 && Math.sign(to - from) !== direction;
+}
+
+/** Successive ops can touch the same alias (soften, then pill the buttons);
+ *  the report shows one entry per alias, first `from` to last `to`. */
+function collapseChanges(changes) {
+  const byVariable = new Map();
+  for (const change of changes) {
+    const entry = byVariable.get(change.variable);
+    if (entry) entry.to = change.to;
+    else byVariable.set(change.variable, { ...change });
+  }
+  return [...byVariable.values()].filter((c) => c.from !== c.to);
+}
+
+/** The open theme, read the way every other door reads it: the local file
+ *  first, then the copy the installed package ships. */
+function readActiveTheme(themesDir) {
+  if (!themesDir) return null;
+  const slug = readJsonIfExists(join(themesDir, '_active.json'))?.activeFile ?? 'default';
+  const theme =
+    readJsonIfExists(join(themesDir, `${slug}.json`)) ??
+    readJsonIfExists(join(packageThemesDir, `${slug}.json`));
+  return theme ? { slug, theme } : null;
+}
+
+/** Each component's live config and where it came from: the buffer, else the
+ *  open theme's embedded copy, else the shipped default. Mirrors the dev
+ *  server's `resolveLiveComponentConfig`, so the CLI adjusts what the page runs. */
+function readLiveConfigs(dir, active) {
+  const configs = {};
+  const sources = {};
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const comp = entry.name;
+    const componentDir = join(dir, comp);
+    const working = readJsonIfExists(join(componentDir, '_working.json'));
+    const embedded = active?.theme?.componentConfigs?.[comp];
+    const config = working ?? embedded ?? readJsonIfExists(join(componentDir, 'default.json'));
+    if (!config) {
+      throw new Error(`component "${comp}": default.json is missing`);
+    }
+    configs[comp] = { ...config, component: comp };
+    sources[comp] = working ? 'working' : embedded ? 'theme' : 'default';
+  }
+  return { configs, sources };
+}
+
+/** `engine` is a test seam; the CLI always runs the compiled bundle. */
+export async function runAdjust({
+  opsPath,
+  dryRun = false,
+  root = process.cwd(),
+  componentConfigsDir,
+  themesDir,
+  engine,
+} = {}) {
+  const { adjustAliases, matchesKind, resolveDataDirs } = engine ?? (await loadEngine());
+
+  const opsFull = resolve(root, opsPath);
+  if (!existsSync(opsFull)) {
+    throw new Error(`ops file not found at ${relative(root, opsFull)}`);
+  }
+  let doc;
+  try {
+    doc = readJson(opsFull);
+  } catch (err) {
+    throw new Error(`ops file is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const ops = doc?.ops;
+  if (!Array.isArray(ops) || ops.length === 0) {
+    throw new Error('ops file needs a non-empty "ops" array');
+  }
+
+  const resolved = componentConfigsDir && themesDir ? null : resolveDataDirs();
+  const dir = componentConfigsDir ?? resolved.componentConfigsDir;
+  if (!existsSync(dir)) {
+    throw new Error(`no component configs at ${relative(root, dir)}. Run the dev server once to create them.`);
+  }
+
+  const active = readActiveTheme(themesDir ?? resolved?.themesDir);
+  const { configs, sources } = readLiveConfigs(dir, active);
+  const now = new Date().toISOString();
+  const { configs: next, report } = adjustAliases(configs, ops, now);
+
+  const components = [];
+  for (const entry of report.components) {
+    const { component, skips } = entry;
+    const changes = collapseChanges(entry.changes);
+
+    if (changes.length > 0 && !dryRun) {
+      writeFileSync(
+        join(dir, component, '_working.json'),
+        JSON.stringify({ ...next[component], component }, null, 2),
+      );
+    }
+
+    components.push({
+      component,
+      source: sources[component],
+      changes: changes.map((c) => ({ ...c, snapped: opposesShift(ops, matchesKind, component, c) })),
+      skips,
+    });
+  }
+  components.sort((a, b) => a.component.localeCompare(b.component));
+
+  const changed = components.filter((c) => c.changes.length > 0);
+  return {
+    configsDir: dir,
+    openTheme: active?.slug ?? null,
+    // The ops file's `name` used to pick a file name. Buffers are fixed slots,
+    // so it now names nothing; say so rather than drop it in silence.
+    ignoredName: doc.name === undefined ? null : String(doc.name),
+    dryRun,
+    buffered: !dryRun && changed.length > 0,
+    components,
+    totals: {
+      components: changed.length,
+      aliases: changed.reduce((n, c) => n + c.changes.length, 0),
+      skips: components.reduce((n, c) => n + c.skips.length, 0),
+    },
+  };
+}
+
+export function formatAdjustResult(result) {
+  const root = process.cwd();
+  const lines = [];
+  const { components: changedCount, aliases, skips } = result.totals;
+
+  if (changedCount === 0) {
+    lines.push(
+      skips > 0
+        ? `Nothing changed: every matching alias was skipped (reasons below).`
+        : `Nothing to change: no alias matched the ops.`,
+    );
+  } else {
+    const verb = result.dryRun ? 'Would edit' : 'Edited';
+    lines.push(`${verb} the open buffer of ${changedCount} component(s).`);
+  }
+  if (result.ignoredName !== null) {
+    lines.push(
+      `Ignored "name": "${result.ignoredName}". adjust edits the open buffer now, ` +
+        `so it writes no file of its own.`,
+    );
+  }
+
+  for (const entry of result.components) {
+    const from =
+      entry.source === 'theme' && result.openTheme
+        ? `theme "${result.openTheme}"`
+        : SOURCE_LABELS[entry.source];
+    lines.push(`\n${entry.component}  (from: ${from})`);
+
+    const width = Math.max(0, ...entry.changes.map((c) => c.variable.length));
+    for (const c of entry.changes) {
+      const note = c.snapped ? '   ← snapped to the nearest editor rung, against the requested shift' : '';
+      lines.push(`  ${c.snapped ? '!' : ' '} ${c.variable.padEnd(width)}  ${c.from} → ${c.to}${note}`);
+    }
+
+    for (const [reason, label] of SKIP_LABELS) {
+      const hit = entry.skips.filter((s) => s.reason === reason);
+      if (hit.length === 0) continue;
+      lines.push(`    skipped, ${label}: ${hit.map((s) => s.variable).join(', ')}`);
+    }
+  }
+
+  lines.push(
+    `\n${changedCount} component(s) changed, ${aliases} alias(es), ${skips} skipped.`,
+  );
+  if (result.buffered) {
+    lines.push(
+      `Reload the app to see it. This is an unsaved edit: save the open theme in the ` +
+        `editor's Theme panel to keep it, or load a theme to discard it.`,
+    );
+  } else if (result.dryRun) {
+    lines.push(`Dry run: nothing written under ${relative(root, result.configsDir)}.`);
+  }
+  return lines.join('\n');
+}

package/bin/cli.mjs

@@ -4,15 +4,25 @@
 //   create <dir>             Scaffold a new app that depends on this package.
 //   setup-claude [--force]   Copy bundled Claude Code skills into ./.claude/skills/.
 //   check-component <id>     Validate a component against the add-component skill contract.
+//   generate-theme <brief>   Build a theme from a 10-seed OKLCH brief and open it.
+//   adjust <ops.json>        Apply radius/padding/gap/border-width ops to the open buffer.
+//   migrate [...]            Reconcile tokens.css, the data tree, and route references.
 
 import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { checkComponent, formatReport } from './check-component.mjs';
-import { runMigrate, formatMigrateResult } from './migrate.mjs';
+import {
+  runMigrate,
+  formatMigrateResult,
+  runMigrateData,
+  formatMigrateDataResult,
+} from './migrate.mjs';
 import { runMigrateRoutes, formatRouteResult } from './migrate-routes.mjs';
 import { runCreate, formatCreateResult } from './create.mjs';
+import { runGenerateTheme, formatGenerateThemeResult } from './generate-theme.mjs';
+import { runAdjust, formatAdjustResult } from './adjust.mjs';
 
 const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
 
@@ -22,15 +32,37 @@ Commands:
   setup-claude [--force]      Install bundled Claude Code skills into ./.claude/skills/
   check-component <id>        Validate <id>'s runtime, editor, and registration
                               against the live-tokens-create-component contract
+  generate-theme <brief.json> [--no-activate] [--dry-run] [--carry-from <name>]
+                              Build a full theme from a 10-seed OKLCH brief
+                              (see the live-tokens-generate-theme skill),
+                              enforce AA contrast on derived text tokens, write
+                              themes/<slug>.json, and open it in the editor.
+                              Opening never changes what your site ships; Adopt
+                              in the editor does that.
+                              --no-activate writes the theme without opening it;
+                              --dry-run prints the contrast report without
+                              writing. Non-color content (gradients, fonts,
+                              component aliases) carries forward from the live
+                              look, or from theme <name> with --carry-from.
+  adjust <ops.json> [--dry-run]
+                              Move radius, padding, gap, and border-width
+                              aliases along their token scales (see the
+                              live-tokens-adjust-shape-space skill). Reads each
+                              component's live config and writes the result to
+                              that component's unsaved buffer, so save the open
+                              theme in the editor to keep it. --dry-run prints
+                              the report without writing.
   migrate [--check] [--write] [--tokens <path>]
                               Reconcile your project with the installed package:
-                              applies additive tokens.css migrations (unless
-                              --check), and reports source references to the
+                              applies additive tokens.css migrations, moves a
+                              pre-0.48 data tree onto the current directory
+                              names, heals what the retired pointer files named,
+                              and reports source references to the
                               editor/components/docs routes that moved to
                               /live-tokens/* in 0.35.0. --write also rewrites the
                               unambiguous route references (never /docs). --check
-                              reports without writing (exit 1 if token migrations
-                              are pending; route findings are advisory).
+                              prints both plans without writing (exit 1 when
+                              either is pending; route findings are advisory).
 `;
 
 function fail(message, code = 1) {
@@ -71,6 +103,51 @@ if (command === 'check-component') {
   process.exit(result.errors.length === 0 ? 0 : 1);
 }
 
+if (command === 'generate-theme') {
+  const briefPath = rest.find((a) => !a.startsWith('-'));
+  if (!briefPath) {
+    fail(`Usage: npx @motion-proto/live-tokens generate-theme <brief.json> [--no-activate] [--dry-run]`);
+  }
+  try {
+    const carryIdx = rest.indexOf('--carry-from');
+    const carryFrom = carryIdx !== -1 ? rest[carryIdx + 1] : undefined;
+    if (carryIdx !== -1 && !carryFrom) fail(`--carry-from requires a theme name`);
+    const result = await runGenerateTheme({
+      briefPath,
+      activate: !rest.includes('--no-activate'),
+      dryRun: rest.includes('--dry-run'),
+      carryFrom,
+    });
+    console.log(formatGenerateThemeResult(result));
+    process.exit(result.report.failures.length === 0 ? 0 : 1);
+  } catch (err) {
+    fail(`generate-theme failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+if (command === 'adjust') {
+  const opsPath = rest.find((a) => !a.startsWith('-'));
+  if (!opsPath) {
+    fail(`Usage: npx @motion-proto/live-tokens adjust <ops.json> [--dry-run]`);
+  }
+  if (rest.includes('--no-activate')) {
+    fail(
+      `adjust has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
+        `Drop the flag and re-run.`,
+    );
+  }
+  try {
+    const result = await runAdjust({
+      opsPath,
+      dryRun: rest.includes('--dry-run'),
+    });
+    console.log(formatAdjustResult(result));
+    process.exit(0);
+  } catch (err) {
+    fail(`adjust failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 if (command === 'migrate') {
   const check = rest.includes('--check');
   const write = rest.includes('--write');
@@ -81,15 +158,23 @@ if (command === 'migrate') {
     const result = await runMigrate({ tokensArg, check });
     console.log(formatMigrateResult(result, { check }));
 
+    // Data-tree pass: retires the pre-working-set pointer files and the copies
+    // they named. Runs on every migrate, --write included, because leaving a
+    // tree half on each model is what the heal exists to end.
+    const data = await runMigrateData({ check });
+    const dataOut = formatMigrateDataResult(data);
+    if (dataOut) console.log('\n' + dataOut);
+
     // Route-reference pass: advisory by default, rewrites the unambiguous hits
     // only with --write (and never under --check).
     const routes = runMigrateRoutes({ root: process.cwd(), apply: write && !check });
     const routeOut = formatRouteResult(routes, { check });
     if (routeOut) console.log('\n' + routeOut);
 
-    // Route findings are advisory; only token migrations gate the exit code.
+    // Route findings are advisory; token migrations and the data heal gate the
+    // exit code.
     if (result.status === 'no-path') process.exit(1);
-    if (check && result.status === 'would-change') process.exit(1);
+    if (check && (result.status === 'would-change' || data.status === 'planned')) process.exit(1);
     process.exit(0);
   } catch (err) {
     fail(`migrate failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -144,6 +229,8 @@ const SAMPLE_PROMPTS = {
   'live-tokens-build-page': 'build a pricing page using live-tokens components',
   'live-tokens-pick-component': "what's the difference between TabBar and SegmentedControl?",
   'live-tokens-create-component': 'author a new Toggle component for my live-tokens project',
+  'live-tokens-generate-theme': 'make me a bright and cheerful color theme',
+  'live-tokens-adjust-shape-space': 'make the buttons pill shaped',
 };
 
 const installedSamples = skills