@motion-proto/live-tokens 0.68.1 → 0.70.0

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

@@ -7,8 +7,8 @@ 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. 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-*)`. No hex literals. No pixel literals. A change in `/live-tokens/editor` should repaint your page.
+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.
 
@@ -45,8 +45,8 @@ const pages = {
 
 ## Avoid
 
-- Hex or pixel literals in page CSS.
-- Hardcoded column counts (`repeat(10, 1fr)`). Use `repeat(var(--columns-count), 1fr)`.
+- Colour literals, and px or rem in spacing, stroke, radius, or shadow.
+- Hardcoded page-grid counts (`repeat(10, 1fr)`). Use `repeat(var(--columns-count), 1fr)`, or `calc(var(--columns-count) - 2)` for a sub-grid that spans fewer page columns. A local two-up or three-up is a layout and is fine.
 - Utility classes overriding shipped components. Extend via the `/live-tokens/components` editor instead.
 - Deep imports from `node_modules/@motion-proto/live-tokens/src/...`. Use public entry points only.
 - Mounting `Editor` or `ComponentEditorPage` outside their dedicated routes.
@@ -54,4 +54,15 @@ const pages = {
 
 ## Verify
 
-In dev: change a colour in `/live-tokens/editor` and confirm your page repaints (proves token usage). The overlay's "Page Source" button on the new route opens the page in VS Code (proves the route's `source`). `ColumnsOverlay` (Cmd+G) shows content sitting inside `--columns-max-width`.
+Run the checker and fix what it reports. Repeat until it exits 0:
+
+```sh
+npx live-tokens check-page src/pages/YourPage.svelte
+# or: npx @motion-proto/live-tokens check-page      (every page under src/)
+```
+
+It fails on a component outside the catalogue, a prop a component does not declare, a variant or size outside the prop's union, a deep import, a `var()` that resolves to nothing, a colour literal in any notation, a route under `/live-tokens/*`, and `site.css` imported from `main.ts`. It warns on a px or rem literal in spacing, stroke, radius, or shadow, a hardcoded column count of four or more, an absolute type value, and a route entry with no `source`. Inline `style=` attributes and `style:` directives are read the same way as the `<style>` block; a `var()` fallback is not the page's value and is never a finding.
+
+Warnings do not fail the run. `--strict` makes them fail, which is the setting to use when the page is meant to be fully tokenized. `--json` prints findings with a stable `rule` id, so you can work through one rule at a time and re-run. `--off=<rule>` silences a rule for a run; `"checks": { "rules": { ... } }` in `live-tokens.config.json` sets it for the project. A project scaffolded by `create` runs the checker, with `check-component`, as `npm run check:design` before every `vite build`, so the page has to pass before it can ship.
+
+Then in dev: change a colour in `/live-tokens/editor` and confirm your page repaints (proves token usage). The overlay's "Page Source" button on the new route opens the page in VS Code (proves the route's `source`). `ColumnsOverlay` (Cmd+G) shows content sitting inside `--columns-max-width`.

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
@@ -52,7 +59,24 @@ For pattern reference, read any shipped component's source directly from the con
    `border-color`, `box-shadow`, `overflow`, `position` and both pseudo-elements
    away from the element it draws, which constrains where the class can go. Read
    `references/sketch-mode.md`.
-6. **Verify** with the checklist at the bottom of this file, then place the component on a page with **live-tokens-build-page**.
+6. **Gate on the checker.** Run it, fix every error, and run it again. Do not
+   call the component done while it reports one:
+   ```bash
+   npx live-tokens check-component <id> --strict --json
+   ```
+   `--json` gives each finding a stable `rule` id and a line number, so work one
+   rule at a time and re-run rather than guessing. `--strict` fails on warnings
+   too, which is the right setting for a new component: every warning it raises
+   is a naming or token decision that is cheaper to make now than to migrate
+   later. Exit code 0 is the gate. With no id it checks every component under
+   `src/system/components`; a project scaffolded by `create` runs that as
+   `npm run check:design` before every `vite build`.
+
+   If it rejects a suffix, do not invent a new name for the role. Find a shipped
+   component that paints the same thing and use the name it uses: the catalogue
+   is the worked reference, and `bin/check-component.test.ts` holds all 26 of
+   them to this same contract.
+7. **Verify** with the checklist at the bottom of this file, then place the component on a page with **live-tokens-build-page**.
 
 ## Token discipline
 
@@ -73,18 +97,32 @@ For pattern reference, read any shipped component's source directly from the con
 The editor picker is chosen by the token's suffix, so the suffix is the naming
 decision that matters. Color and surface: `-surface`, `-border`, `-text`,
 `-icon`, `-label`, `-fill`, `-divider`, `-color`, `-shadow`, `-opacity`,
-`-blur`. Geometry: `-radius`, `-border-width`, `-thickness`, `-width`, `-size`,
-`-padding`, `-gap`. Typography: `-font-family`, `-font-weight`, `-font-size`,
-`-line-height`, `-letter-spacing`.
+`-tint`, `-background`, `-accent`, `-indicator`, `-thumb`, and the
+element-named text roles `-title`, `-body`, `-eyebrow`, `-description`,
+`-hint`, `-error`, `-placeholder`, `-value`. Geometry: `-radius`,
+`-border-width`, `-accent-width`, `-hairline-thickness`, `-thickness`,
+`-width`, `-height`, `-size`, `-padding`, `-margin`, `-gap`, `-inset`,
+`-divider-width`, `-divider-thickness`, `-divider-height`, `-divider-inset`,
+`-track-height`, `-dot-size`, `-thumb-size`, `-icon-size`, `-scale`, `-blur`.
+Motion: `-duration`, `-easing`. Typography: `-font-family`, `-font-weight`,
+`-font-size`, `-line-height`, `-letter-spacing`.
+
+A token that carries a structural keyword rather than a value takes no suffix
+from this list. Declare it in the editor's `intrinsics` instead, which is what
+exempts it, and never end its name in a state word, which reads as
+state-after-property and fails.
 
 Read `references/token-naming.md` for what each one means and when two of them
-compete. A suffix outside that list fails `check-component`.
+compete. A suffix outside that list fails `check-component`. The list lives in
+`KIND_RULES` in the editor's `aliasKinds.ts`, which the picker, the `adjust`
+CLI, and `check-component` all read, so a name accepted here always has a
+control behind it.
 
 ### Rules that bite
 
 - **Fixed overlays must portal to `<body>`.** Any `position: fixed` layer is trapped by a transformed or `contain`ed ancestor, which real pages and the editor's preview pane both have. `check:overlay-portal` fails the build without it. Read `references/fixed-overlays.md` before authoring a modal, lightbox, or backdrop.
-- **State before property.** `--mywidget-button-hover-surface` ✓ — `--mywidget-button-surface-hover` ✗ (breaks sibling matching).
-- **Defaults reference theme tokens, never raw colours.** `var(--surface-primary)` ✓ — `#6a4ce8` ✗, and `check-component` fails the build on one. Composing a token counts and is common: `color-mix(in srgb, var(--surface-neutral-lower) 70%, transparent)`. A property with no theme token behind it takes a bare keyword (`contain`, `start`, `none`). Dimensions are the gap: a raw `16rem` passes the check, so reach for a token anyway unless the component genuinely owns that measurement.
+- **State before property.** `--mywidget-button-hover-surface` ✓ — `--mywidget-button-surface-hover` ✗ (breaks sibling matching). Disabled is terminal in the name too: `-disabled-hover-` and `-selected-disabled-` describe states that never paint, and `check-component` rejects both.
+- **Every default resolves to a theme token.** A component token names a semantic property; its default is the theme token that property reads. That is what makes the component repaint when the theme changes. `var(--surface-primary)` ✓, `#6a4ce8` ✗, `white` ✗, and `var(--surface-imaginary)` ✗: `check-component` fails on a colour literal in any notation, on a `var()` naming a token that does not exist, and on a default with no token behind it at all, so a raw `16rem` fails too. Composing tokens counts and is common: `color-mix(in srgb, var(--surface-neutral-lower) 70%, transparent)`, or `calc(var(--space-64) * 4)` for a width the spacing scale does not reach. The one value allowed without a token is a structural keyword (`contain`, `start`, `none`), and only when the editor declares it in `intrinsics`.
 - **No abbreviations.** `bg` → `surface`; `fg` → `text`; component ids are never abbreviated.
 - **Text aliases.** Neutral scale is `--text-primary` / `--text-secondary` / `--text-tertiary` / `--text-muted` / `--text-disabled`. Family-tinted is `--text-primary-color`, `--text-accent`, `--text-success`. There is no `--text-neutral`.
 - **Typography `groupKey` on multi-slot components must include the slot prefix.** `groupKey: 'value-font-family'` and `groupKey: 'label-font-family'` ✓ — bare `groupKey: 'font-family'` silently merges them into one link tree ✗. Single-slot components can use a bare typography `groupKey`; add the slot prefix the moment a second slot appears. The same trap applies to type-group **colors** (two slots ending in `-text` collapsing to one `text` key). Let the helpers handle both, below.
@@ -186,17 +224,15 @@ npx live-tokens check-component <id>
 # or: npx @motion-proto/live-tokens check-component <id>
 ```
 
-It enforces the file layout, the `:global(:root)` block, token-suffix vocabulary, state-before-property rule, theme-token defaults (no raw colour literals), public-imports rule, and that the id is registered — via either `bootLiveTokens({ components: [{ id }] })` or a direct `registerComponent({ id })` call. It also *warns* (non-fatal) when a type-group font helper is called bare across multiple slots, which would merge their fonts into one link tree. Exit code 0 means the static contract is met; resolve warnings before shipping.
+It enforces the file layout, the `:global(:root)` block, token-suffix vocabulary, state-before-property rule, the terminal disabled state, public-imports rule, that every token an editor row names is declared in the runtime, and that the id is registered, via either `bootLiveTokens({ components: [{ id }] })` or a direct `registerComponent({ id })` call. On the value side it fails on a colour literal in any notation, on a default reading a token that does not exist, and on a default with no theme token behind it that the editor does not declare an intrinsic.
+
+It *warns* (non-fatal) when a token-backed default still carries a px or rem term, and when a type-group font helper is called bare across multiple slots, which would merge their fonts into one link tree.
 
-**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:
+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.
 
-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.
+**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.
 
-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-create-component/references/token-naming.md

@@ -3,7 +3,7 @@
 The editor picker is chosen by suffix. There is no per-token override; if a
 token renders with the wrong picker, rename it to one of these.
 
-`KNOWN_SUFFIXES` in `bin/check-component.mjs` is authoritative, and
+`KIND_RULES` in `src/editor/core/components/aliasKinds.ts` is authoritative, and
 `check-component` fails on a suffix outside it. `check:skills` holds this file
 to that list, so the two cannot drift apart.
 
@@ -22,6 +22,19 @@ to that list, so the two cannot drift apart.
 | `-shadow`   | Box-shadow                                                    |
 | `-opacity`  | Opacity (0–1)                                                 |
 | `-blur`     | Backdrop or filter blur radius                                |
+| `-tint`     | A wash over the surface, aliasing a `--tint-*` stop            |
+| `-background` | Fill, where the component's own vocabulary says background   |
+| `-accent`   | An accent bar or indicator's colour                            |
+| `-indicator` | A selection indicator's colour                                |
+| `-thumb`    | A scrollbar or slider thumb's colour                           |
+| `-title`    | Title text colour                                              |
+| `-body`     | Body text colour                                               |
+| `-eyebrow`  | Eyebrow text colour                                            |
+| `-description` | Description text colour                                     |
+| `-hint`     | Hint text colour                                               |
+| `-error`    | Error text colour                                              |
+| `-placeholder` | Placeholder text colour                                     |
+| `-value`    | A displayed value's colour                                     |
 
 ## Geometry
 
@@ -30,6 +43,22 @@ to that list, so the two cannot drift apart.
 | `-radius`       | Corner radius                                                 |
 | `-border-width` | Stroke thickness (used even when CSS uses `outline:`)         |
 | `-thickness`    | Alternative to `-width` when fallback siblings would collide  |
+| `-accent-width` | An accent bar's thickness                                     |
+| `-hairline-thickness` | A hairline rule's thickness                             |
+| `-dot-size`     | A dot indicator's diameter                                    |
+| `-divider-width` | A divider's thickness                                        |
+| `-divider-thickness` | Alternative to `-divider-width`                          |
+| `-divider-height` | A divider's length                                          |
+| `-divider-inset` | Inset trimmed from a stretched divider                       |
+| `-track-height` | A track's height (progress bar, slider)                       |
+| `-icon-size`    | An icon's rendered size                                       |
+| `-thumb-size`   | A thumb's rendered size                                       |
+| `-height`       | A measured height (a track, a panel)                          |
+| `-margin`       | Outer spacing, moved on the same scale as `-padding`          |
+| `-inset`        | Inset trimmed from a stretched element                        |
+| `-duration`     | Motion duration                                               |
+| `-easing`       | Motion easing curve                                           |
+| `-scale`        | A transform scale factor                                      |
 | `-width`        | Width dimension                                               |
 | `-size`         | Square / uniform dimension                                    |
 | `-padding`      | Internal spacing                                              |

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

@@ -0,0 +1,133 @@
+---
+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).
+---
+
+# Fixing what the checkers report
+
+Two checkers hold a project to its design system. `check-page` holds pages:
+every component comes from the catalogue and is passed only the props it
+declares, and every value in page CSS is a theme token. `check-component`
+holds authored components: every token names a semantic property and its
+default is the theme token that property reads. A page or component that
+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.
+
+## Reach the checkers
+
+```sh
+npx live-tokens check-page --json           # every page under src/
+npx live-tokens check-component --json      # every component authored under src/system/components
+```
+
+- **Unknown command.** The installed package predates the checkers. Upgrade
+  `@motion-proto/live-tokens`, then run `npx live-tokens migrate --check` and
+  apply what it plans with `--write`; `--tokens <path>` names a tokens.css that
+  sits somewhere other than the four default locations.
+- **No `check:design` script.** A project scaffolded by `create` has one. Add
+  it to any other project's `package.json`:
+  `"check:design": "live-tokens check-page && live-tokens check-component"`.
+  Once it passes, gate the build: `"build": "npm run check:design && vite build"`.
+- **A file, not the project.** `check-page src/pages/Home.svelte` and
+  `check-component <id>` scope a run when the user names one thing.
+
+## The loop
+
+1. Run with `--json`. Each finding carries a stable `rule`, a file, and a line.
+2. Group by rule. Take errors before warnings, and the rule with the most
+   findings first, because one recipe clears the whole group.
+3. Apply that rule's recipe, below, to every finding in the group.
+4. Run again. New findings can appear as old ones clear: a token you reached
+   for may not exist, or a moved import may land somewhere the rule now sees.
+5. Stop at exit 0. Then run once with `--strict` and report what it adds, so
+   the user can decide whether warnings are worth clearing now.
+
+Three things the loop never does:
+
+- **Silence a rule to pass.** `--off=<rule>` is for a single run while
+  working. A severity the project wants changed goes in
+  `live-tokens.config.json` under `"checks": { "rules": { "<rule>": "warn" } }`,
+  with the reason in the commit, and only when the user has made that call.
+- **Mint a token.** A literal with no token behind it is remapped to the
+  nearest existing token by role. No new `--surface-*`, `--text-*`, or
+  `--space-*` is added to `tokens.css` to match a value the page happened to
+  use. If nothing fits, say so and leave the finding.
+- **Change what the page looks like without saying so.** Most remaps land on
+  the same value. When the nearest token differs, `14px` to `--space-16` or a
+  55% black to `--scrim`, name the shift in the report.
+
+## Colour by role, never by hue
+
+`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. `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 |
+| --- | --- | --- |
+| Text on a surface | `--text-primary`, `-secondary`, `-tertiary`, `-muted`, `-disabled` | The neutral scale. Family colour is `--text-accent`, `--text-success`, and so on. |
+| Light text on a dark chip over the page | `--text-inverted` | The one flip; no AA guarantee. |
+| A box's fill | `--surface-<family>-<level>` | `neutral` for chrome; `brand`, `accent`, `special` for emphasis; `info`, `success`, `warning`, `danger` for status. |
+| A stroke | `--border-<family>-<level>` | `faint`, `subtle`, base, `medium`, `strong` in the neutral family. |
+| A translucent layer that dims what is behind it | `--scrim-low`, `--scrim`, `--scrim-high` | Behind a modal, under a floating control. |
+| A translucent wash on a surface | `--tint-low`, `--tint`, `--tint-high` | Hover, an active tab, a code chip's background. |
+| Fully transparent | `--color-transparent` | Never `transparent` inside a component default. |
+| A gradient | `--gradient-*` | Or compose one from surface tokens. |
+
+A `var(--x, #fff)` fallback is not a finding. A named colour is: `white` and
+`rebeccapurple` are literals like any hex.
+
+## Geometry by scale
+
+`dimension-literal` fires only on the geometry the theme owns: padding,
+margin, gap, border and outline widths, inset offsets, radius, and shadow.
+Sizing (a hero's height, a max content width, a `minmax()` floor) is layout
+and is never reported, so leave it.
+
+| The literal is | Token | Notes |
+| --- | --- | --- |
+| 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. |
+| Part of a `calc()` | The token inside the calc | `calc(var(--space-64) * -2 + var(--space-8))` |
+
+While in the file, motion values take `--duration-*` and `--ease-*` even
+though no rule reports them, and a `blur()` takes `--blur-*`.
+
+## Every other rule
+
+| Rule | Fix |
+| --- | --- |
+| `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. `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. |
+| `missing-source` | Add `source: 'src/...'` to the route entry so Page Source can open it. |
+| `reserved-route` | Move the route out of `/live-tokens/*`; the package owns that namespace. |
+| `deep-import` | Import from `@motion-proto/live-tokens` or `/component-editor` or `/components/<Name>.svelte`, never from `/src/`. |
+| `unknown-suffix`, `state-after-property`, `disabled-is-terminal` | Rename the token. Borrow the name a shipped component uses for the same role; the vocabulary and the state model are in **live-tokens-create-component**. |
+| `color-literal`, `unknown-token-ref`, `default-not-token` (component) | The `:global(:root)` default reads a theme token, composed if needed. A structural keyword (`start`, `contain`) is declared in the editor's `intrinsics`. |
+| `phantom-editor-token`, `phantom-link` | The editor names a token the runtime never declares, or a bare font helper spans slots. Both are editor fixes; see the same skill. |
+| `missing-registration`, `missing-file`, `missing-root-block` | The component is not wired the way the recipe in **live-tokens-create-component** wires it. |
+
+## Report
+
+Say what changed by rule, one line per rule with the count and any visible
+shift. Say what was left and why, with the config entry if the user chose to
+lower a severity. End with the two commands and their exit codes.
+
+## Verify
+
+Open `/live-tokens/editor` in dev and change a surface colour and a spacing
+step. Every file the loop touched should repaint. One that does not still
+holds a literal the checker cannot see, which is worth reporting as a gap in
+the checker rather than patching around.

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

@@ -11,7 +11,15 @@ For composing a page once you've picked components, see **live-tokens-build-page
 
 ## Catalogue
 
-Action: `Button`, `IconButton`, `InlineEditActions`. Input: `Input`. 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`.
+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
 
@@ -42,6 +50,7 @@ All four pick one option from a set. The right one depends on **option count**,
 
 - `Input` takes an answer the page cannot enumerate: a name, an email, a search string, an amount. It ships the label, the hint line, and the error state as parts (`--input-label-*`, `--input-hint-*`, `--input-error-*`), so style those rather than stacking your own text under a bare field.
 - The boundary is whether you can list the answers. A short fixed set is the single-selection family above; a long fixed set is `MenuSelect`; anything you cannot write down is `Input`.
+- `Slider` takes a number inside a known range where the position carries the meaning: a volume, a price band, a percentage. Its `range` variant takes a low and a high bound on one track. A number the user knows exactly and would rather type is `Input` with `type="number"`.
 - **Don't use it for on/off.** That is `Toggle`, and a one-field form asking for yes or no is the usual way this goes wrong.
 - Its four variants are `default`, `focused`, `disabled`, and `error`. A validation message belongs in the `error` variant, not in a `Callout` next to the field.
 

package/CHANGELOG.md

@@ -1,5 +1,241 @@
 # Changelog
 
+## 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
+
+- **SideNavigation's panel widths read the spacing scale.** `16rem` and `3rem`
+  were the only shipped defaults with no token behind them; both now derive
+  from the largest step, `calc(var(--space-64) * 4)` and
+  `calc(var(--space-64) * 0.75)`. Values are unchanged.
+
+- **The starter `site.css` is fully tokenized.** A paragraph margin and three
+  rule and blockquote strokes were px literals; they read `--space-16` and
+  `--border-width-*` now, so a scaffolded project starts clean under
+  `check-page --strict`. The paragraph margin moves from 14px to 16px.
+
+- **TabBar's active tab and Button's inline-code badge are tints, not scrims.**
+  Both washed a surface rather than dimming what sat behind it, and only read a
+  scrim because no tint family existed. **They restyle**: a 38% near-black wash
+  becomes a 10% white one, so each reads lighter and softer. A theme that pointed
+  the TabBar alias somewhere else keeps its choice.
+
+- **Optional-interaction gates take `-enabled`, not a state word.**
+  `--card-hover-border-active`, `--card-hover-shadow-active`,
+  `--image-zoom-hover`, and `--image-grow-hover` read as state-after-property and
+  failed `check-component`, which meant the documented gate pattern was one a
+  consumer could not use. A gate is not a state: it says whether the interaction
+  is on at all. Values are unchanged.
+
+- **Button's shimmer and ImageLightbox's tile fit are declared intrinsics.**
+  Both were bare keywords with no theme token and no declaration, which is the
+  thing `intrinsics` exists to record. `--button-shimmer` now defaults to
+  `var(--shimmer-on)`, the token that was already there for it.
+
+- **`--hover-*` is now `--tint-*`, and it has a baseline for the first time.** A
+  state is a segment of a property name (`--button-outline-hover-surface`), not
+  a token of its own, so the three stops are named for what they are: a tint
+  shades the surface it sits on. Values are unchanged.
+
+  The theme engine had always emitted these stops, but `tokens.css` never
+  declared them, so they resolved to nothing until a theme was adopted. That is
+  why `var(--hover)` painted no pressed state on a fresh install. `--tint-*` is
+  baselined, and that half of the migration is additive, so it auto-applies.
+
+- **`--overlay-*` is now `--scrim-*`.** A scrim is a translucent layer that dims
+  what sits behind it, which is what a dialog draws over the page. The old name
+  had spread to cover surface tints as well, which are the opposite operation,
+  and it collided with `backdrop`, the exported concept for what paints behind
+  an element and which way it leans. Each name now means one thing. Values are
+  unchanged, so nothing repaints.
+
+  `npx live-tokens migrate` renames the three tokens in a vendored `tokens.css`.
+  Token names are public API, so the migration is breaking and never
+  auto-applies. Saved themes and component configs migrate on load.
+
+  Dialog's part follows its token: `--dialog-overlay-surface` is
+  `--dialog-scrim-surface`, and the editor labels it "scrim color" rather than
+  the "backdrop color" that named a third thing again. The editor's Overlays
+  section is now Washes, holding Scrims and Tints.
+
+### Added
+
+- **The shipped catalogue is now the component contract's fixture.**
+  `check-component` reported 109 errors across all 26 shipped components, and
+  none of them were defects in the components: the checker's suffix list had
+  simply drifted narrower than the catalogue it governs, rejecting `-accent`,
+  `-title`, `-margin`, `-easing` and a dozen more names our own components use.
+  A test now runs the full contract over every registered component and requires
+  zero errors, so the rule and the components can never disagree again.
+
+  The suffix vocabulary moved to `KIND_RULES` in the editor's `aliasKinds.ts`.
+  The picker, the `adjust` CLI, `check-component`, and `check:skills` all read
+  that one table, so a name the checker accepts always has a control behind it.
+
+  Three rules got more accurate along the way. A token the editor declares in
+  `intrinsics` is exempt from the suffix check, because a structural keyword is
+  not a themeable value. Membership in the package's own `builtInRegistry`
+  counts as registration. And a component may prefix its tokens with the
+  hyphenated form of its id, which is what CornerBadge has always done.
+
+- **An optional hover tint on Button, IconButton, TabBar, SegmentedControl,
+  MenuSelect, and SideNavigation.** One stop for the whole component rather than
+  one hover surface per variant: Button and IconButton carried 36 hover tokens
+  each, and every one was tuned by hand. `--<id>-hover-tint` aliases a `--tint-*`
+  stop, and `--<id>-hover-tint-enabled` gates it.
+
+  Off by default, so nothing changes until a project turns it on. The tint rides
+  as a `background-image` over the hover rule's own `background-color`, so it
+  needs no pseudo-element.
+
+  A **tint layer** switch in the component editor's hover state turns it on and
+  points every hover surface at its own base surface, so hover is the tint alone
+  rather than a swap wearing a wash. The hover-surface rows grey out while it is
+  on, since they no longer change anything. Switching it off clears those
+  overrides, returning each surface to its shipped default.
+
+  Switching it on reveals a **tint color** row beside it. It starts on `--tint`,
+  the theme's middle tint stop, and takes any colour token with an alpha, like
+  every other colour row. A `-tint` suffix now resolves to the surface picker
+  rather than falling through, so the row offers the whole palette, not only the
+  tint stops.
+
+  Per instance, the `hoverTint` prop overrides the global default (`undefined`
+  inherits, `true` and `false` force).
+
+- **`live-tokens check-page` validates a page against the build-page
+  contract.** It fails on a component outside the catalogue, a deep import into
+  package internals, a `var()` naming a token that does not exist, a colour
+  literal, a route under the reserved `/live-tokens/*` namespace, and `site.css`
+  imported from `main.ts`, a prop a shipped component does not declare, and a
+  variant or size outside that prop's union. It warns on a px or rem literal
+  in spacing, stroke, radius, or shadow, a hardcoded page-grid count of four
+  columns or more, an absolute type value (the `font` shorthand included), and
+  a route entry with no `source`. Sizing is layout and is never reported.
+  Inline `style=` attributes and `style:` directives are read under the same
+  rules as the `<style>` block, and a named colour is a literal like any hex.
+  Given no paths it checks every page under `src/`.
+
+- **Both check commands take `--json`, `--strict`, and per-rule severity
+  flags.** `--json` prints findings with a stable `rule` id and line number, so
+  a skill can fix one rule at a time and re-run until the exit code is 0.
+  `--strict` promotes warnings to errors. `--off=<rule>`, `--warn=<rule>`, and
+  `--error=<rule>` change a rule for one run; `"checks": { "rules": { ... } }`
+  in `live-tokens.config.json` sets it for the project.
+
+- **`check-component` now checks what a default *resolves to*, not just what it
+  is named.** A component token names a semantic property and its default is the
+  theme token that property reads, which is what makes the component repaint
+  when the theme changes. A default reading a token that does not exist is now
+  an error, including a `var()` naming a state word rather than the token that
+  state should paint. A default with no token behind it is an error unless the
+  editor declares it in `intrinsics`; a colour literal in any notation is an
+  error; a token-backed default that still carries a px or rem term warns.
+  Two more rules read the name alone: `disabled-is-terminal` rejects a token
+  that combines `disabled` with `hover`, `focus`, `selected`, `on`, `active`,
+  or `checked`, and `phantom-editor-token` rejects an editor row naming a
+  token the runtime never declares. Given no id, `check-component` checks
+  every component authored under `src/system/components`, and a scaffolded
+  project runs both checkers as `npm run check:design` before every
+  `vite build`. `check-component` also finds a shipped component's editor
+  beside the other editors, not only next to its runtime.
+
+- **`npm run check:pages` runs the page check over this repo under `--strict`
+  and is part of `prepublishOnly`.** The unit suite covers the same ground:
+  the repo's pages carry no finding at all, and every shipped component
+  default resolves to a real token. Both suites also hold a mutation table: a
+  clean component and a clean page that pass `--strict`, and one smallest
+  break per rule that must fail, so a rule cannot stop firing unnoticed.
+
+- **`Slider`, in two variants.** `single` moves one thumb to a value; `range`
+  moves two thumbs to a low and a high bound on one track. Both share track,
+  fill, and thumb tokens, linked in the editor so an edit to one moves the
+  other until deliberately unlinked, with hover and disabled states and a
+  label and value readout. It was authored by following
+  `live-tokens-create-component` end to end, and `check-component --strict`
+  was clean on the first run.
+
+- **`live-tokens-fix-findings`, the seventh skill.** The loop for code that
+  already exists: run both checkers with `--json`, take the largest group of
+  errors first, apply that rule's recipe, re-run, stop at exit 0. It carries
+  one recipe per rule id, with colour mapped by role rather than hue and
+  geometry by scale, and three refusals: never silence a rule to pass, never
+  mint a token, never shift the look without saying so. Its first run, on the
+  package's own demo site, took three rounds and ended clean.
+
+### Fixed
+
+- **The tint layer switch was unreachable in four editors.** SegmentedControl,
+  TabBar, MenuSelect, and SideNavigation gated the row on a state named
+  `hover`, and their hover states are `hover option`, `hover tab`,
+  `hover item`, and `<Part> / Hover`, so the switch and the tint colour row
+  never rendered. Each condition now names the state the editor has. The
+  render contract caught it once it learned to turn a gate on: a gate row
+  carries `data-token-variables` and the harness flips a `role="switch"`
+  Toggle the way it clicks a checkbox, then exercises the row the gate
+  revealed. A selector whose selections are locked carries a `locked` class,
+  which the harness skips instead of retrying a chip it can never click.
+
+- **`check-page` no longer reports a `var()` fallback as a colour literal.**
+  `var(--surface-neutral, #111)` paints the token; the literal only renders
+  when the token is missing. Against the package's own demo site this was 33
+  of 39 errors.
+
+- **`check-page` reads a custom property with a digit in its name as one
+  declaration.** `--heading-2xl: 1.875rem` was parsed as the property `xl`
+  and reported as a raw dimension. The project's own `tokens.css` and the
+  generated token files are also no longer discovered as pages.
+
+- **Both checkers read a `:global(:root)` block the same way.** They had two
+  extractors, one of which stopped at the first `}`, so a nested at-rule or
+  SCSS block truncated the block. One brace-balanced extractor is shared.
+
+- **An `intrinsics` array on one line still exempts its token.** The
+  exemption required the closing `];` on its own line.
+
+- **A persisted editor session from before the rename no longer breaks the
+  renderer.** `hydrate` shallow-merges persisted state, so a `washes` (or
+  `overlays`) slice saved by an older build replaced the current one wholesale
+  and arrived without its tint stops, throwing `w.tints is not iterable` out of
+  the render path on load. Hydration now reshapes the slice: it carries the
+  saved stops across under their new names and falls back to the shipped
+  defaults for anything unusable.
+
+- **The outline Button and IconButton pressed state had no colour.** Both read
+  `var(--hover)`, which names nothing: a state is a segment of a semantic
+  property name (`--button-outline-hover-surface`), never a token of its own.
+  They read `--surface-neutral-low` now, one step along the scale from their
+  hover surface. `check-component` catches this class of mistake by name.
+
 ## 0.68.1 — A look is a Theme, or it's a sketch style
 
 ### Changed