@motion-proto/live-tokens 0.73.0 → 0.75.0

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

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

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

@@ -0,0 +1,196 @@
+app---
+name: live-tokens-create-component
+description: Create a custom Svelte component in a @motion-proto/live-tokens project with semantic properties that reference the existing theme tokens, a live editor, and registration. Use for a new component or to make an existing component editable. Use live-tokens-create-page to place existing components on a page.
+---
+
+# Creating a Live Tokens component
+
+Create a component whose structure and behavior serve the user's purpose. Give each editable visual property a semantic name and assign its default from the design system's existing token vocabulary. Deliver the runtime component, its editor, and its registration together.
+
+## Design model
+
+Live Tokens has two token layers:
+
+| Layer | Responsibility | Example |
+|---|---|---|
+| Theme tokens | Define the available colors, typography, geometry, and motion values. Theme presets change these values. | `--space-16`, `--radius-md`, `--surface-neutral` |
+| Component properties | Name the visual roles within a component and reference theme tokens. Component presets record these assignments. | `--statcard-frame-padding: var(--space-16)` |
+
+The rendering chain is **theme token → semantic component property → CSS declaration**. The editor changes the assignment; the runtime reads the property. Keep the assignment as a token reference so a theme change reaches the component.
+
+A property describes its purpose: `--statcard-value-text`, `--statcard-frame-radius`, `--statcard-label-font-size`. Its name stays stable when its assigned color or size changes. Use role names such as `surface` and `text`, and full words for component ids and parts.
+
+Build distinct components through their anatomy, proportions, content hierarchy, behavior, and choice of existing tokens. Create only the variants and states the task requires. Keep the theme vocabulary intact during component creation; a new theme token belongs in a separate theme change.
+
+Component props carry content and behavior, such as `value`, `label`, `selected`, and callbacks. Semantic CSS properties carry the editable appearance. Expose variants through props when they represent meaningful component choices.
+
+## Source inspection
+
+Read the project's `package.json`, `live-tokens.config.json`, and application bootstrap before writing files. Run `npx live-tokens components` to inspect the catalogue and `npx live-tokens components <id>` for a candidate's props. Use an existing component when it fulfills the request; create a new component when the request needs distinct structure or behavior.
+
+Locate the installed package at `node_modules/@motion-proto/live-tokens`. When working inside the Live Tokens repository, use the repository root instead. Read these sources from that root:
+
+- `src/system/styles/tokens.css` for the available default tokens, and the project's theme files for overrides. Treat `tokens.generated.css` as generated output.
+- `src/system/components/<Name>.svelte` and `src/editor/component-editor/<Name>Editor.svelte` for a matching runtime/editor pair. Use `Toggle` for interaction states, `Badge` for variants and linking, and `Card` for separate text and container parts.
+- `src/editor/core/components/aliasKinds.ts` for the suffixes that select editor controls.
+- `src/editor/component-editor/index.ts` and the package exports for available authoring APIs.
+
+Use the current source as the contract when older prose differs. For example, the current brand color family uses `--surface-brand`, `--border-brand`, and `--text-brand`; `--text-primary` names neutral primary text.
+
+Read [references/token-naming.md](references/token-naming.md) when choosing property suffixes. Read the other references at the steps that need them.
+
+## Property design
+
+Before implementation, identify the component's parts, text roles, variants, and states. Make a short property map that connects each editable role to an existing default token and the CSS property it controls. Keep separate roles independent even when they start with the same value.
+
+| Component property | Default assignment | CSS use |
+|---|---|---|
+| `--statcard-frame-surface` | `--surface-neutral` | `background` |
+| `--statcard-frame-border` | `--border-neutral` | `border-color` |
+| `--statcard-frame-border-width` | `--border-width-1` | `border-width` |
+| `--statcard-frame-radius` | `--radius-md` | `border-radius` |
+| `--statcard-frame-padding` | `--space-16` | `padding` |
+| `--statcard-value-text` | `--text-primary` | `color` |
+| `--statcard-label-text` | `--text-secondary` | `color` |
+
+Choose defaults from tokens that exist in the target project. Prefer the color role that matches the purpose: surfaces for fills, borders for outlines, and text tokens for text. Select geometry from the relevant spacing, radius, stroke, and icon scales. Give each text role its own family, size, weight, line height, and letter spacing properties, using existing typography tokens.
+
+Name properties with the component id first and the property suffix last:
+
+```text
+--<componentId>-<part-or-variant>[-<state>][-<element>]-<property>
+```
+
+Use a lowercase id with no dashes that matches the runtime filename: `StatCard.svelte` has id `statcard`. Include the segments that distinguish the role. Follow the closest shipped component for components with both variants and parts. Put state segments before the final property: `--statcard-frame-hover-surface`.
+
+The suffix selects the editor control. Use `-surface` for a fill, `-border` for border color, `-border-width` for stroke thickness, `-radius` for corners, and `-padding` or `-gap` for spacing. Use the full typography suffixes such as `-font-size`. Verify other suffixes against `aliasKinds.ts`.
+
+## Runtime component
+
+Create `src/system/components/StatCard.svelte`. Use Svelte 5 props and snippets, semantic HTML, and the behavior the task requires. Start with a short HTML comment that states the component's purpose, suitable uses, and an alternative for uses outside its scope. The component CLI reads this comment and `interface Props` to describe the component.
+
+Declare every editable property explicitly in a literal `:global(:root)` block. The discovery parser reads the Svelte source to seed `component-configs/<id>/default.json`; it needs concrete property names. Keep SCSS loops and interpolation out of this declaration block.
+
+```svelte
+<style>
+  :global(:root) {
+    --statcard-frame-surface: var(--surface-neutral);
+    --statcard-frame-border: var(--border-neutral);
+    --statcard-frame-border-width: var(--border-width-1);
+    --statcard-frame-radius: var(--radius-md);
+    --statcard-frame-padding: var(--space-16);
+    --statcard-value-text: var(--text-primary);
+    --statcard-label-text: var(--text-secondary);
+  }
+
+  .statcard {
+    display: grid;
+    background: var(--statcard-frame-surface);
+    border: var(--statcard-frame-border-width) solid var(--statcard-frame-border);
+    border-radius: var(--statcard-frame-radius);
+    padding: var(--statcard-frame-padding);
+  }
+
+  .value { color: var(--statcard-value-text); }
+  .label { color: var(--statcard-label-text); }
+</style>
+```
+
+This excerpt shows the assignment chain. Add typography, spacing, and other properties from the component's actual property map.
+
+Route editable styling through component properties. Keep structural CSS such as `display: grid`, `width: 100%`, and `align-items: center` in the component's layout rules. Use token references for visual defaults. A token expression such as `calc(var(--space-64) * 4)` can express a dimension beyond the scale when the component needs it; prefer a direct assignment when a preset value fits.
+
+For persistent structural choices such as alignment or visibility, read [references/intrinsics.md](references/intrinsics.md). Declare an `IntrinsicSpec`, mirror its default in `:global(:root)`, and register it through the `intrinsics` field. Keep these choices outside `allTokens`.
+
+## Variants and states
+
+Parts coexist, variants provide alternative presentations, and states reflect runtime conditions. Preserve those distinctions in both the component API and the editor.
+
+Use the default state for shared geometry and typography. Add state properties for the values that change. Follow `Toggle` for a component state such as `on` with an interaction state such as `hover`. Live Tokens treats `disabled` as terminal: its editor fieldset is flat, and its tokens carry no combined hover or selected state.
+
+Make the preview render the state whose properties the user edits. Pair each hover selector with a `.force-hover` selector and expose a class prop so the editor can show hover without a pointer. Preserve native disabled behavior, keyboard operation, and visible focus for interactive controls.
+
+For action emphasis, use `primary` for the single action that completes the page's main task, `secondary` for supporting or directly related actions, and `outline` for unrelated or informational actions. Use `danger` for actions that destroy saved work. The page chooses the one primary action; a component supplies the relevant variants.
+
+## Component editor
+
+Create `src/system/components/StatCardEditor.svelte` beside the custom runtime file. Shipped editors use a separate internal directory; custom components keep both files together.
+
+In `<script module lang="ts">`, declare `const component = 'statcard'`, define the token lists, and export their flat union as `allTokens: Token[]`. Each editable runtime property has one schema entry with the exact variable name. Use `element` to group rows by part and a short `label` to name the property.
+
+```ts
+import type { Token } from '@motion-proto/live-tokens/component-editor';
+
+const component = 'statcard';
+const states: Record<string, Token[]> = {
+  default: [
+    { label: 'surface', element: 'frame', variable: '--statcard-frame-surface' },
+    { label: 'padding', element: 'frame', variable: '--statcard-frame-padding' },
+    { label: 'text', element: 'value', variable: '--statcard-value-text' },
+    { label: 'text', element: 'label', variable: '--statcard-label-text' },
+  ],
+};
+export const allTokens: Token[] = Object.values(states).flat();
+```
+
+Expand this illustrative schema to cover the full property map. In the instance script, import the runtime component and the editor primitives. Mount `ComponentEditorBase` with `component` and `tokens={allTokens}`, then a `VariantGroup` for each variant with its `states`, `component`, and runtime preview. Follow the matching shipped editor for the exact snippet API.
+
+Use public imports in consumer projects:
+
+```ts
+import { ComponentEditorBase, VariantGroup } from '@motion-proto/live-tokens/component-editor';
+import StatCard from './StatCard.svelte';
+```
+
+Read shipped source files for examples; import package APIs through their public exports. Use `--ui-*` tokens for custom editor chrome and let the runtime preview consume the theme through its component properties.
+
+When variants should share properties, read [references/linked-siblings.md](references/linked-siblings.md). Declare intentional sibling sets with `groupKey`, enable the linked controls with `canBeLinked`, and wire the linked block using the shipped helpers. Scope keys to the role: `value-font-size` and `label-font-size` stay independent. When using `buildTypeGroup*` helpers, pass `{ component, variants }` so they derive keys for each slot.
+
+## Registration and persistence
+
+Add the custom component to the existing `bootLiveTokens` call, preserving the project's other registrations and setup:
+
+```ts
+import StatCardEditor, { allTokens as statCardTokens } from './system/components/StatCardEditor.svelte';
+
+bootLiveTokens(App, '#app', {
+  components: [{
+    id: 'statcard',
+    label: 'Stat Card',
+    icon: 'fas fa-chart-simple',
+    sourceFile: 'src/system/components/StatCard.svelte',
+    editorComponent: StatCardEditor,
+    schema: statCardTokens,
+  }],
+});
+```
+
+`bootLiveTokens` registers components after editor initialization and before theme initialization. Use that registration window. For a manual bootstrap, follow the package initialization order and register before mounting the app. Choose a unique id so the registration preserves built-in entries.
+
+The runtime root declarations supply the initial assignments. The plugin derives `default.json`; editor saves write `_working.json`, and Save As creates a named preset. Preserve token references through this flow. Verify the project's configured data path rather than creating a second persistence mechanism.
+
+For a first-party addition inside the Live Tokens package, follow the internal layout instead: runtime in `src/system/components`, editor in `src/editor/component-editor`, and an entry in `builtInRegistry` in `src/editor/component-editor/registry.ts`. Update the built-in id union and catalogue through the repository's existing conventions.
+
+## Rendering integration
+
+Read [references/sketch-mode.md](references/sketch-mode.md) and integrate the component's painted parts with Sketch mode. Custom components use the reserved sketch classes and bind the sketch properties to their own semantic properties. Choose a wrapper that accommodates the layer's positioning, overflow, and pseudo-element requirements. First-party components add the corresponding `PartSpec` entries.
+
+For a fixed overlay, read [references/fixed-overlays.md](references/fixed-overlays.md) and portal the layer to `body`. Follow the existing container pattern when the component owns typography inside a content snippet.
+
+## Verification
+
+Run `npx live-tokens check-component <id> --strict --json`. Inside the package repository, use `node bin/cli.mjs check-component <id> --strict --json`. Resolve findings and rerun until the command passes. Run the project's Svelte checks and the build or tests that cover the new behavior.
+
+Read [references/contract-tests.md](references/contract-tests.md) and verify the registry entry with `checkRegistryEntry`. The contract checks registration, unique schema variables, runtime declarations, seeded defaults, and alias round trips. Include intrinsic checks when the component declares intrinsics.
+
+Open `/live-tokens/components` and verify:
+
+- The component appears under Custom, or among system components for a first-party addition.
+- Each property has the correct editor control and changes the matching runtime part.
+- Preview variants and states match the controls; keyboard and pointer behavior work.
+- Linked properties change together, and separate roles remain independent.
+- Save and reload retain assignments. Reset restores runtime defaults.
+- Theme changes reach every property that references a theme token.
+- Sketch mode renders each painted part correctly and restores the normal appearance when switched off.
+
+Report the files, component id, available props, and verification results. State any checks the environment prevented you from running.