@motion-proto/live-tokens 0.33.1 → 0.35.0

package/.claude/skills/live-tokens-build-page/SKILL.md

@@ -8,7 +8,7 @@ description: Apply the @motion-proto/live-tokens project conventions when buildi
 Two rules above all else:
 
 1. **Use a shipped component if one fits.** Import from `@motion-proto/live-tokens/components/<Name>.svelte`. See [[live-tokens-pick-component]] for the catalogue and the confusing-pair decisions. Author custom markup only when nothing fits, and then consider [[live-tokens-create-component]] so the new piece is editable too.
-2. **Use theme tokens for every value.** Every color, spacing, radius, font-size, and font-family in page CSS is a `var(--token-*)`. No hex literals. No pixel literals. A change in `/editor` should repaint your page.
+2. **Use theme tokens for every value.** Every color, spacing, radius, font-size, and font-family in page CSS is a `var(--token-*)`. No hex literals. No pixel literals. A change in `/live-tokens/editor` should repaint your page.
 
 ## Layout
 
@@ -28,10 +28,10 @@ To place children at specific page-column positions, span the parent grid (`grid
 
 - Hex or pixel literals in page CSS.
 - Hardcoded column counts (`repeat(10, 1fr)`). Use `repeat(var(--columns-count), 1fr)`.
-- Utility classes overriding shipped components. Extend via the `/components` editor instead.
+- Utility classes overriding shipped components. Extend via the `/live-tokens/components` editor instead.
 - Deep imports from `node_modules/@motion-proto/live-tokens/src/...`. Use public entry points only.
 - Mounting `Editor` or `ComponentEditorPage` outside their dedicated routes.
 
 ## Verify
 
-In dev: change a colour in `/editor` and confirm your page repaints (proves token usage). The overlay's "Page Source" button on the new route opens the page in VS Code (proves the route's `source`). `ColumnsOverlay` (Cmd+G) shows content sitting inside `--columns-max-width`.
+In dev: change a colour in `/live-tokens/editor` and confirm your page repaints (proves token usage). The overlay's "Page Source" button on the new route opens the page in VS Code (proves the route's `source`). `ColumnsOverlay` (Cmd+G) shows content sitting inside `--columns-max-width`.

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

@@ -5,7 +5,7 @@ description: Author a brand-new editable component for a @motion-proto/live-toke
 
 # Authoring a component for a live-tokens project
 
-This skill teaches you how to add a new editable component to a project that consumes `@motion-proto/live-tokens`. The end state: a runtime Svelte file, an editor Svelte file, one `registerComponent()` call, and a `/components` page entry under the **CUSTOM** group with full token editing, linked-block sharing, and persistence.
+This skill teaches you how to add a new editable component to a project that consumes `@motion-proto/live-tokens`. The end state: a runtime Svelte file, an editor Svelte file, one `registerComponent()` call, and a `/live-tokens/components` page entry under the **CUSTOM** group with full token editing, linked-block sharing, and persistence.
 
 ## Worked examples ship inside the package
 
@@ -44,7 +44,7 @@ For pattern reference, read any shipped component's source directly from the con
    ```
    The schema side-effect happens inside `registerComponent` (which `bootLiveTokens` calls for you), so you don't call `registerComponentSchema` separately. **Do not place a standalone `registerComponent(...)` *before* `bootLiveTokens`** — that registers before the editor's init hooks run, which is the wrong window and can leave editor changes disconnected from the live page. Only call `registerComponent` directly if your app mounts manually (no `bootLiveTokens`), in which case call it before `mount(App, ...)`.
 4. **Tell the picker** — open `.claude/skills/live-tokens-pick-component/SKILL.md` and add your new component to the **Catalogue** line under the family it belongs to (Action / Input / Selection / Containers / Messaging / Display). If it's confusable with an existing component (a second selection control, a competing container), add a row to that family's decision table explaining the use-case it owns. Without this step, the component exists but [[live-tokens-pick-component]] can't recommend it when a user asks "which component should I use?" — the same rule applies whether the component is first-party (update the picker shipped in this package) or consumer-authored (update the local copy at `.claude/skills/live-tokens-pick-component/SKILL.md` that `setup-claude` placed in your project).
-5. **Verify** — open `/components` and run the verification checklist at the bottom of this file.
+5. **Verify** — open `/live-tokens/components` and run the verification checklist at the bottom of this file.
 
 ## Token discipline
 
@@ -559,7 +559,7 @@ A new first-party component is auto-covered the moment it lands in `builtInRegis
 
 **If your component declares `intrinsics`, the intrinsics contract test covers it too.** `src/editor/component-editor/intrinsicsContract.test.ts` iterates every entry with an `intrinsics` array and asserts, per (intrinsic, variant), that the runtime `:global(:root)` declares a default, the default is one of the spec's `values`, and the editor's `default` equals the runtime default. This is what would have caught a getter defaulting to `center` while `:global(:root)` says `start`. Same auto-coverage rule: declare `intrinsics` on the registry entry and the test picks it up.
 
-Finally navigate to `/components` and confirm the runtime behaviours no static check can see:
+Finally navigate to `/live-tokens/components` and confirm the runtime behaviours no static check can see:
 
 - [ ] 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.

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.35.0 — Dev routes moved to a reserved `/live-tokens/*` namespace
+
+### Changed (breaking)
+
+- **The package's dev-only routes moved under a reserved `/live-tokens/*`
+  namespace:** `/editor` → `/live-tokens/editor`, `/components` →
+  `/live-tokens/components`, `/docs` → `/live-tokens/docs`. These routes are
+  `import.meta.env.DEV`-only and never appear in production, so the longer paths
+  cost nothing where users actually see URLs. Reserving a namespace means a
+  consumer's own `/docs` or `/components` page no longer collides with a package
+  route, and any owned route added in a future release stays inside the namespace
+  (no surprise collisions on a version bump). Relocate or disable any of them via
+  the `editorRoutes` prop exactly as before.
+
+### Fixed
+
+- **A consumer page at `/docs` or `/components` no longer crashes the app.** The
+  package auto-injected nav entries at those paths; a consumer page at the same
+  path produced a duplicate key in the overlay's keyed nav list and threw an
+  uncaught error, and silently shadowed the consumer's page at dispatch. With the
+  reserved namespace the collision cannot occur, so `editorRoutes.docs = false`
+  is no longer needed to dodge it.
+- **`editorRoutes.components` relocation now also moves the overlay's
+  components-view pairing**, which previously compared a hardcoded `/components`.
+
+### Migrating
+
+- **`npx live-tokens migrate` now flags hardcoded route references.** If your
+  source navigates to the old paths (e.g. `navigate('/editor')` from the old
+  scaffold, or `<a href="/components">`), `migrate` reports each one with its
+  file, line, and suggested `/live-tokens/*` replacement. Add `--write` to
+  rewrite the unambiguous ones automatically. `/docs` is never auto-rewritten
+  (you likely own that route), and any path you declare in `pages` or relocate
+  via `editorRoutes` is left for manual review. The editor stays reachable via
+  the dev overlay regardless, so this only affects hardcoded shortcut links.
+
+## 0.34.0 — Token-as-API contract guardrail; opt-in autoMigrate
+
+### Added
+
+- **Token names are now a versioned API contract, with a guardrail.** Each
+  `tokens.css` migration declares `kind: 'additive' | 'breaking'`. A new
+  `check:token-contract` (wired into `prepublishOnly`, plus
+  `tokensCssMigrations/contract.test.ts`) verifies behaviorally that an additive
+  migration never removes or renames a token (catches a breaking change shipped
+  as backward-compatible), and gates breaking migrations on a major bump from
+  1.0.0 (pre-1.0 it warns). See TOKENS.md and RELEASING.md.
+- **`themeFileApi({ autoMigrate: true })`.** Opt-in: the dev server applies
+  pending **additive** token migrations to your `tokens.css` at startup and
+  writes the file (shown in git), so it stays current with the package without a
+  manual step. Breaking migrations are never auto-applied. Off by default, which
+  preserves the invariant that the plugin never writes `tokensCssPath` unless you
+  enable it.
+
+### Docs
+
+- **`TOKENS.md`** gained a plain-language section on how token changes are
+  versioned (additive vs breaking, what an upgrade can and cannot change).
+
 ## 0.33.1 — Ship the changelog in the package
 
 ### Fixed

package/README.md

@@ -8,8 +8,8 @@ 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** (`/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.
-- **Per-component editor** (`/components` route, dev-only) — the home of real-time component-alias editing. Pick token aliases per component without writing CSS.
+- **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.
+- **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`.
@@ -122,7 +122,7 @@ bootLiveTokens(App, '#app', {
 ```
 
 `<LiveTokensRouter>` owns the dev overlay (`<LiveEditorOverlay>` +
-`<ColumnsOverlay>`), the editor routes (`/editor`, `/components`, `/docs`), the
+`<ColumnsOverlay>`), the editor routes (`/live-tokens/editor`, `/live-tokens/components`, `/live-tokens/docs`), the
 in-app link-click interception, and the nav-rail/page-source plumbing the
 overlay needs. Each entry in `pages` is one of your routes; entries with a
 `label` appear in the overlay's nav rail. Pass pages as `lazy: () => import('./Page.svelte')`
@@ -307,7 +307,7 @@ bootLiveTokens(App, '#app', {
 
 (`bootLiveTokens` calls `registerComponent` internally for each entry, gated on `import.meta.env.DEV` so the registration tree-shakes out of production builds. Call `registerComponent` directly if you need finer control over timing.)
 
-The component appears in the `/components` page under a **CUSTOM** group in the nav rail. Token rows, linked-block sharing, per-component config persistence, and reset-to-default work identically to the built-in set. All imports must come from `@motion-proto/live-tokens` or `@motion-proto/live-tokens/component-editor`; never deep-import from `src/`.
+The component appears in the `/live-tokens/components` page under a **CUSTOM** group in the nav rail. Token rows, linked-block sharing, per-component config persistence, and reset-to-default work identically to the built-in set. All imports must come from `@motion-proto/live-tokens` or `@motion-proto/live-tokens/component-editor`; never deep-import from `src/`.
 
 ## Claude Code skills
 
@@ -345,13 +345,13 @@ It enforces the file layout, `:global(:root)` block, token-suffix vocabulary, th
 
 ## How the editor ships changes to prod
 
-1. Edit in `/editor` or `/components`. Saves write to `<dataDir>/themes/{name}.json` and `<dataDir>/component-configs/{comp}/{name}.json`.
+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`.
 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
 
-Knowing which files the plugin touches matters when upgrading the package or working in a repo you don't want overwritten.
+Knowing which files the plugin touches matters when upgrading the package or working in a repo you don't want overwritten. For a plain-language version of how your saved look stays safe across upgrades while `tokens.css` holds the building blocks, see [TOKENS.md](./TOKENS.md).
 
 **On `npm install` or `npm update`: nothing outside `node_modules/`.** No install hooks. Upgrading versions never touches your `src/live-tokens/data/`, or any file in `src/` outside it.
 
@@ -378,6 +378,8 @@ It never writes to your project root, your `src/` outside the data folder, or an
 
 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`.
 
+The one exception is the opt-in `themeFileApi({ autoMigrate: true })` option. When enabled, the dev server applies pending **additive** token migrations (new token names only) to your `tokens.css` at startup and writes the file, so it stays current with the package as you upgrade. The change shows up in git for review. Breaking migrations (rename/remove) are never auto-applied; run `npx live-tokens migrate` for those during a deliberate upgrade. Off by default, so the "never written" rule holds unless you turn it on. See [TOKENS.md](./TOKENS.md).
+
 ## License
 
 MIT. Originally extracted from [RuneGoblin](https://www.runegoblin.com/).

package/bin/cli.mjs

@@ -11,6 +11,7 @@ import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { checkComponent, formatReport } from './check-component.mjs';
 import { runMigrate, formatMigrateResult } from './migrate.mjs';
+import { runMigrateRoutes, formatRouteResult } from './migrate-routes.mjs';
 import { runCreate, formatCreateResult } from './create.mjs';
 
 const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
@@ -21,10 +22,15 @@ 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
-  migrate [--check] [--tokens <path>]
-                              Reconcile your tokens.css with the installed
-                              package's Layer-1 token vocabulary. --check reports
-                              without writing (exit 1 if changes are needed).
+  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
+                              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).
 `;
 
 function fail(message, code = 1) {
@@ -67,13 +73,21 @@ if (command === 'check-component') {
 
 if (command === 'migrate') {
   const check = rest.includes('--check');
+  const write = rest.includes('--write');
   const tokensIdx = rest.indexOf('--tokens');
   const tokensArg = tokensIdx !== -1 ? rest[tokensIdx + 1] : undefined;
   if (tokensIdx !== -1 && !tokensArg) fail(`--tokens requires a path`);
   try {
     const result = await runMigrate({ tokensArg, check });
     console.log(formatMigrateResult(result, { check }));
-    // Exit 1 when --check finds pending changes (CI-friendly) or on no-path.
+
+    // 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.
     if (result.status === 'no-path') process.exit(1);
     if (check && result.status === 'would-change') process.exit(1);
     process.exit(0);

package/bin/migrate-routes.mjs

@@ -0,0 +1,179 @@
+// `live-tokens migrate` route-reference pass (0.35.0 namespace move).
+//
+// The package's dev-only routes moved to a reserved `/live-tokens/*` namespace,
+// so consumer source that hardcoded `/editor`, `/components`, or `/docs` (e.g.
+// `navigate('/editor')` from the old scaffold) now 404s. This scans the
+// consumer's source and reports those references; with `apply`, it rewrites the
+// unambiguous ones.
+//
+// Safety: `/docs` is never auto-rewritten (consumers commonly own a docs page),
+// and any path the project declares as its own (a `pages` key) or manages via
+// `editorRoutes` is left as an advisory. A reference is rewritten only when the
+// package definitely owns that path.
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+
+const MOVED = [
+  { old: '/editor', next: '/live-tokens/editor' },
+  { old: '/components', next: '/live-tokens/components' },
+  { old: '/docs', next: '/live-tokens/docs' },
+];
+
+// Never auto-rewritten: a consumer's own docs page is the common case, and we
+// can't tell their `/docs` from the package's without guessing.
+const NEVER_AUTOWRITE = new Set(['/docs']);
+
+const SCAN_EXTS = new Set(['.svelte', '.ts', '.js', '.mjs', '.tsx', '.jsx']);
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'dist-plugin', '.git', '.svelte-kit', 'build']);
+
+function walk(dir, out = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) walk(join(dir, e.name), out);
+    } else if (SCAN_EXTS.has(extname(e.name))) {
+      out.push(join(dir, e.name));
+    }
+  }
+  return out;
+}
+
+// `navigate('/p')` / `navigate("/p")` / `navigate(`/p`)` and the href forms
+// `href="/p"` / `href='/p'` / `href={'/p'}`. The closing backreference quote
+// pins the path to the exact string, so `/live-tokens/editor` never matches
+// `/editor` (the char before `/editor` there is `s`, not a quote).
+function refRegex(oldPath) {
+  return new RegExp(`(navigate\\(\\s*|href\\s*=\\s*\\{?\\s*)(['"\`])${oldPath}\\2`, 'g');
+}
+
+function kindOf(prefix) {
+  return prefix.trimStart().startsWith('href') ? 'href' : 'navigate';
+}
+
+/**
+ * A path is the consumer's, not the package's, if they declare a page at it
+ * (`'/x':` in a pages map) or name it in an `editorRoutes` override. Conservative
+ * by design: when unsure we mark it owned, which only ever downgrades a rewrite
+ * to an advisory.
+ */
+function detectConsumerOwned(files) {
+  const owned = new Set();
+  for (const file of files) {
+    const c = readFileSync(file, 'utf8');
+    const hasEditorRoutes = /editorRoutes/.test(c);
+    for (const { old } of MOVED) {
+      const key = old.slice(1);
+      if (new RegExp(`['"]\\/${key}['"]\\s*:`).test(c)) owned.add(old);
+      if (hasEditorRoutes && new RegExp(`\\b${key}\\s*:`).test(c)) owned.add(old);
+    }
+  }
+  return owned;
+}
+
+function scanContent(content) {
+  const lines = content.split('\n');
+  const found = [];
+  for (const { old, next } of MOVED) {
+    const re = refRegex(old);
+    lines.forEach((text, i) => {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(text))) {
+        found.push({ line: i + 1, kind: kindOf(m[1]), old, next });
+      }
+    });
+  }
+  return found;
+}
+
+function applyRewrites(content, paths) {
+  let out = content;
+  for (const { old, next } of paths) {
+    out = out.replace(refRegex(old), (_full, prefix, quote) => `${prefix}${quote}${next}${quote}`);
+  }
+  return out;
+}
+
+/**
+ * Scan (and with `apply`, rewrite) source under `root`. Returns
+ * `{ scannedFiles, rewritten, pendingWrite, advisory, owned }` — `rewritten` is
+ * populated only when `apply` is true; otherwise auto-writable hits land in
+ * `pendingWrite`. `advisory` always holds the hits we won't touch automatically.
+ */
+export function runMigrateRoutes({ root = process.cwd(), apply = false } = {}) {
+  const srcDir = join(root, 'src');
+  const base = existsSync(srcDir) ? srcDir : root;
+  const files = walk(base);
+  const owned = detectConsumerOwned(files);
+
+  const rewritten = [];
+  const pendingWrite = [];
+  const advisory = [];
+
+  for (const file of files) {
+    const content = readFileSync(file, 'utf8');
+    const rel = relative(root, file);
+    const hits = scanContent(content).map((h) => ({
+      ...h,
+      file: rel,
+      autoWrite: !NEVER_AUTOWRITE.has(h.old) && !owned.has(h.old),
+      reason: NEVER_AUTOWRITE.has(h.old) ? 'docs-never' : owned.has(h.old) ? 'consumer-owned' : null,
+    }));
+    if (hits.length === 0) continue;
+
+    const auto = hits.filter((h) => h.autoWrite);
+    advisory.push(...hits.filter((h) => !h.autoWrite));
+
+    if (apply && auto.length) {
+      const paths = MOVED.filter((m) => auto.some((h) => h.old === m.old));
+      const next = applyRewrites(content, paths);
+      if (next !== content) {
+        writeFileSync(file, next);
+        rewritten.push(...auto);
+      }
+    } else {
+      pendingWrite.push(...auto);
+    }
+  }
+
+  return { scannedFiles: files.length, rewritten, pendingWrite, advisory, owned: [...owned] };
+}
+
+export function formatRouteResult(result, { check = false } = {}) {
+  const { rewritten, pendingWrite, advisory } = result;
+  if (!rewritten.length && !pendingWrite.length && !advisory.length) return '';
+
+  const ref = (h) => `      ${h.file}:${h.line}  ${h.kind} '${h.old}' → '${h.next}'`;
+  const lines = ['Route references — /editor, /components, /docs moved to /live-tokens/* in 0.35.0:'];
+
+  if (rewritten.length) {
+    lines.push(`  ✓ Rewrote ${rewritten.length} reference(s):`);
+    rewritten.forEach((h) => lines.push(ref(h)));
+  }
+  if (pendingWrite.length) {
+    lines.push(
+      check
+        ? `  Would rewrite ${pendingWrite.length} reference(s) with --write:`
+        : `  ${pendingWrite.length} reference(s) can be rewritten — re-run with --write to apply:`,
+    );
+    pendingWrite.forEach((h) => lines.push(ref(h)));
+  }
+  if (advisory.length) {
+    lines.push(`  ⚠ ${advisory.length} reference(s) need manual review:`);
+    advisory.forEach((h) => {
+      const why =
+        h.reason === 'docs-never'
+          ? `/docs is never auto-rewritten — update to '${h.next}' only if it points at the package guide`
+          : `you declare or relocate '${h.old}' yourself — leave it if it's your route`;
+      lines.push(`      ${h.file}:${h.line}  ${h.kind} '${h.old}'  (${why})`);
+    });
+  }
+  if (rewritten.length) lines.push('\n  Review the diff in git before committing.');
+  return lines.join('\n');
+}

package/dist-plugin/{chunk-MJO4T3CM.js → chunk-D77VD4Z6.js}

@@ -106,6 +106,7 @@ function escapeRe(s) {
 // vite-plugin/tokensCssMigrations/migrations/2026-05-29-typography-scale-additions.ts
 var tokensCssMigration_2026_05_29_typographyScaleAdditions = {
   id: "2026-05-29-typography-scale-additions",
+  kind: "additive",
   description: "Add --line-height-{xs..xl}, --letter-spacing-* and --ease-out-quart scales",
   apply(css) {
     let out = css;
@@ -144,6 +145,7 @@ var tokensCssMigration_2026_05_29_typographyScaleAdditions = {
 var KEEP_SEGMENTS = /* @__PURE__ */ new Set(["lg", "md", "sm"]);
 var tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup = {
   id: "2026-05-29-sectiondivider-legacy-axis-cleanup",
+  kind: "breaking",
   description: "Remove legacy --sectiondivider-* tokens not on the lg/md/sm axis",
   apply(css) {
     return removeTokensMatching(css, (name) => {
@@ -157,6 +159,7 @@ var tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup = {
 // vite-plugin/tokensCssMigrations/migrations/2026-06-03-transform-scale-additions.ts
 var tokensCssMigration_2026_06_03_transformScaleAdditions = {
   id: "2026-06-03-transform-scale-additions",
+  kind: "additive",
   description: "Add the --scale-{sm..2xl} transform-multiplier scale",
   apply(css) {
     return ensureScale(css, {
@@ -176,6 +179,7 @@ var tokensCssMigration_2026_06_03_transformScaleAdditions = {
 // vite-plugin/tokensCssMigrations/migrations/2026-06-04-remove-dead-size-icon-scale.ts
 var tokensCssMigration_2026_06_04_removeDeadSizeIconScale = {
   id: "2026-06-04-remove-dead-size-icon-scale",
+  kind: "breaking",
   description: "Remove the unused --size-icon-* scale (live scale is --icon-size-*)",
   apply(css) {
     return removeTokensMatching(css, (name) => name.startsWith("--size-icon-"));
@@ -185,6 +189,7 @@ var tokensCssMigration_2026_06_04_removeDeadSizeIconScale = {
 // vite-plugin/tokensCssMigrations/migrations/2026-06-04-easing-color-and-typescale-additions.ts
 var tokensCssMigration_2026_06_04_easingColorAndTypescaleAdditions = {
   id: "2026-06-04-easing-color-and-typescale-additions",
+  kind: "additive",
   description: "Add the full --ease-* scale, --color-white/black, and --font-size-7xl",
   apply(css) {
     let out = css;
@@ -313,9 +318,16 @@ var TOKENS_CSS_MIGRATIONS = [
   tokensCssMigration_2026_06_04_easingColorAndTypescaleAdditions
 ];
 function runTokensCssMigrations(css) {
+  return foldMigrations(css, () => true);
+}
+function runAdditiveTokensCssMigrations(css) {
+  return foldMigrations(css, (m) => m.kind === "additive");
+}
+function foldMigrations(css, include) {
   let out = css;
   const applied = [];
   for (const m of TOKENS_CSS_MIGRATIONS) {
+    if (!include(m)) continue;
     const next = m.apply(out);
     if (next !== out) {
       applied.push(m.id);
@@ -324,6 +336,45 @@ function runTokensCssMigrations(css) {
   }
   return { css: out, applied, changed: out !== css };
 }
+function findContractViolations(canonicalCss) {
+  const violations = [];
+  for (const m of TOKENS_CSS_MIGRATIONS) {
+    if (m.kind !== "additive") continue;
+    const before = collectDefinedTokens(canonicalCss);
+    const after = collectDefinedTokens(m.apply(canonicalCss));
+    const removed = [...before].filter((t) => !after.has(t)).sort();
+    if (removed.length) violations.push({ id: m.id, removed });
+  }
+  return violations;
+}
+function semverBumpType(prev, next) {
+  const p = parseSemver(prev);
+  const n = parseSemver(next);
+  if (n.major > p.major) return "major";
+  if (n.major === p.major && n.minor > p.minor) return "minor";
+  if (n.major === p.major && n.minor === p.minor && n.patch > p.patch) return "patch";
+  return "none";
+}
+function parseSemver(v) {
+  const [core] = v.replace(/^v/, "").split(/[-+]/);
+  const [major = 0, minor = 0, patch = 0] = core.split(".").map((n) => Number(n) || 0);
+  return { major, minor, patch };
+}
+function enforceBreakingRequiresMajor(args) {
+  const breakingIds = args.newMigrations.filter((m) => m.kind === "breaking").map((m) => m.id);
+  const bump = semverBumpType(args.prevVersion, args.nextVersion);
+  if (breakingIds.length === 0 || bump === "major") {
+    return { level: "ok", breakingIds, bump, message: "" };
+  }
+  const pre1 = parseSemver(args.nextVersion).major < 1;
+  const ids = breakingIds.join(", ");
+  return {
+    level: pre1 ? "warn" : "error",
+    breakingIds,
+    bump,
+    message: `Breaking token migration(s) [${ids}] are shipping in a ${bump} bump (${args.prevVersion} -> ${args.nextVersion}). Token names are public API; ` + (pre1 ? `pre-1.0 this is allowed, but the CHANGELOG must flag it under "Changed (breaking)".` : `from 1.0.0 a breaking token change requires a major bump.`)
+  };
+}
 function validateTokensCss(input) {
   const defined = /* @__PURE__ */ new Set([
     ...collectDefinedTokens(input.tokensCss),
@@ -361,5 +412,9 @@ export {
   removeTokensMatching,
   TOKENS_CSS_MIGRATIONS,
   runTokensCssMigrations,
+  runAdditiveTokensCssMigrations,
+  findContractViolations,
+  semverBumpType,
+  enforceBreakingRequiresMajor,
   validateTokensCss
 };

package/dist-plugin/index.cjs

@@ -730,6 +730,7 @@ function findTopLevelRoot(lines) {
 // vite-plugin/tokensCssMigrations/migrations/2026-05-29-typography-scale-additions.ts
 var tokensCssMigration_2026_05_29_typographyScaleAdditions = {
   id: "2026-05-29-typography-scale-additions",
+  kind: "additive",
   description: "Add --line-height-{xs..xl}, --letter-spacing-* and --ease-out-quart scales",
   apply(css) {
     let out = css;
@@ -768,6 +769,7 @@ var tokensCssMigration_2026_05_29_typographyScaleAdditions = {
 var KEEP_SEGMENTS = /* @__PURE__ */ new Set(["lg", "md", "sm"]);
 var tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup = {
   id: "2026-05-29-sectiondivider-legacy-axis-cleanup",
+  kind: "breaking",
   description: "Remove legacy --sectiondivider-* tokens not on the lg/md/sm axis",
   apply(css) {
     return removeTokensMatching(css, (name) => {
@@ -781,6 +783,7 @@ var tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup = {
 // vite-plugin/tokensCssMigrations/migrations/2026-06-03-transform-scale-additions.ts
 var tokensCssMigration_2026_06_03_transformScaleAdditions = {
   id: "2026-06-03-transform-scale-additions",
+  kind: "additive",
   description: "Add the --scale-{sm..2xl} transform-multiplier scale",
   apply(css) {
     return ensureScale(css, {
@@ -800,6 +803,7 @@ var tokensCssMigration_2026_06_03_transformScaleAdditions = {
 // vite-plugin/tokensCssMigrations/migrations/2026-06-04-remove-dead-size-icon-scale.ts
 var tokensCssMigration_2026_06_04_removeDeadSizeIconScale = {
   id: "2026-06-04-remove-dead-size-icon-scale",
+  kind: "breaking",
   description: "Remove the unused --size-icon-* scale (live scale is --icon-size-*)",
   apply(css) {
     return removeTokensMatching(css, (name) => name.startsWith("--size-icon-"));
@@ -809,6 +813,7 @@ var tokensCssMigration_2026_06_04_removeDeadSizeIconScale = {
 // vite-plugin/tokensCssMigrations/migrations/2026-06-04-easing-color-and-typescale-additions.ts
 var tokensCssMigration_2026_06_04_easingColorAndTypescaleAdditions = {
   id: "2026-06-04-easing-color-and-typescale-additions",
+  kind: "additive",
   description: "Add the full --ease-* scale, --color-white/black, and --font-size-7xl",
   apply(css) {
     let out = css;
@@ -891,9 +896,16 @@ var TOKENS_CSS_MIGRATIONS = [
   tokensCssMigration_2026_06_04_easingColorAndTypescaleAdditions
 ];
 function runTokensCssMigrations(css) {
+  return foldMigrations(css, () => true);
+}
+function runAdditiveTokensCssMigrations(css) {
+  return foldMigrations(css, (m) => m.kind === "additive");
+}
+function foldMigrations(css, include) {
   let out = css;
   const applied = [];
   for (const m of TOKENS_CSS_MIGRATIONS) {
+    if (!include(m)) continue;
     const next = m.apply(out);
     if (next !== out) {
       applied.push(m.id);
@@ -1233,6 +1245,20 @@ ${lines.join("\n")}
   These render as blank/empty editor slots. Run \`npx live-tokens migrate\` to reconcile.`
     );
   }
+  function autoMigrateAdditive(log) {
+    let before = "";
+    try {
+      before = import_fs3.default.readFileSync(CSS_PATH, "utf-8");
+    } catch {
+      return;
+    }
+    const { css, applied, changed } = runAdditiveTokensCssMigrations(before);
+    if (!changed) return;
+    import_fs3.default.writeFileSync(CSS_PATH, css);
+    log(
+      `[live-tokens] autoMigrate applied ${applied.length} additive migration(s) to ${import_path3.default.relative(process.cwd(), CSS_PATH)}: ${applied.join(", ")}. Review the diff in git.`
+    );
+  }
   function generateDefaultConfig(comp, sourcePath) {
     if (!import_fs3.default.existsSync(sourcePath)) return;
     const r = componentResource(comp);
@@ -2030,6 +2056,7 @@ ${lines.join("\n")}
       ensureComponentConfigsDir();
       ensureManifestsDir();
       regenerateTokensCss();
+      if (opts.autoMigrate) autoMigrateAdditive((msg) => server.config.logger.info(msg));
       warnOnTokenDrift((msg) => server.config.logger.warn(msg));
       server.middlewares.use(async (req, res, next) => {
         const handled = await dispatch(req, res, routes);

package/dist-plugin/index.d.cts

@@ -11,6 +11,7 @@ interface ThemeFileApiOptions {
     componentConfigsDir?: string;
     manifestsDir?: string;
     componentsSrcDir?: string;
+    autoMigrate?: boolean;
 }
 declare function themeFileApi(opts: ThemeFileApiOptions): Plugin;
 

package/dist-plugin/index.d.ts

@@ -11,6 +11,7 @@ interface ThemeFileApiOptions {
     componentConfigsDir?: string;
     manifestsDir?: string;
     componentsSrcDir?: string;
+    autoMigrate?: boolean;
 }
 declare function themeFileApi(opts: ThemeFileApiOptions): Plugin;
 

package/dist-plugin/index.js

@@ -2,9 +2,10 @@ import {
   TOKENS_CSS_MIGRATIONS,
   extractGlobalRootBody,
   resolveDataDirs,
+  runAdditiveTokensCssMigrations,
   runTokensCssMigrations,
   validateTokensCss
-} from "./chunk-MJO4T3CM.js";
+} from "./chunk-D77VD4Z6.js";
 
 // vite-plugin/themeFileApi.ts
 import fs2 from "fs";
@@ -866,6 +867,20 @@ ${lines.join("\n")}
   These render as blank/empty editor slots. Run \`npx live-tokens migrate\` to reconcile.`
     );
   }
+  function autoMigrateAdditive(log) {
+    let before = "";
+    try {
+      before = fs2.readFileSync(CSS_PATH, "utf-8");
+    } catch {
+      return;
+    }
+    const { css, applied, changed } = runAdditiveTokensCssMigrations(before);
+    if (!changed) return;
+    fs2.writeFileSync(CSS_PATH, css);
+    log(
+      `[live-tokens] autoMigrate applied ${applied.length} additive migration(s) to ${path2.relative(process.cwd(), CSS_PATH)}: ${applied.join(", ")}. Review the diff in git.`
+    );
+  }
   function generateDefaultConfig(comp, sourcePath) {
     if (!fs2.existsSync(sourcePath)) return;
     const r = componentResource(comp);
@@ -1663,6 +1678,7 @@ ${lines.join("\n")}
       ensureComponentConfigsDir();
       ensureManifestsDir();
       regenerateTokensCss();
+      if (opts.autoMigrate) autoMigrateAdditive((msg) => server.config.logger.info(msg));
       warnOnTokenDrift((msg) => server.config.logger.warn(msg));
       server.middlewares.use(async (req, res, next) => {
         const handled = await dispatch(req, res, routes);