@motion-proto/live-tokens 0.68.1 → 0.70.0

package/README.md

@@ -11,7 +11,7 @@ The editor is dev-only. Production builds get plain CSS variables and the compon
 ## Features
 
 - **Live token editing.** Colors, typography, spacing, radii, shadows, motion, palettes, and gradients. Every input writes a CSS variable, so the page repaints with no reload and no build step.
-- **Live component editing.** 25 shipped Svelte components (Button, IconButton, Input, Card, Dialog, Badge, Callout, Table, Tooltip, Toggle, TabBar, SegmentedControl, RadioButton, MenuSelect, ProgressBar, CornerBadge, SectionDivider, CollapsibleSection, Notification, Image, ImageLightbox, CodeSnippet, SideNavigation, Panel, InlineEditActions) declare their design-token aliases in a `:global(:root)` block. Rewire an alias from the component's editor and it updates everywhere that component is used, on your real pages.
+- **Live component editing.** 26 shipped Svelte components (Button, IconButton, Input, Card, Dialog, Badge, Callout, Table, Tooltip, Toggle, TabBar, SegmentedControl, RadioButton, MenuSelect, ProgressBar, CornerBadge, SectionDivider, CollapsibleSection, Notification, Image, ImageLightbox, CodeSnippet, SideNavigation, Panel, InlineEditActions) declare their design-token aliases in a `:global(:root)` block. Rewire an alias from the component's editor and it updates everywhere that component is used, on your real pages.
 - **Four dev-only routes.** `/live-tokens/editor` for tokens, `/live-tokens/colors` for palettes, `/live-tokens/components` for per-component aliases, `/live-tokens/docs` for the user guide.
 - **Editor overlay.** Pins to the top right of every dev page and opens the editor in a side panel or floating window, so you edit on the page you are styling. Its "Page Source" button opens the current page's `.svelte` file in VS Code.
 - **Themes.** A theme is a whole look in one file: colors and type plus a config for every component, stored by value. Loading one changes a single pointer file, and nothing your site ships changes until you Adopt. Export a theme and import it into another project to restore the look in one step.
@@ -323,7 +323,10 @@ npx @motion-proto/live-tokens <command>
 |---|---|
 | `create <dir> [--force]` | Scaffold a new Svelte + Vite app wired up with live-tokens. |
 | `setup-claude [--force]` | Install the bundled Claude Code skills into `./.claude/skills/`. |
-| `check-component <id>` | Validate a component's runtime, editor, and registration against the authoring contract. |
+| `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. |
+| `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. |
 | `adjust <ops.json> [--dry-run]` | Move radius, padding, gap, and border-width aliases along their token scales. |
 | `set-fonts <brief.json> [--dry-run] [--no-verify]` | Bind Google Fonts families to the theme's font stacks, verified against the API. |
@@ -333,7 +336,7 @@ Once installed in a project, the same commands are available as `npx live-tokens
 
 ## Claude Code skills
 
-The package bundles six 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, and how geometry moves along the token scales. Each triggers from an ordinary request, so there are no slash commands to learn.
+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.
 
 ### Install
 
@@ -397,13 +400,19 @@ 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-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?".
+
+The two checkers report a stable rule id per finding. The skill runs them with `--json`, groups the findings by rule, and carries one fix recipe per rule: a colour literal becomes the token for its role rather than the nearest hue, a spacing literal moves to the nearest `--space-*` step with the shift named, a raw `font-size` becomes a whole text style, a prop the component does not declare is mapped or dropped, and `site.css` moves out of `main.ts` into each page. It re-runs after every rule and stops at exit 0, then reports what changed, what it left and why, and what `--strict` would add. It never silences a rule to pass and never adds a token to `tokens.css` to match a value a page happened to use.
+
 Verify the result:
 
 ```bash
 npx @motion-proto/live-tokens check-component <id>
 ```
 
-The validator checks the file layout, the `:global(:root)` block, the token-suffix vocabulary, the state-before-property rule, the no-raw-color-defaults rule, the public-imports rule, and the `registerComponent({ id })` call. Exit code 0 means the static contract is met. Use it after Claude generates a component, and as a pre-commit guard on hand-authored ones.
+The validator checks the file layout, the `:global(:root)` block, the token-suffix vocabulary, the state-before-property rule, the public-imports rule, the `registerComponent({ id })` call, and that every default resolves to a theme token rather than a literal. Exit code 0 means the static contract is met. A project scaffolded by `create` runs it, with `check-page`, as `npm run check:design` before every `vite build`, so a component or page that opts out of the theme cannot ship by accident.
 
 ## From edit to production
 

package/bin/check-component.mjs

@@ -10,26 +10,92 @@
 //   - token names match --<id>-<part>[-<state>][-<element>]-<property>
 //     with the property being one of the recognised suffixes,
 //     and state coming before property (never after)
-//   - :global(:root) defaults reference theme tokens (no raw colour literals)
+//   - :global(:root) defaults are semantic: every one resolves to a real theme
+//     token, so the component repaints when the theme changes. A value with no
+//     token behind it must be a declared intrinsic (a structural keyword the
+//     editor exports in `intrinsics`), never a literal.
 //
-// Returns { errors: string[], warnings: string[] }.
+// Returns { errors, warnings, findings }. `errors`/`warnings` are the message
+// strings; `findings` carries the same items with a stable `rule` id and line
+// number for --json consumers.
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { extname, join, relative } from 'node:path';
+import { hasColorLiteral, hasDimensionLiteral, stripVarFallbacks } from './lib/cssValues.mjs';
+import { lineOf } from './lib/findings.mjs';
+import { PKG_ROOT, declaredCustomProperties, extractGlobalRootBlocks, isContractToken, loadVocabulary } from './lib/tokenVocabulary.mjs';
 
-// Property suffixes the editor picker recognises (KIND_PATTERNS in the editor).
-// Keep in sync with the skill's suffix vocabulary.
-const KNOWN_SUFFIXES = [
-  'surface', 'border', 'text', 'icon', 'label', 'fill',
-  'radius', 'border-width', 'font-family', 'font-weight',
-  'font-size', 'line-height', 'letter-spacing', 'padding',
-  'thickness', 'width', 'color', 'size', 'gap', 'opacity',
-  'shadow', 'blur', 'divider',
-];
+export const COMPONENT_RULES = {
+  'invalid-id': 'error',
+  'missing-file': 'error',
+  'missing-root-block': 'error',
+  'no-tokens': 'error',
+  'state-after-property': 'error',
+  'disabled-is-terminal': 'error',
+  'unknown-suffix': 'error',
+  'phantom-editor-token': 'error',
+  'color-literal': 'error',
+  'missing-component-const': 'error',
+  'missing-all-tokens': 'error',
+  'deep-import': 'error',
+  'missing-registration': 'error',
+  'unknown-token-ref': 'error',
+  'default-not-token': 'error',
+  'phantom-link': 'warn',
+  'dimension-literal': 'warn',
+};
+
+// Shipped components keep their editor beside the other editors; a
+// consumer-authored one sits next to its runtime. Probe both.
+const EDITOR_DIRS = ['src/system/components', 'src/editor/component-editor'];
+
+// Property suffixes come from the editor's own kind table, so the checker and
+// the picker can never disagree about what a name means. Read as text rather
+// than imported: this module must load without the compiled engine (CI runs the
+// suite before the plugin is built).
+const ALIAS_KINDS = 'src/editor/core/components/aliasKinds.ts';
+
+function readKnownSuffixes(root) {
+  for (const base of [root, PKG_ROOT]) {
+    const path = join(base, ALIAS_KINDS);
+    if (!existsSync(path)) continue;
+    const src = readFileSync(path, 'utf8');
+    const block = src.match(/KIND_RULES[^=]*=\s*\[([\s\S]*?)\n\];/);
+    if (!block) continue;
+    const out = new Set();
+    for (const m of block[1].matchAll(/suffix:\s*\[([\s\S]*?)\]/g)) {
+      for (const n of m[1].matchAll(/'-([a-z0-9-]+)'/g)) out.add(n[1]);
+    }
+    if (out.size > 0) return [...out];
+  }
+  return [];
+}
+
+const BUILT_IN_REGISTRY = 'src/editor/component-editor/registry.ts';
+
+/** True when `id` is one of the package's own components. */
+function isBuiltIn(id) {
+  for (const base of [PKG_ROOT, process.cwd()]) {
+    const path = join(base, BUILT_IN_REGISTRY);
+    if (!existsSync(path)) continue;
+    const src = readFileSync(path, 'utf8');
+    const block = src.match(/builtInRegistry[^=]*=\s*Object\.freeze\(\{([\s\S]*?)\n\}\);/);
+    if (block && new RegExp(`\\bid:\\s*'${id}'`).test(block[1])) return true;
+  }
+  return false;
+}
+
+// Per-side padding names (`--card-body-padding-top`) are written by the padding
+// selector, never declared by hand, and belong with their parent.
+const SIDE_SUFFIXES = ['-top', '-right', '-bottom', '-left'];
 
 // State tokens that must come *before* the property, never after.
 const STATE_TOKENS = ['hover', 'disabled', 'selected', 'focus', 'active', 'focused'];
 
+// Disabled is terminal: a disabled component cannot be hovered, focused, or
+// selected, so a token naming both describes a state that never paints.
+const TERMINAL_CONFLICTS = ['hover', 'focus', 'focused', 'selected', 'on', 'active', 'checked'];
+
 // Deep imports into the package internals are not a supported API.
 const DEEP_IMPORT_PATTERNS = [
   /^@motion-proto\/live-tokens\/src\//,
@@ -50,39 +116,47 @@ function extractImports(source) {
   return out;
 }
 
-function extractGlobalRootBlocks(source) {
-  const blocks = [];
-  const re = /:global\(:root\)\s*\{([^}]*)\}/g;
-  let m;
-  while ((m = re.exec(source)) !== null) {
-    blocks.push(m[1]);
-  }
-  return blocks;
-}
-
-function extractTokensForId(blocks, id) {
+/**
+ * `--<id>-*` tokens declared in the given blocks.
+ *
+ * The prefix may also be the hyphenated word form of the id: CornerBadge is
+ * registered as `cornerbadge` but names its tokens `--corner-badge-*`, and the
+ * whole system (config, theme, editor) follows that. Segments never end on a
+ * hyphen, so a trailing `-` cannot be mistaken for a token name.
+ */
+function extractTokensForId(blocks, id, kebab) {
   const tokens = new Set();
-  const re = new RegExp(`--${id}-[a-z0-9-]+`, 'g');
-  for (const block of blocks) {
-    const matches = block.match(re) ?? [];
-    for (const t of matches) tokens.add(t);
+  // Comments name tokens too (`the --card-hover-* tokens`); they are prose.
+  blocks = blocks.map((b) => b.replace(/\/\*[\s\S]*?\*\//g, ' '));
+  const prefixes = kebab && kebab !== id ? [id, kebab] : [id];
+  for (const prefix of prefixes) {
+    const re = new RegExp(`--${prefix}(?:-[a-z0-9]+)+`, 'g');
+    for (const block of blocks) {
+      for (const t of block.match(re) ?? []) tokens.add(t);
+    }
   }
   return [...tokens];
 }
 
-function tokenSuffix(token) {
-  for (const suffix of KNOWN_SUFFIXES) {
-    if (token.endsWith(`-${suffix}`)) return suffix;
+/** `CornerBadge` -> `corner-badge`; the other accepted token prefix. */
+function kebabOf(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+function tokenSuffix(token, known) {
+  const bare = SIDE_SUFFIXES.find((x) => token.endsWith(x)) ? token.slice(0, token.lastIndexOf('-')) : token;
+  for (const suffix of known) {
+    if (bare.endsWith(`-${suffix}`)) return suffix;
   }
   return null;
 }
 
-function detectStateAfterProperty(token) {
+function detectStateAfterProperty(token, known) {
   // e.g. --comp-part-surface-hover (wrong) vs --comp-part-hover-surface (right)
   for (const state of STATE_TOKENS) {
     if (token.endsWith(`-${state}`)) {
       const head = token.slice(0, -(state.length + 1));
-      if (tokenSuffix(head)) return state;
+      if (tokenSuffix(head, known)) return state;
     }
   }
   return null;
@@ -125,85 +199,266 @@ function findFilesRecursive(dir, exts) {
   return out;
 }
 
-export function checkComponent(id, root = process.cwd()) {
+/**
+ * Every token the editor names in a row: `variable: '--x'`, the type-group
+ * `colorVariable` / `familyVariable` / ... keys, and the arrow form intrinsics
+ * use. A `${...}` hole stands for a variant segment. Per-side padding names are
+ * written by the padding selector rather than declared, so they resolve to
+ * their parent.
+ */
+function editorTokenRefs(editor) {
+  const literals = new Set();
+  const patterns = [];
+  for (const m of editor.matchAll(/\b(?:variable|[a-zA-Z]+Variable)\s*:\s*(?:\([^)]*\)\s*=>\s*)?[`'"](--(?:\$\{[^}]*\}|[^`'"])+)[`'"]/g)) {
+    const name = stripSide(m[1]);
+    if (name.includes('${')) {
+      patterns.push([name, new RegExp(`^${name.replace(/[.*+?^()|[\]\\]/g, '\\$&').replace(/\$\{[^}]*\}/g, '[a-z0-9-]+')}$`)]);
+    } else {
+      literals.add(name);
+    }
+  }
+  return { literals, patterns };
+}
+
+function stripSide(token) {
+  const side = SIDE_SUFFIXES.find((x) => token.endsWith(x));
+  return side ? token.slice(0, -side.length) : token;
+}
+
+/**
+ * Token patterns the editor declares in `intrinsics` — the only tokens allowed a
+ * bare keyword instead of a theme token.
+ *
+ * Matched on each spec's `variable`, not its `key`: the two need not agree
+ * (Image's `zoom` key declares `--image-zoom-enabled`), and `variable` is what
+ * actually names the token. A `${...}` hole stands for a variant segment.
+ */
+function intrinsicMatchers(editor) {
+  const block = editor.match(/export\s+const\s+intrinsics[^=]*=\s*\[([\s\S]*?)\];/);
+  if (!block) return [];
+  const out = [];
+  for (const m of block[1].matchAll(/\bvariable\s*:[^`'"]*[`'"]([^`'"]+)[`'"]/g)) {
+    const pattern = m[1]
+      .replace(/[.*+?^${}()|[\]\\]/g, (c) => (c === '$' ? '$' : `\\${c}`))
+      .replace(/\$\\\{[^}]*\\\}/g, '[a-z0-9-]+')
+      .replace(/\$\{[^}]*\}/g, '[a-z0-9-]+');
+    out.push(new RegExp(`^${pattern}$`));
+  }
+  return out;
+}
+
+/**
+ * The semantic half of the contract: a component token is a *property name*, and
+ * its default is the theme token that property reads. So every default must
+ * resolve to a real token — otherwise the component stops repainting when the
+ * theme changes, which is the whole point of declaring it.
+ */
+function checkDefaultsAreSemantic({ blocks, runtime, editor, root, runtimePath, record, vocabulary }) {
+  const vocab = vocabulary ?? loadVocabulary({ root });
+  const matchers = intrinsicMatchers(editor);
+  const rel = relative(root, runtimePath);
+
+  const own = new Set();
+  for (const block of blocks) {
+    for (const m of block.matchAll(/(?:^|[;{])\s*(--[a-z0-9-]+)\s*:/gm)) own.add(m[1]);
+  }
+
+  for (const block of blocks) {
+    for (const m of block.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+      const [decl, name, raw] = m;
+      const value = raw.trim();
+      const at = runtime.indexOf(decl);
+
+      const painted = stripVarFallbacks(value);
+      const refs = [...painted.matchAll(/var\(\s*(--[a-z0-9-]+)/g)].map((x) => x[1]);
+      for (const ref of refs) {
+        if (own.has(ref) || vocab.knows(ref)) continue;
+        record(
+          'unknown-token-ref',
+          STATE_TOKENS.includes(ref.replace(/^--/, '').split('-')[0])
+            ? `${rel}: ${name} reads ${ref}, but a state is a segment of a property name, not a token of its own; read the token the state should paint`
+            : isContractToken(ref)
+              ? `${rel}: ${name} reads ${ref}, which looks like a theme token but no longer exists; check tokens.css for a rename`
+              : `${rel}: ${name} reads ${ref}, which is not a theme token or a component token`,
+          at,
+        );
+      }
+
+      if (hasColorLiteral(painted)) {
+        record(
+          'color-literal',
+          `${rel}: ${name}: ${value} is a colour literal; defaults must reference theme tokens (e.g. var(--surface-primary))`,
+          at,
+        );
+        continue;
+      }
+
+      if (refs.length === 0 && !matchers.some((re) => re.test(name))) {
+        record(
+          'default-not-token',
+          `${rel}: ${name}: ${value} has no theme token behind it; back it with a token, or declare it in the editor's \`intrinsics\` if it is a structural keyword`,
+          at,
+        );
+      }
+
+      if (hasDimensionLiteral(painted)) {
+        record(
+          'dimension-literal',
+          `${rel}: ${name}: ${value} pins a raw dimension; use a --space-*, --radius-*, or --border-width-* token`,
+          at,
+        );
+      }
+    }
+  }
+}
+
+export function checkComponent(id, root = process.cwd(), { vocabulary } = {}) {
   const errors = [];
   const warnings = [];
+  const findings = [];
+  let file = '';
+  let source = '';
+
+  const record = (rule, message, index = -1) => {
+    findings.push({
+      rule,
+      file,
+      line: index >= 0 && source ? lineOf(source, index) : 1,
+      message,
+    });
+    (COMPONENT_RULES[rule] === 'warn' ? warnings : errors).push(message);
+  };
+  const done = () => ({ errors, warnings, findings });
 
   if (!/^[a-z][a-z0-9]*$/.test(id)) {
-    errors.push(`id "${id}" is invalid; must be lowercase letters/digits, no dashes`);
-    return { errors, warnings };
+    record('invalid-id', `id "${id}" is invalid; must be lowercase letters/digits, no dashes`);
+    return done();
   }
 
-  const Id = capitalize(id);
-  const runtimePath = join(root, 'src/system/components', `${Id}.svelte`);
-  const editorPath = join(root, 'src/system/components', `${Id}Editor.svelte`);
+  // Resolve the real filename rather than capitalising the id: `cornerbadge`
+  // ships as `CornerBadge.svelte`, and the casing is what gives the kebab form
+  // of its token prefix.
+  const dir = join(root, 'src/system/components');
+  const Id =
+    (existsSync(dir) ? readdirSync(dir) : [])
+      .find((f) => f.toLowerCase() === `${id}.svelte`)
+      ?.replace('.svelte', '') ?? capitalize(id);
+  const runtimePath = join(dir, `${Id}.svelte`);
+  const editorPath =
+    EDITOR_DIRS.map((d) => join(root, d, `${Id}Editor.svelte`)).find(existsSync) ??
+    join(root, EDITOR_DIRS[0], `${Id}Editor.svelte`);
 
+  file = relative(root, runtimePath);
   if (!existsSync(runtimePath)) {
-    errors.push(`runtime missing: ${relative(root, runtimePath)}`);
+    record('missing-file', `runtime missing: ${relative(root, runtimePath)}`);
   }
   if (!existsSync(editorPath)) {
-    errors.push(`editor missing: ${relative(root, editorPath)}`);
+    record('missing-file', `editor missing: ${relative(root, editorPath)}`);
   }
-  if (errors.length) return { errors, warnings };
+  if (errors.length) return done();
 
   const runtime = readFileSync(runtimePath, 'utf8');
   const editor = readFileSync(editorPath, 'utf8');
+  source = runtime;
 
   // Runtime: :global(:root) block present.
   const blocks = extractGlobalRootBlocks(runtime);
   if (blocks.length === 0) {
-    errors.push(`${relative(root, runtimePath)}: missing :global(:root) declaration block`);
+    record('missing-root-block', `${relative(root, runtimePath)}: missing :global(:root) declaration block`);
   }
 
   // Runtime: at least one --<id>-* token.
-  const tokens = extractTokensForId(blocks, id);
+  const tokens = extractTokensForId(blocks, id, kebabOf(Id));
   if (blocks.length > 0 && tokens.length === 0) {
-    errors.push(`${relative(root, runtimePath)}: no --${id}-* tokens declared in :global(:root)`);
+    record('no-tokens', `${relative(root, runtimePath)}: no --${id}-* tokens declared in :global(:root)`);
   }
 
+  // A token the editor declares as an intrinsic carries a structural keyword,
+  // not a themeable value, so a property-suffix rule is the wrong test for it.
+  const intrinsic = intrinsicMatchers(editor);
+  const known = readKnownSuffixes(root);
+
   // Runtime: state-after-property anti-pattern. Report this first; if it fires
   // for a token, skip the unknown-suffix error for the same token (the state-
   // suffix wouldn't be in the suffix list anyway, so it's the same root cause).
   const stateAfterTokens = new Set();
   for (const token of tokens) {
-    const trailingState = detectStateAfterProperty(token);
+    if (intrinsic.some((re) => re.test(token))) continue;
+    const trailingState = detectStateAfterProperty(token, known);
     if (trailingState) {
       stateAfterTokens.add(token);
-      errors.push(
+      record(
+        'state-after-property',
         `${relative(root, runtimePath)}: ${token} has '${trailingState}' after the property; ` +
           `state must come before property (e.g. -${trailingState}-surface, not -surface-${trailingState})`,
+        runtime.indexOf(token),
       );
     }
   }
 
-  // Runtime: every token ends in a known suffix.
   for (const token of tokens) {
-    if (stateAfterTokens.has(token)) continue;
-    if (!tokenSuffix(token)) {
-      errors.push(`${relative(root, runtimePath)}: ${token} doesn't end in a known suffix`);
+    const segments = token.slice(2).split('-');
+    if (!segments.includes('disabled')) continue;
+    const conflict = TERMINAL_CONFLICTS.find((s) => segments.includes(s));
+    if (conflict) {
+      record(
+        'disabled-is-terminal',
+        `${relative(root, runtimePath)}: ${token} combines 'disabled' with '${conflict}'; disabled is terminal, so that state never paints. Drop the token.`,
+        runtime.indexOf(token),
+      );
     }
   }
 
-  // Runtime: defaults inside :global(:root) reference theme tokens, not raw colours.
-  for (const block of blocks) {
-    const rawColours = block.match(/:\s*#[0-9a-fA-F]{3,8}\b/g) ?? [];
-    if (rawColours.length > 0) {
-      errors.push(
-        `${relative(root, runtimePath)}: :global(:root) contains ${rawColours.length} raw colour literal(s); ` +
-          `defaults must reference theme tokens (e.g. var(--surface-primary))`,
+  // Runtime: every token ends in a known suffix.
+  for (const token of tokens) {
+    if (stateAfterTokens.has(token) || intrinsic.some((re) => re.test(token))) continue;
+    if (!tokenSuffix(token, known)) {
+      record(
+        'unknown-suffix',
+        `${relative(root, runtimePath)}: ${token} doesn't end in a known suffix`,
+        runtime.indexOf(token),
       );
     }
   }
 
+  checkDefaultsAreSemantic({ blocks, runtime, editor, root, runtimePath, record, vocabulary });
+
   // Editor: declares `const component = '<id>'` (module block).
   const componentDecl = new RegExp(`\\bconst\\s+component\\s*=\\s*['"]${id}['"]`);
   if (!componentDecl.test(editor)) {
-    errors.push(`${relative(root, editorPath)}: missing 'const component = "${id}"' in <script module>`);
+    record(
+      'missing-component-const',
+      `${relative(root, editorPath)}: missing 'const component = "${id}"' in <script module>`,
+    );
   }
 
   // Editor: exports allTokens.
   if (!/\bexport\s+const\s+allTokens\b/.test(editor)) {
-    errors.push(`${relative(root, editorPath)}: missing 'export const allTokens'`);
+    record('missing-all-tokens', `${relative(root, editorPath)}: missing 'export const allTokens'`);
+  }
+
+  // Editor: every token a row names is one the runtime declares. A row that
+  // names nothing renders a control that edits nothing.
+  const declared = new Set();
+  for (const block of blocks) {
+    for (const n of declaredCustomProperties(block.replace(/\/\*[\s\S]*?\*\//g, ' '))) declared.add(n);
+  }
+  const refs = editorTokenRefs(editor);
+  for (const name of refs.literals) {
+    if (!declared.has(name)) {
+      record(
+        'phantom-editor-token',
+        `${relative(root, editorPath)}: names ${name}, which ${relative(root, runtimePath)} never declares in :global(:root)`,
+      );
+    }
+  }
+  for (const [name, re] of refs.patterns) {
+    if (![...declared].some((d) => re.test(d))) {
+      record(
+        'phantom-editor-token',
+        `${relative(root, editorPath)}: names ${name}, which matches nothing ${relative(root, runtimePath)} declares in :global(:root)`,
+      );
+    }
   }
 
   // Editor: phantom-link guard. The font type-group helpers fall back to bare
@@ -221,7 +476,8 @@ export function checkComponent(id, root = process.cwd()) {
   const fontBare =
     hasBareCall(editor, 'buildTypeGroupFontTokens') || hasBareCall(editor, 'buildTypeGroupTokens');
   if (slots > 1 && fontBare) {
-    warnings.push(
+    record(
+      'phantom-link',
       `${relative(root, editorPath)}: a type-group font helper is called across ${slots} slots without a derivation; ` +
         `its bare font-family/font-size/… keys would phantom-link every slot's fonts. Pass { component, variants } to buildTypeGroupTokens/buildTypeGroupFontTokens.`,
     );
@@ -232,7 +488,7 @@ export function checkComponent(id, root = process.cwd()) {
     for (const imp of extractImports(source)) {
       for (const pattern of DEEP_IMPORT_PATTERNS) {
         if (pattern.test(imp)) {
-          errors.push(`${relative(root, path)}: deep import not supported: ${imp}`);
+          record('deep-import', `${relative(root, path)}: deep import not supported: ${imp}`);
         }
       }
     }
@@ -257,21 +513,44 @@ export function checkComponent(id, root = process.cwd()) {
       // ignore unreadable files
     }
   }
+  // A first-party component is registered by membership in the package's own
+  // `builtInRegistry`, not by a `registerComponent` call, so look there too
+  // before calling it unregistered.
+  if (!registrationFile && isBuiltIn(id)) return done();
+
   if (!registrationFile) {
-    errors.push(`no registration for '${id}' under src/ — expected registerComponent({ id: '${id}', ... }) or bootLiveTokens({ components: [{ id: '${id}', ... }] })`);
+    record(
+      'missing-registration',
+      `no registration for '${id}' under src/ — expected registerComponent({ id: '${id}', ... }) or bootLiveTokens({ components: [{ id: '${id}', ... }] })`,
+    );
   } else {
     // Check the registration file's imports too.
     const regSource = readFileSync(registrationFile, 'utf8');
     for (const imp of extractImports(regSource)) {
       for (const pattern of DEEP_IMPORT_PATTERNS) {
         if (pattern.test(imp)) {
-          errors.push(`${relative(root, registrationFile)}: deep import not supported: ${imp}`);
+          record('deep-import', `${relative(root, registrationFile)}: deep import not supported: ${imp}`);
         }
       }
     }
   }
 
-  return { errors, warnings };
+  return done();
+}
+
+/**
+ * Every component authored in `root`: a runtime file under
+ * src/system/components with an editor beside it or in the package's editor
+ * directory. What `check-component` runs over when no id is named.
+ */
+export function discoverComponents(root = process.cwd()) {
+  const dir = join(root, 'src/system/components');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.svelte') && !f.endsWith('Editor.svelte'))
+    .map((f) => f.replace('.svelte', ''))
+    .filter((Id) => EDITOR_DIRS.some((d) => existsSync(join(root, d, `${Id}Editor.svelte`))))
+    .map((Id) => Id.toLowerCase());
 }
 
 export function formatReport(id, result) {
@@ -290,3 +569,28 @@ export function formatReport(id, result) {
   }
   return lines.join('\n');
 }
+
+/**
+ * The half of the contract that holds for every component, shipped or authored:
+ * each `:global(:root)` default is a semantic property backed by a real token.
+ *
+ * Takes a runtime file rather than an id, so it works on the shipped naming
+ * (`SectionDivider.svelte`) that an id round-trip would flatten, and it skips
+ * the consumer-only rules — registration and file layout — that shipped
+ * components satisfy through the package's own registry instead.
+ */
+export function checkComponentDefaults(runtimePath, { root = process.cwd(), vocabulary } = {}) {
+  const findings = [];
+  const runtime = readFileSync(runtimePath, 'utf8');
+  const rel = relative(root, runtimePath);
+  const record = (rule, message, index = -1) =>
+    findings.push({ rule, file: rel, line: index >= 0 ? lineOf(runtime, index) : 1, message });
+
+  const name = runtimePath.slice(runtimePath.lastIndexOf('/') + 1).replace('.svelte', '');
+  const editorPath = EDITOR_DIRS.map((d) => join(root, d, `${name}Editor.svelte`)).find(existsSync);
+  const editor = editorPath ? readFileSync(editorPath, 'utf8') : '';
+
+  const blocks = extractGlobalRootBlocks(runtime);
+  checkDefaultsAreSemantic({ blocks, runtime, editor, root, runtimePath, record, vocabulary });
+  return findings;
+}