@motion-proto/live-tokens 0.33.1 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 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

@@ -351,7 +351,7 @@ It enforces the file layout, `:global(:root)` block, token-suffix vocabulary, th
 
 ## 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/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);

package/dist-plugin/tokensCssMigrations/index.cjs

@@ -33,12 +33,16 @@ __export(tokensCssMigrations_exports, {
   TOKENS_CSS_MIGRATIONS: () => TOKENS_CSS_MIGRATIONS,
   collectDefinedTokens: () => collectDefinedTokens,
   collectReferencedTokens: () => collectReferencedTokens,
+  enforceBreakingRequiresMajor: () => enforceBreakingRequiresMajor,
   ensureScale: () => ensureScale,
+  findContractViolations: () => findContractViolations,
   readLiveTokensConfig: () => readLiveTokensConfig,
   removeToken: () => removeToken,
   removeTokensMatching: () => removeTokensMatching,
   renameToken: () => renameToken,
+  runAdditiveTokensCssMigrations: () => runAdditiveTokensCssMigrations,
   runTokensCssMigrations: () => runTokensCssMigrations,
+  semverBumpType: () => semverBumpType,
   validateTokensCss: () => validateTokensCss
 });
 module.exports = __toCommonJS(tokensCssMigrations_exports);
@@ -151,6 +155,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;
@@ -189,6 +194,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) => {
@@ -202,6 +208,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, {
@@ -221,6 +228,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-"));
@@ -230,6 +238,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;
@@ -345,9 +354,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);
@@ -356,6 +372,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),
@@ -385,11 +440,15 @@ function validateTokensCss(input) {
   TOKENS_CSS_MIGRATIONS,
   collectDefinedTokens,
   collectReferencedTokens,
+  enforceBreakingRequiresMajor,
   ensureScale,
+  findContractViolations,
   readLiveTokensConfig,
   removeToken,
   removeTokensMatching,
   renameToken,
+  runAdditiveTokensCssMigrations,
   runTokensCssMigrations,
+  semverBumpType,
   validateTokensCss
 });

package/dist-plugin/tokensCssMigrations/index.d.cts

@@ -16,6 +16,16 @@
 interface TokensCssMigration {
     /** Unique id; convention: `YYYY-MM-DD-<short-name>`. */
     id: string;
+    /**
+     * Whether this migration is backward-compatible.
+     *
+     * Token names are public API (see TOKENS.md). `'additive'` only ever inserts
+     * new names, so it is safe to auto-apply to a consumer's vendored `tokens.css`
+     * (the dev plugin's `autoMigrate`). `'breaking'` renames or removes a name a
+     * consumer may reference, so it ships only with a major version (post-1.0) and
+     * is never auto-applied — it rides an explicit `live-tokens migrate`.
+     */
+    kind: 'additive' | 'breaking';
     /** One-line summary shown by the CLI when the migration applies. */
     description: string;
     /** Pure, idempotent transform on the `tokens.css` source. */
@@ -113,6 +123,50 @@ interface RunResult {
 }
 /** Fold every registered migration over `css`. Pure and idempotent. */
 declare function runTokensCssMigrations(css: string): RunResult;
+/**
+ * Fold only the `additive` migrations. Additive changes only insert new token
+ * names, so applying them to a consumer's vendored `tokens.css` is always
+ * backward-compatible — this is what the dev plugin's `autoMigrate` runs. The
+ * `breaking` migrations (rename/remove) are deliberately skipped; they ride an
+ * explicit `live-tokens migrate` during a major upgrade.
+ */
+declare function runAdditiveTokensCssMigrations(css: string): RunResult;
+interface ContractViolation {
+    id: string;
+    /** Token names the migration removed or renamed away despite declaring `additive`. */
+    removed: string[];
+}
+/**
+ * Guardrail for the token-as-API contract: an `additive` migration must never
+ * remove or rename a token. We verify behaviorally rather than trusting the
+ * label — apply each additive migration to the package's own canonical
+ * `tokens.css` (which defines the full current vocabulary) and flag any token
+ * that disappears. A rename surfaces as the removal of its old name, so it is
+ * caught too. This catches the dangerous direction: a breaking change shipped as
+ * a backward-compatible one. (Over-labeling a no-op as `breaking` is harmless
+ * and not checked.)
+ */
+declare function findContractViolations(canonicalCss: string): ContractViolation[];
+type SemverBump = 'major' | 'minor' | 'patch' | 'none';
+/** Classify the bump from `prev` to `next` (leading `v` and pre-release tags ignored). */
+declare function semverBumpType(prev: string, next: string): SemverBump;
+interface BreakingGateResult {
+    level: 'ok' | 'warn' | 'error';
+    breakingIds: string[];
+    bump: SemverBump;
+    message: string;
+}
+/**
+ * The version side of the token contract: a `breaking` migration introduced in a
+ * release requires a major version bump. Pre-1.0 (next major is 0) this is only
+ * a warning, since semver permits breaking changes in 0.x minors; from 1.0.0 on
+ * it is an error. Pure so the release check and its tests share one rule.
+ */
+declare function enforceBreakingRequiresMajor(args: {
+    newMigrations: TokensCssMigration[];
+    prevVersion: string;
+    nextVersion: string;
+}): BreakingGateResult;
 interface ComponentSource {
     name: string;
     source: string;
@@ -141,4 +195,4 @@ interface ValidateInput {
  */
 declare function validateTokensCss(input: ValidateInput): MissingToken[];
 
-export { type ComponentSource, type MissingToken, type RunResult, TOKENS_CSS_MIGRATIONS, type TokensCssMigration, type ValidateInput, collectDefinedTokens, collectReferencedTokens, ensureScale, readLiveTokensConfig, removeToken, removeTokensMatching, renameToken, runTokensCssMigrations, validateTokensCss };
+export { type BreakingGateResult, type ComponentSource, type ContractViolation, type MissingToken, type RunResult, type SemverBump, TOKENS_CSS_MIGRATIONS, type TokensCssMigration, type ValidateInput, collectDefinedTokens, collectReferencedTokens, enforceBreakingRequiresMajor, ensureScale, findContractViolations, readLiveTokensConfig, removeToken, removeTokensMatching, renameToken, runAdditiveTokensCssMigrations, runTokensCssMigrations, semverBumpType, validateTokensCss };

package/dist-plugin/tokensCssMigrations/index.d.ts

@@ -16,6 +16,16 @@
 interface TokensCssMigration {
     /** Unique id; convention: `YYYY-MM-DD-<short-name>`. */
     id: string;
+    /**
+     * Whether this migration is backward-compatible.
+     *
+     * Token names are public API (see TOKENS.md). `'additive'` only ever inserts
+     * new names, so it is safe to auto-apply to a consumer's vendored `tokens.css`
+     * (the dev plugin's `autoMigrate`). `'breaking'` renames or removes a name a
+     * consumer may reference, so it ships only with a major version (post-1.0) and
+     * is never auto-applied — it rides an explicit `live-tokens migrate`.
+     */
+    kind: 'additive' | 'breaking';
     /** One-line summary shown by the CLI when the migration applies. */
     description: string;
     /** Pure, idempotent transform on the `tokens.css` source. */
@@ -113,6 +123,50 @@ interface RunResult {
 }
 /** Fold every registered migration over `css`. Pure and idempotent. */
 declare function runTokensCssMigrations(css: string): RunResult;
+/**
+ * Fold only the `additive` migrations. Additive changes only insert new token
+ * names, so applying them to a consumer's vendored `tokens.css` is always
+ * backward-compatible — this is what the dev plugin's `autoMigrate` runs. The
+ * `breaking` migrations (rename/remove) are deliberately skipped; they ride an
+ * explicit `live-tokens migrate` during a major upgrade.
+ */
+declare function runAdditiveTokensCssMigrations(css: string): RunResult;
+interface ContractViolation {
+    id: string;
+    /** Token names the migration removed or renamed away despite declaring `additive`. */
+    removed: string[];
+}
+/**
+ * Guardrail for the token-as-API contract: an `additive` migration must never
+ * remove or rename a token. We verify behaviorally rather than trusting the
+ * label — apply each additive migration to the package's own canonical
+ * `tokens.css` (which defines the full current vocabulary) and flag any token
+ * that disappears. A rename surfaces as the removal of its old name, so it is
+ * caught too. This catches the dangerous direction: a breaking change shipped as
+ * a backward-compatible one. (Over-labeling a no-op as `breaking` is harmless
+ * and not checked.)
+ */
+declare function findContractViolations(canonicalCss: string): ContractViolation[];
+type SemverBump = 'major' | 'minor' | 'patch' | 'none';
+/** Classify the bump from `prev` to `next` (leading `v` and pre-release tags ignored). */
+declare function semverBumpType(prev: string, next: string): SemverBump;
+interface BreakingGateResult {
+    level: 'ok' | 'warn' | 'error';
+    breakingIds: string[];
+    bump: SemverBump;
+    message: string;
+}
+/**
+ * The version side of the token contract: a `breaking` migration introduced in a
+ * release requires a major version bump. Pre-1.0 (next major is 0) this is only
+ * a warning, since semver permits breaking changes in 0.x minors; from 1.0.0 on
+ * it is an error. Pure so the release check and its tests share one rule.
+ */
+declare function enforceBreakingRequiresMajor(args: {
+    newMigrations: TokensCssMigration[];
+    prevVersion: string;
+    nextVersion: string;
+}): BreakingGateResult;
 interface ComponentSource {
     name: string;
     source: string;
@@ -141,4 +195,4 @@ interface ValidateInput {
  */
 declare function validateTokensCss(input: ValidateInput): MissingToken[];
 
-export { type ComponentSource, type MissingToken, type RunResult, TOKENS_CSS_MIGRATIONS, type TokensCssMigration, type ValidateInput, collectDefinedTokens, collectReferencedTokens, ensureScale, readLiveTokensConfig, removeToken, removeTokensMatching, renameToken, runTokensCssMigrations, validateTokensCss };
+export { type BreakingGateResult, type ComponentSource, type ContractViolation, type MissingToken, type RunResult, type SemverBump, TOKENS_CSS_MIGRATIONS, type TokensCssMigration, type ValidateInput, collectDefinedTokens, collectReferencedTokens, enforceBreakingRequiresMajor, ensureScale, findContractViolations, readLiveTokensConfig, removeToken, removeTokensMatching, renameToken, runAdditiveTokensCssMigrations, runTokensCssMigrations, semverBumpType, validateTokensCss };

package/dist-plugin/tokensCssMigrations/index.js

@@ -2,23 +2,31 @@ import {
   TOKENS_CSS_MIGRATIONS,
   collectDefinedTokens,
   collectReferencedTokens,
+  enforceBreakingRequiresMajor,
   ensureScale,
+  findContractViolations,
   readLiveTokensConfig,
   removeToken,
   removeTokensMatching,
   renameToken,
+  runAdditiveTokensCssMigrations,
   runTokensCssMigrations,
+  semverBumpType,
   validateTokensCss
-} from "../chunk-MJO4T3CM.js";
+} from "../chunk-D77VD4Z6.js";
 export {
   TOKENS_CSS_MIGRATIONS,
   collectDefinedTokens,
   collectReferencedTokens,
+  enforceBreakingRequiresMajor,
   ensureScale,
+  findContractViolations,
   readLiveTokensConfig,
   removeToken,
   removeTokensMatching,
   renameToken,
+  runAdditiveTokensCssMigrations,
   runTokensCssMigrations,
+  semverBumpType,
   validateTokensCss
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -101,12 +101,13 @@
     "check:component-defaults": "node scripts/sync-component-defaults.mjs --check",
     "check:production-is-default": "node scripts/check-production-is-default.mjs",
     "check:docs-content": "node scripts/sync-docs.mjs --check",
+    "check:token-contract": "node scripts/check-token-contract.mjs",
     "sync:component-defaults": "node scripts/sync-component-defaults.mjs --write",
     "sync:docs": "node scripts/sync-docs.mjs --write",
     "collapse:manifest": "node scripts/collapse-manifest-to-default.mjs",
     "check:smoke-install": "bash scripts/smoke-install.sh",
     "check:smoke-create": "bash scripts/smoke-create.sh",
-    "prepublishOnly": "npm run check:no-style-imports && npm run check:slot-prose && npm run check:overlay-portal && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:smoke-install && npm run check:smoke-create"
+    "prepublishOnly": "npm run check:no-style-imports && npm run check:slot-prose && npm run check:overlay-portal && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:token-contract && npm run check:smoke-install && npm run check:smoke-create"
   },
   "peerDependencies": {
     "@sveltejs/vite-plugin-svelte": "^7.0",