@motion-proto/live-tokens 0.16.2 → 0.17.0

package/bin/cli.mjs

@@ -9,13 +9,18 @@ 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';
 
 const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
 
 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
+  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).
 `;
 
 function fail(message, code = 1) {
@@ -38,6 +43,23 @@ if (command === 'check-component') {
   process.exit(result.errors.length === 0 ? 0 : 1);
 }
 
+if (command === 'migrate') {
+  const check = rest.includes('--check');
+  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.
+    if (result.status === 'no-path') process.exit(1);
+    if (check && result.status === 'would-change') process.exit(1);
+    process.exit(0);
+  } catch (err) {
+    fail(`migrate failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 if (command !== 'setup-claude') {
   fail(`Unknown command: ${command}\n\n${USAGE}`);
 }

package/bin/migrate.mjs

@@ -0,0 +1,113 @@
+// `live-tokens migrate` worker.
+//
+// Applies the registered tokens-css migrations to a consumer's developer-authored
+// tokens.css, reconciling Layer-1 drift after a package upgrade. The migration
+// engine itself lives in the built plugin (dist-plugin/tokensCssMigrations) so
+// the CLI and the dev-plugin guardrail share one source of truth; this module
+// only handles path resolution, file IO, and reporting.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const ENGINE = resolve(pkgRoot, 'dist-plugin/tokensCssMigrations/index.js');
+
+// Locations to probe when neither --tokens nor config.tokensCssPath is given.
+const DEFAULT_CANDIDATES = [
+  'src/system/styles/tokens.css',
+  'src/styles/tokens.css',
+  'src/tokens.css',
+  'tokens.css',
+];
+
+async function loadEngine() {
+  if (!existsSync(ENGINE)) {
+    throw new Error(
+      `migration engine not found at ${relative(process.cwd(), ENGINE)}. ` +
+        `Build the plugin first (npm run build:plugin).`,
+    );
+  }
+  return import(ENGINE);
+}
+
+/** --tokens <path> > live-tokens.config.json tokensCssPath > default scan. */
+export function resolveTokensCssPath(explicit, configPath, root = process.cwd()) {
+  if (explicit) return resolve(root, explicit);
+  if (configPath) return resolve(root, configPath);
+  for (const c of DEFAULT_CANDIDATES) {
+    const full = resolve(root, c);
+    if (existsSync(full)) return full;
+  }
+  return null;
+}
+
+/**
+ * Run migrations. Returns a result object; never writes when `check` is true.
+ * `{ status: 'no-path' | 'unchanged' | 'changed' | 'would-change', ... }`
+ */
+export async function runMigrate({ tokensArg, check = false, root = process.cwd() } = {}) {
+  const { runTokensCssMigrations, readLiveTokensConfig } = await loadEngine();
+
+  const config = readLiveTokensConfig();
+  const tokensPath = resolveTokensCssPath(tokensArg, config.tokensCssPath, root);
+  if (!tokensPath) {
+    return {
+      status: 'no-path',
+      message:
+        `Could not locate tokens.css. Pass --tokens <path>, set "tokensCssPath" in ` +
+        `live-tokens.config.json, or place it at one of: ${DEFAULT_CANDIDATES.join(', ')}.`,
+    };
+  }
+  if (!existsSync(tokensPath)) {
+    return { status: 'no-path', message: `tokens.css not found at ${relative(root, tokensPath)}.` };
+  }
+
+  const before = readFileSync(tokensPath, 'utf8');
+  const { css, applied, changed } = runTokensCssMigrations(before);
+  const addedLines = diffAddedLines(before, css);
+
+  if (!changed) {
+    return { status: 'unchanged', tokensPath };
+  }
+  if (check) {
+    return { status: 'would-change', tokensPath, applied, addedLines };
+  }
+  writeFileSync(tokensPath, css);
+  return { status: 'changed', tokensPath, applied, addedLines };
+}
+
+function diffAddedLines(before, after) {
+  const beforeSet = new Set(before.split('\n'));
+  return after.split('\n').filter((l) => l.trim() && !beforeSet.has(l));
+}
+
+export function formatMigrateResult(result, { check }) {
+  const root = process.cwd();
+  switch (result.status) {
+    case 'no-path':
+      return result.message;
+    case 'unchanged':
+      return `✓ ${relative(root, result.tokensPath)} is already up to date.`;
+    case 'would-change':
+    case 'changed': {
+      const verb = result.status === 'changed' ? 'Applied' : 'Would apply';
+      const lines = [
+        `${verb} ${result.applied.length} migration(s) to ${relative(root, result.tokensPath)}:`,
+        ...result.applied.map((id) => `  • ${id}`),
+      ];
+      if (result.addedLines.length) {
+        lines.push(`Added ${result.addedLines.length} line(s):`);
+        for (const l of result.addedLines) lines.push(`  + ${l.trim()}`);
+      }
+      if (check) {
+        lines.push(`\nRun without --check to write these changes, then review the diff in git.`);
+      } else {
+        lines.push(`\nReview the diff in git before committing.`);
+      }
+      return lines.join('\n');
+    }
+    default:
+      return `Unknown result: ${JSON.stringify(result)}`;
+  }
+}

package/dist-plugin/chunk-UBS57IYV.js

@@ -0,0 +1,249 @@
+// src/editor/core/themes/parsers/globalRootBlock.ts
+function extractGlobalRootBody(source) {
+  const re = /:global\(:root\)\s*\{([^}]*)\}/g;
+  const bodies = [];
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    bodies.push(m[1]);
+  }
+  return bodies.join("\n");
+}
+
+// vite-plugin/tokensCssMigrations/cssTokenOps.ts
+var DECL_RE = /(^|[\s;{])(--[a-z0-9-]+)\s*:/gi;
+var REF_RE = /var\(\s*(--[a-z0-9-]+)/gi;
+function collectDefinedTokens(css) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of css.matchAll(DECL_RE)) out.add(m[2]);
+  return out;
+}
+function collectReferencedTokens(css) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of css.matchAll(REF_RE)) out.add(m[1]);
+  return out;
+}
+function ensureScale(css, opts) {
+  const defined = collectDefinedTokens(css);
+  const missing = opts.entries.filter((e) => !defined.has(e.name));
+  if (missing.length === 0) return css;
+  const lines = css.split("\n");
+  const { indent, insertAfter } = findInsertionPoint(lines, opts.anchorPrefixes ?? []);
+  const block = [];
+  if (opts.sectionComment) block.push(`${indent}/* ${opts.sectionComment} */`);
+  for (const e of missing) block.push(`${indent}${e.name}: ${e.value};`);
+  lines.splice(insertAfter + 1, 0, ...block);
+  return lines.join("\n");
+}
+function renameToken(css, oldName, newName) {
+  const defined = collectDefinedTokens(css);
+  if (!defined.has(oldName) || defined.has(newName)) return css;
+  const re = new RegExp(escapeRe(oldName) + "(?![a-z0-9-])", "gi");
+  return css.replace(re, newName);
+}
+function removeToken(css, name) {
+  const lines = css.split("\n");
+  const declRe = new RegExp("(^|[\\s;{])" + escapeRe(name) + "\\s*:");
+  const kept = lines.filter((line) => !declRe.test(line));
+  if (kept.length === lines.length) return css;
+  return kept.join("\n");
+}
+function removeTokensMatching(css, predicate) {
+  const lines = css.split("\n");
+  const declRe = /^\s*(--[a-z0-9-]+)\s*:/;
+  const kept = lines.filter((line) => {
+    const m = line.match(declRe);
+    return !(m && predicate(m[1]));
+  });
+  if (kept.length === lines.length) return css;
+  return kept.join("\n");
+}
+function findInsertionPoint(lines, anchorPrefixes) {
+  for (const prefix of anchorPrefixes) {
+    let last = -1;
+    let indent = "  ";
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/^(\s*)(--[a-z0-9-]+)\s*:/);
+      if (m && m[2].startsWith(prefix)) {
+        last = i;
+        indent = m[1] || "  ";
+      }
+    }
+    if (last !== -1) return { indent, insertAfter: last };
+  }
+  let depth = 0;
+  let inRoot = false;
+  let lastDeclIndent = "  ";
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!inRoot && /(^|\s):root[^{]*\{/.test(line)) {
+      inRoot = true;
+      depth = 1;
+      continue;
+    }
+    if (!inRoot) continue;
+    const declIndent = line.match(/^(\s*)--[a-z0-9-]+\s*:/);
+    if (declIndent) lastDeclIndent = declIndent[1] || "  ";
+    depth += (line.match(/\{/g)?.length ?? 0) - (line.match(/\}/g)?.length ?? 0);
+    if (depth === 0) {
+      return { indent: lastDeclIndent, insertAfter: i - 1 };
+    }
+  }
+  return { indent: "  ", insertAfter: lines.length - 1 };
+}
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// vite-plugin/tokensCssMigrations/migrations/2026-05-29-typography-scale-additions.ts
+var tokensCssMigration_2026_05_29_typographyScaleAdditions = {
+  id: "2026-05-29-typography-scale-additions",
+  description: "Add --line-height-{xs..xl}, --letter-spacing-* and --ease-out-quart scales",
+  apply(css) {
+    let out = css;
+    out = ensureScale(out, {
+      sectionComment: "Line height (t-shirt scale)",
+      anchorPrefixes: ["--line-height-", "--font-size-", "--font-weight-", "--font-"],
+      entries: [
+        { name: "--line-height-xs", value: "1" },
+        { name: "--line-height-sm", value: "1.25" },
+        { name: "--line-height-md", value: "1.5" },
+        { name: "--line-height-lg", value: "1.75" },
+        { name: "--line-height-xl", value: "2" }
+      ]
+    });
+    out = ensureScale(out, {
+      sectionComment: "Letter spacing",
+      anchorPrefixes: ["--letter-spacing-", "--line-height-", "--font-size-", "--font-"],
+      entries: [
+        { name: "--letter-spacing-tighter", value: "-0.04em" },
+        { name: "--letter-spacing-tight", value: "-0.02em" },
+        { name: "--letter-spacing-normal", value: "0" },
+        { name: "--letter-spacing-wide", value: "0.04em" },
+        { name: "--letter-spacing-wider", value: "0.08em" }
+      ]
+    });
+    out = ensureScale(out, {
+      sectionComment: "Easing",
+      anchorPrefixes: ["--ease-", "--transition-", "--duration-"],
+      entries: [{ name: "--ease-out-quart", value: "cubic-bezier(0.25, 1, 0.5, 1)" }]
+    });
+    return out;
+  }
+};
+
+// vite-plugin/tokensCssMigrations/migrations/2026-05-29-sectiondivider-legacy-axis-cleanup.ts
+var KEEP_SEGMENTS = /* @__PURE__ */ new Set(["lg", "md", "sm"]);
+var tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup = {
+  id: "2026-05-29-sectiondivider-legacy-axis-cleanup",
+  description: "Remove legacy --sectiondivider-* tokens not on the lg/md/sm axis",
+  apply(css) {
+    return removeTokensMatching(css, (name) => {
+      if (!name.startsWith("--sectiondivider-")) return false;
+      const segment = name.slice("--sectiondivider-".length).split("-")[0];
+      return !KEEP_SEGMENTS.has(segment);
+    });
+  }
+};
+
+// vite-plugin/files/dataPaths.ts
+import fs from "fs";
+import path from "path";
+var DEFAULT_DATA_DIR = "src/live-tokens/data";
+var KNOWN_CONFIG_KEYS = /* @__PURE__ */ new Set([
+  "dataDir",
+  "themesDir",
+  "componentConfigsDir",
+  "manifestsDir",
+  "tokensCssPath"
+]);
+var cached = null;
+function readLiveTokensConfig() {
+  if (cached) return cached;
+  try {
+    const configPath = path.resolve("live-tokens.config.json");
+    if (!fs.existsSync(configPath)) return cached = {};
+    const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    if (!parsed || typeof parsed !== "object") return cached = {};
+    const unknown = Object.keys(parsed).filter(
+      (k) => k !== "$schema" && !KNOWN_CONFIG_KEYS.has(k)
+    );
+    if (unknown.length > 0) {
+      console.warn(
+        `[live-tokens] Unknown key(s) in live-tokens.config.json: ${unknown.join(", ")}. Known keys: ${Array.from(KNOWN_CONFIG_KEYS).join(", ")}.`
+      );
+    }
+    cached = parsed;
+    return cached;
+  } catch {
+    return cached = {};
+  }
+}
+function resolveDataDirs(opts = {}) {
+  const fileConfig = readLiveTokensConfig();
+  const dataDirRaw = opts.dataDir ?? fileConfig.dataDir ?? DEFAULT_DATA_DIR;
+  const dataDir = path.resolve(dataDirRaw);
+  const sub = (name) => path.resolve(dataDir, name);
+  return {
+    dataDir,
+    themesDir: opts.themesDir ? path.resolve(opts.themesDir) : fileConfig.themesDir ? path.resolve(fileConfig.themesDir) : sub("themes"),
+    componentConfigsDir: opts.componentConfigsDir ? path.resolve(opts.componentConfigsDir) : fileConfig.componentConfigsDir ? path.resolve(fileConfig.componentConfigsDir) : sub("component-configs"),
+    manifestsDir: opts.manifestsDir ? path.resolve(opts.manifestsDir) : fileConfig.manifestsDir ? path.resolve(fileConfig.manifestsDir) : sub("manifests")
+  };
+}
+
+// vite-plugin/tokensCssMigrations/index.ts
+var TOKENS_CSS_MIGRATIONS = [
+  tokensCssMigration_2026_05_29_typographyScaleAdditions,
+  tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup
+];
+function runTokensCssMigrations(css) {
+  let out = css;
+  const applied = [];
+  for (const m of TOKENS_CSS_MIGRATIONS) {
+    const next = m.apply(out);
+    if (next !== out) {
+      applied.push(m.id);
+      out = next;
+    }
+  }
+  return { css: out, applied, changed: out !== css };
+}
+function validateTokensCss(input) {
+  const defined = /* @__PURE__ */ new Set([
+    ...collectDefinedTokens(input.tokensCss),
+    ...collectDefinedTokens(input.generatedCss ?? "")
+  ]);
+  const referencedBy = /* @__PURE__ */ new Map();
+  for (const { name, source } of input.componentSources) {
+    const body = extractGlobalRootBody(source);
+    if (!body) continue;
+    for (const t of collectDefinedTokens(body)) defined.add(t);
+    for (const ref of collectReferencedTokens(body)) {
+      let set = referencedBy.get(ref);
+      if (!set) referencedBy.set(ref, set = /* @__PURE__ */ new Set());
+      set.add(name);
+    }
+  }
+  const missing = [];
+  for (const [token, names] of referencedBy) {
+    if (!defined.has(token)) {
+      missing.push({ token, referencedBy: [...names].sort() });
+    }
+  }
+  return missing.sort((a, b) => a.token.localeCompare(b.token));
+}
+
+export {
+  extractGlobalRootBody,
+  readLiveTokensConfig,
+  resolveDataDirs,
+  collectDefinedTokens,
+  collectReferencedTokens,
+  ensureScale,
+  renameToken,
+  removeToken,
+  removeTokensMatching,
+  TOKENS_CSS_MIGRATIONS,
+  runTokensCssMigrations,
+  validateTokensCss
+};

package/dist-plugin/index.cjs

@@ -30,7 +30,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // vite-plugin/index.ts
 var index_exports = {};
 __export(index_exports, {
-  themeFileApi: () => themeFileApi
+  TOKENS_CSS_MIGRATIONS: () => TOKENS_CSS_MIGRATIONS,
+  runTokensCssMigrations: () => runTokensCssMigrations,
+  themeFileApi: () => themeFileApi,
+  validateTokensCss: () => validateTokensCss
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -564,7 +567,8 @@ var KNOWN_CONFIG_KEYS = /* @__PURE__ */ new Set([
   "dataDir",
   "themesDir",
   "componentConfigsDir",
-  "manifestsDir"
+  "manifestsDir",
+  "tokensCssPath"
 ]);
 var cached = null;
 function readLiveTokensConfig() {
@@ -601,6 +605,168 @@ function resolveDataDirs(opts = {}) {
   };
 }
 
+// vite-plugin/tokensCssMigrations/cssTokenOps.ts
+var DECL_RE = /(^|[\s;{])(--[a-z0-9-]+)\s*:/gi;
+var REF_RE = /var\(\s*(--[a-z0-9-]+)/gi;
+function collectDefinedTokens(css) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of css.matchAll(DECL_RE)) out.add(m[2]);
+  return out;
+}
+function collectReferencedTokens(css) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of css.matchAll(REF_RE)) out.add(m[1]);
+  return out;
+}
+function ensureScale(css, opts) {
+  const defined = collectDefinedTokens(css);
+  const missing = opts.entries.filter((e) => !defined.has(e.name));
+  if (missing.length === 0) return css;
+  const lines = css.split("\n");
+  const { indent, insertAfter } = findInsertionPoint(lines, opts.anchorPrefixes ?? []);
+  const block = [];
+  if (opts.sectionComment) block.push(`${indent}/* ${opts.sectionComment} */`);
+  for (const e of missing) block.push(`${indent}${e.name}: ${e.value};`);
+  lines.splice(insertAfter + 1, 0, ...block);
+  return lines.join("\n");
+}
+function removeTokensMatching(css, predicate) {
+  const lines = css.split("\n");
+  const declRe = /^\s*(--[a-z0-9-]+)\s*:/;
+  const kept = lines.filter((line) => {
+    const m = line.match(declRe);
+    return !(m && predicate(m[1]));
+  });
+  if (kept.length === lines.length) return css;
+  return kept.join("\n");
+}
+function findInsertionPoint(lines, anchorPrefixes) {
+  for (const prefix of anchorPrefixes) {
+    let last = -1;
+    let indent = "  ";
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/^(\s*)(--[a-z0-9-]+)\s*:/);
+      if (m && m[2].startsWith(prefix)) {
+        last = i;
+        indent = m[1] || "  ";
+      }
+    }
+    if (last !== -1) return { indent, insertAfter: last };
+  }
+  let depth = 0;
+  let inRoot = false;
+  let lastDeclIndent = "  ";
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!inRoot && /(^|\s):root[^{]*\{/.test(line)) {
+      inRoot = true;
+      depth = 1;
+      continue;
+    }
+    if (!inRoot) continue;
+    const declIndent = line.match(/^(\s*)--[a-z0-9-]+\s*:/);
+    if (declIndent) lastDeclIndent = declIndent[1] || "  ";
+    depth += (line.match(/\{/g)?.length ?? 0) - (line.match(/\}/g)?.length ?? 0);
+    if (depth === 0) {
+      return { indent: lastDeclIndent, insertAfter: i - 1 };
+    }
+  }
+  return { indent: "  ", insertAfter: lines.length - 1 };
+}
+
+// vite-plugin/tokensCssMigrations/migrations/2026-05-29-typography-scale-additions.ts
+var tokensCssMigration_2026_05_29_typographyScaleAdditions = {
+  id: "2026-05-29-typography-scale-additions",
+  description: "Add --line-height-{xs..xl}, --letter-spacing-* and --ease-out-quart scales",
+  apply(css) {
+    let out = css;
+    out = ensureScale(out, {
+      sectionComment: "Line height (t-shirt scale)",
+      anchorPrefixes: ["--line-height-", "--font-size-", "--font-weight-", "--font-"],
+      entries: [
+        { name: "--line-height-xs", value: "1" },
+        { name: "--line-height-sm", value: "1.25" },
+        { name: "--line-height-md", value: "1.5" },
+        { name: "--line-height-lg", value: "1.75" },
+        { name: "--line-height-xl", value: "2" }
+      ]
+    });
+    out = ensureScale(out, {
+      sectionComment: "Letter spacing",
+      anchorPrefixes: ["--letter-spacing-", "--line-height-", "--font-size-", "--font-"],
+      entries: [
+        { name: "--letter-spacing-tighter", value: "-0.04em" },
+        { name: "--letter-spacing-tight", value: "-0.02em" },
+        { name: "--letter-spacing-normal", value: "0" },
+        { name: "--letter-spacing-wide", value: "0.04em" },
+        { name: "--letter-spacing-wider", value: "0.08em" }
+      ]
+    });
+    out = ensureScale(out, {
+      sectionComment: "Easing",
+      anchorPrefixes: ["--ease-", "--transition-", "--duration-"],
+      entries: [{ name: "--ease-out-quart", value: "cubic-bezier(0.25, 1, 0.5, 1)" }]
+    });
+    return out;
+  }
+};
+
+// vite-plugin/tokensCssMigrations/migrations/2026-05-29-sectiondivider-legacy-axis-cleanup.ts
+var KEEP_SEGMENTS = /* @__PURE__ */ new Set(["lg", "md", "sm"]);
+var tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup = {
+  id: "2026-05-29-sectiondivider-legacy-axis-cleanup",
+  description: "Remove legacy --sectiondivider-* tokens not on the lg/md/sm axis",
+  apply(css) {
+    return removeTokensMatching(css, (name) => {
+      if (!name.startsWith("--sectiondivider-")) return false;
+      const segment = name.slice("--sectiondivider-".length).split("-")[0];
+      return !KEEP_SEGMENTS.has(segment);
+    });
+  }
+};
+
+// vite-plugin/tokensCssMigrations/index.ts
+var TOKENS_CSS_MIGRATIONS = [
+  tokensCssMigration_2026_05_29_typographyScaleAdditions,
+  tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup
+];
+function runTokensCssMigrations(css) {
+  let out = css;
+  const applied = [];
+  for (const m of TOKENS_CSS_MIGRATIONS) {
+    const next = m.apply(out);
+    if (next !== out) {
+      applied.push(m.id);
+      out = next;
+    }
+  }
+  return { css: out, applied, changed: out !== css };
+}
+function validateTokensCss(input) {
+  const defined = /* @__PURE__ */ new Set([
+    ...collectDefinedTokens(input.tokensCss),
+    ...collectDefinedTokens(input.generatedCss ?? "")
+  ]);
+  const referencedBy = /* @__PURE__ */ new Map();
+  for (const { name, source } of input.componentSources) {
+    const body = extractGlobalRootBody(source);
+    if (!body) continue;
+    for (const t of collectDefinedTokens(body)) defined.add(t);
+    for (const ref of collectReferencedTokens(body)) {
+      let set = referencedBy.get(ref);
+      if (!set) referencedBy.set(ref, set = /* @__PURE__ */ new Set());
+      set.add(name);
+    }
+  }
+  const missing = [];
+  for (const [token, names] of referencedBy) {
+    if (!defined.has(token)) {
+      missing.push({ token, referencedBy: [...names].sort() });
+    }
+  }
+  return missing.sort((a, b) => a.token.localeCompare(b.token));
+}
+
 // vite-plugin/themeFileApi.ts
 var import_node_url = require("url");
 var import_meta = {};
@@ -871,6 +1037,33 @@ function themeFileApi(opts) {
   function listComponentNames() {
     return listComponentSourcePaths().map(componentNameFromFile);
   }
+  function warnOnTokenDrift(log) {
+    let tokensCss = "";
+    try {
+      tokensCss = import_fs3.default.readFileSync(CSS_PATH, "utf-8");
+    } catch {
+      return;
+    }
+    let generatedCss = "";
+    try {
+      generatedCss = import_fs3.default.readFileSync(GENERATED_CSS_PATH, "utf-8");
+    } catch {
+    }
+    const componentSources = listComponentSourcePaths().map((p) => ({
+      name: componentNameFromFile(p),
+      source: import_fs3.default.readFileSync(p, "utf-8")
+    }));
+    const missing = validateTokensCss({ tokensCss, generatedCss, componentSources });
+    if (missing.length === 0) return;
+    const lines = missing.map(
+      (m) => `  ${m.token}  (referenced by ${m.referencedBy.join(", ")})`
+    );
+    log(
+      `[live-tokens] ${missing.length} token(s) referenced by components are not defined in ${import_path3.default.relative(process.cwd(), CSS_PATH)}:
+${lines.join("\n")}
+  These render as blank/empty editor slots. Run \`npx live-tokens migrate\` to reconcile.`
+    );
+  }
   function generateDefaultConfig(comp, sourcePath) {
     if (!import_fs3.default.existsSync(sourcePath)) return;
     const r = componentResource(comp);
@@ -1696,6 +1889,7 @@ function themeFileApi(opts) {
       ensureComponentConfigsDir();
       ensureManifestsDir();
       regenerateTokensCss();
+      warnOnTokenDrift((msg) => server.config.logger.warn(msg));
       server.middlewares.use(async (req, res, next) => {
         const handled = await dispatch(req, res, routes);
         if (!handled) next();
@@ -1713,5 +1907,8 @@ function themeFileApi(opts) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  themeFileApi
+  TOKENS_CSS_MIGRATIONS,
+  runTokensCssMigrations,
+  themeFileApi,
+  validateTokensCss
 });

package/dist-plugin/index.d.cts

@@ -1,4 +1,5 @@
 import { Plugin } from 'vite';
+export { ComponentSource, MissingToken, RunResult, TOKENS_CSS_MIGRATIONS, TokensCssMigration, ValidateInput, runTokensCssMigrations, validateTokensCss } from './tokensCssMigrations/index.cjs';
 
 interface ThemeFileApiOptions {
     tokensCssPath: string;

package/dist-plugin/index.d.ts

@@ -1,4 +1,5 @@
 import { Plugin } from 'vite';
+export { ComponentSource, MissingToken, RunResult, TOKENS_CSS_MIGRATIONS, TokensCssMigration, ValidateInput, runTokensCssMigrations, validateTokensCss } from './tokensCssMigrations/index.js';
 
 interface ThemeFileApiOptions {
     tokensCssPath: string;