@motion-proto/live-tokens 0.74.0 → 0.76.0

package/bin/create.mjs

@@ -78,7 +78,7 @@ export function runCreate({ targetDir, pkgRoot, force = false }) {
 export function formatCreateResult({ appName, targetDir }, targetArg) {
   return [
     ``,
-    `Scaffolded ${appName} → ${targetDir}`,
+    `Scaffolded ${appName} in ${targetDir}`,
     ``,
     `Next steps:`,
     `  cd ${targetArg}`,

package/bin/lib/catalogue.mjs

@@ -1,28 +1,33 @@
 // The registry as a query. Every component a project has, shipped or its own,
 // with the props each takes and the tokens each declares, and every theme token
-// grouped by family. Read from files through the same vocabulary the checkers
+// grouped by scale. Read from files through the same vocabulary the checkers
 // use, so a skill or a script sees exactly what the checkers will hold it to.
 
 import { readFileSync } from 'node:fs';
 import { relative } from 'node:path';
-import { CONTRACT_FAMILIES } from './tokenVocabulary.mjs';
+import { CONTRACT_SCALES } from './tokenVocabulary.mjs';
 
-/** The runtime file's leading HTML comment, which is where a component says what it is for. */
+/** The runtime file's leading HTML comment, which is where a component says what
+    it is for. A labelled line (`Use for:`, `Not for:`, `Emphasis:`) opens a line
+    of the description and every other line continues the one above it, so the
+    comment wraps in the source and still reads as its four lines here. */
 function descriptionOf(source) {
   const m = source.match(/^\s*<!--([\s\S]*?)-->/);
   if (!m) return '';
-  return m[1]
-    .split('\n')
-    .map((line) => line.trim())
-    .join(' ')
-    .replace(/\s+/g, ' ')
-    .trim()
-    .replace(/^\S+\.svelte\s*[—–-]+\s*/, '');
+  const lines = [];
+  for (const raw of m[1].split('\n')) {
+    const line = raw.trim().replace(/\s+/g, ' ');
+    if (!line) continue;
+    if (lines.length && !/^[A-Z][A-Za-z ]{0,20}:/.test(line)) lines[lines.length - 1] += ` ${line}`;
+    else lines.push(line);
+  }
+  if (lines.length) lines[0] = lines[0].replace(/^\S+\.svelte\s*(?:[—–-]+|\.)\s*/, '');
+  return lines.join('\n');
 }
 
-function familyOf(name) {
+function scaleOf(name) {
   const stem = name.replace(/^--/, '');
-  const hit = CONTRACT_FAMILIES
+  const hit = CONTRACT_SCALES
     .filter((f) => stem === f || stem.startsWith(`${f}-`))
     .sort((a, b) => b.length - a.length)[0];
   return hit ?? stem.split('-')[0];
@@ -62,15 +67,15 @@ export function describeTokens(vocab, { root = process.cwd() } = {}) {
       if (!values.has(m[1])) values.set(m[1], m[2].trim());
     }
   }
-  const byFamily = new Map();
+  const byScale = new Map();
   for (const name of vocab.themeTokens) {
-    const family = familyOf(name);
-    if (!byFamily.has(family)) byFamily.set(family, []);
-    byFamily.get(family).push({ name, value: values.get(name) ?? '' });
+    const scale = scaleOf(name);
+    if (!byScale.has(scale)) byScale.set(scale, []);
+    byScale.get(scale).push({ name, value: values.get(name) ?? '' });
   }
   return {
     tokensCss: vocab.tokensCssPath ? relative(root, vocab.tokensCssPath) : null,
-    families: [...byFamily].map(([family, tokens]) => ({ family, tokens })),
+    scales: [...byScale].map(([scale, tokens]) => ({ scale, tokens })),
     components: [...vocab.components.values()].map((c) => ({
       id: c.id,
       tokens: [...c.tokens].map(([name, value]) => ({ name, default: value })),
@@ -78,13 +83,15 @@ export function describeTokens(vocab, { root = process.cwd() } = {}) {
   };
 }
 
+const describeLines = (c) => (c.description ? c.description.split('\n') : []);
+
 export function formatComponents(list, { id } = {}) {
   const lines = [];
   if (id) {
     const c = list.find((x) => x.id === id);
     if (!c) return `No component "${id}". Run \`live-tokens components\` for the list.`;
-    lines.push(`${c.name} (${c.id}, ${c.origin}${c.registered ? '' : ', NOT registered'})  ${c.file}`);
-    if (c.description) lines.push(`  ${c.description}`);
+    lines.push(`${c.name} (${c.id}, ${c.origin}${c.registered ? '' : ', unregistered'})  ${c.file}`);
+    for (const line of describeLines(c)) lines.push(`  ${line}`);
     if (c.props.length) {
       lines.push('  props:');
       for (const p of c.props) lines.push(`    ${p.name}${p.values ? `: ${p.values.join(' | ')}` : p.type ? `: ${p.type}` : ''}`);
@@ -96,7 +103,7 @@ export function formatComponents(list, { id } = {}) {
   for (const c of list) {
     const variants = c.variants.length ? `  variants: ${c.variants.join(', ')}` : '';
     lines.push(`${c.id.padEnd(20)} ${c.origin.padEnd(8)} ${c.name}${c.registered ? '' : '  (NOT registered)'}${variants}`);
-    if (c.description) lines.push(`${''.padEnd(29)} ${c.description}`);
+    for (const line of describeLines(c)) lines.push(`    ${line}`);
   }
   lines.push('');
   const unregistered = list.filter((c) => !c.registered).length;
@@ -107,21 +114,21 @@ export function formatComponents(list, { id } = {}) {
   return lines.join('\n');
 }
 
-export function formatTokens(desc, { family } = {}) {
+export function formatTokens(desc, { scale } = {}) {
   const lines = [];
-  const families = family ? desc.families.filter((f) => f.family === family) : desc.families;
-  if (family && families.length === 0) {
-    return `No family "${family}". Families: ${desc.families.map((f) => f.family).join(', ')}.`;
+  const scales = scale ? desc.scales.filter((s) => s.scale === scale) : desc.scales;
+  if (scale && scales.length === 0) {
+    return `No token scale "${scale}". Scales: ${desc.scales.map((s) => s.scale).join(', ')}.`;
   }
-  lines.push(`Theme tokens from ${desc.tokensCss ?? '(no tokens.css found)'}`);
-  for (const f of families) {
+  lines.push(`Design tokens from ${desc.tokensCss ?? '(no tokens.css found)'}`);
+  for (const s of scales) {
     lines.push('');
-    lines.push(`${f.family} (${f.tokens.length})`);
-    for (const t of f.tokens) lines.push(`  ${t.name}: ${t.value}`);
+    lines.push(`${s.scale} (${s.tokens.length})`);
+    for (const t of s.tokens) lines.push(`  ${t.name}: ${t.value}`);
   }
-  if (!family) {
+  if (!scale) {
     lines.push('');
-    lines.push(`Component tokens: ${desc.components.reduce((n, c) => n + c.tokens.length, 0)} across ${desc.components.length} component(s). \`live-tokens components <id>\` lists one component's.`);
+    lines.push(`Semantic properties: ${desc.components.reduce((n, c) => n + c.tokens.length, 0)} across ${desc.components.length} component(s). \`live-tokens components <id>\` lists one component's.`);
   }
   return lines.join('\n');
 }

package/bin/lib/findings.mjs

@@ -52,38 +52,65 @@ export function isExcluded(relPath, root) {
  * Unrecognised flags are returned in `rest` for the caller to handle.
  */
 export function parseCheckFlags(argv) {
-  const opts = { off: [], warn: [], error: [], strict: false, json: false, rest: [] };
+  const opts = { off: [], warn: [], error: [], strict: false, json: false, tests: false, rest: [] };
   for (const arg of argv) {
     const m = arg.match(/^--(off|warn|error)=(.+)$/);
     if (m) {
       opts[m[1]].push(...m[2].split(',').map((s) => s.trim()).filter(Boolean));
     } else if (arg === '--strict') opts.strict = true;
     else if (arg === '--json') opts.json = true;
+    else if (arg === '--tests') opts.tests = true;
     else opts.rest.push(arg);
   }
   return opts;
 }
 
+/** The same last-wins resolution `applySeverity` applies per finding, exposed
+ *  standalone so coverage (which has no findings to attach a severity to, but
+ *  still has to honor `--off`) can ask the same question. */
+export function resolveRuleSeverity(ruleId, rules, opts = {}, config = {}) {
+  const configured = config.rules ?? {};
+  let severity = rules[ruleId] ?? 'error';
+  if (SEVERITIES.includes(configured[ruleId])) severity = configured[ruleId];
+  if (opts.off?.includes(ruleId)) severity = 'off';
+  if (opts.warn?.includes(ruleId)) severity = 'warn';
+  if (opts.error?.includes(ruleId)) severity = 'error';
+  if (opts.strict && severity === 'warn') severity = 'error';
+  return severity;
+}
+
 /**
  * Resolve each finding's severity and drop the ones turned off.
  * `rules` maps rule id to its default severity.
  */
-export function applySeverity(findings, rules, opts = {}, config = {}) {
-  const configured = config.rules ?? {};
-  const resolve = (id) => {
-    let severity = rules[id] ?? 'error';
-    if (SEVERITIES.includes(configured[id])) severity = configured[id];
-    if (opts.off?.includes(id)) severity = 'off';
-    if (opts.warn?.includes(id)) severity = 'warn';
-    if (opts.error?.includes(id)) severity = 'error';
-    if (opts.strict && severity === 'warn') severity = 'error';
-    return severity;
-  };
+export function applySeverity(findings, rules, opts = {}, config = {}, fixes = {}) {
   return findings
-    .map((f) => ({ ...f, severity: resolve(f.rule) }))
+    .map((f) => ({
+      ...f,
+      severity: resolveRuleSeverity(f.rule, rules, opts, config),
+      ...(fixes[f.rule] ? { fix: fixes[f.rule] } : {}),
+    }))
     .filter((f) => f.severity !== 'off');
 }
 
+/**
+ * A coverage entry for a rule resolved to severity 'off' becomes 'disabled',
+ * regardless of what actually happened: the plan requires `--off` to stay
+ * visible as disabled coverage rather than silently reading as a pass (an
+ * obligation that failed but was silenced is not the same as one that ran
+ * clean), and disabled coverage can never establish a complete pass.
+ */
+export function applyCoverageSeverity(coverage, rules, opts = {}, config = {}) {
+  const out = {};
+  for (const [id, ruleMap] of Object.entries(coverage)) {
+    out[id] = {};
+    for (const [rule, entry] of Object.entries(ruleMap)) {
+      out[id][rule] = resolveRuleSeverity(rule, rules, opts, config) === 'off' ? { status: 'disabled' } : entry;
+    }
+  }
+  return out;
+}
+
 export function countBySeverity(findings) {
   return {
     errors: findings.filter((f) => f.severity === 'error').length,
@@ -117,7 +144,11 @@ export function formatFindings(findings, { label, checked = 0 } = {}) {
   return lines.join('\n');
 }
 
-export function toJson(findings, { label, checked = 0 } = {}) {
+export function toJson(findings, { label, checked = 0, coverage } = {}) {
   const { errors, warnings } = countBySeverity(findings);
-  return JSON.stringify({ check: label, checked, errors, warnings, findings }, null, 2);
+  return JSON.stringify(
+    { check: label, checked, errors, warnings, findings, ...(coverage ? { coverage } : {}) },
+    null,
+    2,
+  );
 }

package/bin/lib/report.mjs

@@ -120,7 +120,7 @@ const list = (items, max = 20) =>
 
 export function formatReport(r) {
   const out = [];
-  out.push(`Project: ${r.project.pages} page file(s), ${r.project.components} component(s), ${r.project.themeTokens} theme tokens from ${r.project.tokensCss ?? '(no tokens.css)'}`);
+  out.push(`Project: ${r.project.pages} page file(s), ${r.project.components} component(s), ${r.project.themeTokens} design tokens from ${r.project.tokensCss ?? '(no tokens.css)'}`);
   if (r.migrations) {
     out.push('');
     out.push(`Migrations: ${r.migrations.status}${r.migrations.pending?.length ? ` (${list(r.migrations.pending)})` : ''}`);
@@ -131,11 +131,11 @@ export function formatReport(r) {
   const unread = r.components.filter((c) => c.unread.length);
   out.push(`  tokens declared and read by their own CSS: ${r.components.reduce((n, c) => n + c.tokens - c.unread.length, 0)} of ${r.components.reduce((n, c) => n + c.tokens, 0)}`);
   for (const c of unread) out.push(`    ${c.id}: ${c.unread.length} unread (${list(c.unread, 6)})`);
+  const undescribed = r.components.filter((c) => !c.described).map((c) => c.id);
+  if (undescribed.length) out.push(`  no description comment: ${list(undescribed)}`);
   const custom = r.components.filter((c) => c.origin === 'custom');
   out.push(`  custom: ${custom.length}${custom.length ? ` (${list(custom.map((c) => c.id))})` : ''}`);
   if (r.usage.customUnregistered.length) out.push(`    not registered: ${list(r.usage.customUnregistered)}`);
-  const undescribed = custom.filter((c) => !c.described).map((c) => c.id);
-  if (undescribed.length) out.push(`    no description comment: ${list(undescribed)}`);
 
   out.push('');
   out.push('Usage');

package/bin/lib/tokenVocabulary.mjs

@@ -25,18 +25,18 @@ const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
 
 const SHIPPED_COMPONENTS_DIR = 'src/system/components';
 
-/** Families whose names are governed by the token contract (see TOKENS.md). */
-export const CONTRACT_FAMILIES = [
+/** Token scales whose names are governed by the token contract (see TOKENS.md). */
+export const CONTRACT_SCALES = [
   'surface', 'text', 'border', 'color', 'space', 'radius', 'font', 'line-height',
   'letter-spacing', 'shadow', 'blur', 'icon-size', 'scrim', 'tint', 'columns',
   'heading', 'body', 'editorial', 'eyebrow', 'code', 'easing', 'duration', 'zoom',
   'gradient', 'stroke',
 ];
 
-/** True when `name` belongs to a contract-governed family, so a miss is a typo. */
+/** True when `name` belongs to a contract-governed scale, so a miss is a typo. */
 export function isContractToken(name) {
   const stem = name.replace(/^--/, '');
-  return CONTRACT_FAMILIES.some((f) => stem === f || stem.startsWith(`${f}-`));
+  return CONTRACT_SCALES.some((f) => stem === f || stem.startsWith(`${f}-`));
 }
 
 /** Every `--name:` declared anywhere in a stylesheet or style block. */

package/bin/migrate-routes.mjs

@@ -149,8 +149,8 @@ export function formatRouteResult(result, { check = false } = {}) {
   const { rewritten, pendingWrite, advisory } = result;
   if (!rewritten.length && !pendingWrite.length && !advisory.length) return '';
 
-  const ref = (h) => `      ${h.file}:${h.line}  ${h.kind} '${h.old}' → '${h.next}'`;
-  const lines = ['Route references — /editor, /components, /docs moved to /live-tokens/* in 0.35.0:'];
+  const ref = (h) => `      ${h.file}:${h.line}  ${h.kind} '${h.old}' to '${h.next}'`;
+  const lines = ['Route references: /editor, /components, /docs moved to /live-tokens/* in 0.35.0:'];
 
   if (rewritten.length) {
     lines.push(`  ✓ Rewrote ${rewritten.length} reference(s):`);
@@ -160,7 +160,7 @@ export function formatRouteResult(result, { check = false } = {}) {
     lines.push(
       check
         ? `  Would rewrite ${pendingWrite.length} reference(s) with --write:`
-        : `  ${pendingWrite.length} reference(s) can be rewritten — re-run with --write to apply:`,
+        : `  ${pendingWrite.length} reference(s) can be rewritten. Re-run with --write to apply:`,
     );
     pendingWrite.forEach((h) => lines.push(ref(h)));
   }
@@ -169,8 +169,8 @@ export function formatRouteResult(result, { check = false } = {}) {
     advisory.forEach((h) => {
       const why =
         h.reason === 'docs-never'
-          ? `/docs is never auto-rewritten — update to '${h.next}' only if it points at the package guide`
-          : `you declare or relocate '${h.old}' yourself — leave it if it's your route`;
+          ? `/docs is never auto-rewritten. Update to '${h.next}' only when it points at the package guide`
+          : `the project declares or relocates '${h.old}'. Leave it when it is the project's own route`;
       lines.push(`      ${h.file}:${h.line}  ${h.kind} '${h.old}'  (${why})`);
     });
   }

package/bin/migrate.mjs

@@ -127,13 +127,13 @@ export function formatMigrateDataResult(result) {
     // `sketch-presets/` → `sketch-styles/`. Told apart by the destination
     // name, since `LegacyRename` carries no reason of its own.
     const reason = basename(to) === 'sketch-styles' ? 'sketchstyle rename' : '0.48 layout';
-    lines.push(`  ${planned ? 'would move' : 'moved'} ${rel(from)} → ${rel(to)} (${reason})`);
+    lines.push(`  ${planned ? 'would move' : 'moved'} ${rel(from)} to ${rel(to)} (${reason})`);
   }
   for (const p of result.upgradedThemes) {
     lines.push(`  ${planned ? 'would carry' : 'carried'} ${rel(p)} by value (was a pre-v3 theme naming files)`);
   }
   if (result.production) {
-    lines.push(`  production theme → "${result.production.slug}" (${HOW_SAID[result.production.how]})`);
+    lines.push(`  production theme: "${result.production.slug}" (${HOW_SAID[result.production.how]})`);
   }
   if (result.recoveredThemePath) {
     lines.push(`  ${planned ? 'would write' : 'wrote'} ${rel(result.recoveredThemePath)}`);
@@ -148,13 +148,13 @@ export function formatMigrateDataResult(result) {
     lines.push(`  ${planned ? 'would delete' : 'deleted'} ${rel(p)}: a copy of a saved theme`);
   }
   for (const p of result.keptUserFiles) {
-    lines.push(`  kept ${rel(p)}: it matches no theme, so it is yours`);
+    lines.push(`  kept ${rel(p)}: it matches no theme, so it stays`);
   }
   for (const note of result.droppedRefs) {
     lines.push(`  ${note}`);
   }
   for (const p of result.notThemes) {
-    lines.push(`  left ${rel(p)} alone: it is a colors-and-type file, not a theme`);
+    lines.push(`  left ${rel(p)} alone: it is a colors-and-type file`);
   }
   for (const p of result.shadowedDefaults) {
     lines.push(`  kept ${rel(p)}: it shadows the default the package ships, which has moved on`);

package/bin/save-theme.mjs

@@ -142,35 +142,34 @@ export function formatSaveThemeResult(result) {
   const root = process.cwd();
   const lines = [];
   const wrote = result.dryRun ? 'Would write' : result.existed ? 'Updated' : 'Created';
-  lines.push(`${wrote} theme "${result.name}" → ${relative(root, result.themePath)}`);
+  lines.push(`${wrote} theme "${result.name}" at ${relative(root, result.themePath)}`);
   lines.push(`It carries the colors and type and ${result.components} component config(s) by value.`);
 
   const edited = [
     ...(result.buffered.colorsAndType ? ['colors and type'] : []),
     ...result.buffered.components,
   ];
-  const open = result.openTheme ? `the open theme "${result.openTheme}"` : 'the package defaults';
+  const open = result.openTheme ? `the open theme "${result.openTheme}"` : 'the shipped defaults';
   const kept = result.dryRun ? 'Would save' : 'Saved';
   if (edited.length > 0) {
-    lines.push(`${kept} your unsaved edits: ${edited.join(', ')}.`);
+    lines.push(`${kept} the buffer: ${edited.join(', ')}.`);
     lines.push(`Everything else came from ${open}, or the shipped defaults where it carries no entry.`);
   } else {
-    lines.push(`No unsaved edits; ${kept.toLowerCase()} a copy of ${open}.`);
+    lines.push(`No buffer. ${kept} a copy of ${open}.`);
   }
   if (result.sketchSettings) lines.push(`Sketch settings rode through from the open theme.`);
 
   if (result.activated) {
     lines.push(
-      `\nOpened "${result.slug}" (previously open: "${result.previousActive}"). ` +
-        `Reload the app to see it; switch back any time from Load in the editor's Theme panel. ` +
-        `Adopt it there to publish it to tokens.generated.css.`,
+      `\nLoaded "${result.slug}" (previously open: "${result.previousActive}"). ` +
+        `Adopt in the editor ships it to tokens.generated.css.`,
     );
   } else if (result.dryRun) {
     lines.push(`\nDry run: nothing written under ${relative(root, dirname(result.themePath))}.`);
   } else {
     lines.push(
-      `\nNot opened (--no-activate). Your unsaved edits are still open, so the next ` +
-        `save-theme starts from the same look. Load "${result.slug}" from the editor's Theme panel to see it.`,
+      `\nNot loaded (--no-activate). The buffer is still open, so the next ` +
+        `save-theme starts from the same theme.`,
     );
   }
   return lines.join('\n');

package/bin/set-colors.mjs

@@ -28,9 +28,9 @@ const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const ENGINE = resolve(pkgRoot, 'dist-plugin/setColors/index.js');
 
 const SOURCE_LABELS = {
-  working: 'your unsaved edits',
+  working: 'the buffer',
   theme: 'the open theme',
-  default: 'the package default',
+  default: 'the shipped default',
 };
 
 async function loadEngine() {
@@ -142,7 +142,7 @@ export function formatSetColorsResult(result) {
   if (result.ignoredName !== null) {
     lines.push(
       `Ignored "name": "${result.ignoredName}". The base color file no longer names a theme; ` +
-        `name it when you run save-theme.`,
+        `name it in save-theme.`,
     );
   }
 
@@ -156,13 +156,13 @@ export function formatSetColorsResult(result) {
     );
   }
   if (result.report.failures.length > 0) {
-    lines.push(`\nUnmet floors — adjust the base colors and re-run:`);
+    lines.push(`\nUnmet floors. Adjust the base colors and re-run:`);
     for (const f of result.report.failures) lines.push(`  ! ${f}`);
   }
 
   lines.push(
     result.report.gradients === 'carried'
-      ? '\nGradients: kept your tuned swatch gradients.'
+      ? '\nGradients: kept the tuned swatch gradients.'
       : '\nGradients: swatch tokens rebuilt from the theme families.',
   );
   lines.push(`Shadows: ${result.report.shadows}; carried geometry kept.`);
@@ -172,17 +172,15 @@ export function formatSetColorsResult(result) {
 
   if (result.wrote === 'buffer') {
     lines.push(
-      `\nReload the app to see it. This is an unsaved edit: save the open theme in the ` +
-        `editor's Theme panel to keep it, or run save-theme to write a new one.`,
+      `\nThe buffer holds this edit. Run save-theme to keep it as a theme.`,
     );
   } else if (result.wrote === 'cleared') {
     const held =
-      result.savedSource === 'theme' ? `theme "${result.openTheme}"` : 'the package default';
+      result.savedSource === 'theme' ? `theme "${result.openTheme}"` : 'the shipped default';
     lines.push(
       result.source === 'working'
-        ? `\nThat is what ${held} already holds, so the unsaved buffer was discarded. ` +
-            `Reload the app to see it.`
-        : `\nThat is what ${held} already holds, and there was no unsaved buffer, so nothing was written.`,
+        ? `\nThat is what ${held} already holds, so the buffer was discarded.`
+        : `\nThat is what ${held} already holds, and there was no buffer, so nothing was written.`,
     );
   } else if (result.dryRun) {
     lines.push(`\nDry run: nothing written under ${relative(root, result.colorsAndTypeDir)}.`);

package/bin/set-geometry.mjs

@@ -17,15 +17,16 @@ const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const ENGINE = resolve(pkgRoot, 'dist-plugin/setGeometry/index.js');
 
 const SOURCE_LABELS = {
-  working: 'your unsaved edits',
+  working: 'the buffer',
   theme: 'the open theme',
 };
 
 const SKIP_LABELS = [
-  ['raw-value', 'raw value, not a token'],
-  ['off-ladder', 'off the ladder'],
-  ['clamped', 'already at the ladder end'],
+  ['raw-value', 'raw value'],
+  ['off-scale', 'off the scale'],
+  ['clamped', 'at the end of the scale'],
   ['pill-preserved', 'pill preserved (pass "full": true to move it)'],
+  ['none-preserved', 'no line drawn, preserved (use "set" to draw one)'],
 ];
 
 async function loadEngine() {
@@ -174,7 +175,7 @@ export function formatSetGeometryResult(result) {
 
     const width = Math.max(0, ...entry.changes.map((c) => c.variable.length));
     for (const c of entry.changes) {
-      lines.push(`    ${c.variable.padEnd(width)}  ${c.from} → ${c.to}`);
+      lines.push(`    ${c.variable.padEnd(width)}  ${c.from} to ${c.to}`);
     }
 
     for (const [reason, label] of SKIP_LABELS) {
@@ -189,8 +190,7 @@ export function formatSetGeometryResult(result) {
   );
   if (result.buffered) {
     lines.push(
-      `Reload the app to see it. This is an unsaved edit: save the open theme in the ` +
-        `editor's Theme panel to keep it, or load a theme to discard it.`,
+      `The buffer holds this edit. Run save-theme to keep it as a theme.`,
     );
   } else if (result.dryRun) {
     lines.push(`Dry run: nothing written under ${relative(root, result.configsDir)}.`);

package/bin/set-type.mjs

@@ -24,9 +24,9 @@ const BROWSER_UA =
   'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36';
 
 const SOURCE_LABELS = {
-  working: 'your unsaved edits',
+  working: 'the buffer',
   theme: 'the open theme',
-  default: 'the package default',
+  default: 'the shipped default',
 };
 
 async function loadEngine() {
@@ -196,7 +196,7 @@ export function formatSetTypeResult(result) {
 
   const width = Math.max(0, ...result.changes.map((c) => c.variable.length));
   for (const change of result.changes) {
-    lines.push(`    ${change.variable.padEnd(width)}  ${change.from ?? '(none)'} → ${change.to}`);
+    lines.push(`    ${change.variable.padEnd(width)}  ${change.from ?? '(none)'} to ${change.to}`);
   }
 
   for (const face of result.faces) {
@@ -231,13 +231,11 @@ export function formatSetTypeResult(result) {
 
   if (result.wrote === 'buffer') {
     lines.push(
-      `\nReload the app to see it. This is an unsaved edit: save the open theme in the ` +
-        `editor's Theme panel to keep it, or load a theme to discard it.`,
+      `\nThe buffer holds this edit. Run save-theme to keep it as a theme.`,
     );
   } else if (result.wrote === 'cleared') {
     lines.push(
-      `\nThat is what the open theme already holds, so the unsaved buffer was discarded. ` +
-        `Reload the app to see it.`,
+      `\nThat is what the open theme already holds, so the buffer was discarded.`,
     );
   } else if (result.dryRun) {
     lines.push(`\nDry run: nothing written under ${relative(root, result.colorsAndTypeDir)}.`);

package/bin/setup-claude.mjs

@@ -0,0 +1,110 @@
+// Installs the bundled Claude Code skills into a project's ./.claude/skills/.
+//
+// Claude Code discovers skills only under .claude/skills/, never inside
+// node_modules, so the package's own copy has to be duplicated into each
+// project that wants them. That makes this command the only thing keeping the
+// two trees in step, and `--force` has to mean "make the destination match this
+// release" rather than "write over the files I happen to ship today":
+//
+//   - a skill this release renamed leaves its old directory behind, where it
+//     shadows the new one with stale instructions;
+//   - a reference file this release dropped survives inside a skill that is
+//     otherwise current, because cpSync merges into an existing directory.
+//
+// Both are invisible until a model reads the stale text, so --force replaces
+// each directory outright and prunes the ones this release no longer ships.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+// The package owns this prefix in a project's skills directory. A skill without
+// it is the project's own and is never touched, whatever the flags say.
+const SKILL_PREFIX = 'live-tokens-';
+
+const SAMPLE_PROMPTS = {
+  '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-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',
+};
+
+function directoriesIn(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((name) => statSync(join(dir, name)).isDirectory());
+}
+
+export function runSetupClaude({ pkgRoot, cwd, force = false }) {
+  const srcSkills = join(pkgRoot, '.claude', 'skills');
+
+  if (!existsSync(srcSkills)) {
+    throw new Error(`No bundled skills found at ${srcSkills}. Is the package installed correctly?`);
+  }
+
+  const shipped = directoriesIn(srcSkills);
+  if (shipped.length === 0) {
+    throw new Error('No bundled skills to install.');
+  }
+
+  const destSkills = join(cwd, '.claude', 'skills');
+  mkdirSync(destSkills, { recursive: true });
+
+  const installed = [];
+  const skipped = [];
+  const removed = [];
+
+  for (const skill of shipped) {
+    const dest = join(destSkills, skill);
+    if (existsSync(dest) && !force) {
+      skipped.push(skill);
+      continue;
+    }
+    // Replace rather than merge: a file this release dropped must not survive
+    // inside a directory that otherwise looks current.
+    rmSync(dest, { recursive: true, force: true });
+    cpSync(join(srcSkills, skill), dest, { recursive: true });
+    installed.push(skill);
+  }
+
+  if (force) {
+    for (const name of directoriesIn(destSkills)) {
+      if (!name.startsWith(SKILL_PREFIX) || shipped.includes(name)) continue;
+      rmSync(join(destSkills, name), { recursive: true, force: true });
+      removed.push(name);
+    }
+  }
+
+  return { installed, skipped, removed, destSkills, shipped };
+}
+
+export function formatSetupResult({ installed, skipped, removed, destSkills, shipped }) {
+  const lines = [];
+
+  for (const skill of shipped) {
+    if (installed.includes(skill)) lines.push(`  ok    ${skill}`);
+    else lines.push(`  skip  ${skill}  (already exists; pass --force to overwrite)`);
+  }
+  for (const skill of removed) {
+    lines.push(`  gone  ${skill}  (this release no longer ships it; removed)`);
+  }
+
+  const counts = [`${installed.length} installed`, `${skipped.length} skipped`];
+  if (removed.length > 0) counts.push(`${removed.length} removed`);
+  lines.push(`\n${counts.join(', ')}, in ${destSkills}`);
+
+  if (skipped.length > 0 && removed.length === 0) {
+    lines.push(`\nRe-run with --force to bring every skill up to this release.`);
+  }
+
+  const samples = shipped.map((s) => SAMPLE_PROMPTS[s] && [s, SAMPLE_PROMPTS[s]]).filter(Boolean);
+  if (samples.length > 0) {
+    lines.push(`\nIn Claude Code, prompts like these auto-trigger the matching skill:`);
+    for (const [skill, prompt] of samples) lines.push(`  "${prompt}"\n    ${skill}`);
+  }
+
+  return lines.join('\n');
+}