@motion-proto/live-tokens 0.74.0 → 0.76.0

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

@@ -1,189 +1,241 @@
 ---
 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: Create an editable component for a @motion-proto/live-tokens project. A component is a runtime Svelte file, an editor Svelte file, and one registration. The runtime file declares one semantic property per editable CSS property and assigns each an existing design token. The property names are semantic, based on function, and reuse the names of the existing components. Use when live-tokens-pick-component finds no suitable component, or the user asks for a new component. Use when the user asks to make an existing Svelte component editable in the live-tokens editor. For page integration, read live-tokens-create-page.
 ---
 
-# Authoring a component for a live-tokens project
-
-The end state is a runtime Svelte file, an editor Svelte file, one registration, and an entry on `/live-tokens/components` under the **CUSTOM** group with full token editing, linked-block sharing, and persistence.
-
-## Worked examples ship inside the package
-
-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`.
-  - 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`.
-
-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 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';
-   import MyWidgetEditor, { allTokens as myWidgetTokens } from './system/components/MyWidgetEditor.svelte';
-
-   bootLiveTokens(App, '#app', {
-     components: [{
-       id: 'mywidget',
-       label: 'My Widget',
-       icon: 'fas fa-magic',
-       sourceFile: 'src/system/components/MyWidget.svelte',
-       editorComponent: MyWidgetEditor,
-       schema: myWidgetTokens,
-     }],
-   });
-   ```
-   `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. `--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. `--off=<rule>` silences a rule for one run, which a component still being authored has no use for: the finding is a decision to make. 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
-
-### Naming scheme
+# Creating a component for a live-tokens project
 
-```
---<componentId>-<part|variant>[-<state>][-<element>]-<property>
-```
+Create a component whose structure and behavior serve the user's purpose. Give each editable visual property a semantic name. Assign its default from the existing design tokens. Deliver the runtime file, the editor file, and the registration together.
+
+## Workflow
+
+1. Read the project: `package.json`, `live-tokens.config.json`, `src/main.ts`, the catalogue, the token scales the component will use, a shipped runtime and editor pair, and the property suffixes.
+2. Design the properties: separate the component's parts, variants, and states, then write one row per editable role with its token and the CSS it controls, named the way the shipped components name the same role.
+3. Write the runtime file: the usage comment and the `:global(:root)` block. A structural choice is an intrinsic. Every component joins the sketch layer, and a fixed overlay portals to `<body>`.
+4. Write the editor file: the schema, the preview props, and the markup. Variants that share a value are linked.
+5. Register the component in the module `src/main.ts` and `live-tokens.testing.ts` both name.
+6. Run **live-tokens-check-compliance**, then `npx live-tokens check-component <id> --tests --strict --json` until exit 0 with complete applicable coverage, then the Svelte check and the build.
+7. Reply with the files, the id, the props, and each check's result. Then place the component on a page with **live-tokens-create-page**.
+
+## Design model
+
+A live-tokens project has two layers.
+
+| Layer | Responsibility | Example |
+|---|---|---|
+| Design tokens | Name the available colors, typography, geometry, and motion values. A theme sets the values. | `--space-16`, `--radius-md`, `--surface-neutral` |
+| Semantic properties | Name the visual roles within a component and reference tokens. A component config records these assignments. | `--statcard-padding: var(--space-16)` |
+
+A token is assigned to a property, and a CSS declaration reads the property. The editor changes the assignment; the runtime reads the property. Keep the assignment a token reference, so a theme change reaches the component.
+
+A property describes its purpose: `--statcard-value`, `--statcard-radius`, `--statcard-label-font-size`. Its name stays stable when its assigned color or size changes. Use role names such as `surface` and `text`. Use full words for component ids and parts.
+
+A component is distinct in its anatomy, its proportions, its content hierarchy, and its behavior. Its appearance comes from the existing tokens. Create only the variants and states the task requires. The tokens stay as they are; a new token is a separate change to the design system.
+
+Props carry content and behavior: a value, a label, a callback. Properties carry the editable appearance. When a variant is a choice the page makes, expose it as a prop.
 
-- `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.
+## Source inspection
 
-### Suffix vocabulary
+Before writing a file:
 
-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`,
-`-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`.
+1. Read the project's `package.json`, `live-tokens.config.json`, and `src/main.ts`.
+2. Run `npx live-tokens components`. The list holds every component the project has, with its variants and usage comment. `npx live-tokens components <id>` prints one component's props.
+3. Run `npx live-tokens tokens --scale <name>` for each token scale the component will use. Those names are the tokens a property can reference.
+4. Read a shipped runtime and editor pair: `Toggle` for interaction states, `Badge` for variants and linked values, `Card` for text and container parts.
+5. Read `references/token-naming.md` for the suffixes that select editor controls.
 
-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.
+The shipped sources are in `node_modules/@motion-proto/live-tokens/src/`: the runtime at `system/components/<Name>.svelte`, the editor at `editor/component-editor/<Name>Editor.svelte`. Inside the live-tokens repository, read them from the repository root. The source is the contract.
 
-Read `references/token-naming.md` for what each one means and when two of them
-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
-`set-geometry` CLI, and `check-component` all read, so a name accepted here
-always has a control behind it.
+## Variants and states
 
-### Rules that bite
+A component has three kinds of division. Keep them apart in the props, the names, and the editor.
 
-- **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` 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'` 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`:
+| Kind | Meaning | Example |
+|---|---|---|
+| Part | Regions present at once | Dialog's overlay, header, body, footer |
+| Variant | Alternative presentations the page chooses | Badge's primary, danger |
+| State | A runtime condition | Toggle's on, hover, disabled |
 
-  ```ts
-  // variants = the variant/state segment strings as they appear in the variable name
-  const VARIANTS = ['default', 'hover'] as const;
-  ...buildTypeGroupColorTokens(typeGroups, { component, variants: [...VARIANTS] }),
-  ...buildTypeGroupFontTokens(typeGroups, { component, variants: [...VARIANTS] }),
-  ```
+States have two axes. A component state is one of a set that excludes the others: default, selected (or on), disabled. An interaction state layers on a component state: default, hover, and later focus or active. `disabled` is terminal: no other state layers on it, in the names or in the editor.
 
-  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.
+The default state carries the shared geometry and typography. A state adds properties only for the values that change: `--toggle-on-track-surface`, `--toggle-on-hover-track-surface`.
 
-## State model
+The preview renders the state being edited. Pair each `:hover` selector with a `.force-hover` selector and expose a `class` prop, so the editor shows hover without a pointer. Keep native disabled behavior, keyboard operation, and visible focus on an interactive control.
 
-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.
+A component supplies its variants. The page chooses the one primary action.
 
-When a component does have states, keep the two axes apart:
+## Property design
 
-- **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.
+Before writing a file, identify the component's parts, text roles, variants, and states. Then write a property map: one row per editable role, with the token it is assigned and the CSS property it controls. Keep separate roles independent even when they start with the same value.
 
-Rules:
+| Property | Assigned token | CSS use |
+|---|---|---|
+| `--statcard-surface` | `--surface-neutral` | `background` |
+| `--statcard-border` | `--border-neutral` | `border-color` |
+| `--statcard-border-width` | `--border-width-1` | `border-width` |
+| `--statcard-radius` | `--radius-md` | `border-radius` |
+| `--statcard-padding` | `--space-16` | `padding` |
+| `--statcard-value` | `--text-primary` | `color` of the value |
+| `--statcard-value-font-size` | `--font-size-2xl` | `font-size` of the value |
+| `--statcard-label` | `--text-secondary` | `color` of the label |
 
-- **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.
+Assign from the tokens the project has. Match the token scale to the role: `--surface-*` for a fill, `--border-*` for an outline, `--text-*` for text, and the space, radius, border-width, and icon-size scales for geometry. Give each text role five properties: `-font-family`, `-font-size`, `-font-weight`, `-line-height`, and `-letter-spacing`.
 
-Token naming consequence:
+A property name starts with the component id and ends with the property suffix. Use this shape for part-specific states:
 
+```text
+--<componentId>[-<variant>][-<part>][-<state>]-<property>
 ```
---mywidget-disabled-surface          ✓  component-state-level
---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 does not exist
+
+- `componentId` is the runtime file name in lowercase with no dashes: `StatCard.svelte` is `statcard`.
+- `variant` is present when the component has more than one: `--card-default-surface`, `--card-bare-surface`. A component with one variant has no variant segment: `--toggle-track-surface`.
+- `part` names a region inside the component: `header`, `body`, `track`, `thumb`. The editor's `element` tag groups rows in the panel and is never a name segment.
+- `state` comes before the property: `--card-hover-border`. `disabled` is terminal, so no name pairs `disabled` with another state.
+- `property` is the suffix, and the suffix selects the editor control: `-surface` for a fill, `-border` for a border color, `-border-width` for a stroke, `-radius` for corners, `-padding` and `-gap` for spacing, and the five typography suffixes. `references/token-naming.md` lists every suffix.
+
+For a state that affects several parts, follow Toggle: `--toggle-on-hover-track-surface`. State segments precede the affected part.
+
+Name a role as the shipped component that paints the same thing names it. A fill is `-surface` in every shipped component. A knob is `-thumb`. A text role's color sits on the role's own name, `-title`, `-body`, `-label`, `-value`, and its typography hangs off that name: `--card-default-title-font-size`. A component with one text role uses `-text`: `--badge-primary-text`.
+
+## Runtime component
+
+Create `src/system/components/StatCard.svelte`. `check-component` finds a runtime there only. A component in another directory is listed by `components` and `report` when that directory is named in `"componentDirs"` in `live-tokens.config.json`, and `check-component` does not check it. Use Svelte 5 props and snippets, semantic HTML, and the behavior the task requires.
+
+Open the file with an HTML comment in the shape every shipped component carries. `npx live-tokens components` prints the comment beside the id, and `components <id>` prints the props.
+
+```svelte
+<!--
+  StatCard.svelte. A figure with its label.
+  Use for: one number the reader takes in at a glance.
+  Not for: a set of records (Table); a titled block of content (Card).
+-->
 ```
 
-## User-facing copy
+Declare every editable property in a literal `:global(:root)` block, each assigned a token. The plugin parses the Svelte source to seed `component-configs/<id>/default.json`, so the block holds plain declarations with no SCSS loop or interpolation.
+
+```svelte
+<style>
+  :global(:root) {
+    --statcard-surface: var(--surface-neutral);
+    --statcard-border: var(--border-neutral);
+    --statcard-border-width: var(--border-width-1);
+    --statcard-radius: var(--radius-md);
+    --statcard-padding: var(--space-16);
+    --statcard-value: var(--text-primary);
+    --statcard-value-font-size: var(--font-size-2xl);
+    --statcard-label: var(--text-secondary);
+  }
+
+  .statcard {
+    display: grid;
+    background: var(--statcard-surface);
+    border: var(--statcard-border-width) solid var(--statcard-border);
+    border-radius: var(--statcard-radius);
+    padding: var(--statcard-padding);
+  }
+
+  .value { color: var(--statcard-value); font-size: var(--statcard-value-font-size); }
+  .label { color: var(--statcard-label); }
+</style>
+```
 
-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.
+The excerpt shows the chain for part of the property map. Every editable value reads a property. Structural CSS (`display: grid`, `width: 100%`, `align-items: center`) stays in the layout rules. A value beyond a scale is a token expression: `calc(var(--space-64) * 4)`. A property that carries a structural choice, an alignment or a visibility, is an intrinsic: read `references/intrinsics.md`.
+
+## Component editor
+
+Create `src/system/components/StatCardEditor.svelte` beside the runtime file. The editor has three parts.
+
+1. A `<script module>` block exports `component`, the id, and `allTokens`, one row per property in the map. A row is `{ label, variable, element? }`; `element` groups rows in the panel by part, and `label` names the property in the row.
+2. The instance script imports the runtime component and the editor primitives from the package's public paths, and maps the state being edited to preview props.
+3. The markup mounts `ComponentEditorBase` with one `VariantGroup` per variant, each rendering a preview.
+
+```svelte
+<script module lang="ts">
+  import type { Token } from '@motion-proto/live-tokens/component-editor';
+
+  export const component = 'statcard';
+  const states: Record<string, Token[]> = {
+    default: [
+      { label: 'surface', element: 'frame', variable: '--statcard-surface' },
+      { label: 'border', element: 'frame', variable: '--statcard-border' },
+      { label: 'border width', element: 'frame', variable: '--statcard-border-width' },
+      { label: 'radius', element: 'frame', variable: '--statcard-radius' },
+      { label: 'padding', element: 'frame', variable: '--statcard-padding' },
+      { label: 'text', element: 'value', variable: '--statcard-value' },
+      { label: 'font size', element: 'value', variable: '--statcard-value-font-size' },
+      { label: 'text', element: 'label', variable: '--statcard-label' },
+    ],
+  };
+  export const allTokens: Token[] = Object.values(states).flat();
+</script>
+
+<script lang="ts">
+  import { ComponentEditorBase, VariantGroup } from '@motion-proto/live-tokens/component-editor';
+  import StatCard from './StatCard.svelte';
+</script>
+
+<ComponentEditorBase {component} title="Stat Card" tokens={allTokens}>
+  <VariantGroup name="statcard" title="Stat Card" {states} {component}>
+    <StatCard value="1,204" label="Sessions" />
+  </VariantGroup>
+</ComponentEditorBase>
+```
 
-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.
+The shipped editor for the closest component gives the preview snippet for a component with states. Custom chrome in an editor takes `--ui-*` tokens and no accent color; its copy uses periods and commas, never em-dashes.
 
-## Public imports only
+When variants share a value, read `references/linked-siblings.md`. A `groupKey` is scoped to the text role: `value-font-size` and `label-font-size` stay separate keys. A `buildTypeGroup*` helper takes `{ component, variants }` so it derives one key per role.
 
-Imports in your runtime, editor, and `main.ts` come from exactly two paths:
+## Registration
+
+Register the component in `src/registerComponents.ts`, a registration-only module, beside any registration already there. The id is unique; a registration that repeats a shipped id replaces that component.
 
 ```ts
-import { registerComponent, editorState } from '@motion-proto/live-tokens';
-import {
-  ComponentEditorBase, VariantGroup,
-  computeLinkedBlock, withLinkedDisabled, buildSiblings,
-} from '@motion-proto/live-tokens/component-editor';
-import type { Token } from '@motion-proto/live-tokens/component-editor';
+// src/registerComponents.ts
+import { registerComponent } from '@motion-proto/live-tokens';
+import StatCardEditor, { allTokens as statCardTokens } from './system/components/StatCardEditor.svelte';
+
+registerComponent({
+  id: 'statcard',
+  label: 'Stat Card',
+  icon: 'fas fa-chart-simple',
+  sourceFile: 'src/system/components/StatCard.svelte',
+  editorComponent: StatCardEditor,
+  schema: statCardTokens,
+});
 ```
 
-That covers everything the worked examples use. Additional primitives (`LinkedBlock`, `TypeEditor`, `TokenLayout`, `buildTypeGroupTokens`, `buildTypeGroupColorTokens`, `buildTypeGroupFontTokens`, `buildTypeGroupShareableContexts`, the `TypeGroupConfig` type, more types) are exported from the same paths for advanced cases.
+Import the module from `src/main.ts`, before `bootLiveTokens` or `mount`, and name it as `registrySetup` in `live-tokens.testing.ts`. One module then serves the running app and `check-component --tests`, which imports it to see the registration without mounting the app: read `references/contract-tests.md`. A component that declares intrinsics adds `intrinsics` to the entry. `check-component` finds the registration by the id literal inside the call.
+
+At boot the plugin reads the `:global(:root)` block and writes `component-configs/<id>/default.json`, one token per property. An edit in the editor writes `_working.json`; Save As writes a named config. The assignments stay token references through that flow.
 
-**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.
+Inside the live-tokens repository, a first-party component keeps its editor in `src/editor/component-editor/` and takes an entry in `builtInRegistry` in `src/editor/component-editor/registry.ts`.
 
-## Extensions
+## Sketch mode and overlays
 
-Read the sketch reference for every component; the other two only when they apply.
+Every component joins the sketch layer: read `references/sketch-mode.md`. A suitable root or inner wrapper carries a reserved class and names five `--sketch-*` values from its own properties. Preserve positioning, clipping, and pseudo-elements as the reference specifies. A first-party component adds a `PartSpec` row instead.
 
-- `references/linked-siblings.md`: variants that share base properties and should move together (Badge, Card, SegmentedControl).
-- `references/intrinsics.md`: structural or display choices that are not token values (an alignment, an element's visibility), where the runtime default and the editor's read-back must agree.
-- `references/sketch-mode.md`: joining the sketch layer. **Every component needs this.** One class on the root, the five `--sketch-*` values the layer draws with, and the list of what it takes over from the element. Skip it and the component stays crisp while the page around it goes hand-drawn.
+A fixed overlay portals to `<body>`: read `references/fixed-overlays.md`. A container that owns the typography of its content follows `Card` and its `prose` prop.
 
-## Verification checklist
+## Verification
 
-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.
+1. Run **live-tokens-check-compliance** and address its findings with **live-tokens-fix-findings**. Then run `npx live-tokens check-component <id> --tests --strict --json`. Inside the live-tokens repository, run `node bin/cli.mjs check-component <id> --tests --strict --json`. Each finding carries a rule id and a line; `--off=<rule>` silences a rule for one run. `--tests` runs the registry contract and the component contract suites, and its JSON reports coverage by rule. A `tests-not-installed` finding names the missing package; install `@playwright/test`, `vitest`, and `happy-dom` as devDependencies, then `npx playwright install chromium`. Fix every finding and rerun until exit 0 with complete applicable coverage and no disabled checks.
+2. Run the project's Svelte check and its build.
+3. Reply with the files, the component id, the props, and the results of steps 1 and 2, naming any check the environment prevented.
 
-**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.
+Every finding carries a `fix` slug naming the section that fixes it.
 
-**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`.
+| `fix` | Section |
+|---|---|
+| `property-name` | Property design, the name |
+| `property-token` | Property design, the assigned token |
+| `runtime` | Runtime component |
+| `runtime-defaults` | Runtime component, the `:global(:root)` defaults |
+| `editor` | Component editor |
+| `registration` | Registration |
+| `sketch` | Sketch mode and overlays |
+| `tooling` | The message names the missing tool or the broken path; fix it and rerun |
+| `coverage` | Add the missing contract, or complete the run the message names |
 
-Finally navigate to `/live-tokens/components` and confirm the runtime behaviours no static check can see:
+`--tests` covers every line a reviewer once checked by eye: the component's listing, its controls and preview, persistence and reset, theme projection, linked properties, and Sketch mode.
 
-- [ ] The new component appears in the nav rail under the **CUSTOM** group (system entries above, custom below the labeled divider).
-- [ ] Token rows render. Color pickers, radius selectors, font selectors all work.
-- [ ] Linked-block (if your component has linked siblings): shared rows appear with the link toggle. Changing the linked value broadcasts across every variant.
-- [ ] `component-configs/<id>/default.json` is derived from the `:global(:root)` block at boot. Save writes `_working.json`, the unsaved buffer the open theme captures; Save As also writes a named preset.
-- [ ] Reset returns each variable to its `:global(:root)` default.
-- [ ] Boot validation is clean (no warnings about the component being missing from the server scan, or about disk-vs-registry drift).
-- [ ] Switch Sketch mode on in the editor and walk the checklist at the end of `references/sketch-mode.md`. The component is drawn in every variant and on hover, in its own colours, not crisp and not wearing another part's palette. Switch it off again and the component is unchanged.
+Then place the component on a page with **live-tokens-create-page**.

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

@@ -1,17 +1,45 @@
-# The registry contract as a test in your own project
+# The registry contract as a test in a consumer 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.
+The package ships the contract as a test file. `checkRegistryEntry` is the
+assertion behind it, exported so a project can write its own file instead. The
+contract takes one registry entry and returns a violation line per failure; an
+empty array is the pass.
+
+## The shipped path
+
+`npx live-tokens check-component <id> --tests` runs the shipped file for you,
+under vitest, alongside the Playwright component contract suites, and maps
+every failure to a finding with a rule id and a line. The compiled file is
+`src/testing-js/registry.contract.js`; the `.ts` source it compiles from is not
+in the tarball.
+
+It resolves a shipped component's `sourceFile` against the package and yours
+against your project, and reports a component that exists as files and never
+reached a registration.
+
+Add `@playwright/test`, `vitest`, and `happy-dom` as devDependencies, then
+`npx playwright install chromium`. A missing one is a `tests-not-installed`
+finding naming the install command.
+
+Name the module that registers your components, in `live-tokens.testing.ts` at
+the project root, as a plain quoted string:
 
 ```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';
+// live-tokens.testing.ts
+import { defineTestingConfig } from '@motion-proto/live-tokens/testing/vitest';
+
+export default defineTestingConfig({
+  registrySetup: 'src/registerComponents.ts',
+});
+```
+
+The setup module registers and stops there, exactly as the Registration
+section of live-tokens-create-component wires it up:
+
+```ts
+// src/registerComponents.ts
+import { registerComponent } from '@motion-proto/live-tokens';
+import MyWidgetEditor, { allTokens } from './system/components/MyWidgetEditor.svelte';
 
 registerComponent({
   id: 'mywidget',
@@ -21,53 +49,68 @@ registerComponent({
   editorComponent: MyWidgetEditor,
   schema: allTokens,
 });
+```
 
-const mine = getComponentRegistryEntries().filter((e) => e.origin === 'custom');
+Import the same module from `src/main.ts`, so one list of registrations serves
+the app and the tests. Importing an editor registers nothing, and importing
+`main.ts` would mount the app, which is why the registrations live in a module
+of their own.
 
-describe.each(mine.map((e) => [e.id, e] as const))('%s', (_id, entry) => {
-  it('meets the registry contract', () => {
-    expect(checkRegistryEntry(entry)).toEqual([]);
-  });
-});
-```
+`LIVE_TOKENS_COMPONENT=<id>` is what `check-component <id> --tests` sets for
+you; it narrows the run to one component and fails when no component is
+registered under that id.
+
+## Running vitest yourself
 
-Two lines there are load-bearing.
+`check-component --tests` covers the shipped path. Run vitest directly only
+when you need to drive it outside the CLI. `createVitestConfig` lives at
+`@motion-proto/live-tokens/testing/vitest`, which never imports
+`@playwright/test`, so a project holding only `vitest` and `happy-dom` can
+still build this config:
 
-- **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.
+```ts
+// vitest.contract.config.ts
+import { createVitestConfig } from '@motion-proto/live-tokens/testing/vitest';
+import viteConfig from './vite.config';
+import settings from './live-tokens.testing';
 
-## Setup
+export default createVitestConfig(viteConfig, { registrySetup: settings.registrySetup });
+```
 
-`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.
+```bash
+npx vitest run --config vitest.contract.config.ts
+```
 
-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:
+## Writing your own file
+
+`checkRegistryEntry` is exported at
+`@motion-proto/live-tokens/component-editor/contract`, so a project that wants
+its own suite writes two lines against its own registrations:
 
 ```ts
-// vitest.config.ts
-import { defineConfig, mergeConfig } from 'vitest/config';
-import viteConfig from './vite.config';
+// tests/registryContract.test.ts
+// @vitest-environment happy-dom
+import { describe, it, expect } from 'vitest';
+import { getComponentRegistryEntries } from '@motion-proto/live-tokens';
+import { checkRegistryEntry } from '@motion-proto/live-tokens/component-editor/contract';
+import '../src/registerComponents';
+
+const mine = getComponentRegistryEntries().filter((e) => e.origin === 'custom');
 
-export default mergeConfig(
-  viteConfig,
-  defineConfig({
-    test: {
-      server: { deps: { inline: [/@motion-proto\/live-tokens/, /@fortawesome/] } },
-    },
-  }),
-);
+describe.each(mine.map((e) => [e.id, e] as const))('%s', (_id, entry) => {
+  it('meets the registry contract', () => {
+    expect(checkRegistryEntry(entry)).toEqual([]);
+  });
+});
 ```
 
+Filter on `origin`. The registry always carries the shipped components too, and
+their `sourceFile` paths are relative to the package root. Without the filter
+every built-in fails on a path that does not exist in your project.
+
+The helper reads the runtime file and `default.json` off disk, which is why it
+is node-only and has its own subpath.
+
 ## Paths
 
 Paths resolve against `process.cwd()` and `src/live-tokens/data/component-configs`.
@@ -81,17 +124,17 @@ checkRegistryEntry(entry, { projectRoot, componentConfigsDir });
 
 ## 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
+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
+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
+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.
+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