@motion-proto/live-tokens 0.79.0 → 0.81.0

package/.claude/skills/live-tokens-check-compliance/SKILL.md

@@ -1,32 +1,28 @@
 ---
 name: live-tokens-check-compliance
-description: Check an existing @motion-proto/live-tokens project against the design system and fix it until check-page and check-component both exit 0. Checks for correct use of components, properties, and tokens. Reads the whole project from one run of npx live-tokens report, runs the token migrations, then runs both checkers, which apply every auto repair and return each remaining finding with its own guidance, repair level, and details. Use when the user asks to check, audit, or review the project. Use when the user asks to fix the project or to make check:design pass. Edits the files the checkers name. Updates tokens.css only through the migration command.
+description: Check an existing @motion-proto/live-tokens project against the design system and fix it until check-page and check-component both exit 0. Checks for correct use of components, properties, and tokens. Runs both checkers, which bring tokens.css up to the installed package, apply every auto repair, and return each remaining finding with its own guidance, repair level, and details. Use when the user asks to check, audit, or review the project. Use when the user asks to fix the project or to make the build's design checks pass. Edits the files the checkers name. Changes tokens.css only through its migrations.
 ---
 
 # Checking and fixing a project's adherence to live-tokens
 
 Check the project, then fix every finding of `check-page` and `check-component` until both exit 0. `check-page` checks pages. Every component comes from the catalogue, every prop is declared, and every value in page CSS is a design token. `check-component` checks the project's own components. Every token names a semantic property, and its default is the design token that property reads. Every finding carries its own `guidance`, and the repair follows it.
 
-The report and both checkers are static. They read the project's source, never open a browser, and never mount a runtime. `npx live-tokens check-page <file> --tests` proves a page's rendered paint, and `npx live-tokens check-component <id> --tests` proves a component's declared behavior. **live-tokens-create-page** and **live-tokens-create-component** run those, one file or one id at a time, and their findings carry guidance the same way.
+Both checkers are static. They read the project's source, never open a browser, and never mount a runtime. `npx live-tokens check-page <file> --tests` proves a page's rendered paint, and `npx live-tokens check-component <id> --tests` proves a component's declared behavior. **live-tokens-create-page** and **live-tokens-create-component** run those, one file or one id at a time, and their findings carry guidance the same way.
 
 ## Workflow
 
-1. Run `npx live-tokens report --json`. Read it in its own key order: `project`, `migrations`, `components`, `findings.pages`, `findings.components`, `usage`, per Report sections below.
-2. Run `npx live-tokens migrate --check` to see the plan, then `npx live-tokens migrate` to apply it. The command brings `tokens.css` up to the installed package and heals the data tree. With `--write` it also rewrites the route references it lists. `--tokens <path>` names a tokens.css in an unusual place.
-3. Run both checkers with `--json`. Each first applies every finding whose `repair` is `auto`, checks again, and returns the fixes it applied in `fix.applied` beside the findings that remain. A fix in `fix.skipped` found its text moved, and the next run applies it. `--no-fix` reports without editing, for a build or CI.
+1. Run both checkers with `--json`. Each first brings `tokens.css` up to the installed package by applying every additive migration, then applies every finding whose `repair` is `auto`, checks again, and returns the fixes it applied in `fix.applied` beside the findings that remain. A pending breaking migration returns as a `tokens-breaking-migration` finding, since it renames design tokens the project may read. A fix in `fix.skipped` found its text moved, and the next run applies it. `--no-fix` reports without editing, for a build or CI.
    ```sh
    npx live-tokens check-page --json
    npx live-tokens check-component --json
    ```
-4. Read what remains. Each finding carries the fields under Finding fields, with a `repair` of `choice` or `authored`.
-5. Group the findings by rule. Take the largest error group first, then the remaining errors. Take warnings only when the repair scope includes warnings.
-6. Make every repair in the group from its `guidance`, within Scope below.
-7. Run both checkers again. When repairable findings remain in scope, return to step 5. When no token fits a remaining finding, leave it and continue to the reply with its reason.
-8. When the errors are clear, run both checkers with `--strict`. Report what `--strict` adds. Clear warnings within the existing request. Otherwise ask whether to clear the warnings now.
-9. When the repair scope includes warnings, return to step 5 with `--strict`. When strict checks pass or the user defers warnings, set up the build script.
-10. Add `check:design` to the build, per Build script below.
-11. Reply with:
-    - the report's picture: pending migrations, component facts, and usage
+2. Read what remains. Each finding carries the fields under Finding fields, with a `repair` of `choice` or `authored`.
+3. Group the findings by rule. Take the largest error group first, then the remaining errors. Take warnings only when the repair scope includes warnings.
+4. Make every repair in the group from its `guidance`, within Scope below.
+5. Run both checkers again. When repairable findings remain in scope, return to step 3. When no token fits a remaining finding, leave it and continue to the reply with its reason.
+6. When the errors are clear, run both checkers with `--strict`. Report what `--strict` adds. Clear warnings within the existing request. Otherwise ask whether to clear the warnings now.
+7. When the repair scope includes warnings, return to step 3 with `--strict`. When strict checks pass or the user defers warnings, continue to the reply.
+8. Reply with:
     - the fixes the checkers applied, each with its count and any visible shift
     - the remaining changes by rule, each with its count and any visible shift
     - the findings left, each with its reason and any config entry the user chose
@@ -34,20 +30,9 @@ The report and both checkers are static. They read the project's source, never o
 
 `check-page <path>` scopes a run to one page. `check-component <id>` scopes a run to one component: its runtime, its editor, and its registration. The checkers read tokens.css from its default location.
 
-## Report sections
-
-| Section | Contents |
-| --- | --- |
-| Pending token migrations (`migrations`) | Whether `tokens.css` is behind the installed package. `status` is `pending`, `none pending`, `no tokens.css`, or `unavailable`. A stale file shows downstream as unknown tokens, so step 2 runs the migrations before either checker. |
-| Component facts (`components[]`) | Every component the project has, each with `id`, `origin`, `file`, `registered`, and `tokens` (the count of semantic properties it declares). A component's unread tokens, missing description, and missing registration are the `unread-token`, `missing-description`, and `missing-registration` findings. |
-| Checker findings by rule (`findings.pages`, `findings.components`) | Both checkers' findings by rule under the project's severities, and one strict total with every warning as an error. Errors fail the build today. The strict total is what a fully tokenized project would fail. |
-| Components each page renders (`usage.byPage`) | Which component each page imports, and how many times the page renders it. When a page renders none, say whether it is chrome or markup that a shipped component covers. |
-| Shipped components no page renders (`usage.unusedShipped`) | Information only. |
-| Project components unused (`usage.customUnused`) | The project's own components no page renders. |
-
 ## Finding fields
 
-Every finding from both checkers, under `report --json` and under each checker's `--json`:
+Every finding from both checkers, under each checker's `--json`:
 
 | Field | Value |
 | --- | --- |
@@ -69,8 +54,5 @@ Every finding's `repair` says what moving it costs.
 
 - Add no token to `tokens.css`. Map a literal with no matching token to the nearest existing token by role. When no token fits, leave the finding and say so.
 - When the nearest token differs from the literal, use the token and name the shift in the reply, such as `14px` to `--space-16`.
+- Apply a `tokens-breaking-migration` finding with `npx live-tokens migrate`, after `npx live-tokens migrate --check` prints the plan. `--tokens <path>` names a tokens.css in an unusual place, and `--write` also rewrites the route references the plan lists. Name each renamed design token in the reply.
 - Any finding, at any repair level, can stay as a deliberate exception when the user chooses to keep it. Record that decision in the config entry its `exception` field names, and prefer the narrower entry. When the user has chosen to lower a rule's severity, record it in `live-tokens.config.json` under `"checks": { "rules": { "<rule>": "warn" } }`. `--off=<rule>` silences a rule for one run only.
-
-## Build script
-
-When `package.json` has no `check:design` script, add `"check:design": "live-tokens check-page --no-fix && live-tokens check-component --no-fix"`. `--no-fix` keeps the build from editing files. When both checkers exit 0, prepend `npm run check:design &&` to the existing build command. Preserve its other build steps.

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.81.0 — Skill Atlas links name a block
+
+### Added
+
+- **A Skill Atlas link opens one block.** Clicking a card or badge writes its
+  link to the address bar, named after the card title and the badge label:
+  `#set-type/write-the-font-pairing/voice`. Opening the link selects that
+  block and scrolls both panes to it. `#set-type` still opens the skill, and
+  a link to a block that no longer exists opens its skill.
+
+## 0.80.0 — The build runs the design checks
+
+### Added
+
+- **`vite build` runs the design checks.** `themeFileApi` runs both static
+  checkers at the start of the build, under the project's severities and
+  without repairs. An error stops the build, and warnings print.
+  `themeFileApi({ checks: false })` turns the checks off. The dev server
+  runs no checks.
+
+### Changed
+
+- **A CollapsibleSection header toggles from its label.** Without `href`, the
+  chevron and the label share one button, so a click anywhere on the header
+  opens or closes the section. The label is the button's accessible name, in
+  place of "Expand section" or "Collapse section".
+- **The template's build is `vite build`.** Its `check:design` script is
+  gone, since the plugin runs the same checks.
+- **check-compliance leaves the build alone.** It no longer adds
+  `check:design` to `package.json`.
+- **`migrate` removes the `check:design` build step.** It removes the script
+  and its place in `build` when both hold what live-tokens wrote and the Vite
+  config uses `themeFileApi` with its checks on. It reports any other
+  `check:design` and leaves it in place.
+
+- **The checkers bring `tokens.css` up to the installed package.** Before
+  either checker reads the design tokens, it applies every pending additive
+  migration and lists it in `fix.applied` under `tokens-migration`. A pending
+  breaking migration is a `tokens-breaking-migration` finding with
+  `repair: 'choice'`, and `npx live-tokens migrate` still applies it.
+  `--no-fix` reports both and writes nothing.
+- **check-compliance runs only the checkers.** It no longer runs
+  `npx live-tokens report` or `npx live-tokens migrate` first. `report` stays
+  a CLI command.
+
+### Fixed
+
+- **`migrate`'s usage text names the breaking migrations it applies.** It
+  said additive only, and it has always applied both.
+
 ## 0.79.0 — Checks fix what they find
 
 ### Added

package/README.md

@@ -332,7 +332,7 @@ npx @motion-proto/live-tokens <command>
 | `set-type <pairing.json> [--dry-run] [--no-verify]` | Bind Google Fonts families to the theme's font stacks, verified against the API. |
 | `set-geometry <ops.json> [--dry-run]` | Move radius, padding, gap, and border-width aliases along their token scales. |
 | `save-theme <name> [--no-activate] [--dry-run]` | Compose the live state into `themes/<slug>.json` and open it, which clears the unsaved buffers. |
-| `migrate [--check] [--write] [--tokens <path>]` | Reconcile the project with the installed package: additive `tokens.css` migrations, the pre-0.48 data-tree move, and a report on source references to the routes that moved in 0.35.0. |
+| `migrate [--check] [--write] [--tokens <path>]` | Reconcile the project with the installed package: every `tokens.css` migration, breaking ones included, the pre-0.48 data-tree move, and a report on source references to the routes that moved in 0.35.0. |
 
 Once installed in a project, the same commands are available as `npx live-tokens <command>`.
 
@@ -426,13 +426,13 @@ Verify the result:
 npx @motion-proto/live-tokens check-component <id>
 ```
 
-The validator checks the file layout, the `:global(:root)` block, the token-suffix vocabulary, the state-before-property rule, the public-imports rule, the `registerComponent({ id })` call, and that every default resolves to a design token rather than a literal. Exit code 0 means the static contract is met. A project scaffolded by `create` runs it, with `check-page`, as `npm run check:design` before every `vite build`, so a component or page that opts out of the theme cannot ship by accident.
+The validator checks the file layout, the `:global(:root)` block, the token-suffix vocabulary, the state-before-property rule, the public-imports rule, the `registerComponent({ id })` call, and that every default resolves to a design token rather than a literal. Exit code 0 means the static contract is met. `themeFileApi` runs it, with `check-page`, at the start of every `vite build`, so a component or page that opts out of the theme cannot ship by accident. An error stops the build, and warnings print. `themeFileApi({ checks: false })` turns the checks off.
 
 ### `live-tokens-check-compliance`
 
-Ask how things stand, or ask for the code to catch up: "check this project against the design system and fix it", "audit the pricing page", "make check:design pass", "fix the design-system warnings", "replace the hex and pixel values with tokens", "review this before I upgrade".
+Ask how things stand, or ask for the code to catch up: "check this project against the design system and fix it", "audit the pricing page", "make the build's design checks pass", "fix the design-system warnings", "replace the hex and pixel values with tokens", "review this before I upgrade".
 
-The skill runs `npx live-tokens report --json`, which is the project as facts: pending `tokens.css` migrations, the tokens each component declares and reads, which page renders which component, and both checkers' findings by rule under the project's severities and under `--strict`. It then runs `npx live-tokens migrate` and both checkers, which apply every `auto` repair themselves and return each remaining finding with its own `guidance`. The skill groups what remains by rule, largest error group first, makes each repair from its guidance, and re-runs until both checkers exit 0. It reports what `--strict` adds, clears the warnings when the request covers them, and adds `check:design` to the build with `--no-fix`. The reply names the fixes the checkers applied, the changes by rule with any visible shift, and each finding left with its reason. It never silences a rule to pass and never adds a token to `tokens.css` to match a value a page happened to use. A finding the user chooses to keep goes into the config entry its `exception` field names.
+The skill runs both checkers, which apply every pending additive `tokens.css` migration and every `auto` repair themselves and return each remaining finding with its own `guidance`. The skill groups what remains by rule, largest error group first, makes each repair from its guidance, and re-runs until both checkers exit 0. It reports what `--strict` adds and clears the warnings when the request covers them. The reply names the fixes the checkers applied, the changes by rule with any visible shift, and each finding left with its reason. It never silences a rule to pass and never adds a token to `tokens.css` to match a value a page happened to use. A finding the user chooses to keep goes into the config entry its `exception` field names.
 
 ## From edit to production
 

package/bin/check-component.mjs

@@ -50,6 +50,8 @@ export { unreadTokens } from './lib/componentSource.mjs';
  */
 export const COMPONENT_RULES = assembleRules(
   [
+    'tokens-migration',
+    'tokens-breaking-migration',
     'invalid-id',
     'missing-file',
     'missing-root-block',

package/bin/check-page.mjs

@@ -25,6 +25,8 @@ import * as tokenRules from './rules/tokens.mjs';
  *  three fields, same meanings, as `COMPONENT_RULES`. */
 export const PAGE_RULES = assembleRules(
   [
+    'tokens-migration',
+    'tokens-breaking-migration',
     'unknown-component',
     'unknown-prop',
     'unknown-prop-value',

package/bin/cli.mjs

@@ -12,7 +12,7 @@
 //   set-geometry <ops>       Apply radius/padding/gap/border-width ops to the open buffer.
 //   set-type <pairing>       Bind Google Fonts families to the theme's font stacks.
 //   save-theme <name>        Compose the live state into themes/<slug>.json and open it.
-//   migrate [...]            Reconcile tokens.css, the data tree, and route references.
+//   migrate [...]            Reconcile tokens.css, the data tree, route references, and the build script.
 
 import { writeSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -33,8 +33,10 @@ import {
   formatFindings,
   parseCheckFlags,
   readChecksConfig,
+  resolveRuleSeverity,
   toJson,
 } from './lib/findings.mjs';
+import { checkTokensCssMigrations } from './rules/tokens.mjs';
 import {
   runMigrate,
   formatMigrateResult,
@@ -42,6 +44,7 @@ import {
   formatMigrateDataResult,
 } from './migrate.mjs';
 import { runMigrateRoutes, formatRouteResult } from './migrate-routes.mjs';
+import { runMigrateBuildScript, formatBuildScriptResult } from './migrate-build-script.mjs';
 import { runCreate, formatCreateResult } from './create.mjs';
 import { runSetupClaude, formatSetupResult } from './setup-claude.mjs';
 import { runSetColors, formatSetColorsResult } from './set-colors.mjs';
@@ -102,7 +105,8 @@ check-component and check-page also accept:
                               [...] } drops paths from discovery entirely)
   --no-fix                    Report every finding and edit nothing, for a
                               build or CI. Without it, both checkers first
-                              apply every finding whose repair is auto (a
+                              apply every additive tokens.css migration and
+                              every finding whose repair is auto (a
                               deep import into a component, a raw dimension
                               with one nearest design token, a shipped
                               component's size prop, a semantic property
@@ -150,7 +154,8 @@ check-component and check-page also accept:
                               without writing.
   migrate [--check] [--write] [--tokens <path>]
                               Reconcile the project with the installed package:
-                              applies additive tokens.css migrations, moves a
+                              applies every tokens.css migration, breaking
+                              ones included, moves a
                               pre-0.48 data tree onto the current directory
                               names, heals what the retired pointer files named,
                               and reports source references to the
@@ -159,6 +164,9 @@ check-component and check-page also accept:
                               unambiguous route references (never /docs). --check
                               prints both plans without writing (exit 1 when
                               either is pending; route findings are advisory).
+                              Also removes the check:design script live-tokens
+                              added to the build, since vite build now runs the
+                              design checks through themeFileApi.
 `;
 
 // A large body written through console.log is cut at the pipe buffer when the
@@ -226,6 +234,14 @@ function shiftNote(f) {
   return `  shift ${shifts.join(', ')}`;
 }
 
+async function migrateTokensCss(rules, opts) {
+  const root = process.cwd();
+  const config = readChecksConfig(root);
+  const apply = !opts.noFix && resolveRuleSeverity('tokens-migration', rules, opts, config) !== 'off';
+  const { applied, findings } = await checkTokensCssMigrations({ root, apply });
+  return { applied: applySeverity(applied, rules, opts, config), findings };
+}
+
 /** Resolves severities and exclusions first, so a silenced rule or an excluded
  *  file is never edited. */
 function applyStaticFixes(findings, rules, opts, { exclude } = {}) {
@@ -236,7 +252,11 @@ function applyStaticFixes(findings, rules, opts, { exclude } = {}) {
 function formatFixes({ applied, skipped }) {
   const lines = [];
   for (const f of applied) {
-    lines.push(`  fixed    ${f.file}:${f.line}  ${f.details.patch.from} → ${f.details.patch.to || '(removed)'}  [${f.rule}]${shiftNote(f)}`);
+    lines.push(
+      f.details.patch
+        ? `  fixed    ${f.file}:${f.line}  ${f.details.patch.from} → ${f.details.patch.to || '(removed)'}  [${f.rule}]${shiftNote(f)}`
+        : `  fixed    ${f.file}  ${f.details.migrations.map((m) => m.id).join(', ')}  [${f.rule}]`,
+    );
   }
   for (const f of skipped) lines.push(`  skipped  ${f.file}:${f.line}  ${f.details.patch.from}  [${f.rule}]`);
   if (lines.length === 0) return '';
@@ -291,24 +311,26 @@ if (command === 'check-component') {
     console.log('✓ check-component: no component authored under src/system/components yet.');
     process.exit(0);
   }
+  const migration = await migrateTokensCss(COMPONENT_RULES, opts);
   let results = ids.map((id) => [id, checkComponent(id)]);
   const label = ids.length === 1 ? `check-component ${ids[0]}${opts.tests ? ' --tests' : ''}` : `check-component${opts.tests ? ' --tests' : ''}`;
   let fix;
   if (!opts.noFix) {
     fix = applyStaticFixes(results.flatMap(([, r]) => r.findings), COMPONENT_RULES, opts);
     if (fix.applied.length > 0) results = ids.map((id) => [id, checkComponent(id)]);
+    fix.applied.unshift(...migration.applied);
   }
-  if (!opts.tests && ids.length === 1 && !opts.json && !opts.strict && opts.off.length + opts.warn.length + opts.error.length === 0) {
+  if (!opts.tests && migration.findings.length === 0 && ids.length === 1 && !opts.json && !opts.strict && opts.off.length + opts.warn.length + opts.error.length === 0) {
     const [id, result] = results[0];
     console.log([fix ? formatFixes(fix) : '', formatReport(id, result)].filter(Boolean).join('\n'));
     process.exit(result.errors.length === 0 ? 0 : 1);
   }
   if (!opts.tests) {
-    reportChecks(label, results.flatMap(([, r]) => r.findings), ids.length, COMPONENT_RULES, opts, { fix });
+    reportChecks(label, [...migration.findings, ...results.flatMap(([, r]) => r.findings)], ids.length, COMPONENT_RULES, opts, { fix });
   }
   const { hasHardFailure, runContractTests } = await import('./contractRunner.mjs');
   const testOutcome = await runContractTests(opts.rest[0], { root: process.cwd() });
-  const findings = dedupeAliasFindings([...results.flatMap(([, r]) => r.findings), ...testOutcome.findings]);
+  const findings = dedupeAliasFindings([...migration.findings, ...results.flatMap(([, r]) => r.findings), ...testOutcome.findings]);
   reportChecks(label, findings, Math.max(ids.length, 1), COMPONENT_RULES, opts, {
     fix,
     coverage: testOutcome.coverage,
@@ -319,12 +341,15 @@ if (command === 'check-component') {
 if (command === 'check-page') {
   const opts = parseCheckFlags(rest);
   const targets = opts.rest.length > 0 ? opts.rest : discoverPages(process.cwd());
+  const migration = await migrateTokensCss(PAGE_RULES, opts);
   let { findings, checked } = checkPages(targets, { root: process.cwd() });
   let fix;
   if (!opts.noFix) {
     fix = applyStaticFixes(findings, PAGE_RULES, opts, { exclude: true });
     if (fix.applied.length > 0) ({ findings, checked } = checkPages(targets, { root: process.cwd() }));
+    fix.applied.unshift(...migration.applied);
   }
+  findings = [...migration.findings, ...findings];
   if (!opts.tests) {
     reportChecks('check-page', findings, checked, PAGE_RULES, opts, { exclude: true, fix });
   }
@@ -458,6 +483,12 @@ if (command === 'migrate') {
     const routeOut = formatRouteResult(routes, { check });
     if (routeOut) console.log('\n' + routeOut);
 
+    // Build-script pass: removes the check:design step that themeFileApi now
+    // runs during vite build. Advisory under --check, like the data heal.
+    const buildScript = runMigrateBuildScript({ root: process.cwd(), apply: !check });
+    const buildScriptOut = formatBuildScriptResult(buildScript);
+    if (buildScriptOut) console.log('\n' + buildScriptOut);
+
     // Route findings are advisory; token migrations and the data heal gate the
     // exit code.
     if (result.status === 'no-path') process.exit(1);

package/bin/lib/buildChecks.mjs

@@ -0,0 +1,32 @@
+// The design checks `vite build` runs through themeFileApi: both static
+// checkers with no repairs, under the project's own severities. The same bar
+// `check-page --no-fix` and `check-component --no-fix` hold.
+
+import { COMPONENT_RULES, checkComponent, discoverComponents } from '../check-component.mjs';
+import { PAGE_RULES, checkPages, discoverPages } from '../check-page.mjs';
+import { checkTokensCssMigrations } from '../rules/tokens.mjs';
+import { applySeverity, countBySeverity, formatFindings, readChecksConfig } from './findings.mjs';
+import { loadVocabulary } from './tokenVocabulary.mjs';
+
+export async function runBuildChecks({ root = process.cwd(), engine } = {}) {
+  const config = readChecksConfig(root);
+  const vocabulary = loadVocabulary({ root });
+  const migration = await checkTokensCssMigrations({ root, apply: false, engine });
+  const pages = checkPages(discoverPages(root), { root, vocabulary });
+  const ids = discoverComponents(root);
+  const components = ids.map((id) => checkComponent(id, root, { vocabulary }));
+
+  const pageFindings = applySeverity([...migration.findings, ...pages.findings], PAGE_RULES, {}, config, { exclude: true });
+  const componentFindings = applySeverity(components.flatMap((r) => r.findings), COMPONENT_RULES, {}, config);
+  const page = countBySeverity(pageFindings);
+  const component = countBySeverity(componentFindings);
+
+  return {
+    errors: page.errors + component.errors,
+    warnings: page.warnings + component.warnings,
+    report: [
+      formatFindings(pageFindings, { label: 'check-page', checked: pages.checked }),
+      formatFindings(componentFindings, { label: 'check-component', checked: ids.length }),
+    ].join('\n'),
+  };
+}

package/bin/migrate-build-script.mjs

@@ -0,0 +1,66 @@
+// `live-tokens migrate` build-script pass.
+//
+// Through 0.79 the project template, and the check-compliance skill for an
+// existing project, ran both checkers as `npm run check:design` ahead of
+// `vite build`. themeFileApi now runs them during `vite build` itself, so the
+// script only repeats the work. This pass removes it when package.json holds
+// exactly what the template and the skill wrote and the build still gets the
+// checks from the plugin. Anything else is reported and left alone.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SCRIPT = 'check:design';
+const SHIPPED_SCRIPT = /^(npx )?live-tokens check-page --no-fix && (npx )?live-tokens check-component --no-fix$/;
+const BUILD_PREFIX = /^npm run check:design\s*&&\s*/;
+const VITE_CONFIGS = ['vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'vite.config.mts'];
+
+function viteConfigText(root) {
+  const file = VITE_CONFIGS.map((name) => join(root, name)).find((p) => existsSync(p));
+  return file ? readFileSync(file, 'utf8') : '';
+}
+
+export function runMigrateBuildScript({ root = process.cwd(), apply = true } = {}) {
+  const file = join(root, 'package.json');
+  if (!existsSync(file)) return { status: 'unchanged' };
+  const text = readFileSync(file, 'utf8');
+  let pkg;
+  try {
+    pkg = JSON.parse(text);
+  } catch {
+    return { status: 'unchanged' };
+  }
+  const scripts = pkg.scripts ?? {};
+  if (!(SCRIPT in scripts)) return { status: 'unchanged' };
+
+  const vite = viteConfigText(root);
+  if (!vite.includes('themeFileApi')) {
+    return { status: 'advisory', reason: `keeps "${SCRIPT}": the Vite config does not use themeFileApi, so the build has no other design checks.` };
+  }
+  if (/checks\s*:\s*false/.test(vite)) {
+    return { status: 'advisory', reason: `keeps "${SCRIPT}": themeFileApi is set to checks: false.` };
+  }
+  if (!SHIPPED_SCRIPT.test(String(scripts[SCRIPT]).trim())) {
+    return { status: 'advisory', reason: `keeps "${SCRIPT}": it differs from the script live-tokens added. vite build now runs the design checks, so remove it by hand if it only repeats them.` };
+  }
+  const build = String(scripts.build ?? '');
+  const users = Object.keys(scripts).filter((name) => name !== SCRIPT && name !== 'build' && String(scripts[name]).includes(SCRIPT));
+  if (build.includes(SCRIPT) && !BUILD_PREFIX.test(build)) users.push('build');
+  if (users.length > 0) {
+    return { status: 'advisory', reason: `keeps "${SCRIPT}": ${users.map((u) => `"${u}"`).join(', ')} still run${users.length === 1 ? 's' : ''} it.` };
+  }
+
+  if (!apply) return { status: 'would-change' };
+  if (BUILD_PREFIX.test(build)) scripts.build = build.replace(BUILD_PREFIX, '');
+  delete scripts[SCRIPT];
+  const indent = /^([ \t]+)"/m.exec(text)?.[1] ?? '  ';
+  writeFileSync(file, JSON.stringify(pkg, null, indent) + (text.endsWith('\n') ? '\n' : ''));
+  return { status: 'changed' };
+}
+
+export function formatBuildScriptResult(result) {
+  if (result.status === 'changed') return `✓ package.json: removed "${SCRIPT}" from the build. vite build runs the design checks through themeFileApi.`;
+  if (result.status === 'would-change') return `package.json: would remove "${SCRIPT}" from the build. vite build runs the design checks through themeFileApi.`;
+  if (result.status === 'advisory') return `! package.json ${result.reason}`;
+  return '';
+}

package/bin/migrate.mjs

@@ -37,6 +37,11 @@ async function loadEngine() {
   return import(ENGINE);
 }
 
+/** Null only before build:plugin, which is this repo's own `npm test` in CI; a published package always ships the engine. */
+export async function loadBuiltEngine() {
+  return existsSync(ENGINE) ? import(ENGINE) : null;
+}
+
 /** --tokens <path> > live-tokens.config.json tokensCssPath > default scan. */
 export function resolveTokensCssPath(explicit, configPath, root = process.cwd()) {
   if (explicit) return resolve(root, explicit);

package/bin/rules/tokens.mjs

@@ -1,9 +1,11 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { relative } from 'node:path';
+import { loadBuiltEngine, resolveTokensCssPath } from '../migrate.mjs';
 import { scaleTokens } from '../lib/catalogue.mjs';
 import { COLOR_SCALES, GEOMETRY_SCALES, STATE_TOKENS, readKindRules, tokenScale, unreadTokens } from '../lib/componentSource.mjs';
 import { colorScaleOfProperty, hasColorLiteral, hasDimensionLiteral, stripVarFallbacks } from '../lib/cssValues.mjs';
 import { readComponentConfig } from '../lib/dataDir.mjs';
-import { findJsonKeyLine } from '../lib/findings.mjs';
+import { findJsonKeyLine, isExcluded } from '../lib/findings.mjs';
 import { geometryScaleOfProperty, resolveGeometryLiteral } from '../lib/geometry.mjs';
 import { declarationPatch, declarations, neutralise, pageDeclaredNames } from '../lib/pageSource.mjs';
 import { isContractToken } from '../lib/tokenVocabulary.mjs';
@@ -35,6 +37,18 @@ const COMPONENT_DEFAULT = 'In a component, make the :global(:root) default read
 const INTRINSIC = "Declare a structural keyword, such as start, in the editor's `intrinsics`.";
 
 const shared = {
+  'tokens-migration': {
+    severity: 'error',
+    repair: 'auto',
+    guidance:
+      'A run without --no-fix applies these migrations to tokens.css. Each one adds design tokens the installed package reads and changes no existing token. `details.migrations` names them.',
+  },
+  'tokens-breaking-migration': {
+    severity: 'error',
+    repair: 'choice',
+    guidance:
+      'Each migration in `details.migrations` renames, removes, or rewrites design tokens in tokens.css. Read the plan with `npx live-tokens migrate --check`, apply it with `npx live-tokens migrate`, and move any page or component that reads an old name to the new one. To keep tokens.css as it is, record the `exception`.',
+  },
   'color-literal': {
     severity: 'error',
     repair: 'choice',
@@ -361,3 +375,52 @@ function checkDeclaration(decl, { text, region, vocab, at }, add) {
     );
   }
 }
+
+/**
+ * Runs before either checker reads the vocabulary, so a tokens.css behind the
+ * installed package never surfaces as unknown tokens. `engine` is a test seam.
+ */
+export async function checkTokensCssMigrations({ root = process.cwd(), apply, engine } = {}) {
+  const result = { applied: [], findings: [] };
+  const loaded = engine ?? (await loadBuiltEngine());
+  if (!loaded) return result;
+  const { TOKENS_CSS_MIGRATIONS, readLiveTokensConfig, runAdditiveTokensCssMigrations, runTokensCssMigrations } = loaded;
+  const tokensPath = resolveTokensCssPath(null, readLiveTokensConfig().tokensCssPath, root);
+  if (!tokensPath || !existsSync(tokensPath)) return result;
+  const file = relative(root, tokensPath);
+  if (isExcluded(file, root)) return result;
+
+  const migration = (id) => TOKENS_CSS_MIGRATIONS.find((m) => m.id === id);
+  const listed = (ids) => ids.map((id) => ({ id, description: migration(id).description }));
+
+  let css = readFileSync(tokensPath, 'utf8');
+  const additive = runAdditiveTokensCssMigrations(css);
+  if (additive.changed) {
+    const finding = {
+      rule: 'tokens-migration',
+      file,
+      line: 1,
+      message: `${file} lacks design tokens the installed package reads: ${additive.applied.join(', ')}`,
+      details: { migrations: listed(additive.applied) },
+    };
+    if (apply) {
+      writeFileSync(tokensPath, additive.css);
+      css = additive.css;
+      result.applied.push(finding);
+    } else {
+      result.findings.push(finding);
+    }
+  }
+
+  const breaking = runTokensCssMigrations(css).applied.filter((id) => migration(id).kind === 'breaking');
+  if (breaking.length > 0) {
+    result.findings.push({
+      rule: 'tokens-breaking-migration',
+      file,
+      line: 1,
+      message: `${file} has breaking migrations pending: ${breaking.join(', ')}`,
+      details: { migrations: listed(breaking) },
+    });
+  }
+  return result;
+}

package/dist-plugin/index.cjs

@@ -3925,12 +3925,35 @@ function validateTokensCss(input) {
   return missing.sort((a, b) => a.token.localeCompare(b.token));
 }
 
-// vite-plugin/themeFileApi.ts
+// vite-plugin/buildChecks.ts
+var import_node_path = __toESM(require("path"), 1);
 var import_node_url = require("url");
 var import_meta = {};
+var runPackageChecks = async (root) => {
+  const runner = import_node_path.default.resolve(import_node_path.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url)), "..", "bin", "lib", "buildChecks.mjs");
+  const { runBuildChecks } = await import((0, import_node_url.pathToFileURL)(runner).href);
+  return runBuildChecks({ root });
+};
+async function checkBeforeBuild({
+  root,
+  logger,
+  run = runPackageChecks
+}) {
+  const result = await run(root);
+  if (result.errors > 0) {
+    logger.error(result.report);
+    return `live-tokens: the design checks found ${result.errors} error(s). Run the live-tokens-check-compliance skill, or \`npx live-tokens check-page\` and \`npx live-tokens check-component\`, to repair them.`;
+  }
+  (result.warnings > 0 ? logger.warn : logger.info).call(logger, result.report);
+  return null;
+}
+
+// vite-plugin/themeFileApi.ts
+var import_node_url2 = require("url");
+var import_meta2 = {};
 var PKG_VERSION = (() => {
   try {
-    let dir = import_path5.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url));
+    let dir = import_path5.default.dirname((0, import_node_url2.fileURLToPath)(import_meta2.url));
     for (let i = 0; i < 4; i++) {
       const p = import_path5.default.join(dir, "package.json");
       if (import_fs5.default.existsSync(p)) {
@@ -3988,14 +4011,14 @@ function themeFileApi(opts) {
   const API_BASE = opts.apiBase ?? "/api/live-tokens";
   const consumerComponentDirs = opts.componentsSrcDir ? [import_path5.default.resolve(opts.componentsSrcDir)] : [import_path5.default.resolve("src/components"), import_path5.default.resolve("src/system/components")];
   const packageComponentsDir = import_path5.default.resolve(
-    import_path5.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url)),
+    import_path5.default.dirname((0, import_node_url2.fileURLToPath)(import_meta2.url)),
     "..",
     "src",
     "system",
     "components"
   );
   const packageDataDir = testPackageDataDir() ?? import_path5.default.resolve(
-    import_path5.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url)),
+    import_path5.default.dirname((0, import_node_url2.fileURLToPath)(import_meta2.url)),
     "..",
     "src",
     "live-tokens",
@@ -5347,6 +5370,8 @@ data: ${JSON.stringify(state)}
     { method: "DELETE", pattern: PRODUCTION_ROUTE, handler: methodNotAllowed }
   ];
   const isEditorOwnedJson = (file) => file.endsWith(".json") && import_path5.default.resolve(file).startsWith(dataDirs.dataDir + import_path5.default.sep);
+  let buildLogger = null;
+  let buildChecked = false;
   return {
     name: "theme-file-api",
     config() {
@@ -5359,6 +5384,15 @@ data: ${JSON.stringify(state)}
         server: { watch: { ignored: [isEditorOwnedJson] } }
       };
     },
+    configResolved(config) {
+      buildLogger = config.command === "build" && opts.checks !== false ? config.logger : null;
+    },
+    async buildStart() {
+      if (!buildLogger || buildChecked) return;
+      buildChecked = true;
+      const failure = await checkBeforeBuild({ root: process.cwd(), logger: buildLogger });
+      if (failure) this.error(failure);
+    },
     configureServer(server) {
       legacyLayout = detectLegacyLayout({
         dataDir: dataDirs.dataDir,

package/dist-plugin/index.d.cts

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

package/dist-plugin/index.d.ts

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