@motion-proto/live-tokens 0.68.1 → 0.69.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 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.
+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

@@ -52,7 +52,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 +90,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,7 +217,11 @@ 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.
+
+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:
 

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,131 @@
+---
+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. Read `tokens.css` for the names; 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>` | 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. |
+| 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. 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-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,7 @@ 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`.
 
 ## Action family: Button vs IconButton
 
@@ -42,6 +42,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,212 @@
 # Changelog
 
+## 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

package/README.md

@@ -11,7 +11,7 @@ The editor is dev-only. Production builds get plain CSS variables and the compon
 ## Features
 
 - **Live token editing.** Colors, typography, spacing, radii, shadows, motion, palettes, and gradients. Every input writes a CSS variable, so the page repaints with no reload and no build step.
-- **Live component editing.** 25 shipped Svelte components (Button, IconButton, Input, Card, Dialog, Badge, Callout, Table, Tooltip, Toggle, TabBar, SegmentedControl, RadioButton, MenuSelect, ProgressBar, CornerBadge, SectionDivider, CollapsibleSection, Notification, Image, ImageLightbox, CodeSnippet, SideNavigation, Panel, InlineEditActions) declare their design-token aliases in a `:global(:root)` block. Rewire an alias from the component's editor and it updates everywhere that component is used, on your real pages.
+- **Live component editing.** 26 shipped Svelte components (Button, IconButton, Input, Card, Dialog, Badge, Callout, Table, Tooltip, Toggle, TabBar, SegmentedControl, RadioButton, MenuSelect, ProgressBar, CornerBadge, SectionDivider, CollapsibleSection, Notification, Image, ImageLightbox, CodeSnippet, SideNavigation, Panel, InlineEditActions) declare their design-token aliases in a `:global(:root)` block. Rewire an alias from the component's editor and it updates everywhere that component is used, on your real pages.
 - **Four dev-only routes.** `/live-tokens/editor` for tokens, `/live-tokens/colors` for palettes, `/live-tokens/components` for per-component aliases, `/live-tokens/docs` for the user guide.
 - **Editor overlay.** Pins to the top right of every dev page and opens the editor in a side panel or floating window, so you edit on the page you are styling. Its "Page Source" button opens the current page's `.svelte` file in VS Code.
 - **Themes.** A theme is a whole look in one file: colors and type plus a config for every component, stored by value. Loading one changes a single pointer file, and nothing your site ships changes until you Adopt. Export a theme and import it into another project to restore the look in one step.
@@ -323,7 +323,8 @@ npx @motion-proto/live-tokens <command>
 |---|---|
 | `create <dir> [--force]` | Scaffold a new Svelte + Vite app wired up with live-tokens. |
 | `setup-claude [--force]` | Install the bundled Claude Code skills into `./.claude/skills/`. |
-| `check-component <id>` | Validate a component's runtime, editor, and registration against the authoring contract. |
+| `check-component [id]` | Validate a component's runtime, editor, and registration against the authoring contract; with no id, every component authored under `src/system/components`. |
+| `check-page [paths...]` | Validate pages against the build-page contract: catalogue components and their props, theme tokens over literals, route wiring. |
 | `generate-theme <brief.json> [--no-activate] [--dry-run] [--carry-from <name>]` | Build a full theme from a 10-seed OKLCH brief, enforce AA contrast, write `themes/<slug>.json`, and open it. |
 | `adjust <ops.json> [--dry-run]` | Move radius, padding, gap, and border-width aliases along their token scales. |
 | `set-fonts <brief.json> [--dry-run] [--no-verify]` | Bind Google Fonts families to the theme's font stacks, verified against the API. |
@@ -333,7 +334,7 @@ Once installed in a project, the same commands are available as `npx live-tokens
 
 ## Claude Code skills
 
-The package bundles six Claude Code skills. They encode the conventions this README cannot carry in full: which component fits a need, how a page is wired, what a valid theme looks like in OKLCH, how two typefaces sit together, and how geometry moves along the token scales. Each triggers from an ordinary request, so there are no slash commands to learn.
+The package bundles seven Claude Code skills. They encode the conventions this README cannot carry in full: which component fits a need, how a page is wired, what a valid theme looks like in OKLCH, how two typefaces sit together, how geometry moves along the token scales, and how an existing page or component is brought back into line with all of that. Each triggers from an ordinary request, so there are no slash commands to learn.
 
 ### Install
 
@@ -397,13 +398,19 @@ Ask for something the catalogue lacks: "author a Rating component", "make my Chi
 
 The skill covers the recipe: the runtime `.svelte` file with its `:global(:root)` token block, the editor `.svelte` file exporting `allTokens` and its variant groups, the `registerComponent()` call, and the catalogue entry that keeps `live-tokens-pick-component` current. It carries the naming scheme, the token suffix vocabulary, the state model (component states such as selected and disabled are separate from interaction states such as hover), and the public-imports rule, and points at the shipped `Toggle` in `node_modules` as the worked example. Linked siblings, intrinsics, and the fixed-overlay portal rule sit in reference files the skill reads only when a component needs them.
 
+### `live-tokens-fix-findings`
+
+Ask for the existing code to catch up: "make check:design pass", "fix the design-system warnings", "replace the hex and pixel values with tokens", "why is check-page failing on the pricing page?".
+
+The two checkers report a stable rule id per finding. The skill runs them with `--json`, groups the findings by rule, and carries one fix recipe per rule: a colour literal becomes the token for its role rather than the nearest hue, a spacing literal moves to the nearest `--space-*` step with the shift named, a raw `font-size` becomes a whole text style, a prop the component does not declare is mapped or dropped, and `site.css` moves out of `main.ts` into each page. It re-runs after every rule and stops at exit 0, then reports what changed, what it left and why, and what `--strict` would add. It never silences a rule to pass and never adds a token to `tokens.css` to match a value a page happened to use.
+
 Verify the result:
 
 ```bash
 npx @motion-proto/live-tokens check-component <id>
 ```
 
-The validator checks the file layout, the `:global(:root)` block, the token-suffix vocabulary, the state-before-property rule, the no-raw-color-defaults rule, the public-imports rule, and the `registerComponent({ id })` call. Exit code 0 means the static contract is met. Use it after Claude generates a component, and as a pre-commit guard on hand-authored ones.
+The validator checks the file layout, the `:global(:root)` block, the token-suffix vocabulary, the state-before-property rule, the public-imports rule, the `registerComponent({ id })` call, and that every default resolves to a theme token rather than a literal. Exit code 0 means the static contract is met. A project scaffolded by `create` runs it, with `check-page`, as `npm run check:design` before every `vite build`, so a component or page that opts out of the theme cannot ship by accident.
 
 ## From edit to production