@motion-proto/live-tokens 0.76.0 → 0.78.0

package/src/editor/skill-atlas/skillSources.generated.ts

@@ -5,11 +5,11 @@ export const SKILL_DOC = 'SKILL.md' as const;
 
 export const skillDocs: Record<string, Record<string, string[]>> = {
   "check-compliance": {
-    "SKILL.md": ["---","name: live-tokens-check-compliance","description: Report an existing project's adherence to @motion-proto/live-tokens from one run of npx live-tokens report. Checks for correct use of components, properties, and tokens. The report names the tokens each component reads, the component each page renders, the findings of both checkers, and the recommended fixes. Called as the verification step by live-tokens-create-page and live-tokens-create-component. Use when the user asks to check, audit, or review the project. Edits no file. Hands the fix list to live-tokens-fix-findings.","---","","# Checking a project's adherence to live-tokens","","Run `npx live-tokens report`. The CLI prints a report with the sections in the Report sections table. Say what each finding means and what the fix would cost. When live-tokens-create-page or live-tokens-create-component calls this skill, lead with the findings on the file it built. Edit no file. When the user wants the fixes applied, hand the fix list to **live-tokens-fix-findings**.","","`report` never runs the component contract suites. The `check-component` test run does, and it is what live-tokens-create-component calls to validate a component's runtime behavior.","","## Workflow","","When `report` is an unknown command, route the dependency upgrade to **live-tokens-fix-findings**. Resume the audit after the upgrade.","","1. Run `npx live-tokens report --json`.","2. Read each section of the report with the Report sections table.","3. When a finding needs component or token scale details, run the matching inspection command below. Otherwise continue with classification.","4. Classify each finding as Mechanical, Judgement, or Deliberate. For Deliberate findings, name the narrower config entry.","5. Reply with the findings of each section in the table's order, each with its count.","6. List the recommended fixes, each marked with its finding class, in the order **live-tokens-fix-findings** takes them.","7. End with the hand-off: run **live-tokens-fix-findings** on the list, or on the subset the user chooses.","","For one component, run `npx live-tokens components <id>`. For one token scale, run `npx live-tokens tokens --scale <name>`. Both take `--json`.","","## Report sections","","| Section | Contents | Fix |","| --- | --- | --- |","| Pending token migrations (`migrations`) | Whether `tokens.css` is behind the installed package. `status` is `pending`, `none pending`, `no tokens.css`, or `unavailable`. A stale file shows downstream as unknown tokens. | Fix this first. Run `npx live-tokens migrate --check` to see the plan, then `npx live-tokens migrate` to apply it. `--write` also rewrites the route references the plan lists. `--tokens <path>` names a tokens.css in an unusual place. |","| Checker findings by rule (`findings.pages`, `findings.components`) | Both checkers' findings by rule under the project's severities, and one strict total with every warning as an error. Errors fail the build today. The strict total is what a fully tokenized project would fail. | Classify each finding under Finding classes. |","| Tokens a component never reads (`components[].unread`) | Tokens a component declares and never reads. Each is an editor row that edits nothing. | Wire each token into the CSS, or remove it. No checker rule covers this, so confirm with a second `report` run. |","| Component registration (`components[].registered`) | Whether the component has a `bootLiveTokens` or `registerComponent` entry. Without one it renders with no editor. | Register it. |","| Component usage comment (`components[].described`) | Whether the runtime file has the header comment the picker reads. Without one, `live-tokens components` cannot say what the component is for. | Add the comment. No checker rule covers this, so confirm with a second `report` run. |","| Components each page renders (`usage.byPage`) | Which component each page imports, and how many times the page renders it. | When a page renders none, say whether it is chrome or markup that a shipped component covers. |","| Shipped components no page renders (`usage.unusedShipped`) | Shipped components no page renders. | None. Information only. |","| Project components unregistered or unused (`usage.customUnregistered`, `usage.customUnused`) | The project's own components that are unregistered or unused. | Register or delete each. `check-component` sees a component only under `src/system/components`, so confirm with a second `report` run. |","","## Finding classes","","Every finding is one of three. Say which.","","- **Mechanical.** The value determines the token, such as a spacing literal and its nearest `--space-*` step. When the fix shifts a rendered value, name the shift.","- **Judgement.** A role determines the token, such as a color literal and the role it plays. Say what the options are. Ask the user to choose.","- **Deliberate.** The finding records a decision, such as a layout size the project owns. Name the config entry that would record the decision. Leave the decision to the user. To lower a rule's severity everywhere, the entry is `\"checks\": { \"rules\": { \"<rule>\": \"warn\" } }` in `live-tokens.config.json`. To drop one file that is not a themed surface, the entry is `\"checks\": { \"exclude\": [\"src/art/hero.css\"] }`. The path is project-relative, and a directory covers what is under it. Prefer the narrower entry."],
+    "SKILL.md": ["---","name: live-tokens-check-compliance","description: Report an existing project's adherence to @motion-proto/live-tokens from one run of npx live-tokens report. Checks for correct use of components, properties, and tokens. The report names the tokens each component reads, the component each page renders, the findings of both checkers, and the recommended fixes. Called as the verification step by live-tokens-create-page and live-tokens-create-component. Use when the user asks to check, audit, or review the project. Edits no file. Hands the fix list to live-tokens-fix-findings.","---","","# Checking a project's adherence to live-tokens","","Run `npx live-tokens report`. The CLI prints a report with the sections in the Report sections table. Say what each finding means and what the fix would cost. When live-tokens-create-page or live-tokens-create-component calls this skill, lead with the findings on the file it built. Edit no file. When the user wants the fixes applied, hand the fix list to **live-tokens-fix-findings**.","","`report` never runs the component contract suites. The `check-component` test run does, and it is what live-tokens-create-component calls to validate a component's runtime behavior.","","`report` stays static for pages too. The `check-page` test run is what live-tokens-create-page calls for a rendered page, in a browser against the project's own route, and it reports `page-component-paint`, `page-text-style`, `page-contrast`, `page-grid`, and `page-overflow` findings the same way `report`'s static findings read: by rule, with a fix.","","## Workflow","","When `report` is an unknown command, route the dependency upgrade to **live-tokens-fix-findings**. Resume the audit after the upgrade.","","1. Run `npx live-tokens report --json`.","2. Read each section of the report with the Report sections table.","3. When a finding needs component or token scale details, run the matching inspection command below. Otherwise continue with classification.","4. Classify each finding as Mechanical, Judgement, or Deliberate. For Deliberate findings, name the narrower config entry.","5. Reply with the findings of each section in the table's order, each with its count.","6. List the recommended fixes, each marked with its finding class, in the order **live-tokens-fix-findings** takes them.","7. End with the hand-off: run **live-tokens-fix-findings** on the list, or on the subset the user chooses.","","For one component, run `npx live-tokens components <id>`. For one token scale, run `npx live-tokens tokens --scale <name>`. Both take `--json`.","","## Report sections","","| Section | Contents | Fix |","| --- | --- | --- |","| Pending token migrations (`migrations`) | Whether `tokens.css` is behind the installed package. `status` is `pending`, `none pending`, `no tokens.css`, or `unavailable`. A stale file shows downstream as unknown tokens. | Fix this first. Run `npx live-tokens migrate --check` to see the plan, then `npx live-tokens migrate` to apply it. `--write` also rewrites the route references the plan lists. `--tokens <path>` names a tokens.css in an unusual place. |","| Checker findings by rule (`findings.pages`, `findings.components`) | Both checkers' findings by rule under the project's severities, and one strict total with every warning as an error. Errors fail the build today. The strict total is what a fully tokenized project would fail. | Classify each finding under Finding classes. |","| Tokens a component never reads (`components[].unread`) | Tokens a component declares and never reads. Each is an editor row that edits nothing. | Wire each token into the CSS, or remove it. No checker rule covers this, so confirm with a second `report` run. |","| Component registration (`components[].registered`) | Whether the component has a `bootLiveTokens` or `registerComponent` entry. Without one it renders with no editor. | Register it. |","| Component usage comment (`components[].described`) | Whether the runtime file has the header comment the picker reads. Without one, `live-tokens components` cannot say what the component is for. | Add the comment. No checker rule covers this, so confirm with a second `report` run. |","| Components each page renders (`usage.byPage`) | Which component each page imports, and how many times the page renders it. | When a page renders none, say whether it is chrome or markup that a shipped component covers. |","| Shipped components no page renders (`usage.unusedShipped`) | Shipped components no page renders. | None. Information only. |","| Project components unregistered or unused (`usage.customUnregistered`, `usage.customUnused`) | The project's own components that are unregistered or unused. | Register or delete each. `check-component` sees a component only under `src/system/components`, so confirm with a second `report` run. |","","## Finding classes","","Every finding is one of three. Say which.","","- **Mechanical.** The value determines the token, such as a spacing literal and its nearest `--space-*` step. When the fix shifts a rendered value, name the shift.","- **Judgement.** A role determines the token, such as a color literal and the role it plays. Say what the options are. Ask the user to choose.","- **Deliberate.** The finding records a decision, such as a layout size the project owns. Name the config entry that would record the decision. Leave the decision to the user. To lower a rule's severity everywhere, the entry is `\"checks\": { \"rules\": { \"<rule>\": \"warn\" } }` in `live-tokens.config.json`. To drop one file that is not a themed surface, the entry is `\"checks\": { \"exclude\": [\"src/art/hero.css\"] }`. The path is project-relative, and a directory covers what is under it. Prefer the narrower entry."],
   },
   "create-component": {
-    "SKILL.md": ["---","name: live-tokens-create-component","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.","---","","# Creating a component for a live-tokens project","","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.","","## Source inspection","","Before writing a file:","","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.","","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.","","## Variants and states","","A component has three kinds of division. Keep them apart in the props, the names, and the editor.","","| 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 |","","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 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`.","","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.","","A component supplies its variants. The page chooses the one primary action.","","## Property design","","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.","","| 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 |","","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`.","","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>","```","","- `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).","-->","```","","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>","```","","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>","```","","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.","","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.","","## 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","// 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,","});","```","","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.","","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`.","","## Sketch mode and overlays","","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.","","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","","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.","","Every finding carries a `fix` slug naming the section that fixes it.","","| `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 |","","`--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.","","Then place the component on a page with **live-tokens-create-page**."],
-    "references/contract-tests.md": ["# The registry contract as a test in a consumer project","","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","// 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',","  label: 'My Widget',","  icon: 'fas fa-magic',","  sourceFile: 'src/system/components/MyWidget.svelte',","  editorComponent: MyWidgetEditor,","  schema: allTokens,","});","```","","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.","","`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","","`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:","","```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';","","export default createVitestConfig(viteConfig, { registrySetup: settings.registrySetup });","```","","```bash","npx vitest run --config vitest.contract.config.ts","```","","## 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","// 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');","","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`.","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)."],
+    "SKILL.md": ["---","name: live-tokens-create-component","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.","---","","# Creating a component for a live-tokens project","","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, and write its contract in the module `contractsModule` names.","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.","","## Source inspection","","Before writing a file:","","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.","","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.","","## Variants and states","","A component has three kinds of division. Keep them apart in the props, the names, and the editor.","","| 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 |","","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 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`.","","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.","","A component supplies its variants. The page chooses the one primary action.","","## Property design","","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.","","| 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 |","","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`.","","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>","```","","- `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).","-->","```","","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>","```","","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>","```","","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.","","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.","","## 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","// 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,","});","```","","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. The component's contract, one `ComponentContract` in the module `contractsModule` names, is what the eight component suites run; without it `--tests` reports `contract-missing`. Read `references/contract-tests.md` for both. 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.","","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`.","","## Sketch mode and overlays","","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.","","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","","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, for a component with a contract in the module `contractsModule` names, the component contract suites; 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.","","Every finding carries a `fix` slug naming the section that fixes it.","","| `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 |","","`--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.","","Then place the component on a page with **live-tokens-create-page**."],
+    "references/contract-tests.md": ["# The registry contract as a test in a consumer project","","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.","","A project scaffolded by `create` has `@playwright/test`, `vitest`, and","`happy-dom` installed, with `live-tokens.testing.ts`, `src/registerComponents.ts`,","and `tests/contracts.ts` in place. Any other project adds the three as","devDependencies. Both run `npx playwright install chromium` once. 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","// 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',","  label: 'My Widget',","  icon: 'fas fa-magic',","  sourceFile: 'src/system/components/MyWidget.svelte',","  editorComponent: MyWidgetEditor,","  schema: allTokens,","});","```","","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.","","`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.","","## The component contract","","The eight Playwright suites drive one `ComponentContract` per component. The","package ships one for each of its own components and none for yours. A run","with `LIVE_TOKENS_COMPONENT=<id>` and no contract for `<id>` reports one","`contract-missing` finding, which names the setting that unlocks the suites.","","Name the module that exports your contracts as `contractsModule`, next to","`registrySetup`:","","```ts","// live-tokens.testing.ts","export default defineTestingConfig({","  registrySetup: 'src/registerComponents.ts',","  contractsModule: 'tests/contracts.ts',","});","```","","The module exports a `ComponentContract[]`, as the default export or a named","`contracts` export. The type ships from `@motion-proto/live-tokens/testing`,","and the doc comment on each field is the reference for it. A contract","declares the component's parts as selectors inside the preview, then one","expectation per obligation:","","```ts","// tests/contracts.ts","import type { ComponentContract } from '@motion-proto/live-tokens/testing';","","export const contracts: ComponentContract[] = [","  {","    id: 'statcard',","    origin: 'custom',","    root: 'root',","    parts: { root: '.statcard', value: '.statcard-value' },","    properties: [","      {","        paints: {","          root: {","            backgroundColor: '--statcard-surface',","            borderTopColor: '--statcard-border',","            borderTopWidth: '--statcard-border-width',","            borderRadius: '--statcard-radius',","            paddingTop: '--statcard-padding',","          },","          value: { color: '--statcard-value-text', fontSize: '--statcard-value-font-size' },","        },","      },","    ],","    states: { applicable: false, reason: 'a stat card renders one state' },","    persistence: {","      cases: [","        { shape: 'token', variable: '--statcard-radius', observe: { part: 'root', css: 'borderRadius' } },","      ],","      resetVariable: '--statcard-radius',","    },","    theme: {","      theme: 'brand',","      changed: ['--statcard-radius'],","      unchanged: ['--statcard-padding'],","      aliasedTo: { '--statcard-radius': '--radius-none' },","      observe: { part: 'root', css: 'borderRadius', variable: '--statcard-radius' },","    },","    interaction: { applicable: false, reason: 'a stat card carries no interactive role' },","    sketch: {","      style: 'pencil',","      parts: [{ part: 'root', fill: '--statcard-surface', stroke: '--statcard-border' }],","    },","  },","];","```","","Each obligation and what it needs from the project:","","- `properties`: part key, then CSS property, then the semantic property that","  drives it. One entry per variant tab and state tab the editor renders;","  omit `variant` and `state` when the editor renders one view. The paint maps","  and `uncovered` together name every property in `default.json`. A property","  no computed style shows verbatim, one consumed inside `calc()` or a gradient","  function, goes in `uncovered` with its reason.","- `states`: one entry per state tab, with the class or attributes the preview","  forces. `applicable: false` when the editor renders no state strip.","- `persistence`: an edit the run makes through the editor, saves, reloads, and","  reads back. `resetVariable` is a property one of the cases moves.","- `theme`: a theme in the project's data tree whose block for the component","  reassigns a property. Save one with the editor before the first run.","  `changed` names the properties the theme moves, `unchanged` the ones it","  leaves, and `aliasedTo` the design token each reassigned property resolves","  to under it.","- `interaction`: the interactive part's role and its cases. `applicable:","  false` for a component with no interactive role.","- `sketch`: a sketch style id and the fill and stroke each reserved-class part","  resolves to under it. `applicable: false` only for a component","  `references/sketch-mode.md` exempts.","","## Running vitest yourself","","`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:","","```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';","","export default createVitestConfig(viteConfig, { registrySetup: settings.registrySetup });","```","","```bash","npx vitest run --config vitest.contract.config.ts","```","","## 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","// 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');","","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`.","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)."],
     "references/fixed-overlays.md": ["# Fixed overlays must portal to body","","Any `position: fixed` layer (modal, lightbox, full-screen backdrop) is trapped, clipped or painted under other chrome, by a transformed / `isolation` / `contain` / `will-change` ancestor. Real consumer pages and the editor's own preview pane both have one, so this is the normal case rather than the edge.","","Render the layer with `use:portal` from `src/system/internal/portal.ts` so it escapes to `<body>`. `use:portal={enabled}` keeps an in-flow preview variant where it is; `Dialog` is the worked example. `check:overlay-portal` fails the build when a component sets `position: fixed` without it. Anchored popovers are exempt: `Tooltip` is `position: absolute` against its trigger and belongs in the flow.","","Moving to `<body>` costs two things:","","- DOM events from the layer no longer bubble to a consumer ancestor, so pass component callbacks the way `Dialog` does.","- A subtree-scoped CSS-variable theme no longer reaches it. This library themes via `:root`, so nothing breaks here.","","A modal also needs `role=\"dialog\"` with `aria-modal`, focus moved in on open and restored on close, and `Tab` trapped inside. `ImageLightbox` is the worked example."],
     "references/intrinsics.md": ["# Extension: intrinsics","","Some components expose **structural or display choices** that are not token values: an alignment (start / center), an element's visibility (show / hide), a layout position. These ride a custom `<select>` or checkbox authored in an editor snippet, outside the generic token grid, so they do not belong in `allTokens`. Toggle and most components have none. SectionDivider is the worked example (alignment, hairline position, eyebrow / description visibility).","","An intrinsic still cascades through a CSS custom property with a default in the runtime `:global(:root)`. The trap: that default now lives in two places, the runtime `:global(:root)` AND the editor's read-back getter. When they disagree the control displays a state the page never renders, and a native `<select>` won't even fire `onchange` to write the \"change\" the user thinks they made. `:global(:root)` is the source of truth.","","Declare intrinsics so the editor and the contract test stay honest:","","1. **Runtime `:global(:root)`** carries the per-variant default like any other variable:","","   ```css","   --mywidget-lg-align: start;","   --mywidget-lg-eyebrow-display: block;","   ```","","2. **Editor `<script module>`** exports `intrinsics: IntrinsicSpec[]`, one entry per structural property, each `default` mirroring `:global(:root)` per variant:","","   ```ts","   import type { IntrinsicSpec } from '@motion-proto/live-tokens/component-editor';","","   export const intrinsics: IntrinsicSpec[] = [","     {","       key: 'align',","       variants: ['lg', 'md', 'sm'],","       variable: (v) => `--mywidget-${v}-align`,","       values: ['start', 'center'],","       default: { lg: 'start', md: 'start', sm: 'start' },","     },","   ];","   ```","","3. **Read-back getters fall back to the spec default**, never a hard-coded constant. This is the rule that keeps the control's displayed default in step with what an unedited instance renders:","","   ```ts","   const byKey = new Map(intrinsics.map((i) => [i.key, i]));","   function readIntrinsic(key: string, v: string): string {","     const spec = byKey.get(key)!;","     const raw = readLiteral(spec.variable(v)) ?? spec.default[v];   // store override, else runtime default","     return spec.normalize ? spec.normalize(raw) : raw;","   }","   function getAlign(v: string) {","     return readIntrinsic('align', v) === 'center' ? 'center' : 'start';","   }","   ```","","   Writes go through `setComponentAlias(component, spec.variable(v), { kind: 'literal', value })` so the choice cascades to `:root` like any token.","","4. **Put `intrinsics` on the registry entry** so the contract test can see it. That is the same entry the recipe passes to `bootLiveTokens`, with one more field:","","   ```ts","   bootLiveTokens(App, '#app', {","     components: [{","       id: 'mywidget',","       // ...label, icon, sourceFile, editorComponent, schema...","       intrinsics: myWidgetIntrinsics,","     }],","   });","   ```","","Use `normalize` only when two raw values render identically and the dropdown lists one (SectionDivider folds `above-description` into `below-label`). Properties that resemble intrinsics but are not: preview-only props with no persistence (a size selector that only changes the demo), `setComponentConfig` editor metadata (Dialog's button variants), and token-valued selects (a control choosing between two tokens). None carry a duplicated runtime default, so none need an `IntrinsicSpec`."],
     "references/linked-siblings.md": ["# Extension: linked siblings","","Read this when the component has more than one variant and those variants share base properties (surface, radius, padding) that should move together. Toggle and SectionDivider have no linked tokens and skip all of it.","","Toggle's tokens are flat per state. Most multi-variant components (Badge, Card, SegmentedControl) share base properties across variants and surface that equality via a *linked block*: one edit propagates to every variant, while per-variant properties stay independent. Five additions to the Toggle pattern; see `BadgeEditor.svelte` in `node_modules` for the full file.","","1. **Mark linkable tokens** with `canBeLinked: true` + a `groupKey`. Peers sharing a `groupKey` form a link set across variants.","","   ```ts","   function variantBaseTokens(v: Variant): Token[] {","     return [","       { label: 'padding',       canBeLinked: true, groupKey: 'padding', variable: `--badge-${v}-padding` },","       { label: 'corner radius', canBeLinked: true, groupKey: 'radius',  variable: `--badge-${v}-radius` },","     ];","   }","   // Colors omit canBeLinked. Per-variant by design.","   function variantColorTokens(v: Variant): Token[] {","     return [","       { label: 'surface color', groupKey: 'surface', variable: `--badge-${v}-surface` },","       { label: 'text color',    groupKey: 'text',    variable: `--badge-${v}-text` },","     ];","   }","   ```","","2. **Build a `linkableContexts: Map<variable, contextLabel>`** in `<script module>`. The label (e.g. `\"success base\"`) is how the LinkageChart row identifies this variable. Plain literal Map, no helper needed.","","   ```ts","   const linkableContexts = new Map<string, string>(","     variants.flatMap((v) =>","       variantBaseTokens(v)","         .filter((t) => t.canBeLinked)","         .map((t) => [t.variable, `${v} base`] as [string, string]),","     ),","   );","   ```","","3. **Compute `linked` and mask currently-linked rows** out of per-state lists, so they render once inside the LinkedBlock instead of twice.","","   ```ts","   import { editorState } from '@motion-proto/live-tokens';","   import { computeLinkedBlock, withLinkedDisabled, buildSiblings }","     from '@motion-proto/live-tokens/component-editor';","","   let linked = $derived(computeLinkedBlock(component, linkableContexts, allTokens, $editorState));","   let visibleVariantStates = $derived((v: Variant) => Object.fromEntries(","     Object.entries(variantStates(v)).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),","   ));","   ```","","4. **Pass `{linked}` to `ComponentEditorBase`** so the LinkedBlock renders above the variant groups.","","5. **Multi-variant editors iterate VariantGroups** with `buildSiblings` so cross-variant link rows resolve to their peers.","","   ```svelte","   <ComponentEditorBase {component} title=\"Badge\" tokens={allTokens} {linked} variants={variantOptions}>","     {#each variants as v}","       <VariantGroup","         name={v}","         title={v}","         states={visibleVariantStates(v)}","         {component}","         siblings={buildSiblings(variants, v, variantStates)}","       >","         ...preview snippet","       </VariantGroup>","     {/each}","   </ComponentEditorBase>","   ```","","Single-variant components with multi-state linked tokens still set `canBeLinked` + `linkableContexts`, but skip `buildSiblings` and the `{#each}` loop. Components with no linked tokens (Toggle, SectionDivider) skip all five steps; `ComponentEditorBase` renders without a `{linked}` prop."],
@@ -17,7 +17,7 @@ export const skillDocs: Record<string, Record<string, string[]>> = {
     "references/token-naming.md": ["# Suffix vocabulary","","The editor picker is chosen by suffix. There is no per-token override; if a","token renders with the wrong picker, rename it to one of these.","","`KIND_RULES` in `src/editor/core/components/aliasKinds.ts` is authoritative, and","`check-component` fails on a suffix outside it. `check:skills` holds this file","to that list, so the two cannot drift apart.","","## Color and surface","","| Suffix      | Meaning                                                       |","|-------------|---------------------------------------------------------------|","| `-surface`  | Fill / background color                                        |","| `-border`   | Border color                                                  |","| `-text`     | Text color                                                    |","| `-icon`     | Icon color                                                    |","| `-label`    | Label text color                                              |","| `-fill`     | Inner fill (distinct from outer surface)                      |","| `-divider`  | Divider / separator color                                     |","| `-color`    | Generic color, when none of the above name the role           |","| `-shadow`   | Box-shadow                                                    |","| `-opacity`  | Opacity (0–1)                                                 |","| `-blur`     | Backdrop or filter blur radius                                |","| `-tint`     | A wash over the surface, aliasing a `--tint-*` stop            |","| `-background` | Fill, where the component's own vocabulary says background   |","| `-accent`   | An accent bar or indicator's colour                            |","| `-indicator` | A selection indicator's colour                                |","| `-thumb`    | A scrollbar or slider thumb's colour                           |","| `-title`    | Title text colour                                              |","| `-body`     | Body text colour                                               |","| `-eyebrow`  | Eyebrow text colour                                            |","| `-description` | Description text colour                                     |","| `-hint`     | Hint text colour                                               |","| `-error`    | Error text colour                                              |","| `-placeholder` | Placeholder text colour                                     |","| `-value`    | A displayed value's colour                                     |","","## Geometry","","| Suffix          | Meaning                                                       |","|-----------------|---------------------------------------------------------------|","| `-radius`       | Corner radius                                                 |","| `-border-width` | Stroke thickness (used even when CSS uses `outline:`)         |","| `-thickness`    | Alternative to `-width` when fallback siblings would collide  |","| `-accent-width` | An accent bar's thickness                                     |","| `-indicator-width` | An indicator's thickness, moved with `-accent-width`      |","| `-hairline-thickness` | A hairline rule's thickness                             |","| `-dot-size`     | A dot indicator's diameter                                    |","| `-divider-width` | A divider's thickness                                        |","| `-divider-thickness` | Alternative to `-divider-width`                          |","| `-divider-height` | A divider's length                                          |","| `-divider-inset` | Inset trimmed from a stretched divider                       |","| `-track-height` | A track's height (progress bar, slider)                       |","| `-icon-size`    | An icon's rendered size                                       |","| `-thumb-size`   | A thumb's rendered size                                       |","| `-height`       | A measured height (a track, a panel)                          |","| `-margin`       | Outer spacing, moved on the same scale as `-padding`          |","| `-inset`        | Inset trimmed from a stretched element                        |","| `-duration`     | Motion duration                                               |","| `-easing`       | Motion easing curve                                           |","| `-scale`        | A transform scale factor                                      |","| `-width`        | Width dimension                                               |","| `-size`         | Square / uniform dimension                                    |","| `-padding`      | Internal spacing                                              |","| `-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                  |","|--------------------|--------------------------|","| `-font-family`     | Font family reference    |","| `-font-weight`     | Font weight reference    |","| `-font-size`       | Font size reference      |","| `-line-height`     | Line height              |","| `-letter-spacing`  | Letter spacing           |","","A suffix that is not here is either a rename away from one that is, or","an issue against `@motion-proto/live-tokens`. Inventing one costs the token its","picker: the editor falls back to a plain text input."],
   },
   "create-page": {
-    "SKILL.md": ["---","name: live-tokens-create-page","description: Create a page in a @motion-proto/live-tokens project from the shipped components at their defaults and the theme's text styles. Use when the user asks for a page or a route. Use when the user asks to change the layout of a page. Edits page files and the route table. For a choice between two components, read live-tokens-pick-component. For a component the catalogue lacks, read live-tokens-create-component. For a theme change, read live-tokens-create-theme.","---","","# Creating a page in a live-tokens project","","Assemble the page from the shipped components at their defaults and the theme's text styles. A change to a component is made in the components editor at `/live-tokens/components` and reaches every page. A change to the theme is made with **live-tokens-create-theme**.","","## Workflow","","1. Read the project first: the existing pages and where they live, how `App.svelte` wires routes, `--columns-count` in `tokens.css`, and the catalogue from `npx live-tokens components`.","2. Read the page top to bottom and name each section by its purpose. Take each section's column spans from the Page layouts table.","3. Build the page grid and place each section on it. Separate the sections with the smallest difference that separates them.","4. Give each section its container from the Containers by purpose list.","5. Match a shipped component to each need. When two could fit, read **live-tokens-pick-component**. When nothing in the catalogue fits, read **live-tokens-create-component**.","6. Write the page CSS in design tokens.","7. Set the hierarchy: one text style per element, the shipped size on every control, one primary action, and one space step per position.","8. Add the route, with a lazy import and the source path.","9. Run **live-tokens-check-compliance**, then check the rendered page.","10. Reply with the sections and the layout each took, the components placed, the route, and the compliance result.","","## Layout","","### Page layouts","","Decide the sections before the columns. Read the page top to bottom and name each section by its purpose: what the user reads, types into, or presses. Each section is a row of the page grid. Take the column spans from the layout that matches the reader's task.","","| Layout | Use when | Column spans |","|---|---|---|","| Stacked sections | The reader moves top to bottom: an opening, one section per topic, a close; or a stage, its inputs, and a toolbar. | Each section spans all columns. Copy spans half (6 of 12). |","| Main with a supporting pane | One region is the work and the other adjusts or describes it. | Main two thirds (8), pane one third (4). |","| List with detail | The reader picks an item from a list and inspects it. | List one third (4), detail two thirds (8). |","| Grid of equals | The reader compares or scans items of one kind. | Equal spans. Up to seven per section. |","| Single column | The reader fills a form or reads at length. | Half the columns (6), centered. |","","The stage is the canvas, player, or strip the work is about. Stretch a section's containers to one height (`align-items: stretch`) so their bottom edges align. Below the scaffold's 768px breakpoint, a section's columns stack in reading order.","","### Grid","","The page is the column grid: `display: grid`, `grid-template-columns: repeat(var(--columns-count), 1fr)`, `column-gap: var(--columns-gutter)`, `max-width: var(--columns-max-width)`, `margin: 0 auto`. Each section spans it with `grid-column: 1 / -1`.","","To place a section's children at page-column positions:","","1. Read `--columns-count` in the project's `tokens.css`.","2. Span the parent grid with `grid-column: 1 / -1`.","3. Redeclare `repeat(var(--columns-count), 1fr)` with `column-gap: var(--columns-gutter)`.","4. Place each child by page-column numbers.","","A grid that follows the page columns takes `var(--columns-count)` or a `calc()` of it as its count, so it stays in step with `ColumnsOverlay`. A local grid of two or three equal columns writes its own count. A column number in `grid-column` is fixed to the count read in step 1.","","### Separation","","The page shows one thing, and every other element stays out of its way. Each element that is not content costs attention: a hairline, a border, a header bar, a shadow. Keep an element only when it serves a purpose no other element serves.","","Separate elements with the smallest difference that separates them: space first, then a hairline, then a second surface. Use one separator at a time. Two heavy borders side by side make a third shape between them, and a section of containers with borders and header bars reads as a set of posters.","","Color each element by its layer.","","| Layer | Color |","|---|---|","| Content | `--text-primary`, or the color `site.css` gives the element |","| Label | `--text-secondary` |","| Chrome | `--border-neutral` |","| Overlay on content, such as a grid or a selection | `--border-brand`, which stays visible on any pixel |","","Show related items side by side when the width permits. A line of copy runs 45 to 90 characters; the copy span in Page layouts holds that at body size. On a tool page the stage is the content and each control is chrome, so the stage takes the space.","","`references/layout-sources.md` names the sources for these laws.","","## Containers by purpose","","- `Panel` is a stage: a canvas, a player, a preview. `minHeight` holds its height while what it shows changes.","- An empty stage shows a heading that names the condition and one `secondary` Button that fills it. An error goes in a `Callout variant=\"danger\"`.","- `Card` is a titled block of content. Its `title` prop is the title, and the card's own tokens type it.","- A container in a tool UI labels itself: `Card variant=\"bare\"` with the label in the body as `--body-sm-*` in `--text-secondary`.","- A form puts the essential fields first and the secondary fields in a `CollapsibleSection`. Its actions sit on the bottom edge.","- A row of fields is a flex row with `gap: var(--space-20)`. Each field's wrapper takes `flex: 1`.","- A toolbar is a flex row of Buttons on the section's bottom edge, with no container around it. Group the Buttons left and right with `justify-content: space-between`, the primary last. A `danger` Button sits apart from the group it could be mistaken for.","- A vertical stack of Buttons sets `fullWidth` on each Button. A row omits it.","- `MenuSelect` renders its list open. For a picker, toggle it from a Button with a trailing chevron (`icon=\"fa-solid fa-chevron-down\" iconPosition=\"right\"`) and position the list under the Button at `top: 100%` with a `--space-*` margin.","","## Components","","- Use a shipped component when one fits. Import it from `@motion-proto/live-tokens/components/<Name>.svelte`.","- `npx live-tokens components <id>` prints the declared props, the values each union accepts, and the usage comment. `--json` prints the same as data. The list includes the project's own components.","- Pass only the props a component declares.","- A shipped component fills its parent. To size one, size the element the page wraps it in.","- A native element with no chrome of its own needs no component: an `<input type=\"file\">` behind a Button, a `<canvas>`, an `<img>` inside a stage.","- Text inside a `Card` or a `CollapsibleSection` takes the container's type on nested `p`, `ul`, `ol`, and `li`. When the page owns that type, as full-bleed media does, pass `prose={false}`.","","## Tokens","","- When a design token exists for a value, page CSS takes the token as `var(--token)`. That holds in the `<style>` block, an inline `style=` attribute, and a `style:` directive.","- A width is a span of page columns. The Layout section gives the grid.","- A height follows the content. A stage's `minHeight` is the one fixed height, set from what the stage must show.","- A value that comes from data, such as a sheet's padding in pixels or a chart's scale, is set through a `{}` expression.","","## Hierarchy","","### Type","","One text style per element. A text style has five axes: `-font-family`, `-font-size`, `-font-weight`, `-line-height`, and `-letter-spacing`. Set all five from the one style.","","| Element | Style |","|---|---|","| Page title | `h1` in `--heading-xl-*` |","| Section title | `h2` in `--heading-lg-*`, or `SectionDivider variant=\"sm\"` |","| Card title | the Card `title` prop |","| Label above a group | `--body-sm-*` in `--text-secondary` |","| Body | `p` in `--body-md-*` |","| Secondary line | `--body-sm-*` in `--text-secondary` |","| Count, status, read-out | `--body-sm-*` in `--text-primary` |","| Command or value | `code` in `--code-*` |","","Use the semantic element for each place: one `h1`, an `h2` for each section, `h3` inside a section, `p` for copy. Heading levels run in order with no skipped level. `site.css` types bare `h1` to `h4`, `p`, `code`, `pre`, and list items from these styles, so the tag carries the style. Type an element only when the table gives its tag a different style. A weight alone, on `strong` or a list marker, is the one axis a page sets by itself. A page shows at most two weights.","","### Size","","Omit `size` on every control and container. The shipped default is the page's size.","","### Emphasis","","One `primary` Button per page: the action that completes the page's main task. An action that supports that task is `secondary`. An action unrelated to the task, or informational, is `outline`. An action that destroys saved work is `danger`.","","In a row of actions the primary sits last, on the right. Up to four actions are individual Buttons. Five or more collapse into a `MenuSelect` behind one Button.","","### Spacing","","Each position takes one step of the `--space-*` scale. Space inside a group is smaller than space between groups. A shipped component carries its own inner spacing; the table names the space the page draws.","","| Position | Step |","|---|---|","| Between controls in a row | `--space-8` |","| Inside a wrapper the page draws | `--space-16` |","| Between fields in a form | `--space-20` |","| Between containers in a section | `--columns-gutter` across, `--space-24` down |","| Between sections | `--space-16` above a hairline |","| Page title to first section | `--space-24`, no hairline |","| Page margin | `--space-32` |","","Every section after the first opens with a hairline: `padding-top: var(--space-16)` and `border-top: var(--border-width-1) solid var(--border-neutral)`. The hairline separates, so the gap between sections is smaller than the gap between the containers inside them. A section's edge is the hairline alone.","","## Routing","","Add the route the way `App.svelte` already wires routes.","","- `<LiveTokensRouter pages={...}>`: add a `pages` entry with `lazy: () => import('./YourPage.svelte')` and `source: 'src/...'`. Add `label` and `icon` to show the page in the nav rail; omit `label` to keep the route reachable by URL alone. For a `/:id`, a path prefix, or a gated page, add `resolve(path) => RouteEntry | null` beside `pages`. The entry fields are the same.","- Manual `<LiveEditorOverlay>`: dispatch with `$derived.by(() => import(...))` and register the route's source in `pageSources={...}`.","","Import the page with `lazy`, so page CSS stays off the editor routes. Import `site.css` from each page's `<script>` block for the same reason. `source` is what makes Page Source work. A page route sits outside `/live-tokens/*`, the namespace of the package's own routes, where `Editor` and `ComponentEditorPage` mount.","","```svelte","const pages = {","  '/pricing': {","    lazy: () => import('./pages/Pricing.svelte'),","    source: 'src/pages/Pricing.svelte',","    label: 'Pricing',","    icon: 'fa-tag',","  },","};","```","","## Verify","","Run **live-tokens-check-compliance**. Its report carries both checkers' findings by rule, and **live-tokens-fix-findings** takes the fix list. Repeat until the page is clean.","","The checkers cannot see a layout. Open the page at the width it is built for and check each line below.","","- The first section holds what the user came for.","- One `h1`. Heading levels run in order with no skipped level.","- No label is larger than the page's body copy.","- A line of copy runs 45 to 90 characters.","- The containers in a section align at the bottom.","- Every control stays inside its wrapper. A `width: 100%` field takes `box-sizing: border-box`.","- The actions sit where the eye goes last, with the one primary at the end.","- Every row of actions holds an action that leaves without committing.","- An action that destroys saved work confirms in a `Dialog`.","- An action that runs longer than a moment shows progress in a `ProgressBar` or a `Notification`.","- Every field has a default, and Reset restores it.","- Secondary settings sit in a `CollapsibleSection`. Every control is in view.","- Labels use the user's words, such as \"Export slices\".","- Every `img` has `alt` text. Focus order follows the reading order.","","`references/interaction-sources.md` names the sources for these checks.","","Then read the page from a distance: the sections and their edges are the only shapes that show. Then read it closely. For each border, header bar, and container, ask whether the page loses information when the element is removed. When the answer is no, remove the element. Find the element a reader sees first, second, and third, and confirm that is the reading order the page needs."],
+    "SKILL.md": ["---","name: live-tokens-create-page","description: Create a page in a @motion-proto/live-tokens project from the shipped components at their defaults and the theme's text styles. Use when the user asks for a page or a route. Use when the user asks to change the layout of a page. Edits page files and the route table. For a choice between two components, read live-tokens-pick-component. For a component the catalogue lacks, read live-tokens-create-component. For a theme change, read live-tokens-create-theme.","---","","# Creating a page in a live-tokens project","","Assemble the page from the shipped components at their defaults and the theme's text styles. A change to a component is made in the components editor at `/live-tokens/components` and reaches every page. A change to the theme is made with **live-tokens-create-theme**.","","## Workflow","","1. Read the project first: the existing pages and where they live, how `App.svelte` wires routes, `--columns-count` in `tokens.css`, and the catalogue from `npx live-tokens components`.","2. Read the page top to bottom and name each section by its purpose. Take each section's column spans from the Page layouts table.","3. Build the page grid and place each section on it. Separate the sections with the smallest difference that separates them.","4. Give each section its container from the Containers by purpose list.","5. Match a shipped component to each need. When two could fit, read **live-tokens-pick-component**. When nothing in the catalogue fits, read **live-tokens-create-component**.","6. Write the page CSS in design tokens.","7. Set the hierarchy: one text style per element, the shipped size on every control, one primary action, and one space step per position.","8. Add the route, with a lazy import and the source path.","9. Run **live-tokens-check-compliance** and `npx live-tokens check-page <file> --tests --strict`, then check the rendered page.","10. Reply with the sections and the layout each took, the components placed, the route, and the compliance result.","","## Layout","","### Page layouts","","Decide the sections before the columns. Read the page top to bottom and name each section by its purpose: what the user reads, types into, or presses. Each section is a row of the page grid. Take the column spans from the layout that matches the reader's task.","","| Layout | Use when | Column spans |","|---|---|---|","| Stacked sections | The reader moves top to bottom: an opening, one section per topic, a close; or a stage, its inputs, and a toolbar. | Each section spans all columns. Copy spans half (6 of 12). |","| Main with a supporting pane | One region is the work and the other adjusts or describes it. | Main two thirds (8), pane one third (4). |","| List with detail | The reader picks an item from a list and inspects it. | List one third (4), detail two thirds (8). |","| Grid of equals | The reader compares or scans items of one kind. | Equal spans. Up to seven per section. |","| Single column | The reader fills a form or reads at length. | Half the columns (6), centered. |","","The stage is the canvas, player, or strip the work is about. Stretch a section's containers to one height (`align-items: stretch`) so their bottom edges align.","","### Grid","","The page is the column grid: `display: grid`, `grid-template-columns: repeat(var(--columns-count), 1fr)`, `column-gap: var(--columns-gutter)`, `max-width: var(--columns-max-width)`, `margin: 0 auto`. Each section spans it with `grid-column: 1 / -1`.","","To place a section's children at page-column positions:","","1. Read `--columns-count` in the project's `tokens.css`.","2. Span the parent grid with `grid-column: 1 / -1`.","3. Redeclare `repeat(var(--columns-count), 1fr)` with `column-gap: var(--columns-gutter)`.","4. Place each child by page-column numbers.","","A grid that follows the page columns takes `var(--columns-count)` or a `calc()` of it as its count, so it stays in step with `ColumnsOverlay`. A local grid of two or three equal columns writes its own count. A column number in `grid-column` is fixed to the count read in step 1.","","No scaffold collapses the page grid on a phone: the theme's own column gutter alone exceeds a phone's width at the full column count, so every page writes its own `@media (max-width: 767px)` rule setting `grid-template-columns: 1fr` and `column-gap: 0`, with each section's children spanning `grid-column: 1 / -1`. A section's columns then stack in reading order.","","### Separation","","The page shows one thing, and every other element stays out of its way. Each element that is not content costs attention: a hairline, a border, a header bar, a shadow. Keep an element only when it serves a purpose no other element serves.","","Separate elements with the smallest difference that separates them: space first, then a hairline, then a second surface. Use one separator at a time. Two heavy borders side by side make a third shape between them, and a section of containers with borders and header bars reads as a set of posters.","","Color each element by its layer.","","| Layer | Color |","|---|---|","| Content | `--text-primary`, or the color `site.css` gives the element |","| Label | `--text-secondary` |","| Chrome | `--border-neutral` |","| Overlay on content, such as a grid or a selection | `--border-brand`, which stays visible on any pixel |","","Show related items side by side when the width permits. A line of copy runs 45 to 90 characters; the copy span in Page layouts holds that at body size. On a tool page the stage is the content and each control is chrome, so the stage takes the space.","","`references/layout-sources.md` names the sources for these laws.","","## Containers by purpose","","- `Panel` is a stage: a canvas, a player, a preview. `minHeight` holds its height while what it shows changes.","- An empty stage shows a heading that names the condition and one `secondary` Button that fills it. An error goes in a `Callout variant=\"danger\"`.","- `Card` is a titled block of content. Its `title` prop is the title, and the card's own tokens type it.","- A container in a tool UI labels itself: `Card variant=\"bare\"` with the label in the body as `--body-sm-*` in `--text-secondary`.","- A form puts the essential fields first and the secondary fields in a `CollapsibleSection`. Its actions sit on the bottom edge.","- A row of fields is a flex row with `gap: var(--space-20)`. Each field's wrapper takes `flex: 1`.","- A toolbar is a flex row of Buttons on the section's bottom edge, with no container around it. Group the Buttons left and right with `justify-content: space-between`, the primary last. A `danger` Button sits apart from the group it could be mistaken for.","- A vertical stack of Buttons sets `fullWidth` on each Button. A row omits it.","- `MenuSelect` renders its list open. For a picker, toggle it from a Button with a trailing chevron (`icon=\"fa-solid fa-chevron-down\" iconPosition=\"right\"`) and position the list under the Button at `top: 100%` with a `--space-*` margin.","","## Components","","- Use a shipped component when one fits. Import it from `@motion-proto/live-tokens/components/<Name>.svelte`.","- `npx live-tokens components <id>` prints the declared props, the values each union accepts, and the usage comment. `--json` prints the same as data. The list includes the project's own components.","- Pass only the props a component declares.","- A shipped component fills its parent. To size one, size the element the page wraps it in.","- A native element with no chrome of its own needs no component: an `<input type=\"file\">` behind a Button, a `<canvas>`, an `<img>` inside a stage.","- Text inside a `Card` or a `CollapsibleSection` takes the container's type on nested `p`, `ul`, `ol`, and `li`. When the page owns that type, as full-bleed media does, pass `prose={false}`.","","## Tokens","","- When a design token exists for a value, page CSS takes the token as `var(--token)`. That holds in the `<style>` block, an inline `style=` attribute, and a `style:` directive.","- A width is a span of page columns. The Layout section gives the grid.","- A height follows the content. A stage's `minHeight` is the one fixed height, set from what the stage must show.","- A value that comes from data, such as a sheet's padding in pixels or a chart's scale, is set through a `{}` expression.","","## Hierarchy","","### Type","","One text style per element. A text style has five axes: `-font-family`, `-font-size`, `-font-weight`, `-line-height`, and `-letter-spacing`. Set all five from the one style.","","| Element | Style |","|---|---|","| Page title | `h1` in `--heading-xl-*` |","| Section title | `h2` in `--heading-lg-*`, or `SectionDivider variant=\"sm\"` |","| Card title | the Card `title` prop |","| Label above a group | `--body-sm-*` in `--text-secondary` |","| Body | `p` in `--body-md-*` |","| Secondary line | `--body-sm-*` in `--text-secondary` |","| Count, status, read-out | `--body-sm-*` in `--text-primary` |","| Command or value | `code` in `--code-*` |","","Use the semantic element for each place: one `h1`, an `h2` for each section, `h3` inside a section, `p` for copy. Heading levels run in order with no skipped level. `site.css` types bare `h1` to `h4`, `p`, `code`, `pre`, and list items from these styles, so the tag carries the style. Type an element only when the table gives its tag a different style. A weight alone, on `strong` or a list marker, is the one axis a page sets by itself. A page shows at most two weights.","","### Size","","Omit `size` on every control and container. The shipped default is the page's size.","","### Emphasis","","One `primary` Button per page: the action that completes the page's main task. An action that supports that task is `secondary`. An action unrelated to the task, or informational, is `outline`. An action that destroys saved work is `danger`.","","In a row of actions the primary sits last, on the right. Up to four actions are individual Buttons. Five or more collapse into a `MenuSelect` behind one Button.","","### Spacing","","Each position takes one step of the `--space-*` scale. Space inside a group is smaller than space between groups. A shipped component carries its own inner spacing; the table names the space the page draws.","","| Position | Step |","|---|---|","| Between controls in a row | `--space-8` |","| Inside a wrapper the page draws | `--space-16` |","| Between fields in a form | `--space-20` |","| Between containers in a section | `--columns-gutter` across, `--space-24` down |","| Between sections | `--space-16` above a hairline |","| Page title to first section | `--space-24`, no hairline |","| Page margin | `--space-32` |","","Every section after the first opens with a hairline: `padding-top: var(--space-16)` and `border-top: var(--border-width-1) solid var(--border-neutral)`. The hairline separates, so the gap between sections is smaller than the gap between the containers inside them. A section's edge is the hairline alone.","","## Routing","","Add the route the way `App.svelte` already wires routes.","","- `<LiveTokensRouter pages={...}>`: add a `pages` entry with `lazy: () => import('./YourPage.svelte')` and `source: 'src/...'`. Add `label` and `icon` to show the page in the nav rail; omit `label` to keep the route reachable by URL alone. For a `/:id`, a path prefix, or a gated page, add `resolve(path) => RouteEntry | null` beside `pages`. The entry fields are the same.","- Manual `<LiveEditorOverlay>`: dispatch with `$derived.by(() => import(...))` and register the route's source in `pageSources={...}`.","","Import the page with `lazy`, so page CSS stays off the editor routes. Import `site.css` from each page's `<script>` block for the same reason. `source` is what makes Page Source work. A page route sits outside `/live-tokens/*`, the namespace of the package's own routes, where `Editor` and `ComponentEditorPage` mount.","","```svelte","const pages = {","  '/pricing': {","    lazy: () => import('./pages/Pricing.svelte'),","    source: 'src/pages/Pricing.svelte',","    label: 'Pricing',","    icon: 'fa-tag',","  },","};","```","","## Verify","","Run **live-tokens-check-compliance**, then `npx live-tokens check-page <file> --tests --strict`. The Playwright suite runs against the page's own route and proves what only a rendered page can: the cascade leaves every component painting from its semantic properties, every run of text sits in one shipped text style, every text and surface pair meets AA, sections sit on the page grid, and nothing overflows. Each finding carries a rule id and a line; `--off=<rule>` silences a rule for one run. The two reports carry every finding by rule, and **live-tokens-fix-findings** takes the fix list. Repeat until the page is clean.","","The checkers cannot see a layout. Open the page at the width it is built for and check each line below.","","- The first section holds what the user came for.","- One `h1`. Heading levels run in order with no skipped level.","- No label is larger than the page's body copy.","- A line of copy runs 45 to 90 characters.","- The containers in a section align at the bottom.","- The actions sit where the eye goes last, with the one primary at the end.","- Every row of actions holds an action that leaves without committing.","- An action that destroys saved work confirms in a `Dialog`.","- An action that runs longer than a moment shows progress in a `ProgressBar` or a `Notification`.","- Every field has a default, and Reset restores it.","- Secondary settings sit in a `CollapsibleSection`. Every control is in view.","- Labels use the user's words, such as \"Export slices\".","- Every `img` has `alt` text. Focus order follows the reading order.","","`references/interaction-sources.md` names the sources for these checks.","","Then read the page from a distance: the sections and their edges are the only shapes that show. Then read it closely. For each border, header bar, and container, ask whether the page loses information when the element is removed. When the answer is no, remove the element. Find the element a reader sees first, second, and third, and confirm that is the reading order the page needs."],
     "references/interaction-sources.md": ["# Interaction sources","","Read this when a Verify check or an emphasis rule in SKILL.md needs its reason.","Each principle below is held by one of three parties. A shipped component","holds it when the component's own design answers it, so the page's rule is","the component and pick-component names the test. The page holds it when only","the page can get it right, so SKILL.md states a read or the checker a rule.","The product holds it when no page decision touches it, and the row says so","to keep a later edit from reopening it.","","## Jakob Nielsen, ten usability heuristics","","| Heuristic | Holder | Rule in SKILL.md, or the component |","|---|---|---|","| Visibility of system status | Page | Verify: an action that runs longer than a moment shows progress in a `ProgressBar` or a `Notification`. |","| Match between system and the real world | Page | Verify: labels use the user's words. |","| User control and freedom | Page | Verify: every row of actions holds an action that leaves without committing. Emphasis: an unrelated or informational action is `outline`. |","| Consistency and standards | Page | One size, one primary action, one text style per element. The components carry the rest. |","| Error prevention | Page | Verify: an action that destroys saved work confirms in a `Dialog`; the checker's `danger-without-dialog`. Verify: every field has a default and Reset restores it. |","| Recognition rather than recall | Component | `MenuSelect` lists the options; `Input` carries its label and hint; `Tooltip` defines in place. |","| Flexibility and efficiency of use | Product | Shortcuts and customisation are product decisions. |","| Aesthetic and minimalist design | Page | Layout: each element serves a purpose no other element serves. Verify: secondary settings sit in a `CollapsibleSection`. |","| Help users recognise, diagnose, and recover from errors | Component | `Input` carries the error line; `Callout variant=\"danger\"` carries a section's. |","| Help and documentation | Product | Contextual help is a product decision. |","","The complex-application version of the ten (Kaley, Nielsen Norman Group)","describes a tool with a stage and controls, which is the tool page SKILL.md","lays out. Its additions that the page holds: a wait past ten seconds shows","steps done and steps left, and the stage is the live preview of every","control. Undo, version history, and autosave are the product's.","","## Bruce Tognazzini, first principles of interaction design","","| Principle | Holder | Rule in SKILL.md, or the component |","|---|---|---|","| Anticipation | Page | Layout: show related items side by side. |","| Colour | Component | `Callout`, `Badge`, and `Notification` carry an icon or text beside the colour. |","| Consistency | Page | One size, one primary action. |","| Defaults | Page | Verify: every field has a default and Reset restores it. |","| Discoverability | Page | Verify: every control is in view. |","| Explorable interfaces | Page | Verify: every row of actions holds an action that leaves without committing. |","| Fitts's law | Component | The shipped default is the large target; SKILL.md's one-size rule keeps it. A toolbar sits on the section's bottom edge. |","| Protect users' work | Page | Verify: an action that destroys saved work confirms in a `Dialog`. |","| Readability | Component | live-tokens-set-colors gates every text pair at WCAG AA. |","| Simplicity | Page | Verify: secondary settings sit in a `CollapsibleSection`; no capability is removed for the sake of simplicity. |","| Visible navigation | Component | `SideNavigation` follows the current path. |","| Aesthetics, Autonomy, Efficiency of the user, Human-interface objects, Latency reduction, Learnability, Metaphors, State | Product | Measured, engineered, or researched outside a page. |","","Sources:","","- Nielsen, 10 Usability Heuristics for User Interface Design (1994, updated 2024). https://www.nngroup.com/articles/ten-usability-heuristics/","- Kaley, 10 Usability Heuristics Applied to Complex Applications. https://www.nngroup.com/articles/usability-heuristics-complex-applications/","- Tognazzini, First Principles of Interaction Design (revised 2014). https://asktog.com/atc/principles-of-interaction-design/","","## W3C Web Accessibility Initiative","","| Guidance | Holder | Rule in SKILL.md, or the component |","|---|---|---|","| Headings: one `h1`, levels in order, no skipped level | Page | Type: use the semantic element for each place. Verify: one `h1`, levels in order. |","| Images: text alternatives | Page | Verify: every `img` has `alt` text. |","| Focus order follows the reading order | Page | Verify: focus order follows the reading order. |","| Form labels and error messages | Component | `Input` carries its label, hint, and error line. |","","https://www.w3.org/WAI/tutorials/page-structure/headings/","https://www.w3.org/WAI/tutorials/images/","https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html"],
     "references/layout-sources.md": ["# Layout sources","","Read this when a layout decision in SKILL.md needs its reason. Each law in the","Layout section comes from one of these sources. The sources are for layout and","hierarchy only. Do not take color or type opinions from them: the theme owns","those.","","## Edward Tufte","","Tufte wrote about information graphics. His laws apply to a page because a page","is an information display with controls on it.","","| Law | Statement | Rule in SKILL.md |","|---|---|---|","| Smallest effective difference | Make all visual distinctions as subtle as possible, but still clear and effective. | Separate with space first, then a hairline rule, then a second surface. |","| 1+1=3 | Two heavy marks side by side make a third mark: the space between them. | A section of containers with borders and header bars reads as a set of posters. |","| Layering and separation | Put data on top, labels next, and scaffolding faintest. | Content, labels, and chrome each take their own token. |","| Administrative debris | The metaphor for the interface is the information. Remove the chrome that the tool adds for itself. | The stage takes the space. Controls take their shipped default. |","| Spatial over temporal | Show information adjacent in space. A control that hides it stacks it in time. | Show related items side by side. Frames in a strip are small multiples. |","| Erase non-data ink | Remove each mark that carries no information. | The Verify question: does the page lose information when this element is removed? |","| Micro and macro readings | A good display reads at a distance and up close. | Verify from a distance, then closely. |","","Sources:","","- Envisioning Information (1990): layering and separation, small multiples, micro and macro. https://www.edwardtufte.com/book/envisioning-information/","- The Visual Display of Quantitative Information (1983): data-ink, chartjunk.","- iPhone interface design, edwardtufte.com notebook: administrative debris, spatial over temporal. https://www.edwardtufte.com/notebook/iphone-interface-design/","","## Josef Müller-Brockmann","","Grid Systems in Graphic Design (1981) is the discipline behind the page column","grid. The grid does the separating, so an element needs no border to show","where it sits. His stated aim is compact planning, intelligibility, and","clarity. That is Tufte's aim in a typographer's words.","","## Refactoring UI","","Adam Wathan and Steve Schoger, Refactoring UI (2018), turns both into working","rules for product screens:","","- Put more space around a group than within it.","- Start with too much white space, then remove some.","- Use fewer borders. Separate with space, a shadow, or a second background.","- Emphasize by de-emphasizing the secondary content.","- Labels are a last resort.","- Keep a spacing scale where no two steps are closer than a quarter. The `--space-*` scale is that scale.","","https://www.refactoringui.com/","","## Material Design 3, canonical layouts","","The Page layouts table takes its rows from Material's canonical layouts.","","| Layout | Statement | Row in SKILL.md |","|---|---|---|","| Supporting pane | The primary area takes about two thirds of the window; the secondary pane takes the rest. At compact width the pane moves below the main content. | Main with a supporting pane, two thirds and one third; the stacking sentence. |","| List-detail | The list and the detail of the selected item sit side by side at expanded width. | List with detail. |","| Feed | Equivalent items in an adaptive grid. | Grid of equals. |","","https://m3.material.io/foundations/layout/canonical-examples/overview","https://developer.android.com/develop/adaptive-apps/guides/canonical-layouts","","## Cloudscape patterns","","| Pattern | Statement | Rule in SKILL.md |","|---|---|---|","| Dashboard | Three areas top to bottom: overview, data, support. \"Consider seven as the limit number for data representation.\" | Verify: the first section holds what the user came for. Grid of equals: up to seven per section. |","| Single-page create | One container; the essential fields first and few; secondary inputs in an expandable section; cancel then submit at the bottom. | Containers: a form. Single column. |","| Details page | The title with its actions, then a summary, then related blocks. | Stacked sections. |","| Empty state | A heading, an optional line, and one action. \"Always provide an action.\" Errors go elsewhere. | Containers: an empty stage. |","","https://cloudscape.design/patterns/general/service-dashboard/static-dashboard/","https://cloudscape.design/patterns/resource-management/create/single-page-create/","https://cloudscape.design/patterns/resource-management/details/details-page/","https://cloudscape.design/patterns/general/empty-states/","","## Matthew Butterick, line length","","\"45 to 90 characters per line, including spaces.\" The Separation paragraph and the Verify check carry the measure, and the half-width copy span holds it at body size.","","https://practicaltypography.com/line-length.html","","## Nielsen Norman Group, proximity","","\"Proximity is one of the most important grouping principles and can overpower competing visual cues such as similarity of color or shape.\" Space inside a group is smaller than space between groups. An unrelated action inside a group is camouflaged, so a `danger` Button sits apart from the toolbar group.","","https://www.nngroup.com/articles/gestalt-proximity/"],
   },
@@ -26,7 +26,7 @@ export const skillDocs: Record<string, Record<string, string[]>> = {
     "references/design-directions.md": ["# Design directions: feelings, idioms, and occasions","","Read this once the request names a feeling, a design idiom, an era, a genre, a","holiday, a season, or a natural scene. Each entry places the request and gives","the direction the three intents come from.","","The mechanics live with the executors. Color anchors are in","live-tokens-set-colors, type anchors in live-tokens-set-type, geometry anchors","in live-tokens-set-geometry, each keyed on the same names as the tables below.","Name the anchor in the intent, and the sibling reads its own column.","","Three axes place any request, including one no entry lists:","","| Axis | Reads as | Carried by |","|---|---|---|","| Valence | pleasant against unpleasant | lightness, above everything else |","| Energy | aroused against calm | chroma, and hue distance on screen |","| Dominance | assertive against yielding | surface contrast, type weight, border weight, tightness |","","An idiom sets constraints and a feeling moves dials, so a request that names","both (\"cozy brutalist\", \"clinical Swiss\") reads the idiom first and lets the","feeling move the dials inside it.","","## Feelings","","Valence and energy set the quadrant, and the table runs in quadrant order:","pleasant-aroused, pleasant-calm, unpleasant-aroused, unpleasant-calm. Dominance","separates confident from gentle inside one quadrant and lives almost entirely","outside color.","","| Request | Placement | Direction |","|---|---|---|","| Joyful, exuberant, energetic | pleasant, high energy | warm and bright throughout, with nothing held back |","| Playful, whimsical | pleasant, high energy, low dominance | four hue families at play, soft and generous |","| Optimistic, hopeful | pleasant, moderate energy | a cool ground lit by one warm counterpoint, like sunrise |","| Confident, bold | pleasant, high energy, high dominance | wide contrast, heavy weight, held tight |","| Serene, tranquil | pleasant, low energy | cool and quiet, with nothing loud anywhere |","| Tender, gentle, romantic | pleasant, low energy, low dominance | a soft warm ground, a narrow range, light weights |","| Cozy, comforting | pleasant, low energy | warm through and through, nothing cool on screen |","| Wistful, nostalgic, vintage, faded | pleasant, low energy | chroma withheld rather than light withheld |","| Earthy, grounded, natural | pleasant, low energy, moderate dominance | warm mineral hues, nothing synthetic |","| Clinical, sterile, precise | neutral, low energy, high dominance | an untinted ground, one cool hue, tightly set |","| Contemplative, focused | neutral, low energy | one cool hue and almost nothing else |","| Urgent, alarming | unpleasant, high energy, high dominance | a neutral ground so the alarm lands, heavy and tight |","| Tense, anxious | unpleasant, high energy | an uncomfortable ground under a pair that vibrates |","| Defiant, rebellious, loud | unpleasant, high energy, highest dominance | near-black under one acid hue, blunt everywhere |","| Melancholy, moody, sad | unpleasant, low energy | dark and cool, holding one moment of color |","| Somber, grave, mournful | unpleasant, low energy, high dominance | near-neutral dark, sharp and quiet |","| Ominous, dramatic, haunted | unpleasant, low energy, high dominance | dark with one hot accent and real atmosphere |","| Austere, severe, cold | unpleasant, lowest energy, highest dominance | monochrome at one extreme of lightness |","","## Idioms, eras, and genres","","The table runs modernist, digital, quiet, print, expressive.","","| Request | Placement | Direction |","|---|---|---|","| Swiss, International | neutral, low energy, high dominance | one hue on a near-white ground, rational, tight |","| Bauhaus | pleasant, high energy, high dominance | primaries at full commitment on paper, geometric, square but for the circle |","| Mid-century modern | pleasant, moderate energy | warm muted mid-tones, soft and open, no borders |","| Art deco, opulent, luxurious | pleasant, low energy, high dominance | dark with one metal, high-contrast type, sharp |","| Terminal, phosphor | neutral, moderate energy, high dominance | one phosphor hue on near-black, mono, bordered |","| Cyberpunk, neon noir, futuristic | unpleasant, high energy, high dominance | dark with two neons and a glow, wide type, sharp |","| Vaporwave | pleasant, moderate energy, low dominance | light sunset pastels with a gradient, retro display, soft |","| Y2K, bubble | pleasant, high energy | a chrome ground under electric color, geometric, pills |","| Blueprint | neutral, low energy, high dominance | a drafting ground with pale rules, technical type, gridded |","| Scandinavian, hygge | pleasant, low energy, low dominance | a chalk ground and muted naturals, soft and open |","| Japandi, wabi-sabi | pleasant, lowest energy | unbleached paper, near-monochrome, generous space, no borders |","| Cottagecore, botanical | pleasant, low energy, low dominance | warm cream and garden hues, serif display, soft |","| Editorial, magazine | neutral, low energy, high dominance | paper and ink with one strong hue, carried by rules |","| Newsprint, broadsheet | neutral, low energy | grey-warm paper under near-black ink, serif throughout, tight |","| Risograph, zine | pleasant, high energy, high dominance | two flat spot inks on paper, expressive display, heavy rules |","| Corporate, professional, trustworthy | pleasant, low energy | cool near-white with navy and teal, conventional everywhere |","| Brutalist | unpleasant, high energy, highest dominance | a pure ground, one alarming hue, heavy type, thick borders |","| Memphis, postmodern | pleasant, highest energy | a pastel ground under four hue families, shapes set against each other |","| Industrial, workshop, gritty | neutral, moderate energy, high dominance | concrete and steel with safety orange, condensed type, thick borders |","","## Occasions","","An occasion fixes color only, so its type and geometry intents come from the","feeling it implies or from the generic tables in the sibling skills.","","Every occasion is a statement request: the named color goes on the ground","rather than only on the buttons.","","| Request | Direction |","|---|---|","| Christmas | red and green with gold, one of the two owning the ground |","| Halloween | pumpkin, violet, and poison green, dark either way |","| St. Patrick's | green with gold over a pale ground |","| Ocean | blues held to one narrow band |","| Sunset | a hue sweep through red, falling in lightness |","| Autumn | parchment under rust, gold, and moss |","| Spring | pastels, greens and pinks over a mint ground |"],
   },
   "fix-findings": {
-    "SKILL.md": ["---","name: live-tokens-fix-findings","description: Fix every finding of check-page and check-component in an existing @motion-proto/live-tokens project until both exit 0. Called with the fix list by live-tokens-check-compliance. Use when the user asks to fix the project. Edits the files the checkers name. Updates tokens.css only through the migration command.","---","","# Fixing the findings of check-page and check-component","","Fix every finding of `check-page` and `check-component` until both exit 0. `check-page` checks pages. Every component comes from the catalogue, every prop is declared, and every value in page CSS is a design token. `check-component` checks authored components. Every token names a semantic property, and its default is the design token that property reads. Update `tokens.css` only through the migration command. That command also heals the data tree, and with `--write` rewrites the route references it lists. When live-tokens-check-compliance hands over a fix list, the user's choices in it stand.","","## Workflow","","When `check-page` is an unknown command, upgrade `@motion-proto/live-tokens` first.","","1. Run `npx live-tokens migrate --check` to see the plan, then `npx live-tokens migrate` to apply it. `--tokens <path>` names a tokens.css in an unusual place.","2. Run both checkers with `--json`. Each finding carries a `rule`, a file, and a line.","   ```sh","   npx live-tokens check-page --json","   npx live-tokens check-component --json","   ```","3. Group the findings by rule.","4. Take the largest error group first, then the remaining errors. Take warnings only when the repair scope includes warnings.","5. Fix every finding in the group with its section: Color by role, Geometry by scale, or The remaining rules.","6. Run both checkers again. When repairable findings remain in scope, return to step 3. When no token fits a remaining finding, leave it and continue to the reply with its reason.","7. When the errors are clear, run both checkers with `--strict`. Report what `--strict` adds. Clear warnings within the existing request. Otherwise ask whether to clear the warnings now.","8. When the repair scope includes warnings, return to step 3 with `--strict`. When strict checks pass or the user defers warnings, continue to the reply.","9. Reply with:","   - the changes by rule, each with its count and any visible shift","   - the findings left, each with its reason and any config entry the user chose","   - both checker commands with their exit codes","","`check-page <path>` scopes a run to one page. `check-component <id>` scopes a run to one component: its runtime, its editor, and its registration. The checkers read tokens.css from its default location.","","When `package.json` has no `check:design` script, add `\"check:design\": \"live-tokens check-page && live-tokens check-component\"`. When both checkers exit 0, prepend `npm run check:design &&` to the existing build command. Preserve its other build steps.","","## Scope","","- Add no token to `tokens.css`. Map a literal with no matching token to the nearest existing token by role. When no token fits, leave the finding and say so.","- When the user has chosen to lower a rule's severity, record it in `live-tokens.config.json` under `\"checks\": { \"rules\": { \"<rule>\": \"warn\" } }`. `--off=<rule>` silences a rule for one run only.","- When the nearest token differs from the literal, use the token and name the shift in the report, such as `14px` to `--space-16`.","","## Color by role","","`color-literal` is a judgement finding. The replacement is the token for the role the color plays. The theme moves every role together. `npx live-tokens tokens --scale <name>` prints a scale's names and values, with `--json` for data.","","| Literal | Token | Notes |","| --- | --- | --- |","| Text on a surface | `--text-primary` through `--text-disabled` | The neutral text scale. `--text-<family>` for a family color. |","| Light text on a dark chip | `--text-inverted` | No AA guarantee. |","| A surface fill | `--surface-<family>-<level>` | The role names the family: `neutral` for chrome, `brand` for emphasis, `danger` for status. |","| A stroke | `--border-<family>-<level>` | Levels run `faint` to `strong`. |","| A translucent layer that dims what is behind it | `--scrim-low`, `--scrim`, `--scrim-high` | Behind a modal. |","| A translucent wash on a surface | `--tint-low`, `--tint`, `--tint-high` | A hover state. |","| Any other translucent color | The role's token at an opacity: `color-mix(in srgb, var(--surface-brand) 80%, transparent)` | The editor reads that form. |","| Fully transparent | `--color-transparent` | |","| A gradient | `--gradient-*` | Or compose one from surface tokens. |","","## Geometry by scale","","`dimension-literal` is a mechanical finding. A size, such as a hero's height, is layout. Leave it.","","| Literal | Token | Notes |","| --- | --- | --- |","| Spacing | `--space-<px>` | `npx live-tokens tokens --scale space` prints the steps. Round to the nearest step. |","| A stroke width | `--border-width-1`, `-2`, `-4` | Also for `outline`. |","| A corner | `--radius-sm` through `--radius-4xl`, or `--radius-full` | |","| A shadow | `--shadow-sm` through `--shadow-xl` | Replace the whole value. |","| Part of a `calc()` | The token inside the calc | `calc(var(--space-64) * -2 + var(--space-8))` |","| A duration or easing | `--duration-*`, `--ease-*` | No rule reports it. Fix it while in the file. |","| A `blur()` | `--blur-*` | No rule reports it. Fix it while in the file. |","","## The remaining rules","","| Rule | Fix |","| --- | --- |","| `unknown-token` | Search `tokens.css` for the stem. When a contract-family name is gone, `npx live-tokens migrate --check` lists the migration that adds the current name. |","| `raw-text-axis` | Set every axis from one text style, `-font-family` through `-letter-spacing`. `npx live-tokens tokens --scale heading` prints one text style. The text styles are `heading`, `body`, `editorial`, and `code`. Rewrite a `font:` shorthand the same way. |","| `unknown-component` | Read **live-tokens-pick-component** for the shipped component that fits. When none fits, author one with **live-tokens-create-component**. |","| `unknown-prop` | `npx live-tokens components <id>` prints the declared props and their values. Map the prop to one of them, or delete it. |","| `unknown-prop-value` | Use a value from the union the message lists. |","| `control-size` | Delete the `size` prop. The shipped default is the page's size. When that default is wrong for the project, retune the component in `/live-tokens/components`. |","| `multiple-primary` | Keep the action that completes the main task `primary`. A Button with no `variant` counts as `primary`. Use `secondary` for supporting or related actions and `outline` for unrelated or informational actions. |","| `danger-without-dialog` | Open a `Dialog` from the danger Button or IconButton and run the action from the Dialog's confirm. The rule fires once per page, when the page imports no Dialog. For other actions, assign emphasis by the action's relationship to the main task. |","| `hardcoded-columns` | `repeat(var(--columns-count), 1fr)` for the page grid. `calc(var(--columns-count) - 2)` for a sub-grid spanning fewer columns. |","| `site-css-in-main` | Delete the import from `main.ts`. Add it to each page's `<script>`. Page CSS then stays off the editor routes. |","| `missing-source` | Add `source: 'src/...'` to the route entry. |","| `reserved-route` | Move the route out of `/live-tokens/*`. |","| `deep-import` | Import from `@motion-proto/live-tokens`, `/component-editor`, or `/components/<Name>.svelte`. |","| `fix: property-name` | Rename the token to the name a shipped component uses for the same role. The vocabulary and the state model are in **live-tokens-create-component**. |","| `fix: property-token` | Make the `:global(:root)` default read a design token, composed when needed. Declare a structural keyword, such as `start`, in the editor's `intrinsics`. |","| `fix: runtime` | Wire the component as the recipe in **live-tokens-create-component** wires it. |","| `fix: runtime-defaults` | Make the `:global(:root)` default the value Reset should restore, per the Runtime component section of **live-tokens-create-component**. |","| `fix: editor` | The editor names a token the runtime never declares, or a property targets the wrong part. Fix the editor's schema, states, or preview props by the Component editor section of **live-tokens-create-component**. |","| `fix: registration` | Register the component in the shared module the Registration section of **live-tokens-create-component** wires up, importable by the app and by `check-component --tests`. |","| `fix: sketch` | Add the missing Sketch part or marker, per the Sketch mode and overlays section of **live-tokens-create-component**. |","| `fix: tooling` | Install the named package (`@playwright/test`, `vitest`, or `happy-dom`) as a devDependency, then `npx playwright install chromium` for a missing browser. A bad path or config is named in the message; fix it and rerun `check-component <id> --tests`. |","| `fix: coverage` | A contract obligation never ran to a result. Add the missing contract, or find why the suite skipped it, then rerun. |","","A `tests-*` finding names a problem with the run itself: the tool, the path, or a missing contract. Fix what the message names and rerun `check-component <id> --tests --json` until every applicable rule passes with no rule left `--off`."],
+    "SKILL.md": ["---","name: live-tokens-fix-findings","description: Fix every finding of check-page and check-component in an existing @motion-proto/live-tokens project until both exit 0. Called with the fix list by live-tokens-check-compliance. Use when the user asks to fix the project. Edits the files the checkers name. Updates tokens.css only through the migration command.","---","","# Fixing the findings of check-page and check-component","","Fix every finding of `check-page` and `check-component` until both exit 0. `check-page` checks pages. Every component comes from the catalogue, every prop is declared, and every value in page CSS is a design token. `check-component` checks authored components. Every token names a semantic property, and its default is the design token that property reads. Update `tokens.css` only through the migration command. That command also heals the data tree, and with `--write` rewrites the route references it lists. When live-tokens-check-compliance hands over a fix list, the user's choices in it stand.","","## Workflow","","When `check-page` is an unknown command, upgrade `@motion-proto/live-tokens` first.","","1. Run `npx live-tokens migrate --check` to see the plan, then `npx live-tokens migrate` to apply it. `--tokens <path>` names a tokens.css in an unusual place.","2. Run both checkers with `--json`. Each finding carries a `rule`, a file, and a line.","   ```sh","   npx live-tokens check-page --json","   npx live-tokens check-component --json","   ```","3. Group the findings by rule.","4. Take the largest error group first, then the remaining errors. Take warnings only when the repair scope includes warnings.","5. Fix every finding in the group with its section: Color by role, Geometry by scale, or The remaining rules.","6. Run both checkers again. When repairable findings remain in scope, return to step 3. When no token fits a remaining finding, leave it and continue to the reply with its reason.","7. When the errors are clear, run both checkers with `--strict`. Report what `--strict` adds. Clear warnings within the existing request. Otherwise ask whether to clear the warnings now.","8. When the repair scope includes warnings, return to step 3 with `--strict`. When strict checks pass or the user defers warnings, continue to the reply.","9. Reply with:","   - the changes by rule, each with its count and any visible shift","   - the findings left, each with its reason and any config entry the user chose","   - both checker commands with their exit codes","","`check-page <path>` scopes a run to one page. `check-component <id>` scopes a run to one component: its runtime, its editor, and its registration. The checkers read tokens.css from its default location.","","When `package.json` has no `check:design` script, add `\"check:design\": \"live-tokens check-page && live-tokens check-component\"`. When both checkers exit 0, prepend `npm run check:design &&` to the existing build command. Preserve its other build steps.","","## Scope","","- Add no token to `tokens.css`. Map a literal with no matching token to the nearest existing token by role. When no token fits, leave the finding and say so.","- When the user has chosen to lower a rule's severity, record it in `live-tokens.config.json` under `\"checks\": { \"rules\": { \"<rule>\": \"warn\" } }`. `--off=<rule>` silences a rule for one run only.","- When the nearest token differs from the literal, use the token and name the shift in the report, such as `14px` to `--space-16`.","","## Color by role","","`color-literal` is a judgement finding. The replacement is the token for the role the color plays. The theme moves every role together. `npx live-tokens tokens --scale <name>` prints a scale's names and values, with `--json` for data.","","| Literal | Token | Notes |","| --- | --- | --- |","| Text on a surface | `--text-primary` through `--text-disabled` | The neutral text scale. `--text-<family>` for a family color. |","| Light text on a dark chip | `--text-inverted` | No AA guarantee. |","| A surface fill | `--surface-<family>-<level>` | The role names the family: `neutral` for chrome, `brand` for emphasis, `danger` for status. |","| A stroke | `--border-<family>-<level>` | Levels run `faint` to `strong`. |","| A translucent layer that dims what is behind it | `--scrim-low`, `--scrim`, `--scrim-high` | Behind a modal. |","| A translucent wash on a surface | `--tint-low`, `--tint`, `--tint-high` | A hover state. |","| Any other translucent color | The role's token at an opacity: `color-mix(in srgb, var(--surface-brand) 80%, transparent)` | The editor reads that form. |","| Fully transparent | `--color-transparent` | |","| A gradient | `--gradient-*` | Or compose one from surface tokens. |","","## Geometry by scale","","`dimension-literal` is a mechanical finding. A size, such as a hero's height, is layout. Leave it.","","| Literal | Token | Notes |","| --- | --- | --- |","| Spacing | `--space-<px>` | `npx live-tokens tokens --scale space` prints the steps. Round to the nearest step. |","| A stroke width | `--border-width-1`, `-2`, `-4` | Also for `outline`. |","| A corner | `--radius-sm` through `--radius-4xl`, or `--radius-full` | |","| A shadow | `--shadow-sm` through `--shadow-xl` | Replace the whole value. |","| Part of a `calc()` | The token inside the calc | `calc(var(--space-64) * -2 + var(--space-8))` |","| A duration or easing | `--duration-*`, `--ease-*` | No rule reports it. Fix it while in the file. |","| A `blur()` | `--blur-*` | No rule reports it. Fix it while in the file. |","","## The remaining rules","","| Rule | Fix |","| --- | --- |","| `unknown-token` | Search `tokens.css` for the stem. When a contract-family name is gone, `npx live-tokens migrate --check` lists the migration that adds the current name. |","| `raw-text-axis` | Set every axis from one text style, `-font-family` through `-letter-spacing`. `npx live-tokens tokens --scale heading` prints one text style. The text styles are `heading`, `body`, `editorial`, and `code`. Rewrite a `font:` shorthand the same way. |","| `unknown-component` | Read **live-tokens-pick-component** for the shipped component that fits. When none fits, author one with **live-tokens-create-component**. |","| `unknown-prop` | `npx live-tokens components <id>` prints the declared props and their values. Map the prop to one of them, or delete it. |","| `unknown-prop-value` | Use a value from the union the message lists. |","| `control-size` | Delete the `size` prop. The shipped default is the page's size. When that default is wrong for the project, retune the component in `/live-tokens/components`. |","| `multiple-primary` | Keep the action that completes the main task `primary`. A Button with no `variant` counts as `primary`. Use `secondary` for supporting or related actions and `outline` for unrelated or informational actions. |","| `danger-without-dialog` | Open a `Dialog` from the danger Button or IconButton and run the action from the Dialog's confirm. The rule fires once per page, when the page imports no Dialog. For other actions, assign emphasis by the action's relationship to the main task. |","| `native-control` | Replace the native element with the shipped component the message names: Button or IconButton, Input, MenuSelect. |","| `property-override` | Delete the declaration from the page. Retune the component's token for the whole project at `/live-tokens/components`. |","| `page-component-paint` | The finding names the page file and the line of the instance whose part painted a value its semantic property never resolves to. Remove the global rule reaching past the component, from `site.css` or the page's own CSS, and retune the component's token for the whole project at `/live-tokens/components`. |","| `page-text-style` | The finding names the page file and the line of the text element and the nearest bundle it missed. Set the container's text style directly on the text element, one shipped bundle from `npx live-tokens tokens --scale heading` (or `body`, `editorial`, `code`), rather than leaving it to inherit from an ancestor typed for a different role. |","| `page-contrast` | The finding names the page file and the line of the text element, the surface ancestor, and both computed colors. Pick the text token the surface pairs with, from the Color by role table above. |","| `page-grid` | The finding names the page file and the line of the section whose edge sits off a column line. Move the edge to the line: place it by page-column numbers per the Grid section of **live-tokens-create-page**, and give a centered section symmetric insets rather than a margin, a width, or a transform. |","| `page-overflow` | The finding names the page file and the line of the element or the instance that overflows. Give the control its shipped width, remove a fixed width that does not fit its column at the viewport, and set `overflow-x: auto` only on an element deliberately meant to scroll, such as a code block. When the overflow is the page grid itself at a phone width, collapse it: `grid-template-columns: 1fr`, `column-gap: 0`, per the Grid section of **live-tokens-create-page**. |","| `hardcoded-columns` | `repeat(var(--columns-count), 1fr)` for the page grid. `calc(var(--columns-count) - 2)` for a sub-grid spanning fewer columns. |","| `site-css-in-main` | Delete the import from `main.ts`. Add it to each page's `<script>`. Page CSS then stays off the editor routes. |","| `missing-source` | Add `source: 'src/...'` to the route entry. |","| `reserved-route` | Move the route out of `/live-tokens/*`. |","| `deep-import` | Import from `@motion-proto/live-tokens`, `/component-editor`, or `/components/<Name>.svelte`. |","| `fix: property-name` | Rename the token to the name a shipped component uses for the same role. The vocabulary and the state model are in **live-tokens-create-component**. |","| `fix: property-token` | Make the `:global(:root)` default read a design token, composed when needed. Declare a structural keyword, such as `start`, in the editor's `intrinsics`. |","| `fix: runtime` | Wire the component as the recipe in **live-tokens-create-component** wires it. |","| `fix: runtime-defaults` | Make the `:global(:root)` default the value Reset should restore, per the Runtime component section of **live-tokens-create-component**. |","| `fix: editor` | The editor names a token the runtime never declares, or a property targets the wrong part. Fix the editor's schema, states, or preview props by the Component editor section of **live-tokens-create-component**. |","| `fix: registration` | Register the component in the shared module the Registration section of **live-tokens-create-component** wires up, importable by the app and by `check-component --tests`. |","| `fix: sketch` | Add the missing Sketch part or marker, per the Sketch mode and overlays section of **live-tokens-create-component**. |","| `fix: tooling` | Install the named package (`@playwright/test`, `vitest`, or `happy-dom`) as a devDependency, then `npx playwright install chromium` for a missing browser. A bad path or config is named in the message; fix it and rerun `check-component <id> --tests`. |","| `fix: coverage` | A contract obligation never ran to a result. Add the missing contract, or find why the suite skipped it, then rerun. |","","A `tests-*` finding names a problem with the run itself: the tool, the path, or a missing contract. Fix what the message names and rerun `check-component <id> --tests --json` until every applicable rule passes with no rule left `--off`."],
   },
   "pick-component": {
     "SKILL.md": ["---","name: live-tokens-pick-component","description: Recommend which shipped @motion-proto/live-tokens component fits a UX need, with a decision test for each confusable family. Called by live-tokens-create-page when more than one component could fit, and by live-tokens-create-component before it authors anything. Use when the user asks which component to use, or what the difference between two components is. Use when the user asks how to show or capture a UX outcome. Edits no file. For size, emphasis, or placement, read live-tokens-create-page. When the catalogue lacks a component with chrome, read live-tokens-create-component.","---","","# Picking a live-tokens component","","When more than one shipped component could fit, find the family below that names the candidates. Apply its test, which asks what the choice means to the reader.","","## Catalogue","","Before choosing, run `npx live-tokens components`. The list holds every component the project has, shipped and custom, with each one's variants and usage comment. The family tests below name the shipped set only. Weigh a custom component by the same tests.","","## Action family","","- The action needs a word to be unambiguous: `Button`.","- The glyph alone is plain (close, edit, delete) and space is short: `IconButton`.","- The pair that confirms or cancels an inline edit: `InlineEditActions`.","","## Single-selection family","","Four components pick one option from a set. The test is the option count, whether the selection swaps the content below, and how much the choice asks of the reader.","","| Component | Test | Option count |","|---|---|---|","| `SegmentedControl` | An inline switch between views of the same data. It sits in a row of controls. | 2 to 4 |","| `TabBar` | The content area below swaps. | 2 to 7 |","| `RadioButton` | The reader reads every option as text inside a larger form. | any |","| `MenuSelect` | The options would overflow a row. | any |","","- When a label would wrap in a `SegmentedControl`, use `RadioButton` rows.","- The URL changes: `SideNavigation`. Sections inside one page: `TabBar`.","","## Text entry","","The test is whether the answer comes from a predefined list of options.","","- A predefined list (a status, a currency, a size, a country): the single-selection family, by its own test. Up to four options sit in a row; more go in a `MenuSelect`, which scrolls.","- No list (a name, a search string, an amount, a message, a street address): `Input`. Validation keeps a typed answer well-formed.","- A long list the reader would rather filter by typing (a city): no shipped component filters a list. Use `Input` with validation, or author a filtering select with **live-tokens-create-component**.","- A number where the position on a track carries the meaning (a volume, a price band, a percentage): `Slider`. A number the reader knows and would rather type: `Input` with `type=\"number\"`.","","## On and off","","Three components express a binary choice. The test is whether the two states have names of their own.","","| Component | Test |","|---|---|","| `Toggle` | A setting that takes effect at once. The label names the setting. The switch position is the state. |","| `SegmentedControl` | Two named alternatives the reader compares (Light / Dark, List / Grid). Both labels show at once. |","| `RadioButton` pair | A yes or no the reader answers inside a larger form. |","","When the two states share the feature's one name, use `Toggle`. \"Email notifications\" has no \"off\" label.","","## Container family","","Four components hold a block of content. The test is what the block is to the reader: one item, a section of the page, secondary content that stays collapsed until opened, or a decision.","","| Component | Modality | Test |","|---|---|---|","| `Card` | Inline, always open | One item, or each item in a set: a product, a record, a plan. It has a title and can react to hover. |","| `Panel` | Inline, always open | One section of the page's content in a frame: a stage, a list, a form, a block of copy. `minHeight` holds its height while the content changes. |","| `CollapsibleSection` | Inline, collapsed until the reader opens it | Secondary content most readers skip. |","| `Dialog` | Modal, blocks the page | A decision the page cannot continue without: a destructive confirmation, payment, sign-in. |","","A set of items is one `Card` per item. A routine form goes inline in a `Panel`.","","## Messaging family","","Five components carry a message. The test is what the message is about, what brings it on, and whether the reader dismisses it.","","| Component | Scope | Trigger | Dismissable | Test |","|---|---|---|---|---|","| `Callout` | A section | Always present | No | Something the reader must know about the content around it |","| `Notification` | The system | An action or event | Yes | Feedback about something that just happened |","| `Tooltip` | An element | Hover or focus | On leave | A definition or hint the reader can do without |","| `Badge` | An element | Always present | No | A standing label read at a glance (\"Beta\", \"New\", \"v2\") |","| `CornerBadge` | A parent's corner | Always present | No | A count or status marker on the thing it describes |","","`Badge` and `CornerBadge` differ in position only.","","## Display family","","Each pair holds a block the reader views and one the reader interacts with. The test is which of the two the page needs.","","- A picture the page shows: `Image`. A picture whose detail the reader must open, or a gallery: `ImageLightbox`.","- Records the reader scans and compares: `Table`. A set of items the reader acts on: one `Card` per item.","- A read-out of progress: `ProgressBar`. A number the reader sets: `Slider`.","- Text the reader runs or pastes (an install command, a key, an id): `CodeSnippet`. Prose the reader only reads: a paragraph in its `Card` or `Panel`.","- A titled break between the sections of one page: `SectionDivider`. Movement between pages: `SideNavigation`.","","## Nothing fits","","A native element with no chrome of its own needs no component: an `<input type=\"file\">` behind a Button, a `<canvas>`, an `<img>` inside a stage. When nothing in the catalogue fits a piece with chrome (a `DatePicker`, a `Stepper`), author the component with **live-tokens-create-component**. Size, emphasis, and placement are **live-tokens-create-page**'s.","","`npx live-tokens components <id>` prints one component's usage comment, its declared props, and the values each union accepts. `--json` returns the same as data."],

package/src/editor/skill-atlas/trees/check-compliance.ts

@@ -2,7 +2,7 @@ import type { SkillTree } from '../types';
 
 export const checkCompliance: SkillTree = {
   "id": "live-tokens-check-compliance",
-  "digest": "sha256:63b3e0e064051940",
+  "digest": "sha256:6ec5bd44eeee644c",
   "title": "check-compliance",
   "tagline": "Check to Ensure Live Tokens Is Used",
   "nodes": [
@@ -30,47 +30,47 @@ export const checkCompliance: SkillTree = {
       "kind": "chipset",
       "title": "Read the report sections",
       "desc": "Fixes in the report are listed by section.",
-      "lines": [17, 17],
+      "lines": [19, 19],
       "anchor": "Read each section of the report with the Report sections tab",
       "chips": [
         {
           "label": "Pending token migrations",
-          "lines": [30, 30],
+          "lines": [32, 32],
           "anchor": "| Pending token migrations (`migrations`) | Whether `tokens."
         },
         {
           "label": "Checker findings by rule",
-          "lines": [31, 31],
+          "lines": [33, 33],
           "anchor": "| Checker findings by rule (`findings.pages`, `findings.comp"
         },
         {
           "label": "Tokens a component never reads",
-          "lines": [32, 32],
+          "lines": [34, 34],
           "anchor": "| Tokens a component never reads (`components[].unread`) | T"
         },
         {
           "label": "Component registration",
-          "lines": [33, 33],
+          "lines": [35, 35],
           "anchor": "| Component registration (`components[].registered`) | Wheth"
         },
         {
           "label": "Component usage comment",
-          "lines": [34, 34],
+          "lines": [36, 36],
           "anchor": "| Component usage comment (`components[].described`) | Wheth"
         },
         {
           "label": "Components each page renders",
-          "lines": [35, 35],
+          "lines": [37, 37],
           "anchor": "| Components each page renders (`usage.byPage`) | Which comp"
         },
         {
           "label": "Shipped components no page renders",
-          "lines": [36, 36],
+          "lines": [38, 38],
           "anchor": "| Shipped components no page renders (`usage.unusedShipped`)"
         },
         {
           "label": "Project components unregistered or unused",
-          "lines": [37, 37],
+          "lines": [39, 39],
           "anchor": "| Project components unregistered or unused (`usage.customUn"
         }
       ]
@@ -81,22 +81,22 @@ export const checkCompliance: SkillTree = {
       "kind": "decide",
       "title": "Get details",
       "desc": "A finding may need more about one component or one token scale, such as space or color.",
-      "lines": [18, 18],
+      "lines": [20, 20],
       "anchor": "When a finding needs component or token scale details, run t",
       "chips": [
         {
           "label": "component",
-          "lines": [24, 24],
+          "lines": [26, 26],
           "anchor": "For one component, run `npx live-tokens components <id>`. Fo"
         },
         {
           "label": "token scale",
-          "lines": [24, 24],
+          "lines": [26, 26],
           "anchor": "For one component, run `npx live-tokens components <id>`. Fo"
         },
         {
           "label": "continue with classification",
-          "lines": [19, 19],
+          "lines": [21, 21],
           "anchor": "Classify each finding as Mechanical, Judgement, or Deliberat"
         }
       ]
@@ -107,7 +107,7 @@ export const checkCompliance: SkillTree = {
       "kind": "cli",
       "title": "Inspect the component",
       "desc": "Shows one component's props and usage.",
-      "lines": [24, 24],
+      "lines": [26, 26],
       "anchor": "For one component, run `npx live-tokens components <id>`. Fo"
     },
     {
@@ -116,7 +116,7 @@ export const checkCompliance: SkillTree = {
       "kind": "cli",
       "title": "Inspect the token scale",
       "desc": "Shows every token in one scale, such as space or color, with its value.",
-      "lines": [24, 24],
+      "lines": [26, 26],
       "anchor": "For one component, run `npx live-tokens components <id>`. Fo"
     },
     {
@@ -125,7 +125,7 @@ export const checkCompliance: SkillTree = {
       "kind": "chipset",
       "title": "Classify the findings",
       "desc": "Mechanical maps a value to an existing token.\nJudgement asks the user to decide.\nDeliberate records a decision the project made.",
-      "lines": [19, 19],
+      "lines": [21, 21],
       "anchor": "Classify each finding as Mechanical, Judgement, or Deliberat"
     },
     {
@@ -134,7 +134,7 @@ export const checkCompliance: SkillTree = {
       "kind": "hand",
       "title": "live-tokens-fix-findings",
       "desc": "Reply with the findings and the fixes, in the order the repair skill takes them, and hand it the list.",
-      "lines": [20, 22],
+      "lines": [22, 24],
       "anchor": "Reply with the findings of each section in the table's order",
       "anchorEnd": "End with the hand-off: run **live-tokens-fix-findings** on t"
     }

package/src/editor/skill-atlas/trees/create-component.ts

@@ -2,7 +2,7 @@ import type { SkillTree } from '../types';
 
 export const createComponent: SkillTree = {
   "id": "live-tokens-create-component",
-  "digest": "sha256:b923ee9c68cc13fc",
+  "digest": "sha256:6f7b5810d03739a0",
   "title": "create-component",
   "tagline": "Create a LiveTokens Component",
   "nodes": [
@@ -165,7 +165,7 @@ export const createComponent: SkillTree = {
       "row": 5,
       "kind": "chipset",
       "title": "Register the component",
-      "desc": "Register it in the shared module main.ts and live-tokens.testing.ts both name, so check-component --tests can see it.",
+      "desc": "Register it in the shared module main.ts and live-tokens.testing.ts both name, and write its contract, so check-component --tests can see and drive it.",
       "lines": [16, 16],
       "anchor": "Register the component in the module `src/main.ts` and `live",
       "chips": [
@@ -180,6 +180,11 @@ export const createComponent: SkillTree = {
           "lines": [207, 207],
           "anchor": "Import the module from `src/main.ts`, before `bootLiveTokens"
         },
+        {
+          "label": "Contract",
+          "lines": [207, 207],
+          "anchor": "Import the module from `src/main.ts`, before `bootLiveTokens"
+        },
         {
           "label": "First-party",
           "lines": [211, 211],
@@ -192,7 +197,7 @@ export const createComponent: SkillTree = {
       "row": 6,
       "kind": "chipset",
       "title": "Run the checks",
-      "desc": "Get a report from check-compliance, then run check-component --tests until it passes.",
+      "desc": "Get a report from check-compliance, then run check-component --tests until it passes with the contract's suites covered.",
       "lines": [17, 17],
       "anchor": "Run **live-tokens-check-compliance**, then `npx live-tokens ",
       "chips": [