@motion-proto/live-tokens 0.70.0 → 0.71.0

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

@@ -0,0 +1,72 @@
+---
+name: live-tokens-check-compliance
+description: Check an existing @motion-proto/live-tokens project against its design system and report, without changing a file: which tokens each component reads, which page renders which component, what the two checkers find, and a list of recommended fixes handed to live-tokens-fix-findings. Use when the user asks to check, audit, validate, or review the project, a page, or a component against the design system; asks how compliant it is, what is off, or what it would take to make the build pass; or wants a look before an upgrade. Not for making the changes (live-tokens-fix-findings), and not for a single token (use the editor).
+---
+
+# Checking a project against its design system
+
+The answer to "check this project" is a report, and every fact in it comes
+from one command. This skill runs it, reads it, and says what the facts mean
+and what fixing them would involve. It edits nothing. When the user wants the
+changes made, that is **live-tokens-fix-findings**, and the report is what it
+starts from.
+
+## Run the report
+
+```sh
+npx live-tokens report --json
+```
+
+It always exits 0: it is a reading, not a gate. Unknown command means the
+installed package predates it; upgrade `@motion-proto/live-tokens` first. The
+sections, in the order the report gives them:
+
+| Section | Fact | What it means when it is not clean |
+| --- | --- | --- |
+| `migrations` | Whether `tokens.css` is behind the installed package | A stale file shows up downstream as unknown tokens. This is the first fix, and it is one command: `npx live-tokens migrate --check`, then `--write` (`--tokens <path>` for a tokens.css in an unusual place). |
+| `components[].unread` | Tokens a component declares that nothing in its file reads | An editor row that edits nothing. Each is a token to wire into the CSS or to remove. |
+| `components[].registered` | A component file with no `bootLiveTokens` or `registerComponent` entry | It renders on the page but has no editor. |
+| `components[].described` | Whether the runtime file has the header comment the picker reads | Without one, `live-tokens components` cannot say what it is for. |
+| `usage.byPage` | Which catalogue component each page renders, and how many times | A page rendering none is either chrome or hand-rolled markup that a shipped component covers. |
+| `usage.unusedShipped` | Shipped components no page renders | Information, not a finding. |
+| `usage.customUnregistered`, `usage.customUnused` | The project's own components that are unregistered or unused | Dead or half-wired work. |
+| `findings.pages`, `findings.components` | Both checkers' findings by rule, under the project's severities and again under `--strict` | The errors are what fails the build today; the strict count is what a fully tokenized project would fail. |
+
+`npx live-tokens components <id>` and `npx live-tokens tokens --family <name>`
+(both take `--json`) answer any question the report raises about one
+component or one scale.
+
+## Read it
+
+Facts are the report's; the reading is yours. For each rule with findings, say
+in a line what the rule holds and which of two kinds the fix is:
+
+- **Mechanical**: a spacing literal to its nearest `--space-*` step, a stroke
+  to `--border-width-*`, a hardcoded column count to `var(--columns-count)`,
+  `site.css` moved out of `main.ts`, a route given its `source`. Name any
+  visible shift, such as a `14px` margin becoming `16px`.
+- **Judgement**: a colour literal mapped by the role it plays rather than its
+  hue, a raw type axis set from a text style, a prop the component does not
+  declare mapped or dropped. Say what the choice is, not what you would pick.
+
+Where a finding looks deliberate, a translucent overlay on an app shell or a
+layout size the project owns, say so and name the config entry that would
+record the decision: `"checks": { "rules": { "<rule>": "warn" } }` in
+`live-tokens.config.json`. Recording it is the user's call, not yours.
+
+## Report
+
+In this order, each line carrying its count:
+
+1. Migrations pending, and the one command that clears them.
+2. What fails the build now: errors by rule, with the files.
+3. What `--strict` would add: warnings by rule.
+4. Components: unread tokens, unregistered, undescribed.
+5. Usage: what each page renders, and what is used nowhere.
+6. Recommended fixes, in the order **live-tokens-fix-findings** would take
+   them: migrations, then the largest group of errors, then the rest, then
+   warnings. Mark each as mechanical or judgement.
+
+End with the hand-off: "Run live-tokens-fix-findings to apply these", or the
+subset the user chooses. Do not start applying them here, even when the fix is
+one line, because the user asked how things stand.

package/.claude/skills/live-tokens-fix-findings/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: live-tokens-fix-findings
-description: Bring an existing @motion-proto/live-tokens project into line with its design system by running check-page and check-component, reading the findings, and fixing each by rule until both exit 0. Use when the user asks to make the build pass, fix the design-system errors or warnings, clean up the literals, replace hex or pixel values with tokens, make a page or component themeable, audit the site or a file against the design system, or asks why check:design fails. Not for building a new page (live-tokens-build-page) or a new component (live-tokens-create-component), which run the same gate as their last step, and not for a single token edit (use the editor).
+description: Bring an existing @motion-proto/live-tokens project into line with its design system by running check-page and check-component, reading the findings, and fixing each by rule until both exit 0. Use when the user asks to make the build pass, fix the design-system errors or warnings, clean up the literals, replace hex or pixel values with tokens, make a page or component themeable, or apply what a check reported. Not for the check itself (live-tokens-check-compliance reports and edits nothing), not for building a new page (live-tokens-build-page) or a new component (live-tokens-create-component), which run the same gate as their last step, and not for a single token edit (use the editor).
 ---
 
 # Fixing what the checkers report
@@ -14,7 +14,10 @@ passes repaints when the theme changes. One that does not has opted out of the
 system silently, and these findings are where.
 
 This skill is the loop for code that already exists. Run the checker, fix one
-rule at a time, run it again, and stop only when both exit 0.
+rule at a time, run it again, and stop only when both exit 0. When the user has
+not seen the state of the project yet, `npx live-tokens report --json` is the
+reading to start from, and **live-tokens-check-compliance** is the skill that
+presents it without editing; this one edits.
 
 ## Reach the checkers
 

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.71.0 — Check this project
+
+### Added
+
+- **`npx live-tokens report` is the project as facts.** Pending `tokens.css`
+  migrations, the tokens each component declares and how many its own CSS
+  reads (a read counts a `var()`, a `style:` directive, a padding mixin's
+  string, or an SCSS-interpolated pattern), whether a component is registered
+  and carries the description comment the picker reads, which page renders
+  which component and how many times, the shipped and custom components used
+  nowhere, and both checkers' findings by rule under the project's severities
+  and again under `--strict`. It always exits 0: a reading, not a gate. `--json`
+  for data.
+
+- **`live-tokens-check-compliance`, the eighth skill.** "Check this project"
+  runs the report and presents it without editing a file: what fails the
+  build now, what `--strict` would add, the components and usage facts, and a
+  list of recommended fixes marked mechanical or judgement with any visible
+  shift named, handed to `live-tokens-fix-findings`. A finding that looks
+  deliberate is flagged with the config entry that would record the decision,
+  which stays the user's call. `live-tokens-fix-findings` no longer claims the
+  audit wording, and starts from the report when the user has not seen it.
+
 ## 0.70.0 — The registry is a query
 
 ### Added

package/README.md

@@ -325,6 +325,7 @@ npx @motion-proto/live-tokens <command>
 | `setup-claude [--force]` | Install the bundled Claude Code skills into `./.claude/skills/`. |
 | `components [id] [--json]` | List every component the project has, shipped and its own, with the props each takes; with an id, its props, variants, tokens, and defaults. |
 | `tokens [--family <name>] [--json]` | List every theme token the project's `tokens.css` declares, by family, with its value. |
+| `report [--json]` | The project as facts: pending migrations, tokens each component reads, which page renders which component, and both checkers' findings by rule. Always exits 0. |
 | `check-component [id]` | Validate a component's runtime, editor, and registration against the authoring contract; with no id, every component authored under `src/system/components`. |
 | `check-page [paths...]` | Validate pages against the build-page contract: catalogue components and their props, theme tokens over literals, route wiring. |
 | `generate-theme <brief.json> [--no-activate] [--dry-run] [--carry-from <name>]` | Build a full theme from a 10-seed OKLCH brief, enforce AA contrast, write `themes/<slug>.json`, and open it. |
@@ -336,7 +337,7 @@ Once installed in a project, the same commands are available as `npx live-tokens
 
 ## Claude Code skills
 
-The package bundles seven Claude Code skills. They encode the conventions this README cannot carry in full: which component fits a need, how a page is wired, what a valid theme looks like in OKLCH, how two typefaces sit together, how geometry moves along the token scales, and how an existing page or component is brought back into line with all of that. Each triggers from an ordinary request, so there are no slash commands to learn.
+The package bundles eight Claude Code skills. They encode the conventions this README cannot carry in full: which component fits a need, how a page is wired, what a valid theme looks like in OKLCH, how two typefaces sit together, how geometry moves along the token scales, how a project is checked against all of that, and how an existing page or component is brought back into line. Each triggers from an ordinary request, so there are no slash commands to learn.
 
 ### Install
 
@@ -400,6 +401,12 @@ Ask for something the catalogue lacks: "author a Rating component", "make my Chi
 
 The skill covers the recipe: the runtime `.svelte` file with its `:global(:root)` token block, the editor `.svelte` file exporting `allTokens` and its variant groups, the `registerComponent()` call, and the catalogue entry that keeps `live-tokens-pick-component` current. It carries the naming scheme, the token suffix vocabulary, the state model (component states such as selected and disabled are separate from interaction states such as hover), and the public-imports rule, and points at the shipped `Toggle` in `node_modules` as the worked example. Linked siblings, intrinsics, and the fixed-overlay portal rule sit in reference files the skill reads only when a component needs them.
 
+### `live-tokens-check-compliance`
+
+Ask how things stand: "check this project against the design system", "audit the pricing page", "what would it take to make the build pass?", "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 presents the report, says what each rule holds, marks each recommended fix as mechanical or a judgement call, names any visible shift, and flags a finding that looks deliberate together with the config entry that would record the decision. It edits nothing and ends by handing the list to `live-tokens-fix-findings`.
+
 ### `live-tokens-fix-findings`
 
 Ask for the existing code to catch up: "make check:design pass", "fix the design-system warnings", "replace the hex and pixel values with tokens", "why is check-page failing on the pricing page?".

package/bin/check-page.mjs

@@ -35,7 +35,7 @@ export const PAGE_RULES = {
 // 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 =
+export const COMPONENT_IMPORT =
   /(?:@motion-proto\/live-tokens\/components|[./][^'"]*\/system\/components)\/([A-Za-z0-9]+)\.svelte$/;
 
 const DEEP_IMPORT_PATTERNS = [

package/bin/cli.mjs

@@ -5,6 +5,7 @@
 //   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.
+//   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.
@@ -19,6 +20,7 @@ import process from 'node:process';
 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 { buildReport, formatReport as formatProjectReport } from './lib/report.mjs';
 import { loadVocabulary } from './lib/tokenVocabulary.mjs';
 import {
   applySeverity,
@@ -54,6 +56,12 @@ Commands:
   tokens [--family <name>] [--json]
                               List every theme token the project's tokens.css
                               declares, by family, 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
@@ -190,6 +198,24 @@ if (command === 'tokens') {
   process.exit(0);
 }
 
+if (command === 'report') {
+  const opts = parseCheckFlags(rest);
+  const report = buildReport(loadVocabulary());
+  try {
+    const plan = await runMigrate({ check: true });
+    report.migrations =
+      plan.status === 'no-path'
+        ? { status: 'no tokens.css' }
+        : plan.status === 'would-change'
+          ? { status: 'pending', pending: plan.applied ?? plan.migrations ?? [] }
+          : { status: 'none pending' };
+  } catch {
+    report.migrations = { status: 'unavailable (compiled engine not built)' };
+  }
+  writeOut(opts.json ? JSON.stringify(report, null, 2) : formatProjectReport(report));
+  process.exit(0);
+}
+
 if (command === 'check-component') {
   const opts = parseCheckFlags(rest);
   const ids = opts.rest.length > 0 ? [opts.rest[0]] : discoverComponents();
@@ -368,6 +394,7 @@ const SAMPLE_PROMPTS = {
   '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',
+  'live-tokens-check-compliance': 'check this project against the design system',
 };
 
 const installedSamples = skills

package/bin/lib/report.mjs

@@ -0,0 +1,158 @@
+// The project as facts. Every section is deterministic: what the tokens.css
+// declares, what each component reads, which component each page renders, and
+// what the two checkers report under the project's severities and under
+// --strict. Nothing here interprets; the check skill narrates it and the fix
+// skill acts on it. Reads files only, like the vocabulary it is built on.
+
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { COMPONENT_RULES, checkComponent, discoverComponents } from '../check-component.mjs';
+import { COMPONENT_IMPORT, PAGE_RULES, checkPages, discoverPages } from '../check-page.mjs';
+import { applySeverity, readChecksConfig } from './findings.mjs';
+import { extractGlobalRootBlocks } from './tokenVocabulary.mjs';
+
+const SIDES = ['-top', '-right', '-bottom', '-left'];
+
+/**
+ * Tokens a component declares that nothing in its file reads. A read is the
+ * name appearing outside the `:global(:root)` block: in a `var()`, in a `style:`
+ * directive, or as the string a padding mixin takes. SCSS interpolation
+ * (`--badge-#{$v}-surface`) reads every token the pattern covers. A per-side
+ * padding is read through its parent.
+ */
+export function unreadTokens(source, tokens) {
+  let body = source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/<!--[\s\S]*?-->/g, ' ');
+  for (const block of extractGlobalRootBlocks(body)) body = body.replace(block, ' ');
+  const patterns = [...body.matchAll(/--[a-z0-9-]*(?:#\{[^}]*\}[a-z0-9-]*)+/g)].map(
+    (m) => new RegExp(`^${m[0].replace(/[.*+?^()|[\]\\]/g, '\\$&').replace(/#\{[^}]*\}/g, '[a-z0-9-]+')}$`),
+  );
+  const isRead = (name) => body.includes(name) || patterns.some((re) => re.test(name));
+  return [...tokens].filter((name) => {
+    const side = SIDES.find((s) => name.endsWith(s));
+    return !isRead(name) && !(side && isRead(name.slice(0, -side.length)));
+  });
+}
+
+function countByRule(findings) {
+  const out = {};
+  for (const f of findings) out[f.rule] = (out[f.rule] ?? 0) + 1;
+  return out;
+}
+
+function summarise(findings, rules, config) {
+  const resolved = applySeverity(findings, rules, {}, config);
+  const strict = applySeverity(findings, rules, { strict: true }, config);
+  return {
+    errors: resolved.filter((f) => f.severity === 'error').length,
+    warnings: resolved.filter((f) => f.severity === 'warn').length,
+    strictErrors: strict.filter((f) => f.severity === 'error').length,
+    byRule: countByRule(resolved),
+    items: resolved.map((f) => ({ rule: f.rule, severity: f.severity, file: f.file, line: f.line, message: f.message })),
+  };
+}
+
+export function buildReport(vocab, { root = process.cwd() } = {}) {
+  const config = readChecksConfig(root);
+
+  const components = [...vocab.components.values()].map((c) => {
+    const source = readFileSync(c.file, 'utf8');
+    return {
+      id: c.id,
+      name: c.name,
+      origin: c.origin,
+      file: relative(root, c.file),
+      registered: c.origin === 'shipped' || vocab.registered.has(c.id),
+      described: /^\s*<!--[\s\S]*?-->/.test(source),
+      tokens: c.tokens.size,
+      unread: unreadTokens(source, c.tokens.keys()),
+    };
+  });
+
+  const pageFiles = discoverPages(root);
+  const byPage = [];
+  const pagesOf = new Map();
+  for (const file of pageFiles) {
+    if (!file.endsWith('.svelte')) continue;
+    const text = readFileSync(file, 'utf8').replace(/<style[^>]*>[\s\S]*?<\/style>/g, ' ');
+    const used = [];
+    for (const m of text.matchAll(/import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g)) {
+      const comp = m[2].match(COMPONENT_IMPORT);
+      if (!comp) continue;
+      const id = comp[1].toLowerCase();
+      const rendered = [...text.matchAll(new RegExp(`<${m[1]}(?=[\\s/>])`, 'g'))].length;
+      used.push({ id, rendered });
+      if (!pagesOf.has(id)) pagesOf.set(id, []);
+      pagesOf.get(id).push(relative(root, file));
+    }
+    byPage.push({ file: relative(root, file), components: used });
+  }
+  const byComponent = components.map((c) => ({ id: c.id, origin: c.origin, pages: pagesOf.get(c.id) ?? [] }));
+
+  const pageFindings = checkPages(pageFiles, { root, vocabulary: vocab }).findings;
+  const authored = discoverComponents(root);
+  const componentFindings = authored.flatMap((id) => checkComponent(id, root, { vocabulary: vocab }).findings);
+
+  return {
+    project: {
+      root,
+      tokensCss: vocab.tokensCssPath ? relative(root, vocab.tokensCssPath) : null,
+      themeTokens: vocab.themeTokens.size,
+      components: components.length,
+      pages: pageFiles.length,
+    },
+    components,
+    usage: {
+      byPage,
+      byComponent,
+      unusedShipped: byComponent.filter((c) => c.origin === 'shipped' && c.pages.length === 0).map((c) => c.id),
+      customUnregistered: components.filter((c) => c.origin === 'custom' && !c.registered).map((c) => c.id),
+      customUnused: byComponent.filter((c) => c.origin === 'custom' && c.pages.length === 0).map((c) => c.id),
+    },
+    findings: {
+      pages: summarise(pageFindings, PAGE_RULES, config),
+      components: { checked: authored, ...summarise(componentFindings, COMPONENT_RULES, config) },
+    },
+  };
+}
+
+const list = (items, max = 20) =>
+  items.length <= max ? items.join(', ') : `${items.slice(0, max).join(', ')}, +${items.length - max} more`;
+
+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)'}`);
+  if (r.migrations) {
+    out.push('');
+    out.push(`Migrations: ${r.migrations.status}${r.migrations.pending?.length ? ` (${list(r.migrations.pending)})` : ''}`);
+  }
+
+  out.push('');
+  out.push('Components');
+  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 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');
+  for (const p of r.usage.byPage) {
+    if (p.components.length === 0) continue;
+    out.push(`  ${p.file}: ${p.components.map((c) => `${c.id}×${c.rendered}`).join(', ')}`);
+  }
+  out.push(`  pages rendering no catalogue component: ${r.usage.byPage.filter((p) => p.components.length === 0).length}`);
+  out.push(`  shipped components used nowhere: ${r.usage.unusedShipped.length}${r.usage.unusedShipped.length ? ` (${list(r.usage.unusedShipped)})` : ''}`);
+  if (r.usage.customUnused.length) out.push(`  custom components used nowhere: ${list(r.usage.customUnused)}`);
+
+  const section = (label, s) => {
+    out.push('');
+    out.push(`${label}: ${s.errors} error(s), ${s.warnings} warning(s); ${s.strictErrors} under --strict`);
+    for (const [rule, n] of Object.entries(s.byRule).sort((a, b) => b[1] - a[1])) out.push(`  ${rule}: ${n}`);
+  };
+  section('check-page', r.findings.pages);
+  section(`check-component (${r.findings.components.checked.length} authored)`, r.findings.components);
+  return out.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [