@motion-proto/live-tokens 0.69.0 → 0.71.0

package/.claude/skills/live-tokens-build-page/SKILL.md

@@ -7,7 +7,7 @@ description: Apply the @motion-proto/live-tokens project conventions when buildi
 
 Two rules above all else:
 
-1. **Use a shipped component if one fits.** Import from `@motion-proto/live-tokens/components/<Name>.svelte`. See **live-tokens-pick-component** for the catalogue and the confusing-pair decisions. Pass only the props its `interface Props` declares, with variant and size values from its union: a prop it does not declare is dropped silently at runtime, and the checker reports it. Author custom markup only when nothing fits, and then consider **live-tokens-create-component** so the new piece is editable too.
+1. **Use a shipped component if one fits.** Import from `@motion-proto/live-tokens/components/<Name>.svelte`. See **live-tokens-pick-component** for the catalogue and the confusing-pair decisions. Pass only the props it declares, with variant and size values from its union: `npx live-tokens components <id>` prints them (`--json` for data), and the list includes the project's own components beside the shipped ones. A prop a component does not declare is dropped silently at runtime, and the checker reports it. Author custom markup only when nothing fits, and then consider **live-tokens-create-component** so the new piece is editable too.
 2. **Use theme tokens for every value.** Every color, spacing, radius, font-size, and font-family in page CSS is a `var(--token-*)`, whether it sits in the `<style>` block, an inline `style=` attribute, or a `style:` directive. No colour literals in any notation, `white` and `rgb()` included. No px or rem in spacing, stroke, radius, or shadow: that is the geometry the theme owns and `adjust` moves. Sizing is layout, not theme: a hero's height, a max content width, or a column's minimum width stays a literal. A change in `/live-tokens/editor` should repaint your page.
 
 For text, reach for a whole text style rather than assembling one: `--heading-xl` through `--heading-sm`, `--body-md`, `--body-sm`, `--editorial-xl` through `--editorial-sm`, `--eyebrow`, and `--code` each carry a `-font-family`, `-font-size`, `-font-weight`, `-line-height`, and `-letter-spacing`. A heading set from `--heading-lg-*` retypes when the theme's fonts change; one set from a raw `font-size` does not.

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-create-component/SKILL.md

@@ -15,11 +15,10 @@ For pattern reference, read any shipped component's source directly from the con
   - Simplest reads (no state, no linked-block): `Card` (single variant with parts), `Badge` and `Callout` (multi-variant).
   - Multi-state (hover, disabled, focus): `Button`, `Input`.
   - Multi-part (overlay / header / body / footer): `Dialog`.
-  - Multi-variant with linked siblings (`canBeLinked` + `groupKey`): `SegmentedControl`, `TabBar`.
-  - Composes another shipped component: `CodeSnippet` (renders a `Tooltip` for the copy-confirmation popover).
+  - Multi-variant with linked siblings (`canBeLinked` + `groupKey`): `SegmentedControl`, `TabBar`. Composes another shipped component: `CodeSnippet`.
 - Editor files: `node_modules/@motion-proto/live-tokens/src/editor/component-editor/<Name>Editor.svelte`.
 
-**File-location note.** Shipped editors live in `src/editor/component-editor/` because they're library-internal. For *your* component, **co-locate** both files in `src/system/components/` per the recipe below. Read the shipped files for pattern, ignore their location.
+**File-location note.** Shipped editors live in `src/editor/component-editor/` because they're library-internal. For *your* component, **co-locate** both files in `src/system/components/`. Read the shipped files for pattern, ignore their location.
 
 ## The recipe
 
@@ -43,7 +42,15 @@ For pattern reference, read any shipped component's source directly from the con
    });
    ```
    The schema side-effect happens inside `registerComponent` (which `bootLiveTokens` calls for you), so you don't call `registerComponentSchema` separately. **Do not place a standalone `registerComponent(...)` *before* `bootLiveTokens`** — that registers before the editor's init hooks run, which is the wrong window and can leave editor changes disconnected from the live page. Only call `registerComponent` directly if your app mounts manually (no `bootLiveTokens`), in which case call it before `mount(App, ...)`.
-4. **Tell the picker** — open `.claude/skills/live-tokens-pick-component/SKILL.md` and add your new component to the **Catalogue** line under the family it belongs to (Action / Input / Selection / Containers / Messaging / Display). If it's confusable with an existing component (a second selection control, a competing container), add a row to that family's decision table explaining the use-case it owns. Without this step, the component exists but **live-tokens-pick-component** can't recommend it when a user asks "which component should I use?" — the same rule applies whether the component is first-party (update the picker shipped in this package) or consumer-authored (update the local copy at `.claude/skills/live-tokens-pick-component/SKILL.md` that `setup-claude` placed in your project).
+4. **Say what it is for.** The runtime file's leading HTML comment is the
+   component's description. `npx live-tokens components` prints it beside the
+   id with the variants and props read from `interface Props` (`--json` for
+   data); that is how **live-tokens-pick-component** weighs a project's own
+   component against the shipped set, so no skill file is edited and nothing
+   is lost when `setup-claude` refreshes the skills. Name the job it does and
+   what it is not for. A directory other than `src/system/components` goes in
+   `"componentDirs"` in `live-tokens.config.json`; a first-party component is
+   also added to the picker's **Catalogue** line, which `check:skills` holds.
 5. **Join the sketch layer** — the effect draws a fixed set of parts, so a new
    component stays crisp while the page around it goes hand-drawn until it opts
    in. A consumer component carries one of four reserved classes on its root and
@@ -223,15 +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:
+**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.
 
-1. Registration resolves to a real `sourceFile` and a non-empty schema.
-2. Schema variables are unique within the component.
-3. Every editable token (excluding `hidden: true`, `kind: 'gradient'`, and padding-side suffixes) is declared in the runtime `<style>` block.
-4. Every editable token is seeded in `src/live-tokens/data/component-configs/<id>/default.json`.
-5. `setComponentAlias` round-trips the alias through the slice.
-
-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 (the same test logic works against any `registerComponent` registration; iterate `getComponentRegistryEntries()` after your `main.ts` has run).
+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.
 
 **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-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
 
@@ -64,7 +67,9 @@ Three things the loop never does:
 `color-literal` is the finding that takes judgement. The replacement is the
 token for what the colour *does*, not the token that happens to be closest in
 hue, because the theme will move every role together and the page must move
-with it. Read `tokens.css` for the names; the families are fixed.
+with it. `npx live-tokens tokens --family surface` prints a family's names and
+values (`text`, `border`, `scrim`, `tint` likewise; `--json` for data); the
+families are fixed.
 
 | The literal is | Token family | Notes |
 | --- | --- | --- |
@@ -89,7 +94,7 @@ and is never reported, so leave it.
 
 | The literal is | Token | Notes |
 | --- | --- | --- |
-| Padding, margin, gap, an offset | `--space-<px>` | Steps: 0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 64, 96, 128. Round to the nearest step and name the shift. |
+| Padding, margin, gap, an offset | `--space-<px>` | `npx live-tokens tokens --family space` prints the steps. Round to the nearest one and name the shift. |
 | A stroke width | `--border-width-1`, `-2`, `-4` | Also for `outline`. |
 | A corner | `--radius-sm` through `-4xl`, `--radius-full` | |
 | A shadow | `--shadow-sm` through `-xl` | Replace the whole value, never one offset. |
@@ -105,7 +110,7 @@ though no rule reports them, and a `blur()` takes `--blur-*`.
 | `unknown-token` | A typo or a rename. Search `tokens.css` for the stem. A contract-family name (`--surface-…`, `--text-…`) that is gone was renamed: `npx live-tokens migrate --check` names the migration. |
 | `raw-text-axis` | Set the whole axis set from one text style: `--heading-xl` through `-sm`, `--body-md`, `--body-sm`, `--editorial-*`, `--eyebrow`, `--code`, each carrying `-font-family`, `-font-size`, `-font-weight`, `-line-height`, `-letter-spacing`. A `font:` shorthand is rewritten the same way. `em`, `%`, and a unitless line-height are relative and fine. |
 | `unknown-component` | Not in the catalogue. Read **live-tokens-pick-component** for the shipped one that fits, or author it with **live-tokens-create-component**. |
-| `unknown-prop` | The component drops it at runtime. Read its `interface Props` in `node_modules/@motion-proto/live-tokens/src/system/components/<Name>.svelte` and either map it to a declared prop or delete it. A `class` on a component that declares none does nothing. |
+| `unknown-prop` | The component drops it at runtime. `npx live-tokens components <id>` prints the props it declares and the values each union accepts; map the prop to one of them or delete it. A `class` on a component that declares none does nothing. |
 | `unknown-prop-value` | Pick a value from the union the message lists. |
 | `hardcoded-columns` | `repeat(var(--columns-count), 1fr)` for the page grid; `calc(var(--columns-count) - 2)` for a sub-grid spanning fewer page columns. A two-up or three-up is a layout and is not reported. |
 | `site-css-in-main` | Delete the import from `main.ts` and add it to each page's `<script>`, so page CSS never reaches the editor routes. |

package/.claude/skills/live-tokens-pick-component/SKILL.md

@@ -13,6 +13,14 @@ For composing a page once you've picked components, see **live-tokens-build-page
 
 Action: `Button`, `IconButton`, `InlineEditActions`. Input: `Input`, `Slider`. Selection: `SegmentedControl`, `TabBar`, `RadioButton`, `MenuSelect`, `Toggle`. Containers: `Card`, `CollapsibleSection`, `Dialog`, `Panel`. Messaging: `Callout`, `Notification`, `Tooltip`, `Badge`, `CornerBadge`. Display: `Table`, `Image`, `ImageLightbox`, `ProgressBar`, `SectionDivider`, `SideNavigation`, `CodeSnippet`.
 
+That line is the shipped set. A project can register components of its own,
+and those never appear in this file: run `npx live-tokens components` before
+choosing. It lists every component the project has, shipped and custom, with
+the variants each takes and the purpose its header comment states, so a custom
+component is weighed against the shipped set on the same footing.
+`npx live-tokens components <id>` prints one component's props, the values each
+union accepts, and its tokens with defaults; `--json` returns the same as data.
+
 ## Action family: Button vs IconButton
 
 Both trigger an action and share the same six variants (primary, secondary, outline, success, danger, warning), three states (default, hover, disabled) and two sizes (default, small). They differ only in content.

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # 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
+
+- **The registry is a query.** `npx live-tokens components` lists every
+  component a project has, shipped and its own, with the variants and props
+  read from each `interface Props` and the purpose its header comment states;
+  `components <id>` prints one component's props, unions, tokens, and
+  defaults. `npx live-tokens tokens` lists every theme token the project's
+  `tokens.css` declares by family with its value, `--family <name>` for one
+  scale. Both take `--json`. A project's components in a directory other than
+  `src/system/components` are found through `"componentDirs"` in
+  `live-tokens.config.json`. The same vocabulary the checkers read answers the
+  query, so a skill sees exactly what the checkers will hold it to.
+
+- **`getComponentRegistryEntries` is exported from the package**, so a
+  project's own test suite can run the registry contract over every
+  registration, shipped and custom. The create-component skill pointed at it
+  before it was public.
+
+### Changed
+
+- **The skills read the registry instead of carrying it.** The picker's
+  catalogue line is the shipped set only; a project's own component is found
+  by `live-tokens components`, weighed by the description its header comment
+  states, and never written into a skill file, so `setup-claude --force` no
+  longer loses anything. build-page and fix-findings read a component's props
+  from the same query, and fix-findings reads a token scale from `tokens`.
+
 ## 0.69.0 — Every value reads a token, and the build says so
 
 ### Changed

package/README.md

@@ -323,6 +323,9 @@ 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/`. |
+| `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. |
@@ -334,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
 
@@ -398,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

@@ -3,6 +3,9 @@
 // Subcommands:
 //   create <dir>             Scaffold a new app that depends on this package.
 //   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.
@@ -10,12 +13,15 @@
 //   set-fonts <brief.json>   Bind Google Fonts families to the theme's font stacks.
 //   migrate [...]            Reconcile tokens.css, the data tree, and route references.
 
-import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync, writeSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { 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,
   countBySeverity,
@@ -42,6 +48,20 @@ Commands:
   create <dir> [--force]      Scaffold a new Svelte + Vite app wired up with
                               live-tokens (editor, components, theme tokens)
   setup-claude [--force]      Install bundled Claude Code skills into ./.claude/skills/
+  components [id] [--json]    List every component the project has, shipped and
+                              its own (src/system/components plus any
+                              "componentDirs" in live-tokens.config.json), with
+                              the props each takes; with an id, that component's
+                              props, variants, tokens, and defaults
+  tokens [--family <name>] [--json]
+                              List every theme token the project's tokens.css
+                              declares, by family, with its value
+  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
@@ -101,6 +121,20 @@ Both check commands accept:
                               either is pending; route findings are advisory).
 `;
 
+// A large body written through console.log is cut at the pipe buffer when the
+// process exits before stdout drains, so a query writes synchronously.
+function writeOut(text) {
+  const buf = Buffer.from(`${text}\n`);
+  let offset = 0;
+  while (offset < buf.length) {
+    try {
+      offset += writeSync(1, buf, offset, buf.length - offset);
+    } catch (error) {
+      if (error.code !== 'EAGAIN') throw error;
+    }
+  }
+}
+
 function fail(message, code = 1) {
   console.error(message);
   process.exit(code);
@@ -141,6 +175,47 @@ function reportChecks(label, findings, checked, rules, opts) {
   process.exit(countBySeverity(resolved).errors === 0 ? 0 : 1);
 }
 
+if (command === 'components') {
+  const opts = parseCheckFlags(rest);
+  const list = describeComponents(loadVocabulary());
+  const id = opts.rest[0];
+  if (id && !list.some((c) => c.id === id)) fail(formatComponents(list, { id }));
+  writeOut(opts.json ? JSON.stringify(id ? list.find((c) => c.id === id) : list, null, 2) : formatComponents(list, { id }));
+  process.exit(0);
+}
+
+if (command === 'tokens') {
+  const opts = parseCheckFlags(rest);
+  const at = opts.rest.indexOf('--family');
+  const family = at >= 0 ? opts.rest[at + 1] : undefined;
+  const desc = describeTokens(loadVocabulary());
+  if (family && !desc.families.some((f) => f.family === family)) fail(formatTokens(desc, { family }));
+  writeOut(
+    opts.json
+      ? JSON.stringify(family ? desc.families.find((f) => f.family === family) : desc, null, 2)
+      : formatTokens(desc, { family }),
+  );
+  process.exit(0);
+}
+
+if (command === '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();
@@ -319,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/catalogue.mjs

@@ -0,0 +1,123 @@
+// The registry as a query. Every component a project has, shipped or its own,
+// with the props each takes and the tokens each declares, and every theme token
+// grouped by family. Read from files through the same vocabulary the checkers
+// use, so a skill or a script sees exactly what the checkers will hold it to.
+
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { CONTRACT_FAMILIES } from './tokenVocabulary.mjs';
+
+/** The runtime file's leading HTML comment, which is where a component says what it is for. */
+function descriptionOf(source) {
+  const m = source.match(/^\s*<!--([\s\S]*?)-->/);
+  if (!m) return '';
+  return m[1]
+    .split('\n')
+    .map((line) => line.trim())
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^\S+\.svelte\s*[—–-]+\s*/, '');
+}
+
+function familyOf(name) {
+  const stem = name.replace(/^--/, '');
+  const hit = CONTRACT_FAMILIES
+    .filter((f) => stem === f || stem.startsWith(`${f}-`))
+    .sort((a, b) => b.length - a.length)[0];
+  return hit ?? stem.split('-')[0];
+}
+
+export function describeComponents(vocab, { root = process.cwd() } = {}) {
+  const out = [];
+  for (const entry of vocab.components.values()) {
+    const source = readFileSync(entry.file, 'utf8');
+    const props = entry.props
+      ? [...entry.props.props].map((name) => ({
+          name,
+          type: entry.props.types.get(name) ?? '',
+          values: entry.props.enums.has(name) ? [...entry.props.enums.get(name)] : undefined,
+        }))
+      : [];
+    out.push({
+      id: entry.id,
+      name: entry.name,
+      origin: entry.origin,
+      file: relative(root, entry.file),
+      registered: entry.origin === 'shipped' || vocab.registered.has(entry.id),
+      description: descriptionOf(source),
+      variants: entry.props?.enums.get('variant') ? [...entry.props.enums.get('variant')] : [],
+      props,
+      tokens: [...entry.tokens].map(([name, value]) => ({ name, default: value })),
+    });
+  }
+  return out.sort((a, b) => a.origin.localeCompare(b.origin) || a.id.localeCompare(b.id));
+}
+
+export function describeTokens(vocab, { root = process.cwd() } = {}) {
+  const values = new Map();
+  if (vocab.tokensCssPath) {
+    const css = readFileSync(vocab.tokensCssPath, 'utf8').replace(/\/\*[\s\S]*?\*\//g, ' ');
+    for (const m of css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+      if (!values.has(m[1])) values.set(m[1], m[2].trim());
+    }
+  }
+  const byFamily = new Map();
+  for (const name of vocab.themeTokens) {
+    const family = familyOf(name);
+    if (!byFamily.has(family)) byFamily.set(family, []);
+    byFamily.get(family).push({ name, value: values.get(name) ?? '' });
+  }
+  return {
+    tokensCss: vocab.tokensCssPath ? relative(root, vocab.tokensCssPath) : null,
+    families: [...byFamily].map(([family, tokens]) => ({ family, tokens })),
+    components: [...vocab.components.values()].map((c) => ({
+      id: c.id,
+      tokens: [...c.tokens].map(([name, value]) => ({ name, default: value })),
+    })),
+  };
+}
+
+export function formatComponents(list, { id } = {}) {
+  const lines = [];
+  if (id) {
+    const c = list.find((x) => x.id === id);
+    if (!c) return `No component "${id}". Run \`live-tokens components\` for the list.`;
+    lines.push(`${c.name} (${c.id}, ${c.origin}${c.registered ? '' : ', NOT registered'})  ${c.file}`);
+    if (c.description) lines.push(`  ${c.description}`);
+    if (c.props.length) {
+      lines.push('  props:');
+      for (const p of c.props) lines.push(`    ${p.name}${p.values ? `: ${p.values.join(' | ')}` : p.type ? `: ${p.type}` : ''}`);
+    }
+    lines.push(`  tokens (${c.tokens.length}):`);
+    for (const t of c.tokens) lines.push(`    ${t.name}: ${t.default}`);
+    return lines.join('\n');
+  }
+  for (const c of list) {
+    const variants = c.variants.length ? `  variants: ${c.variants.join(', ')}` : '';
+    lines.push(`${c.id.padEnd(20)} ${c.origin.padEnd(8)} ${c.name}${c.registered ? '' : '  (NOT registered)'}${variants}`);
+    if (c.description) lines.push(`${''.padEnd(29)} ${c.description}`);
+  }
+  lines.push('');
+  lines.push(`${list.length} component(s). \`live-tokens components <id>\` prints one with its props and tokens.`);
+  return lines.join('\n');
+}
+
+export function formatTokens(desc, { family } = {}) {
+  const lines = [];
+  const families = family ? desc.families.filter((f) => f.family === family) : desc.families;
+  if (family && families.length === 0) {
+    return `No family "${family}". Families: ${desc.families.map((f) => f.family).join(', ')}.`;
+  }
+  lines.push(`Theme tokens from ${desc.tokensCss ?? '(no tokens.css found)'}`);
+  for (const f of families) {
+    lines.push('');
+    lines.push(`${f.family} (${f.tokens.length})`);
+    for (const t of f.tokens) lines.push(`  ${t.name}: ${t.value}`);
+  }
+  if (!family) {
+    lines.push('');
+    lines.push(`Component tokens: ${desc.components.reduce((n, c) => n + c.tokens.length, 0)} across ${desc.components.length} component(s). \`live-tokens components <id>\` lists one component's.`);
+  }
+  return lines.join('\n');
+}

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/bin/lib/tokenVocabulary.mjs

@@ -26,7 +26,7 @@ const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
 const SHIPPED_COMPONENTS_DIR = 'src/system/components';
 
 /** Families whose names are governed by the token contract (see TOKENS.md). */
-const CONTRACT_FAMILIES = [
+export const CONTRACT_FAMILIES = [
   'surface', 'text', 'border', 'color', 'space', 'radius', 'font', 'line-height',
   'letter-spacing', 'shadow', 'blur', 'icon-size', 'scrim', 'tint', 'columns',
   'heading', 'body', 'editorial', 'eyebrow', 'code', 'easing', 'duration', 'zoom',
@@ -111,13 +111,26 @@ export function componentProps(source) {
 
   const props = new Set();
   const enums = new Map();
+  const types = new Map();
   const body = iface[1].replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
   for (const m of body.matchAll(/^\s*(?:readonly\s+)?(\w+)\??\s*:\s*([^;\n]+)/gm)) {
     props.add(m[1]);
+    types.set(m[1], m[2].trim());
     const values = resolveEnum(m[2]);
     if (values) enums.set(m[1], new Set(values));
   }
-  return { props, enums };
+  return { props, enums, types };
+}
+
+/** `live-tokens.config.json` at the project root, or nothing. */
+export function readProjectConfig(root) {
+  const path = join(root, 'live-tokens.config.json');
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
 }
 
 function walk(dir, exts, out = []) {
@@ -186,14 +199,28 @@ export function loadVocabulary({ root = process.cwd(), pkgRoot = PKG_ROOT } = {}
 
   const componentTokens = new Set();
   const components = new Map();
-  const dirs = [join(pkgRoot, SHIPPED_COMPONENTS_DIR), join(root, SHIPPED_COMPONENTS_DIR)];
+  // A project's own components sit beside the shipped ones, plus any directory
+  // `componentDirs` in live-tokens.config.json names.
+  const own = [SHIPPED_COMPONENTS_DIR, ...(readProjectConfig(root).componentDirs ?? [])].map((d) => join(root, d));
+  const shippedDir = join(pkgRoot, SHIPPED_COMPONENTS_DIR);
+  const dirs = [shippedDir, ...own];
   for (const file of componentFiles(dirs)) {
     const Id = file.slice(file.lastIndexOf('/') + 1).replace('.svelte', '');
     const src = readFileSync(file, 'utf8');
-    components.set(Id.toLowerCase(), { id: Id.toLowerCase(), name: Id, file, props: componentProps(src) });
+    const tokens = new Map();
     for (const block of extractGlobalRootBlocks(src)) {
-      for (const n of declaredCustomProperties(block)) componentTokens.add(n);
+      const clean = block.replace(/\/\*[\s\S]*?\*\//g, ' ');
+      for (const n of declaredCustomProperties(clean)) componentTokens.add(n);
+      for (const m of clean.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) if (!tokens.has(m[1])) tokens.set(m[1], m[2].trim());
     }
+    components.set(Id.toLowerCase(), {
+      id: Id.toLowerCase(),
+      name: Id,
+      file,
+      origin: file.startsWith(shippedDir) ? 'shipped' : 'custom',
+      props: componentProps(src),
+      tokens,
+    });
   }
   const registered = registeredIds(root);
 

package/package.json

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

package/src/editor/index.ts

@@ -82,5 +82,5 @@ export type { Oklch } from './core/palettes/oklch';
 
 export { initializeTheme } from './core/themes/themeInit';
 
-export { registerComponent } from './component-editor/registry';
+export { registerComponent, getComponentRegistryEntries } from './component-editor/registry';
 export type { RegisterComponentEntry, RegistryEntry, ComponentId } from './component-editor/registry';