@motion-proto/live-tokens 0.70.0 → 0.72.0

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

@@ -0,0 +1,78 @@
+---
+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`. Where a whole file is not a themed surface at all,
+hand-tuned artwork or vendored CSS, the entry is
+`"checks": { "exclude": ["src/art/hero.css"] }` — a project-relative path, a
+directory covering what is under it, and naming the file on the command line
+still checks it. Prefer the narrower one: an exclusion drops one file, a
+severity change drops a rule everywhere. Recording either 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-create-component/SKILL.md

@@ -230,9 +230,9 @@ It *warns* (non-fatal) when a token-backed default still carries a px or rem ter
 
 Exit code 0 means the static contract is met. Resolve warnings before shipping, or run with `--strict` to make them fail. `--json` prints findings with a stable `rule` id, so you can work through one rule at a time and re-run.
 
-**Then run the registry contract test.** If you're authoring inside the package itself, `src/editor/component-editor/registryContract.test.ts` runs `describe.each(getComponentRegistryEntries())` and verifies, per component, that the registration resolves to a real `sourceFile` and a non-empty schema, that schema variables are unique, that every editable token (excluding `hidden: true`, `kind: 'gradient'`, and padding-side suffixes) is declared in the runtime `<style>` block and seeded in `src/live-tokens/data/component-configs/<id>/default.json`, and that `setComponentAlias` round-trips the alias through the slice.
+**Then run the registry contract test.** `checkRegistryEntry`, from `@motion-proto/live-tokens/component-editor/contract`, takes one registry entry and returns a violation line per failure, so a suite over your own components is a `describe.each` and one call. Per component it verifies that the registration resolves to a real `sourceFile` and a non-empty schema, that schema variables are unique, that every editable token is declared in the runtime `<style>` block and seeded in `component-configs/<id>/default.json`, that a token declaring `minOpacity` seeds at or above its floor, and that `setComponentAlias` round-trips the alias through the slice. The test file, the two lines in it that are load-bearing, and the path options are in `references/contract-tests.md`.
 
-A new first-party component is auto-covered the moment it lands in `builtInRegistry` — `npm test` will fail if any of the five checks miss. For a consumer-authored component, mirror this pattern in your own test suite if you want the same drift protection: `getComponentRegistryEntries` is exported from `@motion-proto/live-tokens` and returns every registration, shipped and custom, once your `main.ts` has run.
+Inside the package, `src/editor/component-editor/registryContract.test.ts` is that same file over `builtInRegistry`, so a new first-party component is auto-covered the moment it lands there — `npm test` fails if any check misses.
 
 **If your component declares `intrinsics`, the intrinsics contract test covers it too.** `src/editor/component-editor/intrinsicsContract.test.ts` iterates every entry with an `intrinsics` array and asserts, per (intrinsic, variant), that the runtime `:global(:root)` declares a default, the default is one of the spec's `values`, and the editor's `default` equals the runtime default. This is what would have caught a getter defaulting to `center` while `:global(:root)` says `start`. Same auto-coverage rule: declare `intrinsics` on the registry entry and the test picks it up.
 

package/.claude/skills/live-tokens-create-component/references/contract-tests.md

@@ -0,0 +1,99 @@
+# The registry contract as a test in your own project
+
+`checkRegistryEntry` is the contract the package holds its own 26 components
+to, exported so a project outside the package can run it over its own. It takes
+one registry entry and returns a violation line per failure; an empty array is
+the pass.
+
+```ts
+// tests/registryContract.test.ts
+// @vitest-environment happy-dom
+import { describe, it, expect } from 'vitest';
+import { getComponentRegistryEntries, registerComponent } from '@motion-proto/live-tokens';
+import { checkRegistryEntry } from '@motion-proto/live-tokens/component-editor/contract';
+import MyWidgetEditor, { allTokens } from '../src/system/components/MyWidgetEditor.svelte';
+
+registerComponent({
+  id: 'mywidget',
+  label: 'My Widget',
+  icon: 'fas fa-magic',
+  sourceFile: 'src/system/components/MyWidget.svelte',
+  editorComponent: MyWidgetEditor,
+  schema: allTokens,
+});
+
+const mine = getComponentRegistryEntries().filter((e) => e.origin === 'custom');
+
+describe.each(mine.map((e) => [e.id, e] as const))('%s', (_id, entry) => {
+  it('meets the registry contract', () => {
+    expect(checkRegistryEntry(entry)).toEqual([]);
+  });
+});
+```
+
+Two lines there are load-bearing.
+
+- **Register at the top of the test file**, rather than importing `main.ts`.
+  The entries have to exist before `describe.each` reads them, and
+  `bootLiveTokens` would mount the app.
+- **Filter on `origin`.** The registry always carries the shipped components
+  too, and their `sourceFile` paths are relative to the package root, not
+  yours. Without the filter every built-in fails on a path that does not exist
+  in your project.
+
+## Setup
+
+`vitest` and `happy-dom` as devDependencies, and the svelte plugin already in
+`vite.config.ts` so the editor `.svelte` import resolves. The helper reads the
+runtime file and `default.json` off disk, which is why it is node-only and has
+its own subpath.
+
+The package ships Svelte and TypeScript source, and `bootLiveTokens` imports the
+FontAwesome stylesheet. Left external, Node meets that `.css` and stops with
+`Unknown file extension ".css"`, before a single test runs. Inline both so Vite
+transforms them:
+
+```ts
+// vitest.config.ts
+import { defineConfig, mergeConfig } from 'vitest/config';
+import viteConfig from './vite.config';
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      server: { deps: { inline: [/@motion-proto\/live-tokens/, /@fortawesome/] } },
+    },
+  }),
+);
+```
+
+## Paths
+
+Paths resolve against `process.cwd()` and `src/live-tokens/data/component-configs`.
+A project that moved either passes them:
+
+```ts
+checkRegistryEntry(entry, { projectRoot, componentConfigsDir });
+```
+
+`componentConfigsDir` is the same directory `live-tokens.config.json` names.
+
+## What it holds
+
+1. **Registration** — `sourceFile` resolves to a real file, the schema is non-empty.
+2. **Uniqueness** — no schema variable is declared twice.
+3. **Editor to runtime** — every editable token's CSS var is declared in the
+   runtime's `<style>` block, so an edit has something to repaint.
+4. **Editor to default config** — every editable token has a seed alias in
+   `component-configs/<id>/default.json`, so the component adopts with full
+   defaults. A component with no `default.json` is editor-only; this check and
+   the next one skip it.
+5. **Opacity floors** — a token declaring `minOpacity` ships a default at or
+   above it, so a floating panel starts out legible over page content.
+6. **Round-trip** — `setComponentAlias` persists into the slice under the same key.
+
+Checks 3 and 4 exclude `hidden: true` tokens, `kind: 'gradient'` tokens (stored
+as gradient objects, not vars), and `-padding-(top|right|bottom|left)` suffixes
+(written on demand by the split-padding UI and read through the `themed-padding`
+mixin's fallback chain, so they exist as neither `:root` declarations nor seeds).

package/.claude/skills/live-tokens-create-component/references/sketch-mode.md

@@ -176,8 +176,7 @@ inherits, so one declaration covers everything under it:
 
 Travel is stated in px against a glyph whose size the layer cannot know, so the
 dial that suits a card's worth of artwork tears a 16px icon apart. Reach for the
-soft bank before reaching for `none`. The shipped `SectionDivider` is the worked
-example.
+soft bank before reaching for `none`.
 
 ## First-party components
 

package/.claude/skills/live-tokens-create-component/references/token-naming.md

@@ -64,6 +64,12 @@ to that list, so the two cannot drift apart.
 | `-padding`      | Internal spacing                                              |
 | `-gap`          | Spacing between sibling elements                              |
 
+`-width`, `-height` and `-size` are the fall-through: any dimension with no
+more specific name behind it. They read the `--space-*` scale through the same
+picker `-gap` uses, and they match last, so `-border-width`, `-divider-height`,
+`-icon-size` and the rest claim their token first. Reach for the specific name
+when one fits; a stroke is `-border-width` even where the CSS says `outline:`.
+
 ## Typography
 
 | Suffix             | Meaning                  |

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,105 @@
 # Changelog
 
+## 0.72.0 — The contract a consumer can run
+
+### Added
+
+- **The registry contract is a function a consumer can run.** The six
+  per-component checks that hold this package's own components — registration
+  resolves, schema variables are unique, every editable token is declared in
+  the runtime `<style>` and seeded in `default.json`, a declared `minOpacity`
+  is honoured, `setComponentAlias` round-trips — are now `checkRegistryEntry`,
+  exported from `@motion-proto/live-tokens/component-editor/contract`. It takes
+  one registry entry and returns a violation line per failure, so a project
+  outside this package holds its own components to the same contract with a
+  `describe.each` and one call. Paths resolve against `process.cwd()` and
+  `src/live-tokens/data/component-configs`, or the `projectRoot` and
+  `componentConfigsDir` passed in. Node-only, hence its own subpath.
+  `live-tokens-create-component` carries the test file in
+  `references/contract-tests.md`; filtering the registry on
+  `origin === 'custom'` is the line that matters, since the shipped entries
+  name paths relative to the package root.
+
+- **`"checks": { "exclude": [...] }` in `live-tokens.config.json`.** Paths the
+  checkers skip when they discover their own targets: a project-relative path,
+  a directory covering what is under it. For a file that is not a themed
+  surface at all — hand-tuned artwork, vendored CSS — where the only other way
+  out was downgrading a rule for the whole project. Naming the file on the
+  command line still checks it, so the escape hatch cannot hide a file from
+  someone looking straight at it. The dev plugin now also recognises `checks`
+  and `componentDirs`, which the CLI has read for some time while the plugin
+  warned they were unknown keys.
+
+### Changed (breaking)
+
+- **`FloatingTokenTags` is demo artwork, not a shipped component.** It moved to
+  `src/demo/`, so it leaves the published package, the component query and the
+  count, which now agree with the registry at 26. **Breaking for anyone
+  importing `@motion-proto/live-tokens/components/FloatingTokenTags.svelte`;**
+  it was only ever the hero animation of the demo, and it never had a
+  `:global(:root)` block, an editor, or a registry entry.
+
+- **The SectionDivider title outline is removed.** It was the only reason the title was an
+  SVG `<text>` behind a `feMorphology` filter rather than an element, and that
+  SVG carried a `getBBox()` viewBox, a per-instance `MutationObserver` on the
+  document's inline style (filter primitives cannot read a CSS var, so the
+  resolved width and colour had to be read back and pushed onto them by hand),
+  font-load listeners to re-measure, and a title that was neither selectable nor
+  findable. It shipped transparent in the default and in all eight presets, and
+  the trap-out it was built for is done by the layout: the `through-label`
+  hairlines flank the title in a flex row, so no rule ever runs behind the
+  glyphs. The title is now a span that inherits typography like every other
+  component's. `--sectiondivider-{lg,md,sm}-title-outline-width` and
+  `-title-outline-color` are dropped by a component-config migration; the
+  `outlineWidthVariable` / `outlineColorVariable` rows on `TypeGroupConfig` go
+  with them, since nothing else declared one.
+
+### Changed
+
+- **`registered` is read from the registry for shipped components too.** The
+  query assumed a component under `src/system/components` was registered, so
+  `live-tokens components` could name one the editor cannot open and
+  pick-component does not list. It now reads the package's own
+  `builtInRegistry`, the same parse `check-component` uses, which the two now
+  share. A component that is discovered but registered nowhere reports
+  `registered: false`, prints `(NOT registered)`, and is counted out of the
+  catalogue in the summary line.
+
+### Fixed
+
+- **A bare `-width`, `-height` or `-size` no longer renders a colour picker.**
+  The three sat in `KIND_RULES` under `surface`, so `--widget-panel-width` drew
+  a palette while the naming vocabulary documented it as geometry. They are now
+  a `length` kind, matched last among the geometry rules so `-border-width`,
+  `-divider-height`, `-icon-size` and the rest still claim their token first,
+  and drawn with the `--space-*` picker `-gap` uses. The suffix vocabulary is
+  unchanged, so no token is renamed and no project has to migrate. `adjust`
+  does not take the kind: its ladders are density and shape, and a panel width
+  is neither.
+
+## 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

@@ -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.** 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.
+- **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, Slider) 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.
@@ -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-component.mjs

@@ -23,7 +23,7 @@ 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';
+import { PKG_ROOT, builtInIds, declaredCustomProperties, extractGlobalRootBlocks, isContractToken, loadVocabulary } from './lib/tokenVocabulary.mjs';
 
 export const COMPONENT_RULES = {
   'invalid-id': 'error',
@@ -71,18 +71,9 @@ function readKnownSuffixes(root) {
   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;
+  return builtInIds(process.cwd(), PKG_ROOT).has(id);
 }
 
 // Per-side padding names (`--card-body-padding-top`) are written by the padding

package/bin/check-page.mjs

@@ -12,7 +12,7 @@
 
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, relative, resolve, basename } from 'node:path';
-import { lineOf } from './lib/findings.mjs';
+import { isExcluded, 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';
@@ -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 = [
@@ -382,6 +382,7 @@ export function discoverPages(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 (isExcluded(rel, root)) 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);
@@ -396,7 +397,7 @@ export function checkPages(targets, { root = process.cwd(), vocabulary } = {}) {
     const full = resolve(root, t);
     if (!existsSync(full)) continue;
     if (statSync(full).isDirectory()) {
-      files.push(...walk(full, ['.svelte', '.css']));
+      files.push(...walk(full, ['.svelte', '.css']).filter((f) => !isExcluded(relative(root, f), root)));
     } else {
       files.push(full);
     }

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
@@ -67,7 +75,8 @@ Both check commands accept:
   --strict                    Treat warnings as errors
   --off=<rule,...>            Silence rules; --warn=/--error= change severity
                               (or set "checks": { "rules": {...} } in
-                              live-tokens.config.json)
+                              live-tokens.config.json; "checks": { "exclude":
+                              [...] } drops paths from discovery entirely)
   generate-theme <brief.json> [--no-activate] [--dry-run] [--carry-from <name>]
                               Build a full theme from a 10-seed OKLCH brief
                               (see the live-tokens-generate-theme skill),
@@ -190,6 +199,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 +395,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/catalogue.mjs

@@ -44,7 +44,7 @@ export function describeComponents(vocab, { root = process.cwd() } = {}) {
       name: entry.name,
       origin: entry.origin,
       file: relative(root, entry.file),
-      registered: entry.origin === 'shipped' || vocab.registered.has(entry.id),
+      registered: vocab.builtIn.has(entry.id) || vocab.registered.has(entry.id),
       description: descriptionOf(source),
       variants: entry.props?.enums.get('variant') ? [...entry.props.enums.get('variant')] : [],
       props,
@@ -99,7 +99,11 @@ export function formatComponents(list, { id } = {}) {
     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.`);
+  const unregistered = list.filter((c) => !c.registered).length;
+  lines.push(
+    `${list.length} component(s)${unregistered ? `, ${unregistered} not registered and so not in the catalogue` : ''}. ` +
+      '`live-tokens components <id>` prints one with its props and tokens.',
+  );
   return lines.join('\n');
 }
 

package/bin/lib/findings.mjs

@@ -30,6 +30,23 @@ export function readChecksConfig(root) {
   }
 }
 
+/**
+ * `checks.exclude` in live-tokens.config.json: paths the checkers do not read
+ * when they discover their own targets. Each entry is a project-relative path;
+ * a directory entry covers everything under it. For a file that is not a themed
+ * surface — hand-tuned artwork, vendored CSS — where the alternative is
+ * downgrading a rule for the whole project. Naming the file explicitly on the
+ * command line still checks it.
+ */
+export function isExcluded(relPath, root) {
+  const list = readChecksConfig(root).exclude;
+  if (!Array.isArray(list)) return false;
+  return list.some((entry) => {
+    const e = String(entry).replace(/\/+$/, '');
+    return relPath === e || relPath.startsWith(`${e}/`);
+  });
+}
+
 /**
  * Parse `--off=a,b --warn=c --error=d --strict --json` out of argv.
  * Unrecognised flags are returned in `rest` for the caller to handle.