@motion-proto/live-tokens 0.73.0 → 0.75.0

package/bin/check-page.mjs

@@ -1,7 +1,7 @@
 // Static validator for a live-tokens page.
 //
 // Asserts that a page satisfies the contract described in the
-// live-tokens-build-page skill: it is assembled from catalogue components, and
+// live-tokens-create-page skill: it is assembled from catalogue components, and
 // every value in its CSS is a theme token rather than a literal. The rules and
 // their default severities are in PAGE_RULES; each is overridable per project
 // (live-tokens.config.json) or per run (--off/--warn/--error/--strict), because
@@ -26,10 +26,13 @@ export const PAGE_RULES = {
   'color-literal': 'error',
   'reserved-route': 'error',
   'site-css-in-main': 'error',
+  'raw-text-axis': 'error',
   'dimension-literal': 'warn',
   'hardcoded-columns': 'warn',
-  'raw-text-axis': 'warn',
   'missing-source': 'warn',
+  'control-size': 'warn',
+  'multiple-primary': 'warn',
+  'danger-without-dialog': 'warn',
 };
 
 // Directories that hold the system, not pages built on it.
@@ -45,10 +48,17 @@ const DEEP_IMPORT_PATTERNS = [
 
 const TEXT_AXES = ['font-size', 'font-family', 'font-weight', 'line-height', 'letter-spacing'];
 
+// The single-axis scales in tokens.css. A text style bundle carries its axis
+// as a suffix (--body-md-font-size, --code-font-family), so no bundle name
+// matches, and neither does a custom property the page declares itself. A
+// weight alone cannot move the scale or the fonts, so --font-weight-* is not one.
+const SINGLE_AXIS_TOKEN =
+  /^--(?:font-size|line-height|letter-spacing)-|^--font-(?:sans|serif|mono|display|editorial)$/;
+
 // The geometry the theme owns: spacing, stroke, radius, and shadow all have a
-// token scale, and `adjust` moves them. Sizing (a hero's height, a column's
-// minimum width, a max content width) is layout, has no scale, and stays
-// literal.
+// token scale, and `set-geometry` moves them. Sizing (a hero's height, a
+// column's minimum width, a max content width) is layout, has no scale, and
+// stays literal.
 const THEMED_GEOMETRY = /^(padding|margin|gap|row-gap|column-gap|border|outline|inset|top|right|bottom|left|box-shadow|text-shadow)(-|$)|-radius$/;
 
 // A local two-up or three-up is a layout. From four columns on, a hardcoded
@@ -184,7 +194,10 @@ function tagAttributes(code, start) {
   return { attrs, end: tagEnd };
 }
 
-/** Props a page passes that the component does not declare, or values outside a prop's union. */
+/**
+ * Props a page passes that the component does not declare, values outside a
+ * prop's union, and a shipped component the page sizes itself.
+ */
 function checkComponentUsage(code, imports, add) {
   for (const [local, entry] of imports) {
     const props = entry.props;
@@ -203,11 +216,64 @@ function checkComponentUsage(code, imports, add) {
         if (allowed && value !== null && !allowed.has(value)) {
           add('unknown-prop-value', index, `${entry.name} ${name}="${value}" is not one of ${[...allowed].join(', ')}`);
         }
+        if (name === 'size' && entry.origin === 'shipped') {
+          add(
+            'control-size',
+            index,
+            `${entry.name} ${value === null ? 'is sized here' : `size="${value}"`}. Drop it for the shipped default, or retune ${entry.name} for the whole project in /live-tokens/components.`,
+          );
+        }
       }
     }
   }
 }
 
+/**
+ * One finding when a page holds more than one primary Button, at the second of
+ * them. Emphasis is what the variant carries, so a second primary leaves the
+ * page with no single most important action. A Button with no variant is
+ * primary, the component's default.
+ */
+function checkPrimaryActions(code, imports, add) {
+  const primaries = [];
+  for (const [local, entry] of imports) {
+    if (entry.id !== 'button') continue;
+    for (const m of code.matchAll(new RegExp(`<${local}(?=[\\s/>])`, 'g'))) {
+      const tag = tagAttributes(code, m.index);
+      const variant = tag?.attrs.find((a) => a.name === 'variant');
+      if (tag && (variant === undefined || variant.value === 'primary')) primaries.push(m.index);
+    }
+  }
+  if (primaries.length < 2) return;
+  primaries.sort((a, b) => a - b);
+  add(
+    'multiple-primary',
+    primaries[1],
+    `${primaries.length} primary Buttons in this page. Keep the most important action primary and make the other ${primaries.length - 1} secondary.`,
+  );
+}
+
+/**
+ * One finding when a page holds a danger Button and imports no Dialog. A
+ * danger action destroys saved work, and the page has nothing to confirm it.
+ */
+function checkDestructiveActions(code, imports, add) {
+  if ([...imports.values()].some((entry) => entry.id === 'dialog')) return;
+  for (const [local, entry] of imports) {
+    if (entry.id !== 'button' && entry.id !== 'iconbutton') continue;
+    for (const m of code.matchAll(new RegExp(`<${local}(?=[\\s/>])`, 'g'))) {
+      const tag = tagAttributes(code, m.index);
+      if (!tag?.attrs.some((a) => a.name === 'variant' && a.value === 'danger')) continue;
+      add(
+        'danger-without-dialog',
+        m.index,
+        `${entry.name} variant="danger" with no Dialog in this page. A destructive action confirms in a Dialog before it runs.`,
+      );
+      return;
+    }
+  }
+}
+
 /** The object literal enclosing `index`, found by balancing braces outward. */
 function enclosingObject(text, index) {
   let depth = 0;
@@ -267,6 +333,8 @@ function checkFile(file, text, vocab, root) {
       if (local) imports.set(local, entry);
     }
     checkComponentUsage(code, imports, add);
+    checkPrimaryActions(code, imports, add);
+    checkDestructiveActions(code, imports, add);
 
     for (const m of code.matchAll(/['"](\/live-tokens[^'"]*)['"]\s*:/g)) {
       add('reserved-route', m.index, `route '${m[1]}' is inside the reserved /live-tokens/* namespace`);
@@ -315,8 +383,8 @@ function checkFile(file, text, vocab, root) {
         'unknown-token',
         at(m.index),
         isContractToken(name)
-          ? `${name} looks like a theme token but no longer exists; check tokens.css for a rename`
-          : `${name} is not a theme token, a component token, or declared in this file`,
+          ? `${name} has the shape of a design token but no longer exists. Check tokens.css for a rename`
+          : `${name} is not a design token, a semantic property, or declared in this file`,
       );
     }
 
@@ -328,25 +396,38 @@ function checkFile(file, text, vocab, root) {
       // inside one is not the page's value.
       const painted = stripVarFallbacks(value);
       if (!TEXT_AXES.includes(prop) && hasColorLiteral(painted)) {
-        add('color-literal', at(index), `${prop}: ${value}. Use a theme token, not a colour literal.`);
+        add('color-literal', at(index), `${prop}: ${value}. Use a design token.`);
         continue;
       }
 
-      // Only absolute type values are a finding. `em`, `%`, and a unitless
-      // line-height are relative to the inherited type, so they ride whatever
-      // the theme sets rather than overriding it.
-      if (
-        (TEXT_AXES.includes(prop) || prop === 'font') &&
-        !value.includes('var(') &&
-        !/^(inherit|initial|unset|normal)$/.test(value) &&
-        /\d(px|rem|pt)\b|^[a-z"']/i.test(value)
-      ) {
-        add(
-          'raw-text-axis',
-          at(index),
-          `${prop}: ${value}. Set type from a text style bundle (--heading-*, --body-*, --editorial-*).`,
-        );
-        continue;
+      if (TEXT_AXES.includes(prop) || prop === 'font') {
+        const axis = [...painted.matchAll(/var\(\s*(--[a-z0-9-]+)/g)]
+          .map((m) => m[1])
+          .find((name) => SINGLE_AXIS_TOKEN.test(name));
+        if (axis) {
+          add(
+            'raw-text-axis',
+            at(index),
+            `${prop}: ${value}. ${axis} is one axis. Set every axis from one text style bundle (--heading-*, --body-*, --editorial-*, --code-*).`,
+          );
+          continue;
+        }
+
+        // Of the literals only absolute type values are a finding. `em`, `%`,
+        // and a unitless line-height are relative to the inherited type, so
+        // they ride whatever the theme sets rather than overriding it.
+        if (
+          !value.includes('var(') &&
+          !/^(inherit|initial|unset|normal)$/.test(value) &&
+          /\d(px|rem|pt)\b|^[a-z"']/i.test(value)
+        ) {
+          add(
+            'raw-text-axis',
+            at(index),
+            `${prop}: ${value}. Set type from a text style bundle (--heading-*, --body-*, --editorial-*, --code-*).`,
+          );
+          continue;
+        }
       }
 
       if (THEMED_GEOMETRY.test(prop) && hasDimensionLiteral(painted)) {

package/bin/cli.mjs

@@ -4,25 +4,27 @@
 //   create <dir>             Scaffold a new app that depends on this package.
 //   setup-claude [--force]   Copy bundled Claude Code skills into ./.claude/skills/.
 //   components [id]          List every component the project has, shipped and its own, with props and tokens.
-//   tokens [--family <name>] List every theme token by family, with its value.
+//   tokens [--scale <name>]  List every design token by scale, with its value.
 //   report                   The project as facts: tokens read, components used, findings by rule. Always exits 0.
 //   check-component [id]     Validate a component (or every authored one) against the create-component skill contract.
-//   check-page [paths...]    Validate pages against the build-page skill contract.
-//   generate-theme <brief>   Build a theme from a 10-seed OKLCH brief and open it.
-//   adjust <ops.json>        Apply radius/padding/gap/border-width ops to the open buffer.
-//   set-fonts <brief.json>   Bind Google Fonts families to the theme's font stacks.
+//   check-page [paths...]    Validate pages against the create-page skill contract.
+//   set-colors <colors>      Build the color identity from 10 OKLCH base colors, into the open buffer.
+//   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.
 
 import { cpSync, existsSync, mkdirSync, readdirSync, statSync, writeSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
-import { COMPONENT_RULES, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
+import { COMPONENT_RULES, COMPONENT_RULE_FIX, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
 import { PAGE_RULES, checkPages, discoverPages } from './check-page.mjs';
 import { describeComponents, describeTokens, formatComponents, formatTokens } from './lib/catalogue.mjs';
 import { buildReport, formatReport as formatProjectReport } from './lib/report.mjs';
 import { loadVocabulary } from './lib/tokenVocabulary.mjs';
 import {
+  applyCoverageSeverity,
   applySeverity,
   countBySeverity,
   formatFindings,
@@ -38,38 +40,45 @@ import {
 } from './migrate.mjs';
 import { runMigrateRoutes, formatRouteResult } from './migrate-routes.mjs';
 import { runCreate, formatCreateResult } from './create.mjs';
-import { runGenerateTheme, formatGenerateThemeResult } from './generate-theme.mjs';
-import { runAdjust, formatAdjustResult } from './adjust.mjs';
-import { runSetFonts, formatSetFontsResult } from './set-fonts.mjs';
+import { runSetColors, formatSetColorsResult } from './set-colors.mjs';
+import { runSetGeometry, formatSetGeometryResult } from './set-geometry.mjs';
+import { runSetType, formatSetTypeResult } from './set-type.mjs';
+import { runSaveTheme, formatSaveThemeResult } from './save-theme.mjs';
 
 const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
 
 Commands:
   create <dir> [--force]      Scaffold a new Svelte + Vite app wired up with
-                              live-tokens (editor, components, theme tokens)
+                              live-tokens (editor, components, design tokens)
   setup-claude [--force]      Install bundled Claude Code skills into ./.claude/skills/
   components [id] [--json]    List every component the project has, shipped and
                               its own (src/system/components plus any
-                              "componentDirs" in live-tokens.config.json), with
-                              the props each takes; with an id, that component's
-                              props, variants, tokens, and defaults
-  tokens [--family <name>] [--json]
-                              List every theme token the project's tokens.css
-                              declares, by family, with its value
+                              "componentDirs" in live-tokens.config.json). With
+                              an id, that component's props, variants, tokens,
+                              and defaults
+  tokens [--scale <name>] [--json]
+                              List every design token the project's tokens.css
+                              declares, by scale, with its value
   report [--json]             The project as facts: pending migrations, 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. A reading, not a gate: always
-                              exits 0
-  check-component [id]        Validate <id>'s runtime, editor, and registration
-                              against the live-tokens-create-component contract
-  check-page [paths...]       Validate pages against the live-tokens-build-page
+                              and under --strict. Always exits 0
+  check-component [id] [--tests]
+                              Validate <id>'s runtime, editor, and registration
+                              against the live-tokens-create-component contract.
+                              --tests also runs the registry contract under
+                              vitest and the component contract suites under
+                              Playwright, reporting coverage by rule. Needs
+                              @playwright/test, vitest, and happy-dom; a
+                              missing one is a tests-not-installed finding
+                              naming the install command
+  check-page [paths...]       Validate pages against the live-tokens-create-page
                               contract: catalogue components only, and every CSS
-                              value a theme token. Checks every page under src/
+                              value a design token. Checks every page under src/
                               when given no paths.
 
-Both check commands accept:
+check-component and check-page also accept:
   --json                      Machine-readable findings, for a skill to iterate
                               against until the exit code is 0
   --strict                    Treat warnings as errors
@@ -77,40 +86,47 @@ Both check commands accept:
                               (or set "checks": { "rules": {...} } in
                               live-tokens.config.json; "checks": { "exclude":
                               [...] } drops paths from discovery entirely)
-  generate-theme <brief.json> [--no-activate] [--dry-run] [--carry-from <name>]
-                              Build a full theme from a 10-seed OKLCH brief
-                              (see the live-tokens-generate-theme skill),
-                              enforce AA contrast on derived text tokens, write
-                              themes/<slug>.json, and open it in the editor.
-                              Opening never changes what your site ships; Adopt
-                              in the editor does that.
-                              --no-activate writes the theme without opening it;
-                              --dry-run prints the contrast report without
-                              writing. Non-color content (gradients, fonts,
-                              component aliases) carries forward from the live
-                              look, or from theme <name> with --carry-from.
-  adjust <ops.json> [--dry-run]
+  set-colors <base-colors.json> [--dry-run]
+                              Build the theme's whole color identity from 10
+                              OKLCH base colors (see the live-tokens-set-colors
+                              skill) and enforce AA contrast on the derived text
+                              tokens. Reads the live colors and type and writes
+                              the result to the colors-and-type buffer. Run
+                              save-theme to keep it as a theme. Fonts and every
+                              override no palette owns carry forward. --dry-run
+                              prints the contrast report without writing.
+  set-geometry <ops.json> [--dry-run]
                               Move radius, padding, gap, and border-width
                               aliases along their token scales (see the
-                              live-tokens-adjust-geometry skill). Reads each
+                              live-tokens-set-geometry skill). Reads each
                               component's live config and writes the result to
-                              that component's unsaved buffer, so save the open
-                              theme in the editor to keep it. --dry-run prints
-                              the report without writing.
-  set-fonts <brief.json> [--dry-run] [--no-verify]
+                              that component's buffer. Run save-theme to keep it
+                              as a theme. --dry-run prints the report without
+                              writing.
+  set-type <pairing.json> [--dry-run] [--no-verify]
                               Bind Google Fonts families to --font-display,
                               --font-sans, --font-serif, --font-mono and
                               --font-editorial (see
-                              the live-tokens-pair-fonts skill). Each family is
+                              the live-tokens-set-type skill). Each family is
                               verified against the Google Fonts API and the URL
-                              is negotiated from the weights it actually has.
-                              Writes the result to the unsaved colors-and-type
-                              buffer, so save the open theme in the editor to
-                              keep it. --dry-run prints the report without
-                              writing; --no-verify skips the network and
-                              requires an explicit URL per family.
+                              is negotiated from the weights it has. Writes the
+                              result to the colors-and-type buffer. Run
+                              save-theme to keep it as a theme. --dry-run prints
+                              the report without writing. --no-verify skips the
+                              network and requires an explicit URL per family.
+  save-theme <name> [--no-activate] [--dry-run]
+                              Compose the live state (the buffers, the open
+                              theme under them, the shipped defaults under that)
+                              into themes/<slug>.json and load it, which clears
+                              the buffers. With no buffer it saves a copy of the
+                              open theme under the new name. Loading never
+                              changes what the site ships. Adopt in the editor
+                              does that. --no-activate writes the theme and does
+                              not load it, so a set of themes comes off one
+                              starting theme. --dry-run prints the report
+                              without writing.
   migrate [--check] [--write] [--tokens <path>]
-                              Reconcile your project with the installed package:
+                              Reconcile the project with the installed package:
                               applies additive tokens.css migrations, moves a
                               pre-0.48 data tree onto the current directory
                               names, heals what the retired pointer files named,
@@ -150,7 +166,7 @@ if (!command || command === '--help' || command === '-h') {
 
 const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-if (command === 'create' || command === 'init') {
+if (command === 'create') {
   const targetArg = rest.find((a) => !a.startsWith('-'));
   if (!targetArg) {
     fail(`Usage: npx @motion-proto/live-tokens create <project-directory>`);
@@ -166,14 +182,19 @@ if (command === 'create' || command === 'init') {
   }
 }
 
-function reportChecks(label, findings, checked, rules, opts) {
-  const resolved = applySeverity(findings, rules, opts, readChecksConfig(process.cwd()));
+function reportChecks(label, findings, checked, rules, opts, { coverage, hardFailure, fixes } = {}) {
+  const checksConfig = readChecksConfig(process.cwd());
+  const resolved = applySeverity(findings, rules, opts, checksConfig, fixes ?? {});
+  const resolvedCoverage = coverage ? applyCoverageSeverity(coverage, rules, opts, checksConfig) : coverage;
   console.log(
     opts.json
-      ? toJson(resolved, { label, checked })
+      ? toJson(resolved, { label, checked, coverage: resolvedCoverage })
       : formatFindings(resolved, { label, checked }),
   );
-  process.exit(countBySeverity(resolved).errors === 0 ? 0 : 1);
+  // Decision 2: a missing tool or a setup failure under --tests is an error
+  // even if a project silenced its rule id, since silencing it would read as
+  // "the tests passed" rather than "the tests did not run".
+  process.exit(countBySeverity(resolved).errors === 0 && !hardFailure ? 0 : 1);
 }
 
 if (command === 'components') {
@@ -187,14 +208,14 @@ if (command === 'components') {
 
 if (command === 'tokens') {
   const opts = parseCheckFlags(rest);
-  const at = opts.rest.indexOf('--family');
-  const family = at >= 0 ? opts.rest[at + 1] : undefined;
+  const at = opts.rest.indexOf('--scale');
+  const scale = at >= 0 ? opts.rest[at + 1] : undefined;
   const desc = describeTokens(loadVocabulary());
-  if (family && !desc.families.some((f) => f.family === family)) fail(formatTokens(desc, { family }));
+  if (scale && !desc.scales.some((s) => s.scale === scale)) fail(formatTokens(desc, { scale }));
   writeOut(
     opts.json
-      ? JSON.stringify(family ? desc.families.find((f) => f.family === family) : desc, null, 2)
-      : formatTokens(desc, { family }),
+      ? JSON.stringify(scale ? desc.scales.find((s) => s.scale === scale) : desc, null, 2)
+      : formatTokens(desc, { scale }),
   );
   process.exit(0);
 }
@@ -220,18 +241,28 @@ if (command === 'report') {
 if (command === 'check-component') {
   const opts = parseCheckFlags(rest);
   const ids = opts.rest.length > 0 ? [opts.rest[0]] : discoverComponents();
-  if (ids.length === 0) {
+  if (ids.length === 0 && !opts.tests) {
     console.log('✓ check-component: no component authored under src/system/components yet.');
     process.exit(0);
   }
   const results = ids.map((id) => [id, checkComponent(id)]);
-  if (ids.length === 1 && !opts.json && !opts.strict && opts.off.length + opts.warn.length + opts.error.length === 0) {
+  if (!opts.tests && ids.length === 1 && !opts.json && !opts.strict && opts.off.length + opts.warn.length + opts.error.length === 0) {
     const [id, result] = results[0];
     console.log(formatReport(id, result));
     process.exit(result.errors.length === 0 ? 0 : 1);
   }
-  const label = ids.length === 1 ? `check-component ${ids[0]}` : 'check-component';
-  reportChecks(label, results.flatMap(([, r]) => r.findings), ids.length, COMPONENT_RULES, opts);
+  const label = ids.length === 1 ? `check-component ${ids[0]}${opts.tests ? ' --tests' : ''}` : `check-component${opts.tests ? ' --tests' : ''}`;
+  if (!opts.tests) {
+    reportChecks(label, results.flatMap(([, r]) => r.findings), ids.length, COMPONENT_RULES, opts, { fixes: COMPONENT_RULE_FIX });
+  }
+  const { hasHardFailure, runContractTests } = await import('./contractRunner.mjs');
+  const testOutcome = await runContractTests(opts.rest[0], { root: process.cwd() });
+  const findings = [...results.flatMap(([, r]) => r.findings), ...testOutcome.findings];
+  reportChecks(label, findings, Math.max(ids.length, 1), COMPONENT_RULES, opts, {
+    fixes: COMPONENT_RULE_FIX,
+    coverage: testOutcome.coverage,
+    hardFailure: hasHardFailure(testOutcome.findings),
+  });
 }
 
 if (command === 'check-page') {
@@ -241,72 +272,97 @@ if (command === 'check-page') {
   reportChecks('check-page', findings, checked, PAGE_RULES, opts);
 }
 
-if (command === 'generate-theme') {
-  const briefPath = rest.find((a) => !a.startsWith('-'));
-  if (!briefPath) {
-    fail(`Usage: npx @motion-proto/live-tokens generate-theme <brief.json> [--no-activate] [--dry-run]`);
+if (command === 'set-colors') {
+  const baseColorsPath = rest.find((a) => !a.startsWith('-'));
+  if (!baseColorsPath) {
+    fail(`Usage: npx @motion-proto/live-tokens set-colors <base-colors.json> [--dry-run]`);
+  }
+  if (rest.includes('--no-activate')) {
+    fail(
+      `set-colors has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
+        `Nothing is activated until save-theme, which takes the flag.`,
+    );
+  }
+  if (rest.includes('--carry-from')) {
+    fail(
+      `set-colors has no --carry-from: it reads the live theme and edits it in place, so a second theme ` +
+        `already starts from the first. Run save-theme --no-activate between themes.`,
+    );
   }
   try {
-    const carryIdx = rest.indexOf('--carry-from');
-    const carryFrom = carryIdx !== -1 ? rest[carryIdx + 1] : undefined;
-    if (carryIdx !== -1 && !carryFrom) fail(`--carry-from requires a theme name`);
-    const result = await runGenerateTheme({
-      briefPath,
-      activate: !rest.includes('--no-activate'),
+    const result = await runSetColors({
+      baseColorsPath,
       dryRun: rest.includes('--dry-run'),
-      carryFrom,
     });
-    console.log(formatGenerateThemeResult(result));
+    console.log(formatSetColorsResult(result));
     process.exit(result.report.failures.length === 0 ? 0 : 1);
   } catch (err) {
-    fail(`generate-theme failed: ${err instanceof Error ? err.message : String(err)}`);
+    fail(`set-colors failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
-if (command === 'adjust') {
+if (command === 'set-geometry') {
   const opsPath = rest.find((a) => !a.startsWith('-'));
   if (!opsPath) {
-    fail(`Usage: npx @motion-proto/live-tokens adjust <ops.json> [--dry-run]`);
+    fail(`Usage: npx @motion-proto/live-tokens set-geometry <ops.json> [--dry-run]`);
   }
   if (rest.includes('--no-activate')) {
     fail(
-      `adjust has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
+      `set-geometry has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
         `Drop the flag and re-run.`,
     );
   }
   try {
-    const result = await runAdjust({
+    const result = await runSetGeometry({
       opsPath,
       dryRun: rest.includes('--dry-run'),
     });
-    console.log(formatAdjustResult(result));
+    console.log(formatSetGeometryResult(result));
     process.exit(0);
   } catch (err) {
-    fail(`adjust failed: ${err instanceof Error ? err.message : String(err)}`);
+    fail(`set-geometry failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
-if (command === 'set-fonts') {
-  const briefPath = rest.find((a) => !a.startsWith('-'));
-  if (!briefPath) {
-    fail(`Usage: npx @motion-proto/live-tokens set-fonts <brief.json> [--dry-run] [--no-verify]`);
+if (command === 'set-type') {
+  const pairingPath = rest.find((a) => !a.startsWith('-'));
+  if (!pairingPath) {
+    fail(`Usage: npx @motion-proto/live-tokens set-type <pairing.json> [--dry-run] [--no-verify]`);
   }
   if (rest.includes('--no-activate')) {
     fail(
-      `set-fonts has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
+      `set-type has no --no-activate: it edits the open buffer, which is what the page already runs. ` +
         `Drop the flag and re-run.`,
     );
   }
   try {
-    const result = await runSetFonts({
-      briefPath,
+    const result = await runSetType({
+      pairingPath,
       dryRun: rest.includes('--dry-run'),
       verify: !rest.includes('--no-verify'),
     });
-    console.log(formatSetFontsResult(result));
+    console.log(formatSetTypeResult(result));
+    process.exit(0);
+  } catch (err) {
+    fail(`set-type failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+if (command === 'save-theme') {
+  const name = rest.find((a) => !a.startsWith('-'));
+  if (!name) {
+    fail(`Usage: npx @motion-proto/live-tokens save-theme <name> [--no-activate] [--dry-run]`);
+  }
+  try {
+    const result = await runSaveTheme({
+      name,
+      activate: !rest.includes('--no-activate'),
+      dryRun: rest.includes('--dry-run'),
+    });
+    console.log(formatSaveThemeResult(result));
     process.exit(0);
   } catch (err) {
-    fail(`set-fonts failed: ${err instanceof Error ? err.message : String(err)}`);
+    fail(`save-theme failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
@@ -385,15 +441,16 @@ for (const skill of skills) {
   installed++;
 }
 
-console.log(`\n${installed} installed, ${skipped} skipped → ${destSkills}`);
+console.log(`\n${installed} installed, ${skipped} skipped, in ${destSkills}`);
 
 const SAMPLE_PROMPTS = {
-  'live-tokens-build-page': 'build a pricing page using live-tokens components',
+  'live-tokens-create-page': 'build a pricing page using live-tokens components',
   'live-tokens-pick-component': "what's the difference between TabBar and SegmentedControl?",
   'live-tokens-create-component': 'author a new Toggle component for my live-tokens project',
-  'live-tokens-generate-theme': 'make me a bright and cheerful theme',
-  'live-tokens-adjust-geometry': 'make the buttons pill shaped',
-  'live-tokens-pair-fonts': 'pair some fonts for this theme',
+  'live-tokens-create-theme': 'make me a bright and cheerful theme',
+  'live-tokens-set-colors': 'give me a cooler palette, same fonts',
+  'live-tokens-set-type': 'pair some fonts for this theme',
+  'live-tokens-set-geometry': 'make the buttons pill shaped',
   'live-tokens-fix-findings': 'make check:design pass',
   'live-tokens-check-compliance': 'check this project against the design system',
 };
@@ -405,6 +462,6 @@ const installedSamples = skills
 if (installedSamples.length > 0) {
   console.log(`\nIn Claude Code, prompts like these auto-trigger the matching skill:`);
   for (const [skill, prompt] of installedSamples) {
-    console.log(`  • "${prompt}"\n    → ${skill}`);
+    console.log(`  "${prompt}"\n    ${skill}`);
   }
 }