@motion-proto/live-tokens 0.71.0 → 0.72.1

package/.claude/skills/live-tokens-adjust-geometry/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: live-tokens-adjust-geometry
-description: Adjust corner radius, padding, gap, and border width across live-tokens components by moving each token alias along the shipped scales. Use when the user asks for pill or capsule buttons; rounded, rounder, sharp, sharper, square, softer, or harder corners; thicker or thinner borders; or density — space it out, tighter, denser, more compact, airier, more breathing room. Also invoked by live-tokens-generate-theme for the geometry half of a whole look. Changes shape and space aliases per component, never color, fonts, or tokens.css. Not for editing a single token (use the editor) or for color (see live-tokens-generate-theme).
+description: Adjust corner radius, padding, gap, and border width across live-tokens components by moving each token alias along the shipped scales. Use when the user asks for pill or capsule buttons; rounded, rounder, sharp, sharper, square, softer, or harder corners; thicker or thinner borders; or density: space it out, tighter, denser, more compact, airier, more breathing room. Also invoked by live-tokens-generate-theme for the geometry half of a whole look. Changes shape and space aliases per component, never color, fonts, or tokens.css. Not for editing a single token (use the editor) or for color (see live-tokens-generate-theme).
 ---
 
 # Adjusting geometry

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

@@ -16,7 +16,7 @@ Text inside a `Card` or a `CollapsibleSection` is typed by that container, not b
 
 ## Layout
 
-Pages sit inside the column grid via `--columns-count`, `--columns-gutter`, `--columns-max-width`. Toggle `ColumnsOverlay` (Cmd+G in dev) to visualise it while placing content.
+Pages sit inside the column grid via `--columns-count`, `--columns-gutter`, `--columns-max-width`. The columns button in the overlay's header (the vertical-lines icon) draws the grid over the page while you place content.
 
 To place children at specific page-column positions, span the parent grid (`grid-column: 1 / -1`), redeclare `repeat(var(--columns-count), 1fr)` with `--columns-gutter`, then refer to children by real page-column numbers. Never fabricate a local `repeat(N, 1fr)` with a hardcoded count: the widths drift from the page grid and the numbers stop matching `ColumnsOverlay`.
 
@@ -61,8 +61,8 @@ 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.
+It fails on a component outside the catalogue, a prop or value the component does not declare, 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 the geometry the theme owns, a hardcoded page-column count, a raw type axis, 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 never a finding. The recipe for each rule is in **live-tokens-fix-findings**.
 
 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`.
+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`). The columns overlay shows content sitting inside `--columns-max-width`.

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

@@ -5,23 +5,20 @@ description: Check an existing @motion-proto/live-tokens project against its des
 
 # Checking a project against its design system
 
-The answer to "check this project" is a report, and every fact in it comes
-from one command. This skill runs it, reads it, and says what the facts mean
-and what fixing them would involve. It edits nothing. When the user wants the
-changes made, that is **live-tokens-fix-findings**, and the report is what it
-starts from.
+The answer to "check this project" is a report. Every fact in it comes from one command; the reading of those facts, and what fixing them would cost, is yours. This skill edits nothing. When the user wants the changes made, that is **live-tokens-fix-findings**, and this report is what it starts from.
 
-## Run the report
+## Workflow
 
-```sh
-npx live-tokens report --json
-```
+1. Run `npx live-tokens report --json`. It always exits 0: it is a reading, not a gate. Unknown command means the installed package predates it; upgrade `@motion-proto/live-tokens` first.
+2. Read each section against the table below. For every rule with findings, say in a line what the rule holds and whether the fix is mechanical or a judgement.
+3. Where a finding looks deliberate, name the config entry that would record the decision, and leave the decision to the user.
+4. Report in the order under Summary, each line carrying its count, and end by handing the list to **live-tokens-fix-findings**. Do not start applying fixes here, even one-liners, because the user asked how things stand.
 
-It always exits 0: it is a reading, not a gate. Unknown command means the
-installed package predates it; upgrade `@motion-proto/live-tokens` first. The
-sections, in the order the report gives them:
+`npx live-tokens components <id>` and `npx live-tokens tokens --family <name>` (both take `--json`) answer any question the report raises about one component or one scale.
 
-| Section | Fact | What it means when it is not clean |
+## The report's sections
+
+| Section | Fact | When it is not clean |
 | --- | --- | --- |
 | `migrations` | Whether `tokens.css` is behind the installed package | A stale file shows up downstream as unknown tokens. This is the first fix, and it is one command: `npx live-tokens migrate --check`, then `--write` (`--tokens <path>` for a tokens.css in an unusual place). |
 | `components[].unread` | Tokens a component declares that nothing in its file reads | An editor row that edits nothing. Each is a token to wire into the CSS or to remove. |
@@ -32,41 +29,22 @@ sections, in the order the report gives them:
 | `usage.customUnregistered`, `usage.customUnused` | The project's own components that are unregistered or unused | Dead or half-wired work. |
 | `findings.pages`, `findings.components` | Both checkers' findings by rule, under the project's severities and again under `--strict` | The errors are what fails the build today; the strict count is what a fully tokenized project would fail. |
 
-`npx live-tokens components <id>` and `npx live-tokens tokens --family <name>`
-(both take `--json`) answer any question the report raises about one
-component or one scale.
-
-## Read it
-
-Facts are the report's; the reading is yours. For each rule with findings, say
-in a line what the rule holds and which of two kinds the fix is:
+## Mechanical or judgement
 
-- **Mechanical**: a spacing literal to its nearest `--space-*` step, a stroke
-  to `--border-width-*`, a hardcoded column count to `var(--columns-count)`,
-  `site.css` moved out of `main.ts`, a route given its `source`. Name any
-  visible shift, such as a `14px` margin becoming `16px`.
-- **Judgement**: a colour literal mapped by the role it plays rather than its
-  hue, a raw type axis set from a text style, a prop the component does not
-  declare mapped or dropped. Say what the choice is, not what you would pick.
+- **Mechanical**: a spacing literal to its nearest `--space-*` step, a stroke to `--border-width-*`, a hardcoded column count to `var(--columns-count)`, `site.css` moved out of `main.ts`, a route given its `source`. Name any visible shift, such as a `14px` margin becoming `16px`.
+- **Judgement**: a colour literal mapped by the role it plays rather than its hue, a raw type axis set from a text style, a prop the component does not declare mapped or dropped. Say what the choice is, not what you would pick.
 
-Where a finding looks deliberate, a translucent overlay on an app shell or a
-layout size the project owns, say so and name the config entry that would
-record the decision: `"checks": { "rules": { "<rule>": "warn" } }` in
-`live-tokens.config.json`. Recording it is the user's call, not yours.
+## Deliberate findings
 
-## Report
+A translucent overlay on an app shell, or a layout size the project owns, may be a decision rather than a miss. Say so and name the entry that would record it: `"checks": { "rules": { "<rule>": "warn" } }` in `live-tokens.config.json`. Where a whole file is not a themed surface at all, hand-tuned artwork or vendored CSS, the entry is `"checks": { "exclude": ["src/art/hero.css"] }`: a project-relative path, a directory covering what is under it, and naming the file on the command line still checks it. Prefer the narrower one: an exclusion drops one file, a severity change drops a rule everywhere. Recording either is the user's call, not yours.
 
-In this order, each line carrying its count:
+## Summary
 
 1. Migrations pending, and the one command that clears them.
 2. What fails the build now: errors by rule, with the files.
 3. What `--strict` would add: warnings by rule.
 4. Components: unread tokens, unregistered, undescribed.
 5. Usage: what each page renders, and what is used nowhere.
-6. Recommended fixes, in the order **live-tokens-fix-findings** would take
-   them: migrations, then the largest group of errors, then the rest, then
-   warnings. Mark each as mechanical or judgement.
+6. Recommended fixes, in the order **live-tokens-fix-findings** would take them: migrations, then the largest group of errors, then the rest, then warnings. Mark each as mechanical or judgement.
 
-End with the hand-off: "Run live-tokens-fix-findings to apply these", or the
-subset the user chooses. Do not start applying them here, even when the fix is
-one line, because the user asked how things stand.
+End with the hand-off: "Run live-tokens-fix-findings to apply these", or the subset the user chooses.

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

@@ -1,6 +1,6 @@
 ---
 name: live-tokens-create-component
-description: Author a brand-new editable component for a @motion-proto/live-tokens project when nothing in the shipped catalogue fits — runtime and editor Svelte files, registration, naming, state model, and verification. Use when the user asks to author, create, or build a new tokenized component; make an existing Svelte component editable in the live-tokens editor; add a component to the catalogue; register a custom component with the editor; or build a [Thing] component that does not exist in the shipped set. Not for placing an existing shipped component on a page (see live-tokens-build-page); read live-tokens-pick-component first to confirm nothing in the catalogue fits.
+description: Author a brand-new editable component for a @motion-proto/live-tokens project when nothing in the shipped catalogue fits: runtime and editor Svelte files, registration, naming, state model, and verification. Use when the user asks to author, create, or build a new tokenized component; make an existing Svelte component editable in the live-tokens editor; add a component to the catalogue; register a custom component with the editor; or build a [Thing] component that does not exist in the shipped set. Not for placing an existing shipped component on a page (see live-tokens-build-page); read live-tokens-pick-component first to confirm nothing in the catalogue fits.
 ---
 
 # Authoring a component for a live-tokens project
@@ -9,22 +9,23 @@ The end state is a runtime Svelte file, an editor Svelte file, one registration,
 
 ## Worked examples ship inside the package
 
-For pattern reference, read any shipped component's source directly from the consumer's `node_modules`:
+Read a shipped component's source from the consumer's `node_modules` rather than from memory, because the files are the contract and this skill is not:
 
 - Runtime files: `node_modules/@motion-proto/live-tokens/src/system/components/<Name>.svelte`.
   - 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`.
-- Editor files: `node_modules/@motion-proto/live-tokens/src/editor/component-editor/<Name>Editor.svelte`.
+  - Every rule below in the fewest lines: `Toggle`. Component states name themselves in the token (`--toggle-on-*`, `--toggle-disabled-*`), interaction states layer on top (`--toggle-hover-*`, `--toggle-on-hover-*`), disabled is terminal (no `--toggle-disabled-hover-*`), and each `:hover` selector has a `.force-hover` sibling so the editor's preview can paint hover tokens without a pointer.
+- Editor files: `node_modules/@motion-proto/live-tokens/src/editor/component-editor/<Name>Editor.svelte`. `ToggleEditor` has no `groupKey` and no `canBeLinked`; for components that share base properties across variants, read `references/linked-siblings.md`.
 
-**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.
+Shipped editors live in `src/editor/component-editor/` because they are library-internal. For *your* component, co-locate both files in `src/system/components/`. Read the shipped files for pattern, ignore their location.
 
 ## The recipe
 
-1. **Runtime file** — `src/system/components/MyWidget.svelte`. Declare every editable slot as a CSS custom property inside `:global(:root)`, defaulting to a theme token (never a raw value). The plugin parses `:global(:root)` to seed `component-configs/<id>/default.json`; variables declared anywhere else can't be edited.
-2. **Editor file** — `src/system/components/MyWidgetEditor.svelte`. In a `<script module>` block, declare `const component = 'mywidget'`, build a `states: Record<string, Token[]>` for each VariantGroup, and export the flat union as `allTokens: Token[]`. Components with linked siblings also build a `linkableContexts: Map<string, string>` (read `references/linked-siblings.md`). Components with structural/display controls that aren't token values (alignment, element visibility, layout position) also export an `intrinsics: IntrinsicSpec[]` (read `references/intrinsics.md`). In the runtime `<script>` block, mount `ComponentEditorBase` with one `VariantGroup` per variant.
-3. **Register** — pass the component to `bootLiveTokens` in `src/main.ts`. This is the standard boot the scaffold generates and the README documents; `bootLiveTokens` calls `registerComponent` internally at the right point — after its editor init hooks (`cssVarSync.init`, `editorStore.init`), before it seeds configs and mounts the app:
+1. **Runtime file**, `src/system/components/MyWidget.svelte`. Declare every editable slot as a CSS custom property inside `:global(:root)`, defaulting to a theme token (never a raw value). The plugin parses `:global(:root)` to seed `component-configs/<id>/default.json`; variables declared anywhere else cannot be edited.
+2. **Editor file**, `src/system/components/MyWidgetEditor.svelte`. In a `<script module>` block, declare `const component = 'mywidget'`, build a `states: Record<string, Token[]>` for each VariantGroup, and export the flat union as `allTokens: Token[]`. Components with linked siblings also build a `linkableContexts: Map<string, string>` (read `references/linked-siblings.md`). Components with structural or display controls that are not token values (alignment, element visibility, layout position) also export an `intrinsics: IntrinsicSpec[]` (read `references/intrinsics.md`). In the runtime `<script>` block, mount `ComponentEditorBase` with one `VariantGroup` per variant.
+3. **Register** by passing the component to `bootLiveTokens` in `src/main.ts`, the boot the scaffold generates:
    ```ts
    import { bootLiveTokens } from '@motion-proto/live-tokens';
    import App from './App.svelte';
@@ -41,41 +42,16 @@ 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. **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
-   names the five `--sketch-*` values it is drawn with; a first-party component
-   adds a `PartSpec` row instead. The layer also takes `background`,
-   `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. **Gate on the checker.** Run it, fix every error, and run it again. Do not
-   call the component done while it reports one:
+   `bootLiveTokens` calls `registerComponent` for you after its editor init hooks and before it seeds configs, so a standalone `registerComponent(...)` placed *before* `bootLiveTokens` lands in the wrong window and can leave editor changes disconnected from the live page. Call `registerComponent` directly only when the app mounts manually, and then before `mount(App, ...)`. Registering against a built-in id wins with a console warning; the right call is a unique id.
+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), which is how **live-tokens-pick-component** weighs a project's own component against the shipped set: 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 names the five `--sketch-*` values it is drawn with; a first-party component adds a `PartSpec` row instead. The layer also takes `background`, `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. **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.
+   `--json` gives each finding a stable `rule` id and a line number, so work one rule at a time. `--strict` fails on warnings too, the right setting for a new component: every warning 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: every shipped component passes this same check, so the catalogue is the worked reference.
 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
@@ -86,11 +62,11 @@ For pattern reference, read any shipped component's source directly from the con
 --<componentId>-<part|variant>[-<state>][-<element>]-<property>
 ```
 
-- `componentId` — the literal id passed to `registerComponent()`. Lowercase, no dashes, no abbreviations (`segmentedcontrol` not `sc`). The file id matches: `MyWidget.svelte` → id `mywidget`.
-- `part` or `variant` — the sub-region (`bar`, `option`, `track`, `header`, `body`, `footer`, `overlay`, `value`, `label`), or, on a component whose variants differ in more than one property, the variant name: `--badge-accent-surface`, `--callout-danger-border`. A component with both stacks them outer to inner, so the bar in its small size is `--segmentedcontrol-bar-small-padding`.
-- `state` (optional) — interaction or component state (`hover`, `disabled`, `selected`, `focus`). **Always before the property.**
-- `element` (optional) — sub-element inside the part (`dot`, `icon`, `label`, `text`).
-- `property` — theme role or CSS property. Always last.
+- `componentId`: the literal id passed to `registerComponent()`. Lowercase, no dashes, no abbreviations (`segmentedcontrol` not `sc`). The file id matches: `MyWidget.svelte` is id `mywidget`.
+- `part` or `variant`: the sub-region (`bar`, `option`, `track`, `header`, `body`, `footer`, `overlay`, `value`, `label`), or, on a component whose variants differ in more than one property, the variant name: `--badge-accent-surface`, `--callout-danger-border`. A component with both stacks them outer to inner, so the bar in its small size is `--segmentedcontrol-bar-small-padding`.
+- `state` (optional): interaction or component state (`hover`, `disabled`, `selected`, `focus`). **Always before the property.**
+- `element` (optional): sub-element inside the part (`dot`, `icon`, `label`, `text`).
+- `property`: theme role or CSS property. Always last.
 
 ### Suffix vocabulary
 
@@ -121,12 +97,12 @@ 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). 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.
+- **State before property.** `--mywidget-button-hover-surface` passes; `--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, which is what makes the component repaint when the theme changes. `var(--surface-primary)` passes; `#6a4ce8`, `white`, `var(--surface-imaginary)`, and a bare `16rem` all fail, because `check-component` rejects a colour literal in any notation, a `var()` naming a token that does not exist, and a default with no token behind it. 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` is `surface`; `fg` is `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.
-- **Let the type-group helpers derive slot-scoped keys; never rely on the bare last-dash default.** When you build typography tokens with `buildTypeGroupColorTokens` / `buildTypeGroupTokens` / `buildTypeGroupFontTokens`, **pass `{ component, variants }`** so each slot gets a distinct, structural `groupKey`:
+- **Typography `groupKey` on multi-slot components must include the slot prefix.** `groupKey: 'value-font-family'` and `groupKey: 'label-font-family'` stay distinct; a bare `groupKey: 'font-family'` silently merges the slots 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 colours (two slots ending in `-text` collapsing to one `text` key).
+- **Let the type-group helpers derive slot-scoped keys.** When you build typography tokens with `buildTypeGroupColorTokens` / `buildTypeGroupTokens` / `buildTypeGroupFontTokens`, pass `{ component, variants }` so each slot gets a distinct, structural `groupKey`:
 
   ```ts
   // variants = the variant/state segment strings as they appear in the variable name
@@ -135,24 +111,23 @@ control behind it.
   ...buildTypeGroupFontTokens(typeGroups, { component, variants: [...VARIANTS] }),
   ```
 
-  The helper strips the `--<component>-` prefix and those segments, keeping the rest: `--mywidget-header-default-text` → `header-text`, `--mywidget-header-default-text-font-family` → `header-text-font-family`. Two parts ending in the same word stay distinct; one slot across variants collapses to one key. To override a single derived key, set `colorGroupKey` on that type-group config — it wins and is never recomputed, so your fix survives. There is no name-based fallback: a bare `buildTypeGroupColorTokens` call emits un-grouped (solo) colors rather than guessing, and a bare *font* helper across multiple slots is a `check-component` warning (its default `font-family`/… keys would merge the slots' fonts).
-
+  The helper strips the `--<component>-` prefix and those segments, keeping the rest: `--mywidget-header-default-text` becomes `header-text`, and `--mywidget-header-default-text-font-family` becomes `header-text-font-family`. Two parts ending in the same word stay distinct; one slot across variants collapses to one key. To override a single derived key, set `colorGroupKey` on that type-group config; it wins and is never recomputed. There is no name-based fallback: a bare `buildTypeGroupColorTokens` call emits un-grouped (solo) colours rather than guessing, and a bare *font* helper across multiple slots is a `check-component` warning, because its default keys would merge the slots' fonts.
 
 ## State model
 
-Components *can* have two state axes. Many don't: container and messaging components (Card, Badge, Callout, CollapsibleSection) have only variants, no hover/disabled. Skip the rest of this section for those.
+Components *can* have two state axes. Many do not: container and messaging components (Card, Badge, Callout, CollapsibleSection) have only variants, no hover or disabled. Skip the rest of this section for those.
 
-When a component does have states, don't mix the two axes:
+When a component does have states, keep the two axes apart:
 
-- **Component states** — mutually exclusive top-level fieldsets: `default`, `selected`, `disabled` (names vary by component). One fieldset per component state.
-- **Interaction states** — a select *inside* each component-state fieldset: `default`, `hover`. Add `focus`/`active` later if needed.
+- **Component states** are mutually exclusive top-level fieldsets: `default`, `selected`, `disabled` (names vary by component). One fieldset per component state.
+- **Interaction states** are a select *inside* each component-state fieldset: `default`, `hover`. Add `focus` or `active` later if needed.
 
 Rules:
 
-- **Disabled is terminal.** A disabled component can't be hovered or focused. The `disabled` fieldset is flat — no interaction selector.
-- **`selected-disabled` is impossible.** Don't author tokens or fieldsets for it.
-- **Parts ≠ states.** Dialog's `overlay | header | body | footer` are *parts* (all present simultaneously), not states. The VariantGroup tab strip defaults its label to "Element" (neutral). If you label tabs anywhere, use **part** for structure and **state** for runtime conditions. Never call a footer a state.
-- **Don't call interaction states "option states" or "selected states"** in the UI. `selected` is a *component* state.
+- **Disabled is terminal.** A disabled component cannot be hovered or focused. The `disabled` fieldset is flat, with no interaction selector.
+- **`selected-disabled` is impossible.** Do not author tokens or fieldsets for it.
+- **Parts are not states.** Dialog's `overlay | header | body | footer` are *parts* (all present at once), not states. The VariantGroup tab strip defaults its label to "Element" (neutral). If you label tabs anywhere, use **part** for structure and **state** for runtime conditions. Never call a footer a state.
+- **Do not call interaction states "option states" or "selected states"** in the UI. `selected` is a *component* state.
 
 Token naming consequence:
 
@@ -161,14 +136,14 @@ Token naming consequence:
 --mywidget-option-disabled-surface   ✗  implies disabled is an interaction state
 --mywidget-option-hover-surface      ✓  default-component-state, hover-interaction
 --mywidget-selected-hover-surface    ✓  selected-component-state, hover-interaction
---mywidget-selected-disabled-text    ✗  selected-disabled doesn't exist
+--mywidget-selected-disabled-text    ✗  selected-disabled does not exist
 ```
 
 ## User-facing copy
 
-Strings you author for the editor UI use periods and commas, never em-dashes. Em-dashes read as an AI tell. This applies to `title=` and `description=` on `ComponentEditorBase`, token row labels, info popovers, and any text inside `previewActions` / `canvasToolbarExtras` snippets. Code comments are unaffected.
+Strings you author for the editor UI use periods and commas, never em-dashes, which read as an AI tell. This applies to `title=` and `description=` on `ComponentEditorBase`, token row labels, info popovers, and any text inside `previewActions` / `canvasToolbarExtras` snippets. Code comments are unaffected.
 
-If you add custom chrome inside an editor snippet (rare — `ComponentEditorBase` and `VariantGroup` carry the standard chrome), keep it greyscale (no accent colors) and reference heading sizes via `--ui-font-size-md` / `-lg` / `-2xl` rather than pixel literals.
+Custom chrome inside an editor snippet is rare, since `ComponentEditorBase` and `VariantGroup` carry the standard chrome. Where you add some, keep it greyscale (no accent colours) and reference heading sizes via `--ui-font-size-md` / `-lg` / `-2xl` rather than pixel literals.
 
 ## Public imports only
 
@@ -187,26 +162,6 @@ That covers everything the worked examples use. Additional primitives (`LinkedBl
 
 **Never deep-import `node_modules/@motion-proto/live-tokens/src/...`.** Reading those files for pattern reference is fine; importing them at runtime is not. If you need something not exported, file an issue rather than reaching in.
 
-## Worked example: the shipped Toggle
-
-Toggle exercises every rule above in the fewest lines. Read both files from the package rather than from memory, because they are the contract and this skill is not:
-
-- `node_modules/@motion-proto/live-tokens/src/system/components/Toggle.svelte`
-- `node_modules/@motion-proto/live-tokens/src/editor/component-editor/ToggleEditor.svelte`
-
-What to notice in the runtime file:
-
-- Component states (`on`, `disabled`) name themselves in the token: `--toggle-on-*`, `--toggle-disabled-*`.
-- Interaction states layer on top: `--toggle-hover-*` for default+hover, `--toggle-on-hover-*` for on+hover.
-- Disabled is terminal: no `--toggle-disabled-hover-*`, no `--toggle-on-disabled-*`.
-- The `force-hover` class pairs with the editor's preview hook so hover tokens paint without a real pointer. Each `:hover` selector has a matching `.force-hover` sibling.
-
-What to notice in the editor file:
-
-- No `groupKey`, no `canBeLinked`: Toggle has no linked siblings. For components that share base properties across variants, read `references/linked-siblings.md`.
-
-For your own component, copy the pattern and substitute your id. Registering against a built-in id wins with a console warning, but the right call is a unique id.
-
 ## Extensions
 
 Read the sketch reference for every component; the other two only when they apply.
@@ -217,24 +172,11 @@ Read the sketch reference for every component; the other two only when they appl
 
 ## Verification checklist
 
-After saving, run the static validator first:
-
-```bash
-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, 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, 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.
+Step 6 of the recipe is the static gate: `npx live-tokens check-component <id>` at exit 0, with `--strict` clean or its warnings resolved. It enforces the file layout, the `:global(:root)` block, the suffix vocabulary, state-before-property, the terminal disabled state, public imports, that every token an editor row names is declared in the runtime, that every default reads a theme token, and that the id is registered through `bootLiveTokens({ components: [{ id }] })` or a direct `registerComponent({ id })` call.
 
-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.
+**Then run the registry contract test.** `checkRegistryEntry`, from `@motion-proto/live-tokens/component-editor/contract`, takes one registry entry and returns a violation line per failure, so a suite over your own components is a `describe.each` and one call. It verifies that the registration resolves to a real `sourceFile` and a non-empty schema, that schema variables are unique, that every editable token is declared in the runtime `<style>` block and seeded in `component-configs/<id>/default.json`, that a token declaring `minOpacity` seeds at or above its floor, and that `setComponentAlias` round-trips the alias through the slice. The test file and its path options are in `references/contract-tests.md`. Inside the package, `registryContract.test.ts` runs that same check over `builtInRegistry`, so a first-party component is covered the moment it lands there.
 
-**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.
+**If your component declares `intrinsics`, the intrinsics contract test covers it too.** `intrinsicsContract.test.ts` asserts, per (intrinsic, variant), that the runtime `:global(:root)` declares a default, that it is one of the spec's `values`, and that the editor's `default` equals it. This is what would have caught a getter defaulting to `center` while `:global(:root)` says `start`.
 
 Finally navigate to `/live-tokens/components` and confirm the runtime behaviours no static check can see:
 

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

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

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

@@ -85,10 +85,17 @@ preview of the hover state, and a hover the sketch layer cannot paint reads as
 no hover at all once the real background is transparent.
 
 An inner part that carries its own surface (a header strip, a footer) takes its
-own class and its own five values. Where such a part draws no outline, bind the
+own class and its own five values. The class is easy to forget, because the part
+already has its own values and looks finished without it — a part carrying only
+the values is left crisp, and reads as a hard-edged rectangle dropped inside a
+drawn box. No checker sees it. Where such a part draws no outline, bind the
 hatch ink to the ink its **parent** is outlined in, so the component reads as one
 drawing rather than a shaded panel dropped into a box:
 
+```svelte
+<span class="mywidget-header sketch-chip">{label}</span>
+```
+
 ```css
 .mywidget-header {
   --sketch-fill: var(--mywidget-header-surface);
@@ -176,8 +183,7 @@ inherits, so one declaration covers everything under it:
 
 Travel is stated in px against a glyph whose size the layer cannot know, so the
 dial that suits a card's worth of artwork tears a 16px icon apart. Reach for the
-soft bank before reaching for `none`. The shipped `SectionDivider` is the worked
-example.
+soft bank before reaching for `none`.
 
 ## First-party components
 

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

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