@motion-proto/live-tokens 0.68.1 → 0.70.0

package/bin/check-page.mjs

@@ -0,0 +1,409 @@
+// 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
+// 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
+// the line between "wrong" and "deliberate" moves with the project.
+//
+// Returns { findings, checked } — findings carry a stable `rule` id so a skill
+// can parse --json output, fix, and re-run until the exit code is 0.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve, basename } from 'node:path';
+import { lineOf } from './lib/findings.mjs';
+import { blankStrings, hasColorLiteral, hasDimensionLiteral, stripVarFallbacks } from './lib/cssValues.mjs';
+import { isContractToken, loadVocabulary, walk } from './lib/tokenVocabulary.mjs';
+import { resolveTokensCssPath } from './migrate.mjs';
+
+export const PAGE_RULES = {
+  'unknown-component': 'error',
+  'unknown-prop': 'error',
+  'unknown-prop-value': 'error',
+  'deep-import': 'error',
+  'unknown-token': 'error',
+  'color-literal': 'error',
+  'reserved-route': 'error',
+  'site-css-in-main': 'error',
+  'dimension-literal': 'warn',
+  'hardcoded-columns': 'warn',
+  'raw-text-axis': 'warn',
+  'missing-source': 'warn',
+};
+
+// Directories that hold the system, not pages built on it.
+const NOT_PAGES = ['src/system', 'src/editor', 'src/lib', 'src/live-tokens'];
+
+const COMPONENT_IMPORT =
+  /(?:@motion-proto\/live-tokens\/components|[./][^'"]*\/system\/components)\/([A-Za-z0-9]+)\.svelte$/;
+
+const DEEP_IMPORT_PATTERNS = [
+  /^@motion-proto\/live-tokens\/src\//,
+  /node_modules\/@motion-proto\/live-tokens/,
+];
+
+const TEXT_AXES = ['font-size', 'font-family', 'font-weight', 'line-height', 'letter-spacing'];
+
+// 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.
+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
+// count reads as a claim about the page grid, which `--columns-count` owns.
+const PAGE_GRID_COLUMNS = 4;
+
+/** Blank out comments, url() payloads, and string contents so none of them can match a rule. */
+function neutralise(css) {
+  return blankStrings(
+    css
+      .replace(/\/\*[\s\S]*?\*\//g, (m) => ' '.repeat(m.length))
+      .replace(/url\((?:[^()]|\([^()]*\))*\)/g, (m) => ' '.repeat(m.length)),
+  );
+}
+
+/** `<style>` blocks with their absolute offset in the file; whole file for .css. */
+function styleRegions(text, file) {
+  if (file.endsWith('.css')) return [{ text, offset: 0 }];
+  const out = [];
+  for (const m of text.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/g)) {
+    out.push({ text: m[1], offset: m.index + m[0].indexOf(m[1]) });
+  }
+  return out;
+}
+
+/**
+ * Inline styles in markup, as declaration lists the value rules can read: a
+ * `style="..."` attribute verbatim, and a `style:prop="value"` directive
+ * rewritten as `prop: value;`. A `{...}` expression is dynamic and skipped.
+ */
+function inlineStyleRegions(code) {
+  const out = [];
+  for (const m of code.matchAll(/\sstyle=(["'])([^"']*)\1/g)) {
+    out.push({ text: `${m[2]};`, offset: m.index + m[0].indexOf(m[2]) });
+  }
+  for (const m of code.matchAll(/\sstyle:([a-z-]+)=(["'])([^"']*)\2/g)) {
+    out.push({ text: `${m[1]}: ${m[3]};`, offset: m.index + 1 });
+  }
+  return out;
+}
+
+/** Everything outside `<style>`: script and markup. */
+function codeRegion(text, file) {
+  if (file.endsWith('.css')) return null;
+  return text.replace(/<style[^>]*>[\s\S]*?<\/style>/g, (m) => ' '.repeat(m.length));
+}
+
+/**
+ * Declarations in a stylesheet, with at-rule preludes excluded. A breakpoint in
+ * `@media (max-width: 768px)` is structural geometry, not a themeable value.
+ * A property name is read from its start, so `--heading-2xl` is one custom
+ * property and never the property `xl`.
+ */
+function declarations(css) {
+  const body = css.replace(/@[a-z-]+[^;{]*(?=\{)/gi, (m) => ' '.repeat(m.length));
+  const out = [];
+  for (const m of body.matchAll(/(?<![\w-])((?:--)?[a-z][\w-]*)\s*:\s*([^;{}]+)[;}]/gi)) {
+    out.push({ prop: m[1].toLowerCase(), value: m[2].trim(), index: m.index });
+  }
+  return out;
+}
+
+/**
+ * The attributes of one component tag starting at `start` (the `<`), read with
+ * `{}` depth and quotes tracked so an expression holding `>` does not end the
+ * tag early. Returns null when the tag spreads an object, which makes its prop
+ * set unknowable.
+ */
+function tagAttributes(code, start) {
+  let i = code.indexOf(' ', start);
+  const tagEnd = (() => {
+    let depth = 0;
+    let quote = null;
+    for (let j = start; j < code.length; j++) {
+      const c = code[j];
+      if (quote) {
+        if (c === quote) quote = null;
+      } else if (c === '"' || c === "'") quote = c;
+      else if (c === '{') depth++;
+      else if (c === '}') depth--;
+      else if (c === '>' && depth === 0) return j;
+    }
+    return code.length;
+  })();
+  if (i === -1 || i > tagEnd) return { attrs: [], end: tagEnd };
+  const attrs = [];
+  while (i < tagEnd) {
+    const c = code[i];
+    if (/\s/.test(c) || c === '/') {
+      i++;
+      continue;
+    }
+    if (c === '{') {
+      let depth = 0;
+      let j = i;
+      for (; j < tagEnd; j++) {
+        if (code[j] === '{') depth++;
+        else if (code[j] === '}' && --depth === 0) break;
+      }
+      const inner = code.slice(i + 1, j).trim();
+      if (inner.startsWith('...')) return null;
+      if (/^\w+$/.test(inner)) attrs.push({ name: inner, value: null, index: i });
+      i = j + 1;
+      continue;
+    }
+    const name = code.slice(i).match(/^[^\s=/>]+/)?.[0];
+    if (!name) break;
+    const at = i;
+    i += name.length;
+    let value = null;
+    if (code[i] === '=') {
+      i++;
+      const q = code[i];
+      if (q === '"' || q === "'") {
+        const close = code.indexOf(q, i + 1);
+        value = code.slice(i + 1, close === -1 ? tagEnd : close);
+        i = close === -1 ? tagEnd : close + 1;
+      } else if (q === '{') {
+        let depth = 0;
+        for (; i < tagEnd; i++) {
+          if (code[i] === '{') depth++;
+          else if (code[i] === '}' && --depth === 0) break;
+        }
+        i++;
+      } else {
+        const bare = code.slice(i).match(/^[^\s>]+/)?.[0] ?? '';
+        value = bare;
+        i += bare.length;
+      }
+    }
+    attrs.push({ name, value, index: at });
+  }
+  return { attrs, end: tagEnd };
+}
+
+/** Props a page passes that the component does not declare, or values outside a prop's union. */
+function checkComponentUsage(code, imports, add) {
+  for (const [local, entry] of imports) {
+    const props = entry.props;
+    if (!props) continue;
+    const re = new RegExp(`<${local}(?=[\\s/>])`, 'g');
+    for (const m of code.matchAll(re)) {
+      const tag = tagAttributes(code, m.index);
+      if (!tag) continue;
+      for (const { name, value, index } of tag.attrs) {
+        if (name.includes(':') || name.startsWith('@') || name === 'children') continue;
+        if (!props.props.has(name)) {
+          add('unknown-prop', index, `${entry.name} has no prop '${name}'; it accepts ${[...props.props].join(', ')}`);
+          continue;
+        }
+        const allowed = props.enums.get(name);
+        if (allowed && value !== null && !allowed.has(value)) {
+          add('unknown-prop-value', index, `${entry.name} ${name}="${value}" is not one of ${[...allowed].join(', ')}`);
+        }
+      }
+    }
+  }
+}
+
+/** The object literal enclosing `index`, found by balancing braces outward. */
+function enclosingObject(text, index) {
+  let depth = 0;
+  let start = -1;
+  for (let i = index; i >= 0; i--) {
+    const c = text[i];
+    if (c === '}') depth++;
+    else if (c === '{') {
+      if (depth === 0) {
+        start = i;
+        break;
+      }
+      depth--;
+    }
+  }
+  if (start === -1) return null;
+  depth = 0;
+  for (let i = start; i < text.length; i++) {
+    const c = text[i];
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+function checkFile(file, text, vocab, root) {
+  const rel = relative(root, file);
+  const findings = [];
+  const add = (rule, index, message) =>
+    findings.push({ rule, file: rel, line: lineOf(text, index), message });
+
+  const code = codeRegion(text, file);
+  if (code !== null) {
+    const imports = new Map();
+    for (const m of code.matchAll(/import\s+(?:([^'"]*?)\s+from\s+)?['"]([^'"]+)['"]/g)) {
+      const spec = m[2];
+      for (const pattern of DEEP_IMPORT_PATTERNS) {
+        if (pattern.test(spec)) {
+          add('deep-import', m.index, `deep import into package internals: ${spec}`);
+        }
+      }
+      const comp = spec.match(COMPONENT_IMPORT);
+      if (!comp) continue;
+      const entry = vocab.components.get(comp[1].toLowerCase());
+      if (!entry) {
+        add(
+          'unknown-component',
+          m.index,
+          `'${comp[1]}' is not in the component catalogue; author it with live-tokens-create-component or pick a shipped one`,
+        );
+        continue;
+      }
+      const local = m[1]?.trim().match(/^(\w+)$/)?.[1];
+      if (local) imports.set(local, entry);
+    }
+    checkComponentUsage(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`);
+    }
+
+    for (const m of code.matchAll(/\blazy\s*:/g)) {
+      const entry = enclosingObject(code, m.index);
+      if (entry && !/\bsource\s*:/.test(entry)) {
+        add('missing-source', m.index, `route entry has no 'source', so Page Source cannot open it`);
+      }
+    }
+
+    if (/^main\.(ts|js)$/.test(basename(file))) {
+      for (const m of code.matchAll(/import\s+['"]([^'"]*site\.css)['"]/g)) {
+        add(
+          'site-css-in-main',
+          m.index,
+          `site.css imported from main; import it from each page's <script> so it cannot leak into editor routes`,
+        );
+      }
+    }
+  }
+
+  // A page may also mint a custom property outside its <style> block — a
+  // `style:--x={...}` directive or an el.style.setProperty call — and those are
+  // just as declared as one written in CSS.
+  const declaredHere = new Set();
+  const regions = styleRegions(text, file);
+  for (const region of regions) {
+    for (const m of neutralise(region.text).matchAll(/(?:^|[;{])\s*(--[a-z0-9-]+)\s*:/gim)) {
+      declaredHere.add(m[1]);
+    }
+  }
+  for (const m of text.matchAll(/(?:style:|setProperty\(\s*['"`]|['"`])(--[a-z0-9-]+)/g)) {
+    declaredHere.add(m[1]);
+  }
+
+  for (const region of [...regions, ...(code === null ? [] : inlineStyleRegions(code))]) {
+    const css = neutralise(region.text);
+    const at = (i) => region.offset + i;
+
+    for (const m of css.matchAll(/var\(\s*(--[a-z0-9-]+)/g)) {
+      const name = m[1];
+      if (declaredHere.has(name) || vocab.knows(name)) continue;
+      add(
+        '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`,
+      );
+    }
+
+    for (const decl of declarations(css)) {
+      const { prop, value, index } = decl;
+      if (prop.startsWith('--')) continue;
+
+      // A `var()` fallback only renders when the token is missing, so a literal
+      // 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.`);
+        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 (THEMED_GEOMETRY.test(prop) && hasDimensionLiteral(painted)) {
+        add(
+          'dimension-literal',
+          at(index),
+          `${prop}: ${value}. Use a --space-*, --radius-*, --border-width-*, or --shadow-* token.`,
+        );
+      }
+
+      const columns = value.match(/\brepeat\(\s*(\d+)\s*,\s*1fr\s*\)/);
+      if (columns && Number(columns[1]) >= PAGE_GRID_COLUMNS) {
+        add(
+          'hardcoded-columns',
+          at(index),
+          `${prop}: ${value}. Use repeat(var(--columns-count), 1fr) so the page grid stays in step.`,
+        );
+      }
+    }
+  }
+
+  return findings;
+}
+
+// Files that define the vocabulary rather than consume it.
+const TOKEN_SOURCES = ['tokens.generated.css', 'fonts.css'];
+
+/** Pages to check when the caller names none: every .svelte/.css under src/ that is not system code. */
+export function discoverPages(root) {
+  const src = join(root, 'src');
+  if (!existsSync(src)) return [];
+  const tokensCss = resolveTokensCssPath(null, null, root);
+  return walk(src, ['.svelte', '.css', '.ts', '.js']).filter((f) => {
+    const rel = relative(root, f);
+    if (NOT_PAGES.some((d) => rel.startsWith(`${d}/`))) return false;
+    if (f === tokensCss || TOKEN_SOURCES.includes(basename(f))) return false;
+    if (/\.(test|spec)\.[tj]s$/.test(rel)) return false;
+    if (rel.endsWith('.ts') || rel.endsWith('.js')) return /main\.(ts|js)$/.test(rel);
+    return true;
+  });
+}
+
+export function checkPages(targets, { root = process.cwd(), vocabulary } = {}) {
+  const vocab = vocabulary ?? loadVocabulary({ root });
+  const files = [];
+  for (const t of targets) {
+    const full = resolve(root, t);
+    if (!existsSync(full)) continue;
+    if (statSync(full).isDirectory()) {
+      files.push(...walk(full, ['.svelte', '.css']));
+    } else {
+      files.push(full);
+    }
+  }
+  const findings = [];
+  for (const file of files) {
+    findings.push(...checkFile(file, readFileSync(file, 'utf8'), vocab, root));
+  }
+  return { findings, checked: files.length };
+}

package/bin/cli.mjs

@@ -3,17 +3,31 @@
 // Subcommands:
 //   create <dir>             Scaffold a new app that depends on this package.
 //   setup-claude [--force]   Copy bundled Claude Code skills into ./.claude/skills/.
-//   check-component <id>     Validate a component against the add-component skill contract.
+//   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.
+//   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.
 //   migrate [...]            Reconcile tokens.css, the data tree, and route references.
 
-import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+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 { checkComponent, formatReport } from './check-component.mjs';
+import { COMPONENT_RULES, 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 { loadVocabulary } from './lib/tokenVocabulary.mjs';
+import {
+  applySeverity,
+  countBySeverity,
+  formatFindings,
+  parseCheckFlags,
+  readChecksConfig,
+  toJson,
+} from './lib/findings.mjs';
 import {
   runMigrate,
   formatMigrateResult,
@@ -32,8 +46,28 @@ Commands:
   create <dir> [--force]      Scaffold a new Svelte + Vite app wired up with
                               live-tokens (editor, components, theme tokens)
   setup-claude [--force]      Install bundled Claude Code skills into ./.claude/skills/
-  check-component <id>        Validate <id>'s runtime, editor, and registration
+  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
+  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
+                              contract: catalogue components only, and every CSS
+                              value a theme token. Checks every page under src/
+                              when given no paths.
+
+Both check commands accept:
+  --json                      Machine-readable findings, for a skill to iterate
+                              against until the exit code is 0
+  --strict                    Treat warnings as errors
+  --off=<rule,...>            Silence rules; --warn=/--error= change severity
+                              (or set "checks": { "rules": {...} } in
+                              live-tokens.config.json)
   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),
@@ -79,6 +113,20 @@ Commands:
                               either is pending; route findings are advisory).
 `;
 
+// A large body written through console.log is cut at the pipe buffer when the
+// process exits before stdout drains, so a query writes synchronously.
+function writeOut(text) {
+  const buf = Buffer.from(`${text}\n`);
+  let offset = 0;
+  while (offset < buf.length) {
+    try {
+      offset += writeSync(1, buf, offset, buf.length - offset);
+    } catch (error) {
+      if (error.code !== 'EAGAIN') throw error;
+    }
+  }
+}
+
 function fail(message, code = 1) {
   console.error(message);
   process.exit(code);
@@ -109,12 +157,61 @@ if (command === 'create' || command === 'init') {
   }
 }
 
+function reportChecks(label, findings, checked, rules, opts) {
+  const resolved = applySeverity(findings, rules, opts, readChecksConfig(process.cwd()));
+  console.log(
+    opts.json
+      ? toJson(resolved, { label, checked })
+      : formatFindings(resolved, { label, checked }),
+  );
+  process.exit(countBySeverity(resolved).errors === 0 ? 0 : 1);
+}
+
+if (command === 'components') {
+  const opts = parseCheckFlags(rest);
+  const list = describeComponents(loadVocabulary());
+  const id = opts.rest[0];
+  if (id && !list.some((c) => c.id === id)) fail(formatComponents(list, { id }));
+  writeOut(opts.json ? JSON.stringify(id ? list.find((c) => c.id === id) : list, null, 2) : formatComponents(list, { id }));
+  process.exit(0);
+}
+
+if (command === 'tokens') {
+  const opts = parseCheckFlags(rest);
+  const at = opts.rest.indexOf('--family');
+  const family = at >= 0 ? opts.rest[at + 1] : undefined;
+  const desc = describeTokens(loadVocabulary());
+  if (family && !desc.families.some((f) => f.family === family)) fail(formatTokens(desc, { family }));
+  writeOut(
+    opts.json
+      ? JSON.stringify(family ? desc.families.find((f) => f.family === family) : desc, null, 2)
+      : formatTokens(desc, { family }),
+  );
+  process.exit(0);
+}
+
 if (command === 'check-component') {
-  const id = rest[0];
-  if (!id) fail(`Usage: npx @motion-proto/live-tokens check-component <id>`);
-  const result = checkComponent(id);
-  console.log(formatReport(id, result));
-  process.exit(result.errors.length === 0 ? 0 : 1);
+  const opts = parseCheckFlags(rest);
+  const ids = opts.rest.length > 0 ? [opts.rest[0]] : discoverComponents();
+  if (ids.length === 0) {
+    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) {
+    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);
+}
+
+if (command === 'check-page') {
+  const opts = parseCheckFlags(rest);
+  const targets = opts.rest.length > 0 ? opts.rest : discoverPages(process.cwd());
+  const { findings, checked } = checkPages(targets, { root: process.cwd() });
+  reportChecks('check-page', findings, checked, PAGE_RULES, opts);
 }
 
 if (command === 'generate-theme') {
@@ -270,6 +367,7 @@ const SAMPLE_PROMPTS = {
   '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-fix-findings': 'make check:design pass',
 };
 
 const installedSamples = skills

package/bin/lib/catalogue.mjs

@@ -0,0 +1,123 @@
+// 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
+// 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';
+
+/** The runtime file's leading HTML comment, which is where a component says what it is for. */
+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*/, '');
+}
+
+function familyOf(name) {
+  const stem = name.replace(/^--/, '');
+  const hit = CONTRACT_FAMILIES
+    .filter((f) => stem === f || stem.startsWith(`${f}-`))
+    .sort((a, b) => b.length - a.length)[0];
+  return hit ?? stem.split('-')[0];
+}
+
+export function describeComponents(vocab, { root = process.cwd() } = {}) {
+  const out = [];
+  for (const entry of vocab.components.values()) {
+    const source = readFileSync(entry.file, 'utf8');
+    const props = entry.props
+      ? [...entry.props.props].map((name) => ({
+          name,
+          type: entry.props.types.get(name) ?? '',
+          values: entry.props.enums.has(name) ? [...entry.props.enums.get(name)] : undefined,
+        }))
+      : [];
+    out.push({
+      id: entry.id,
+      name: entry.name,
+      origin: entry.origin,
+      file: relative(root, entry.file),
+      registered: entry.origin === 'shipped' || vocab.registered.has(entry.id),
+      description: descriptionOf(source),
+      variants: entry.props?.enums.get('variant') ? [...entry.props.enums.get('variant')] : [],
+      props,
+      tokens: [...entry.tokens].map(([name, value]) => ({ name, default: value })),
+    });
+  }
+  return out.sort((a, b) => a.origin.localeCompare(b.origin) || a.id.localeCompare(b.id));
+}
+
+export function describeTokens(vocab, { root = process.cwd() } = {}) {
+  const values = new Map();
+  if (vocab.tokensCssPath) {
+    const css = readFileSync(vocab.tokensCssPath, 'utf8').replace(/\/\*[\s\S]*?\*\//g, ' ');
+    for (const m of css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+      if (!values.has(m[1])) values.set(m[1], m[2].trim());
+    }
+  }
+  const byFamily = 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) ?? '' });
+  }
+  return {
+    tokensCss: vocab.tokensCssPath ? relative(root, vocab.tokensCssPath) : null,
+    families: [...byFamily].map(([family, tokens]) => ({ family, tokens })),
+    components: [...vocab.components.values()].map((c) => ({
+      id: c.id,
+      tokens: [...c.tokens].map(([name, value]) => ({ name, default: value })),
+    })),
+  };
+}
+
+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}`);
+    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}` : ''}`);
+    }
+    lines.push(`  tokens (${c.tokens.length}):`);
+    for (const t of c.tokens) lines.push(`    ${t.name}: ${t.default}`);
+    return lines.join('\n');
+  }
+  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}`);
+  }
+  lines.push('');
+  lines.push(`${list.length} component(s). \`live-tokens components <id>\` prints one with its props and tokens.`);
+  return lines.join('\n');
+}
+
+export function formatTokens(desc, { family } = {}) {
+  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(', ')}.`;
+  }
+  lines.push(`Theme tokens from ${desc.tokensCss ?? '(no tokens.css found)'}`);
+  for (const f of families) {
+    lines.push('');
+    lines.push(`${f.family} (${f.tokens.length})`);
+    for (const t of f.tokens) lines.push(`  ${t.name}: ${t.value}`);
+  }
+  if (!family) {
+    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.`);
+  }
+  return lines.join('\n');
+}