@motion-proto/live-tokens 0.78.0 → 0.79.0

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

@@ -1,47 +1,76 @@
 ---
 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.
+description: Check an existing @motion-proto/live-tokens project against the design system and fix it until check-page and check-component both exit 0. Checks for correct use of components, properties, and tokens. Reads the whole project from one run of npx live-tokens report, runs the token migrations, then runs both checkers, which apply every auto repair and return each remaining finding with its own guidance, repair level, and details. Use when the user asks to check, audit, or review the project. Use when the user asks to fix the project or to make check:design pass. Edits the files the checkers name. Updates tokens.css only through the migration command.
 ---
 
-# Checking a project's adherence to live-tokens
+# Checking and fixing 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**.
+Check the project, then 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 the project's own components. Every token names a semantic property, and its default is the design token that property reads. Every finding carries its own `guidance`, and the repair follows it.
 
-`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.
+The report and both checkers are static. They read the project's source, never open a browser, and never mount a runtime. `npx live-tokens check-page <file> --tests` proves a page's rendered paint, and `npx live-tokens check-component <id> --tests` proves a component's declared behavior. **live-tokens-create-page** and **live-tokens-create-component** run those, one file or one id at a time, and their findings carry guidance the same way.
 
 ## 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.
+1. Run `npx live-tokens report --json`. Read it in its own key order: `project`, `migrations`, `components`, `findings.pages`, `findings.components`, `usage`, per Report sections below.
+2. Run `npx live-tokens migrate --check` to see the plan, then `npx live-tokens migrate` to apply it. The command brings `tokens.css` up to the installed package and heals the data tree. With `--write` it also rewrites the route references it lists. `--tokens <path>` names a tokens.css in an unusual place.
+3. Run both checkers with `--json`. Each first applies every finding whose `repair` is `auto`, checks again, and returns the fixes it applied in `fix.applied` beside the findings that remain. A fix in `fix.skipped` found its text moved, and the next run applies it. `--no-fix` reports without editing, for a build or CI.
+   ```sh
+   npx live-tokens check-page --json
+   npx live-tokens check-component --json
+   ```
+4. Read what remains. Each finding carries the fields under Finding fields, with a `repair` of `choice` or `authored`.
+5. Group the findings by rule. Take the largest error group first, then the remaining errors. Take warnings only when the repair scope includes warnings.
+6. Make every repair in the group from its `guidance`, within Scope below.
+7. Run both checkers again. When repairable findings remain in scope, return to step 5. When no token fits a remaining finding, leave it and continue to the reply with its reason.
+8. 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.
+9. When the repair scope includes warnings, return to step 5 with `--strict`. When strict checks pass or the user defers warnings, set up the build script.
+10. Add `check:design` to the build, per Build script below.
+11. Reply with:
+    - the report's picture: pending migrations, component facts, and usage
+    - the fixes the checkers applied, each with its count and any visible shift
+    - the remaining 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
 
-For one component, run `npx live-tokens components <id>`. For one token scale, run `npx live-tokens tokens --scale <name>`. Both take `--json`.
+`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.
 
 ## 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. |
+| Section | Contents |
+| --- | --- |
+| 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, so step 2 runs the migrations before either checker. |
+| Component facts (`components[]`) | Every component the project has, each with `id`, `origin`, `file`, `registered`, and `tokens` (the count of semantic properties it declares). A component's unread tokens, missing description, and missing registration are the `unread-token`, `missing-description`, and `missing-registration` findings. |
+| 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. |
+| 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`) | Information only. |
+| Project components unused (`usage.customUnused`) | The project's own components no page renders. |
+
+## Finding fields
+
+Every finding from both checkers, under `report --json` and under each checker's `--json`:
+
+| Field | Value |
+| --- | --- |
+| `rule`, `severity`, `file`, `line`, `message` | What the finding is and where. |
+| `guidance` | How to make the repair: the token for the role or the scale step, the command that prints the candidates, or the section of a create skill that owns the fix. |
+| `repair` | `auto`, `choice`, or `authored`. See Repair levels. |
+| `exception` | The narrower config entry that records a decision to leave the finding as it is: `{ "checks": { "exclude": ["<file>"] } }` for a page or CSS file, otherwise `{ "checks": { "rules": { "<rule>": "warn" } } }`. Applying it steps the rule down one level, error to warn and warn to off. |
+| `details` | Per-rule data the message already states in prose, such as the accepted values behind `unknown-prop-value` or the nearest design-token candidates behind `dimension-literal`. Absent when a rule has nothing to add. |
+
+## Repair levels
+
+Every finding's `repair` says what moving it costs.
+
+- **`auto`.** The value determines the fix, such as a spacing literal with one nearest design-token step. The checkers apply it and list it in `fix.applied`.
+- **`choice`.** A role or an ambiguous value determines the fix, such as a color literal and the role it plays, or a spacing literal tied between two steps. `details` lists the candidates, and `guidance` says how to pick one.
+- **`authored`.** New code is the fix: a runtime that has to start behaving, an editor schema that has to name a token, a route that has to move. `guidance` names what to write. No candidate list applies.
+
+## Scope
 
-## Finding classes
+- 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 nearest token differs from the literal, use the token and name the shift in the reply, such as `14px` to `--space-16`.
+- Any finding, at any repair level, can stay as a deliberate exception when the user chooses to keep it. Record that decision in the config entry its `exception` field names, and prefer the narrower entry. 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.
 
-Every finding is one of three. Say which.
+## Build script
 
-- **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.
+When `package.json` has no `check:design` script, add `"check:design": "live-tokens check-page --no-fix && live-tokens check-component --no-fix"`. `--no-fix` keeps the build from editing files. When both checkers exit 0, prepend `npm run check:design &&` to the existing build command. Preserve its other build steps.

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

@@ -11,10 +11,10 @@ Create a component whose structure and behavior serve the user's purpose. Give e
 
 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>`.
+3. Write the runtime file: the catalogue export 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.
+6. Run `npx live-tokens check-component <id> --tests --strict --json` until it exits 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
@@ -34,12 +34,14 @@ A component is distinct in its anatomy, its proportions, its content hierarchy,
 
 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.
 
+Prop names follow the shipped components. `label` names a control, `title` heads content, `text` is body copy. `open` is the one prop for an open state. `value` holds a selection's id. A size prop's values are `default` and `small`. A callback prop is `on` followed by the event name, all lowercase, as in `onchange`, `onclose`, and `onsave`.
+
 ## 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.
+2. Run `npx live-tokens components`. The list holds every component the project has, with its variants and catalogue entry. `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.
@@ -53,7 +55,7 @@ A component has three kinds of division. Keep them apart in the props, the names
 | Kind | Meaning | Example |
 |---|---|---|
 | Part | Regions present at once | Dialog's overlay, header, body, footer |
-| Variant | Alternative presentations the page chooses | Badge's primary, danger |
+| Variant | Alternative presentations the page chooses | Badge's brand, 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.
@@ -95,20 +97,24 @@ A property name starts with the component id and ends with the property 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`.
+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-brand-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.
+Open the file with a `<script module lang="ts">` block that exports a `catalogue` entry in the shape every shipped component carries. `npx live-tokens components` prints it beside the id, and `components <id>` prints it with the props. Each field is `key: <string literal>`, in single, double, or backtick quotes; no `${}` interpolation, no concatenation, no identifier reference. An optional `props` map adds one line per prop whose values carry a choice, such as `variant`; each key names a prop the file declares, and the text says what the values mean.
 
 ```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).
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '@motion-proto/live-tokens';
+
+  export const catalogue = {
+    description: 'A figure with its label.',
+    useFor: 'one number the reader takes in at a glance.',
+    notFor: 'a set of records (Table); a titled block of content (Card).',
+  } satisfies CatalogueEntry;
+</script>
 ```
 
 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.
@@ -192,6 +198,7 @@ Register the component in `src/registerComponents.ts`, a registration-only modul
 ```ts
 // src/registerComponents.ts
 import { registerComponent } from '@motion-proto/live-tokens';
+import { catalogue } from './system/components/StatCard.svelte';
 import StatCardEditor, { allTokens as statCardTokens } from './system/components/StatCardEditor.svelte';
 
 registerComponent({
@@ -201,6 +208,7 @@ registerComponent({
   sourceFile: 'src/system/components/StatCard.svelte',
   editorComponent: StatCardEditor,
   schema: statCardTokens,
+  catalogue,
 });
 ```
 
@@ -218,23 +226,10 @@ A fixed overlay portals to `<body>`: read `references/fixed-overlays.md`. A cont
 
 ## 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 |
+1. 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`. It applies every `auto` repair, runs the registry contract and, for a component with a contract in the module `contractsModule` names, the component contract suites, and returns the fixes it applied, the findings that remain, and coverage by rule. `--off=<rule>` silences a rule for one run, and `--no-fix` reports without editing.
+2. Each remaining finding carries a rule id, a line, and its `guidance`. Make each repair from its guidance, and run the command again until it exits 0 with complete applicable coverage and no disabled checks.
+3. Run the project's Svelte check and its build.
+4. Reply with the files, the component id, the props, and the result of each check, naming any check the environment prevented.
 
 `--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.
 

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

@@ -152,10 +152,71 @@ Each obligation and what it needs from the project:
   to under it.
 - `interaction`: the interactive part's role and its cases. `applicable:
   false` for a component with no interactive role.
+- `behavior`: what a callback prop does. See Behavior below.
 - `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.
 
+## Behavior
+
+`behavior` runs under Vitest with `mount` from Svelte and happy-dom, not in
+the editor preview, because a controlled component's callback prop has
+nothing driving it there: the preview edits the token, not the prop. One
+case names the props the runtime mounts with, the action a user takes, and
+what that should do.
+
+```ts
+behavior: {
+  cases: [
+    {
+      name: 'clicking an off toggle asks for on',
+      props: { checked: false },
+      action: { kind: 'click', part: 'root' },
+      expect: { kind: 'callback', prop: 'onchange', args: [true] },
+    },
+    {
+      name: 'clicking leaves the switch where the prop put it',
+      props: { checked: false },
+      action: { kind: 'click', part: 'root' },
+      expect: { kind: 'attribute', part: 'root', name: 'aria-checked', value: 'false' },
+    },
+    {
+      name: 'checked drives aria-checked',
+      props: { checked: true },
+      expect: { kind: 'attribute', part: 'root', name: 'aria-checked', value: 'true' },
+    },
+    {
+      name: 'a disabled toggle stays silent',
+      props: { checked: false, disabled: true },
+      action: { kind: 'click', part: 'root' },
+      expect: { kind: 'no-callback', prop: 'onchange' },
+    },
+  ],
+},
+```
+
+Toggle is controlled: it never flips `checked` itself, so the click case
+that asks for `on` and the mount case that reads `checked` are two separate
+cases, not one. The disabled case pins that a disabled toggle calls nothing
+back: the prop reaches the DOM as a real `disabled` attribute on the part,
+and happy-dom withholds a dispatched click from a disabled `<button>`. A
+component that reports through `input` rather than `click`, such as Slider,
+gets no disabled case, because happy-dom delivers a dispatched `input` event
+to a disabled control and the case would assert the environment rather than
+the component.
+
+A component with no callback prop declares the obligation inapplicable, in
+one line:
+
+```ts
+behavior: { applicable: false, reason: 'a table wrapper declares no callback prop; its rows arrive as a snippet' },
+```
+
+The fault this suite catches is a callback that fires with the wrong
+argument, fires when a case says it should stay silent, or never fires at
+all. `check-component <id> --tests` reports it as `contract-behavior`,
+naming the case.
+
 ## Running vitest yourself
 
 `check-component --tests` covers the shipped path. Run vitest directly only

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

@@ -138,8 +138,8 @@ Make the rule an element, give it `sketch-rule`, and name its ink as the fill.
 ```css
 .mywidget-rule {
   height: var(--border-width-2);
-  background: var(--mywidget-divider);
-  --sketch-fill: var(--mywidget-divider);
+  background: var(--mywidget-hairline-color);
+  --sketch-fill: var(--mywidget-hairline-color);
 }
 ```
 

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

@@ -17,15 +17,12 @@ to that list, so the two cannot drift apart.
 | `-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           |
+| `-color`    | A hairline rule's colour, or a color no role word above names |
 | `-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                                |
+| `-indicator` | The colour of the bar or stripe that marks an item             |
 | `-thumb`    | A scrollbar or slider thumb's colour                           |
 | `-title`    | Title text colour                                              |
 | `-body`     | Body text colour                                               |
@@ -42,21 +39,15 @@ to that list, so the two cannot drift apart.
 |-----------------|---------------------------------------------------------------|
 | `-radius`       | Corner radius                                                 |
 | `-border-width` | Stroke thickness (used even when CSS uses `outline:`)         |
-| `-thickness`    | Alternative to `-width` when fallback siblings would collide  |
-| `-accent-width` | An accent bar's thickness                                     |
-| `-indicator-width` | An indicator's thickness, moved with `-accent-width`      |
-| `-hairline-thickness` | A hairline rule's thickness                             |
+| `-indicator-width` | An indicator's thickness                                  |
+| `-hairline-width` | 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                       |
+| `-hairline-inset` | Inset trimmed from a stretched hairline                     |
 | `-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                                      |
@@ -67,7 +58,7 @@ to that list, so the two cannot drift apart.
 
 `-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`,
+picker `-gap` uses, and they match last, so `-border-width`, `-hairline-width`,
 `-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:`.
 

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

@@ -17,8 +17,8 @@ Assemble the page from the shipped components at their defaults and the theme's
 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.
+9. Run `npx live-tokens check-page <file> --tests --strict --json` until it exits 0, then check the rendered page.
+10. Reply with the sections and the layout each took, the components placed, the route, and the check-page result.
 
 ## Layout
 
@@ -85,7 +85,7 @@ Show related items side by side when the width permits. A line of copy runs 45 t
 ## 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.
+- `npx live-tokens components <id>` prints the declared props, the values each union accepts, and the catalogue entry. `--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.
@@ -165,7 +165,9 @@ const pages = {
 
 ## 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.
+Run `npx live-tokens check-page <file> --tests --strict --json`. It applies every `auto` repair, runs the Playwright suite against the page's own route, and returns the fixes it applied and the findings that remain. The suite 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. `--off=<rule>` silences a rule for one run, and `--no-fix` reports without editing.
+
+Each remaining finding carries a rule id, a line, and its `guidance`. Make each remaining repair from its guidance, and run the command again until it exits 0.
 
 The checkers cannot see a layout. Open the page at the width it is built for and check each line below.
 

package/.claude/skills/live-tokens-create-theme/references/design-directions.md

@@ -88,7 +88,7 @@ rather than only on the buttons.
 | 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 |
+| Ocean | blues held to one narrow range |
 | 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 |

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

@@ -9,7 +9,7 @@ When more than one shipped component could fit, find the family below that names
 
 ## 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.
+Before choosing, run `npx live-tokens components`. The list holds every component the project has, shipped and custom, with each one's variants and catalogue entry. The family tests below name the shipped set only. Weigh a custom component by the same tests.
 
 ## Action family
 
@@ -38,7 +38,7 @@ 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"`.
+- A number where the position on a track carries the meaning (a volume, a price range, a percentage): `Slider`. A number the reader knows and would rather type: `Input` with `type="number"`.
 
 ## On and off
 
@@ -93,4 +93,4 @@ Each pair holds a block the reader views and one the reader interacts with. The
 
 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.
+`npx live-tokens components <id>` prints one component's catalogue entry, its declared props, and the values each union accepts. `--json` returns the same as data.

package/.claude/skills/live-tokens-set-colors/references/color-anchors.md

@@ -1,7 +1,7 @@
 # Color anchors: feelings, idioms, and occasions
 
 Read this when the color intent names one of these. Entries are starting
-points: apply the chroma budget, the per-role bands, and the canvas commitment
+points: apply the chroma budget, the per-role ranges, and the canvas commitment
 rules from SKILL.md on top of them.
 
 An idiom sets constraints and overrides the generic defaults in SKILL.md. The

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

@@ -37,7 +37,7 @@ Targeted, absolute:
 ```
 
 - `target` (optional): a component id, one of the folder names under `src/live-tokens/data/component-configs/`. "Windows" or "modals" is `dialog`, "cards" is `card`, "tabs" is `tabbar`. "The UI", "everything", or no noun means global, so omit `target`.
-- `kind`: `radius | padding | gap | border-width | divider-width | accent-width`. `border-width` moves `-border-width` aliases. `divider-width` moves dividers, hairline rules, and `-thickness` aliases. `accent-width` moves accent bars and indicators.
+- `kind`: `radius | padding | gap | border-width | hairline-width | indicator-width`. `border-width` moves `-border-width` aliases. `hairline-width` moves `-hairline-width` aliases. `indicator-width` moves the bar or stripe an indicator draws.
 - `set` or `shift`, one of the two. `set` takes a token on that kind's scale. `shift` is a whole number of steps and stops at the ends of the scale.
 - `full` (radius shifts only): admits `--radius-full` as the top of the scale. A pill request is `set: "--radius-full"` with no `full` flag.
 

package/.claude/skills/live-tokens-set-geometry/references/geometry-anchors.md

@@ -7,7 +7,7 @@ came from, and a style's geometry is often targeted rather than global.
 Entries are written in the ops vocabulary. "radius +2" is a radius shift of 2.
 "borders +1" is a border-width shift of 1. "padding +1" is a padding and gap
 shift of 1. "hairline borders" is border-width `set: "--border-width-1"`, and
-"no borders" is `set: "--border-width-0"`. "hairline rules" is divider-width
+"no borders" is `set: "--border-width-0"`. "hairline rules" is hairline-width
 `set: "--border-width-1"`. A named component means a targeted op. Controls squeeze before containers,
 so a compaction of more than one step still spends its extra steps on
 containers by name.