@motion-proto/live-tokens 0.72.0 → 0.73.0

package/.claude/skills/live-tokens-fix-findings/SKILL.md

@@ -3,73 +3,36 @@ name: live-tokens-fix-findings
 description: Bring an existing @motion-proto/live-tokens project into line with its design system by running check-page and check-component, reading the findings, and fixing each by rule until both exit 0. Use when the user asks to make the build pass, fix the design-system errors or warnings, clean up the literals, replace hex or pixel values with tokens, make a page or component themeable, or apply what a check reported. Not for the check itself (live-tokens-check-compliance reports and edits nothing), not for building a new page (live-tokens-build-page) or a new component (live-tokens-create-component), which run the same gate as their last step, and not for a single token edit (use the editor).
 ---
 
-# Fixing what the checkers report
-
-Two checkers hold a project to its design system. `check-page` holds pages:
-every component comes from the catalogue and is passed only the props it
-declares, and every value in page CSS is a theme token. `check-component`
-holds authored components: every token names a semantic property and its
-default is the theme token that property reads. A page or component that
-passes repaints when the theme changes. One that does not has opted out of the
-system silently, and these findings are where.
-
-This skill is the loop for code that already exists. Run the checker, fix one
-rule at a time, run it again, and stop only when both exit 0. When the user has
-not seen the state of the project yet, `npx live-tokens report --json` is the
-reading to start from, and **live-tokens-check-compliance** is the skill that
-presents it without editing; this one edits.
-
-## Reach the checkers
-
-```sh
-npx live-tokens check-page --json           # every page under src/
-npx live-tokens check-component --json      # every component authored under src/system/components
-```
-
-- **Unknown command.** The installed package predates the checkers. Upgrade
-  `@motion-proto/live-tokens`, then run `npx live-tokens migrate --check` and
-  apply what it plans with `--write`; `--tokens <path>` names a tokens.css that
-  sits somewhere other than the four default locations.
-- **No `check:design` script.** A project scaffolded by `create` has one. Add
-  it to any other project's `package.json`:
-  `"check:design": "live-tokens check-page && live-tokens check-component"`.
-  Once it passes, gate the build: `"build": "npm run check:design && vite build"`.
-- **A file, not the project.** `check-page src/pages/Home.svelte` and
-  `check-component <id>` scope a run when the user names one thing.
-
-## The loop
-
-1. Run with `--json`. Each finding carries a stable `rule`, a file, and a line.
-2. Group by rule. Take errors before warnings, and the rule with the most
-   findings first, because one recipe clears the whole group.
-3. Apply that rule's recipe, below, to every finding in the group.
-4. Run again. New findings can appear as old ones clear: a token you reached
-   for may not exist, or a moved import may land somewhere the rule now sees.
-5. Stop at exit 0. Then run once with `--strict` and report what it adds, so
-   the user can decide whether warnings are worth clearing now.
-
-Three things the loop never does:
-
-- **Silence a rule to pass.** `--off=<rule>` is for a single run while
-  working. A severity the project wants changed goes in
-  `live-tokens.config.json` under `"checks": { "rules": { "<rule>": "warn" } }`,
-  with the reason in the commit, and only when the user has made that call.
-- **Mint a token.** A literal with no token behind it is remapped to the
-  nearest existing token by role. No new `--surface-*`, `--text-*`, or
-  `--space-*` is added to `tokens.css` to match a value the page happened to
-  use. If nothing fits, say so and leave the finding.
-- **Change what the page looks like without saying so.** Most remaps land on
-  the same value. When the nearest token differs, `14px` to `--space-16` or a
-  55% black to `--scrim`, name the shift in the report.
+# Fixing the checkers' findings
+
+Two checkers hold a project to its design system. `check-page` holds pages: every component comes from the catalogue and is passed only the props it declares, and every value in page CSS is a theme token. `check-component` holds authored components: every token names a semantic property and its default is the theme token that property reads. A page or component that passes repaints when the theme changes. One that fails has opted out of the system silently, and its findings say where.
+
+This skill is the loop for code that already exists. When the user has not seen the state of the project yet, **live-tokens-check-compliance** presents `npx live-tokens report` without editing; this skill edits.
+
+## Workflow
+
+1. Run both checkers with `--json`. Each finding carries a stable `rule`, a file, and a line.
+   ```sh
+   npx live-tokens check-page --json           # every page under src/
+   npx live-tokens check-component --json      # every component authored under src/system/components
+   ```
+   `check-page src/pages/Home.svelte` and `check-component <id>` scope a run when the user names one thing. Unknown command means the installed package predates the checkers: upgrade `@motion-proto/live-tokens`, then run `npx live-tokens migrate --check` and apply what it plans with `--write` (`--tokens <path>` for a tokens.css outside the four default locations).
+2. Group by rule. Take errors before warnings, and the rule with the most findings first, because one recipe clears the whole group.
+3. Apply that rule's recipe to every finding in the group: colour by role, geometry by scale, or the row in the table below. A component outside the catalogue hands off to **live-tokens-pick-component** for the shipped one that fits, or to **live-tokens-create-component**.
+4. Run again. New findings can appear as old ones clear: a token you reached for may not exist, or a moved import may land where a rule now sees it. Stop at exit 0.
+5. Run once with `--strict` and report what it adds, so the user can decide whether warnings are worth clearing now. Then report by rule.
+
+A project scaffolded by `create` has a `check:design` script. Give any other project one in `package.json`, `"check:design": "live-tokens check-page && live-tokens check-component"`, and once it passes, gate the build: `"build": "npm run check:design && vite build"`.
+
+## Three things the loop never does
+
+- **Silence a rule to pass.** `--off=<rule>` is for a single run while working. A severity the project wants changed goes in `live-tokens.config.json` under `"checks": { "rules": { "<rule>": "warn" } }`, with the reason in the commit, and only when the user has made that call.
+- **Mint a token.** A literal with no token behind it is remapped to the nearest existing token by role. No new `--surface-*`, `--text-*`, or `--space-*` is added to `tokens.css` to match a value the page happened to use. If nothing fits, say so and leave the finding.
+- **Change what the page looks like without saying so.** Most remaps land on the same value. When the nearest token differs, `14px` to `--space-16` or a 55% black to `--scrim`, name the shift in the report.
 
 ## Colour by role, never by hue
 
-`color-literal` is the finding that takes judgement. The replacement is the
-token for what the colour *does*, not the token that happens to be closest in
-hue, because the theme will move every role together and the page must move
-with it. `npx live-tokens tokens --family surface` prints a family's names and
-values (`text`, `border`, `scrim`, `tint` likewise; `--json` for data); the
-families are fixed.
+`color-literal` is the finding that takes judgement. The replacement is the token for what the colour *does*, not the token nearest in hue, because the theme moves every role together and the page must move with it. `npx live-tokens tokens --family surface` prints a family's names and values (`text`, `border`, `scrim`, `tint` likewise; `--json` for data); the families are fixed.
 
 | The literal is | Token family | Notes |
 | --- | --- | --- |
@@ -82,15 +45,11 @@ families are fixed.
 | Fully transparent | `--color-transparent` | Never `transparent` inside a component default. |
 | A gradient | `--gradient-*` | Or compose one from surface tokens. |
 
-A `var(--x, #fff)` fallback is not a finding. A named colour is: `white` and
-`rebeccapurple` are literals like any hex.
+A `var(--x, #fff)` fallback is not a finding. A named colour is: `white` and `rebeccapurple` are literals like any hex.
 
 ## Geometry by scale
 
-`dimension-literal` fires only on the geometry the theme owns: padding,
-margin, gap, border and outline widths, inset offsets, radius, and shadow.
-Sizing (a hero's height, a max content width, a `minmax()` floor) is layout
-and is never reported, so leave it.
+`dimension-literal` fires only on the geometry the theme owns: padding, margin, gap, border and outline widths, inset offsets, radius, and shadow. Sizing (a hero's height, a max content width, a `minmax()` floor) is layout and is never reported, so leave it.
 
 | The literal is | Token | Notes |
 | --- | --- | --- |
@@ -100,8 +59,7 @@ and is never reported, so leave it.
 | A shadow | `--shadow-sm` through `-xl` | Replace the whole value, never one offset. |
 | Part of a `calc()` | The token inside the calc | `calc(var(--space-64) * -2 + var(--space-8))` |
 
-While in the file, motion values take `--duration-*` and `--ease-*` even
-though no rule reports them, and a `blur()` takes `--blur-*`.
+While in the file, motion values take `--duration-*` and `--ease-*` even though no rule reports them, and a `blur()` takes `--blur-*`.
 
 ## Every other rule
 
@@ -120,17 +78,12 @@ though no rule reports them, and a `blur()` takes `--blur-*`.
 | `unknown-suffix`, `state-after-property`, `disabled-is-terminal` | Rename the token. Borrow the name a shipped component uses for the same role; the vocabulary and the state model are in **live-tokens-create-component**. |
 | `color-literal`, `unknown-token-ref`, `default-not-token` (component) | The `:global(:root)` default reads a theme token, composed if needed. A structural keyword (`start`, `contain`) is declared in the editor's `intrinsics`. |
 | `phantom-editor-token`, `phantom-link` | The editor names a token the runtime never declares, or a bare font helper spans slots. Both are editor fixes; see the same skill. |
-| `missing-registration`, `missing-file`, `missing-root-block` | The component is not wired the way the recipe in **live-tokens-create-component** wires it. |
+| `invalid-id`, `missing-file`, `missing-root-block`, `no-tokens`, `missing-component-const`, `missing-all-tokens`, `missing-registration` | The component is not wired the way the recipe in **live-tokens-create-component** wires it: a lowercase id, a runtime file with a `:global(:root)` block, an editor file exporting `component` and `allTokens`, and a `bootLiveTokens` entry. |
 
 ## Report
 
-Say what changed by rule, one line per rule with the count and any visible
-shift. Say what was left and why, with the config entry if the user chose to
-lower a severity. End with the two commands and their exit codes.
+Say what changed by rule, one line per rule with the count and any visible shift. Say what was left and why, with the config entry if the user chose to lower a severity. End with the two commands and their exit codes.
 
 ## Verify
 
-Open `/live-tokens/editor` in dev and change a surface colour and a spacing
-step. Every file the loop touched should repaint. One that does not still
-holds a literal the checker cannot see, which is worth reporting as a gap in
-the checker rather than patching around.
+Open `/live-tokens/editor` in dev and change a surface colour and a spacing step. Every file the loop touched should repaint. One that does not still holds a literal the checker cannot see, which is worth reporting as a gap in the checker rather than patching around.

package/.claude/skills/live-tokens-generate-theme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: live-tokens-generate-theme
-description: Generate a complete live-tokens theme — color, type, and geometry — from a natural-language brief, delegating the type and geometry halves to its sibling skills. Use whenever the user asks for a theme, look, vibe, brand feel, color scheme, or palette by mood, style, era, season, holiday, or hue; when they name only a color (something red-based, green and gold for St. Patrick's Day); or when they refine an existing theme (warmer, more contrast, calmer). Examples: bright and cheerful, dark and moody, brutalist, mid-century modern, Swiss and minimal, cyberpunk neon, editorial magazine, make it feel like a terminal. Not for a single token (use the editor), type alone (live-tokens-pair-fonts), or geometry alone (live-tokens-adjust-geometry).
+description: Generate a complete live-tokens theme (color, type, and geometry) from a natural-language brief, delegating the type and geometry halves to its sibling skills. Use whenever the user asks for a theme, look, vibe, brand feel, color scheme, or palette by mood, style, era, season, holiday, or hue; when they name only a color (something red-based, green and gold for St. Patrick's Day); or when they refine an existing theme (warmer, more contrast, calmer). Examples: bright and cheerful, dark and moody, brutalist, mid-century modern, Swiss and minimal, cyberpunk neon, editorial magazine, make it feel like a terminal. Not for a single token (use the editor), type alone (live-tokens-pair-fonts), or geometry alone (live-tokens-adjust-geometry).
 ---
 
 # Generating a theme from a brief
@@ -145,7 +145,7 @@ This table is the fallback. When the brief matched an entry in the mood or style
 
 One adjective moves one dial. Warmer and cooler rotate hue; calmer and louder move chroma; lighter, darker, and moodier move Canvas L and the scheme; more contrast widens the L gap between Canvas and Brand and takes chroma out of the ground rather than adding it to the garnish. Leave every seed the user did not name alone, because a refinement that re-rolls the whole palette reads as a different theme and loses the thing they liked.
 
-## What each step writes
+## Files each step writes
 
 Color writes `themes/<slug>.json` and opens it. Type and geometry write the unsaved buffers, which the page already runs. One Save in the editor keeps all three; Adopt ships them. Component aliases and gradients carry forward from the live look into a generated theme; user-tuned gradients survive, stock ones rebuild from the new families.
 

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

@@ -39,7 +39,7 @@ All four pick one option from a set. The right one depends on **option count**,
 | `SegmentedControl`| Inline switch between alternative *views of the same data*              | Compact pill     | 2–4          |
 | `TabBar`          | Switching between *tab panels* (content area swaps below)               | Page-section     | 2–7          |
 | `RadioButton`     | Form-style selection where the user reviews all options as text         | Form-row         | Any          |
-| `MenuSelect`      | Hide the option set behind a dropdown to save vertical/horizontal space | Compact dropdown | Any          |
+| `MenuSelect`      | A list of options, one checked; renders open, so a dropdown toggles it from a `Button` | Open list        | Any          |
 
 - `TabBar` implies "this changes the page"; `SegmentedControl` implies "this is one knob among others."
 - Use `RadioButton` when labels deserve room to breathe and the user is committing to a larger form.
@@ -63,7 +63,7 @@ All four pick one option from a set. The right one depends on **option count**,
 | `Dialog`              | Modal, blocks page  | Confirmations, focused tasks the page can't continue around |
 | `Panel`               | Inline, fixed stage | A demo or preview surface whose height must not reflow     |
 
-- Default to `Card`. It's the workhorse. For full-bleed media — cover art, a poster, a chart that reaches its own border — pass `flush` (with `prose={false}`) rather than zeroing its padding tokens from the page.
+- Default to `Card`. It's the workhorse. For full-bleed media (cover art, a poster, a chart that reaches its own border) pass `flush` (with `prose={false}`) rather than zeroing its padding tokens from the page.
 - Reach for `CollapsibleSection` only when the content is *legitimately secondary* (advanced users open it; most skip). Don't use collapse as a styling choice when the content matters.
 - `Panel` is a stage, not a content container. It pins its own height so what it shows can resize without moving the page, which is what a component preview or a live example needs and what article content does not. Content goes in `Card`.
 - **Don't use `Dialog` for routine forms.** Reach for it only when the page cannot meaningfully continue until the user decides (destructive confirmations, payment, sign-in). Routine forms go inline in a `Card`.
@@ -83,7 +83,7 @@ All four pick one option from a set. The right one depends on **option count**,
 - `Tooltip` is for *what an element means*. **Don't use `Tooltip` as the primary location of important content;** it auto-dismisses and isn't accessible for must-read content.
 - `Badge` and `CornerBadge` differ only in positioning. `CornerBadge` lives at a `top-right` / `bottom-left` anchor on a parent (notification counts, "NEW" stickers).
 
-## Display family: what the page shows rather than what it asks
+## Display family: shown, not asked
 
 - `Image` frames a picture in the flow at one of four sizes, with an optional hover zoom. It is the default for any picture the page simply shows.
 - `ImageLightbox` adds click-to-open at full size and takes an array for a gallery. Use it when the detail is the point (screenshots, artwork, charts that need reading), and not for decoration: it puts a modal behind every picture it wraps.
@@ -108,4 +108,4 @@ All three can express a binary choice. The right one depends on what the choice
 
 ---
 
-If nothing in the catalogue fits (a `Slider`, a `DatePicker`, a `Stepper`, a custom widget), author it via **live-tokens-create-component**. **Don't reach for a custom component before checking the catalogue;** a custom component is a maintenance commitment.
+If nothing in the catalogue fits (a `DatePicker`, a `Stepper`, a custom widget), author it via **live-tokens-create-component**. **Don't reach for a custom component before checking the catalogue;** a custom component is a maintenance commitment.

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## 0.73.0 — The skill atlas ships from the package
+
+### Added
+
+- **A public export for the skill atlas, `@motion-proto/live-tokens/skill-atlas`.**
+  The atlas is a Svelte component that diagrams the reasoning tree behind each
+  bundled skill, with the source `SKILL.md` and its reference files alongside
+  so a reader can see which lines drive which step. It carries no route of its
+  own; a consumer mounts it wherever it likes. `live-tokens-online` is its
+  first consumer, mounting it at its existing `/skills` route. Skill text
+  reaches the component through a generated module built from `.claude/skills`
+  and gated by `check:skill-sources`; the trees each carry a digest of the
+  `SKILL.md` they cite and are gated by `check:skill-atlas`. Both run in
+  `prepublishOnly`.
+
+### Changed
+
+- **`live-tokens-build-page` lays out the page before it places columns.**
+  The Layout section opens with bands: name each by its job, put a tool
+  page's stage on top and its toolbar along the bottom edge, separate bands
+  with space and a rule, and stretch a band's boxes to one height. Two new
+  subsections follow. *Containers by job* says what `Panel`, `Card`, a bare
+  compact `Card` with its own text-style label, and a toolbar are each for,
+  and that a card header is typed by the card's own tokens at 2xl. *Density*
+  covers `size="small"` in toolbars and compose rows, forwarding `size` from
+  a project component, text inside a card body inheriting the card's size,
+  and toggling `MenuSelect` from a `Button`. Verify now asks for a look at
+  the page band by band, since the checker cannot see a layout. The gap
+  came from a studio page whose card headers, buttons, and inherited body
+  text all ran large with every check green; `docs/build-page-gap-analysis.md`
+  records it.
+
+- **`live-tokens-build-page` opens Layout with the laws behind its rules.**
+  A short block before the bands states what a layout is for: the page
+  shows one thing, each mark that is not content must do a job no other mark does,
+  separate with the smallest difference that separates (space, then a
+  hairline rule, then a second surface), rank content, labels, and
+  scaffolding on their own tokens, show related items side by side, and
+  give a tool page's space to the stage. Verify adds a look from a distance,
+  a removal question for each border and header bar, and a check of the
+  reading order. The laws are Tufte's (smallest effective difference,
+  1+1=3, layering and separation, administrative debris), with
+  Müller-Brockmann and Refactoring UI as the working restatements;
+  `references/layout-sources.md` in the skill names each source and where
+  it lands.
+
+- **`live-tokens-pick-component` says `MenuSelect` renders open.** The
+  selection table called it a compact dropdown; the shipped component is a
+  list, and a dropdown is a `Button` that toggles it.
+
+## 0.72.1 — The compliance skills have a spine
+
+### Changed
+
+- **`live-tokens-check-compliance` and `live-tokens-fix-findings` open with a
+  numbered workflow**, the same spine the other six skills have: run the
+  command, read the result, apply the recipe, re-run, hand off. Both were
+  prose-first, so a reader (and the Skill Atlas that draws them) had no steps,
+  no gate, and no hand-off to find. fix-findings now also covers the four
+  wiring rules its table skipped (`invalid-id`, `no-tokens`,
+  `missing-component-const`, `missing-all-tokens`).
+
+- **`live-tokens-create-component` is 189 lines, down from 247.** The
+  standalone Toggle walkthrough is folded into the worked-examples list, the
+  verification checklist no longer restates the checker step, and the
+  registration caveat is shorter. Nothing a consumer needs to author a
+  component was removed.
+
+- **The sketch reference's inner-part example carries its reserved class.**
+  The prose said a drawn part takes its own class and its own five
+  `--sketch-*` values; the code under it showed only the CSS, so a part
+  authored from the example was left crisp inside a drawn box.
+
+### Fixed
+
+- **`live-tokens-build-page` no longer promises a Cmd+G shortcut.** There is
+  none; the columns overlay is the vertical-lines button in the overlay's
+  header.
+
+- **`live-tokens-pick-component` no longer lists `Slider` as a component the
+  catalogue lacks.** It shipped in 0.71.0.
+
 ## 0.72.0 — The contract a consumer can run
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -101,6 +101,11 @@
       "svelte": "./src/editor/docs/Docs.svelte",
       "default": "./src/editor/docs/Docs.svelte"
     },
+    "./skill-atlas": {
+      "types": "./src/editor/skill-atlas/SkillAtlas.svelte.d.ts",
+      "svelte": "./src/editor/skill-atlas/SkillAtlas.svelte",
+      "default": "./src/editor/skill-atlas/SkillAtlas.svelte"
+    },
     "./backdrop": {
       "svelte": "./src/system/backdrop/index.ts",
       "types": "./src/system/backdrop/index.ts",
@@ -154,15 +159,17 @@
     "check:token-contract": "node scripts/check-token-contract.mjs",
     "check:preset-themes": "node scripts/check-preset-themes.mjs",
     "check:skills": "node scripts/check-skills.mjs",
+    "check:skill-sources": "node scripts/sync-skill-sources.mjs --check",
     "check:skill-atlas": "node scripts/sync-skill-atlas.mjs",
     "sync:component-defaults": "node scripts/sync-component-defaults.mjs --write",
     "sync:docs": "node scripts/sync-docs.mjs --write",
+    "sync:skill-sources": "node scripts/sync-skill-sources.mjs --write",
     "sync:skill-atlas": "node scripts/sync-skill-atlas.mjs --write",
     "seed:preset-theme": "node scripts/seed-preset-theme.mjs",
     "collapse:theme": "node scripts/collapse-theme-to-default.mjs",
     "check:smoke-install": "bash scripts/smoke-install.sh",
     "check:smoke-create": "bash scripts/smoke-create.sh",
-    "prepublishOnly": "npm run check:no-style-imports && npm run check:no-tooling-imports && npm run check:slot-prose && npm run check:overlay-portal && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:pages && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:token-contract && npm run check:preset-themes && npm run check:skills && npm run check:skill-atlas && npm run check:smoke-install && npm run check:smoke-create"
+    "prepublishOnly": "npm run check:no-style-imports && npm run check:no-tooling-imports && npm run check:slot-prose && npm run check:overlay-portal && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:pages && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:token-contract && npm run check:preset-themes && npm run check:skills && npm run check:skill-sources && npm run check:skill-atlas && npm run check:smoke-install && npm run check:smoke-create"
   },
   "peerDependencies": {
     "@sveltejs/vite-plugin-svelte": "^7.0",

package/src/editor/docs/content/creating-components.md

@@ -16,6 +16,19 @@ npx @motion-proto/live-tokens setup-claude
 This copies the bundled skills into your project's `.claude/skills/`. Once
 they're there, Claude Code picks them up automatically.
 
+## Browse the skill atlas
+
+The package also ships a Skill Atlas component: a diagram of the reasoning
+behind each bundled skill, with its `SKILL.md` and reference files alongside
+so you can see exactly which lines drive which step. Import it from
+`@motion-proto/live-tokens/skill-atlas` and mount it on a route of your own:
+
+```js
+'/skills': {
+  lazy: () => import('@motion-proto/live-tokens/skill-atlas'),
+},
+```
+
 ## Ask for a component
 
 Describe what you want in plain English. Phrases like these trigger the skill:

package/src/editor/docs/content.generated.ts

@@ -3,7 +3,7 @@
 
 export const docContent: Record<string, string> = {
   "01-overview": "# Overview\n\nLiveTokens is a design system for building Svelte microsites quickly. You\nstyle your site by editing tokens and components in a live editor. When it looks right, you save the theme and ship it.\n\n## How it works\n\n- The editor runs in your dev server, on top of your real pages. You style in\n  context, not in a separate sandbox.\n- Every change updates a CSS variable, so the page repaints instantly. No\n  reload, no build step.\n- Saving writes a small JSON file into your project. Shipping bakes your chosen\n  theme into a plain CSS file that the build bundles.\n- The editor is dev-only. Production ships plain CSS variables and the\n  components you used, nothing else.\n\n## What you can edit\n\n- **Tokens**: the design-system primitives, colour palettes, type, spacing,\n  radius, shadow, and gradients, that apply across your whole site.\n- **Components**: the package ships about 25 editable components (Button,\n  IconButton, Card, Dialog, Table, and more). You style components by changing\n  the tokens assigned to each property.\n\n## Where to go next\n\n- **[Getting started](getting-started.md)**: scaffold a project and make your\n  first edit.\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Sketch mode](sketch-mode.md)**: redraw the page by hand.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own components\n  editable.\n",
-  "creating-components": "# Creating components\n\nThe package ships about 25 editable components. When you need one it doesn't\nhave, you can make your own Svelte component editable, so anyone using the\neditor can re-point its colours, type, and spacing without touching code.\n\nThe simplest way is to ask Claude. The package bundles a Claude Code skill that\nknows the conventions, writes the files, and checks the result for you.\n\n## Install the skills\n\n```bash\nnpx @motion-proto/live-tokens setup-claude\n```\n\nThis copies the bundled skills into your project's `.claude/skills/`. Once\nthey're there, Claude Code picks them up automatically.\n\n## Ask for a component\n\nDescribe what you want in plain English. Phrases like these trigger the skill:\n\n- \"Add a Toggle component to live-tokens\"\n- \"Make this Svelte component editable in the live-tokens editor\"\n- \"Create a Stat component with a value and a label\"\n\nClaude asks any clarifying questions it needs (which variants, which states,\nwhich parts), then writes the component, registers it with the editor, and runs\nits verification checklist. When it finishes, open `/live-tokens/components` to see your new\ncomponent in the editor and confirm everything works.\n\n## What you get\n\n- A runtime component whose editable properties default to your theme tokens.\n- An editor entry that appears under **Custom** in the `/live-tokens/components` view.\n- The naming and wiring handled for you, so the component fits the system.\n\nAdvanced authors who want to write a component by hand can read the naming and\nstate-model conventions shipped in the package\n(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).\n",
+  "creating-components": "# Creating components\n\nThe package ships about 25 editable components. When you need one it doesn't\nhave, you can make your own Svelte component editable, so anyone using the\neditor can re-point its colours, type, and spacing without touching code.\n\nThe simplest way is to ask Claude. The package bundles a Claude Code skill that\nknows the conventions, writes the files, and checks the result for you.\n\n## Install the skills\n\n```bash\nnpx @motion-proto/live-tokens setup-claude\n```\n\nThis copies the bundled skills into your project's `.claude/skills/`. Once\nthey're there, Claude Code picks them up automatically.\n\n## Browse the skill atlas\n\nThe package also ships a Skill Atlas component: a diagram of the reasoning\nbehind each bundled skill, with its `SKILL.md` and reference files alongside\nso you can see exactly which lines drive which step. Import it from\n`@motion-proto/live-tokens/skill-atlas` and mount it on a route of your own:\n\n```js\n'/skills': {\n  lazy: () => import('@motion-proto/live-tokens/skill-atlas'),\n},\n```\n\n## Ask for a component\n\nDescribe what you want in plain English. Phrases like these trigger the skill:\n\n- \"Add a Toggle component to live-tokens\"\n- \"Make this Svelte component editable in the live-tokens editor\"\n- \"Create a Stat component with a value and a label\"\n\nClaude asks any clarifying questions it needs (which variants, which states,\nwhich parts), then writes the component, registers it with the editor, and runs\nits verification checklist. When it finishes, open `/live-tokens/components` to see your new\ncomponent in the editor and confirm everything works.\n\n## What you get\n\n- A runtime component whose editable properties default to your theme tokens.\n- An editor entry that appears under **Custom** in the `/live-tokens/components` view.\n- The naming and wiring handled for you, so the component fits the system.\n\nAdvanced authors who want to write a component by hand can read the naming and\nstate-model conventions shipped in the package\n(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).\n",
   "editing-tokens": "# Editing tokens\n\nA tour of the editor. The page behind it repaints on every change; saving\nwrites a theme file you can reload later.\n\nThe editor has four views:\n\n- **Tokens**: the design-system primitives (colour, type, spacing, and so on).\n  They apply everywhere your site uses them.\n- **Color Wheel**: the harmony wheel, the palette curves, and the story your colours\n  tell across a page.\n- **Components**: per-component editors. Re-Assign what tokens a component uses\n  without changing the underlying system.\n- **Sketchstyle**: an effect layer that redraws the page by hand. See\n  [Sketch mode](sketch-mode.md).\n\nThis page covers **Tokens**. For components, see\n[Creating components](creating-components.md).\n\n## Palettes\n\nMost colour work happens here. Each palette (Brand, Accent, Neutral, Canvas,\nSuccess, Warning, Info, Danger, and a few more) has:\n\n- **Base colour.** Pick a hex; the palette derives an 11-step ramp (100 to 950)\n  from it.\n- **Curves.** Three curves shape the ramp, in stack order: Hue, Saturation,\n  Lightness. Drag the handles to bias it warmer or cooler, more or less\n  saturated, darker or lighter. Hue drifts the ramp's temperature without\n  moving contrast, because OKLCH hue rotation is close to lightness-preserving.\n  It holds ±45 degrees; a bigger shift belongs on the base colour or the\n  harmony axis.\n- **Overrides.** Lock a single step to a hand-picked hex when the curve doesn't\n  land where you want.\n\nEditing a palette base ripples through every colour that depends on it, in real\ntime. Colours use OKLCH, so the ramp stays perceptually even across hues\nwithout muddy mid-tones.\n\n## Type\n\n- **Fonts.** Add sources from Google Fonts, Adobe (Typekit), a CSS URL, or an\n  inline `@font-face`. The font loads in the page as soon as you add it.\n- **Stacks.** Named font cascades you reference by token, such as a display\n  stack and a body stack.\n- **Sizes and weights.** A t-shirt scale (xs, sm, md, lg, xl, 2xl…) for size and\n  a numeric scale (100 to 900) for weight.\n\n## Spacing, radius, shadow\n\nNumeric scales with a slider per step.\n\n- **Spacing**: the padding, gap, and margin scale.\n- **Radius**: none through full.\n- **Shadow**: colour, offset, blur, spread, and opacity per step, with stacked\n  shadows supported.\n\nChange a step and every element using it repaints.\n\n## Washes and gradients\n\n- **Scrims** are translucent layers that dim what sits behind them, like the\n  one a dialog draws over the page. Set a colour and opacity per stop.\n- **Tints** are the opposite operation: they shade the surface they sit on\n  rather than dimming what is behind it, which is what a hover needs.\n- **Gradients** are reusable gradient tokens with a stop list and direction, for\n  hero panels and accent backgrounds.\n\n## Columns\n\nThe page-grid overlay. Set column count, gutter, and outer margin, and toggle\nthe visual guide with `Cmd/Ctrl+G`. Pages built on the column system reflow\nlive.\n\n## Saving\n\nThe editor saves to your browser continuously, so work survives a reload\nmid-edit. Writing a file is a separate step: the **Theme** panel at the foot of\nthe sidebar has **Save**, **Save As**, and **Load**, and each theme is one JSON\nfile under `src/live-tokens/data/themes/`.\n\nThe header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`). You can keep\nmany themes side by side; one is open at a time, and only **Adopt** publishes\none. See [Themes](themes-workflow.md) for the full lifecycle.\n",
   "getting-started": "# Getting started\n\nScaffold a live token site in a moments. You need Node 20 or later, a\npackage manager (npm, pnpm, or yarn), and a browser. Open claude code in your repo and start building.\n\n## Scaffold a new app\n\n```bash\nnpm create @motion-proto/live-tokens@latest my-app\ncd my-app\nnpm install\nnpm run dev\n```\n\nOpen the URL Vite prints (usually `http://localhost:5173`). You get a\none-page Svelte + Vite app that depends on the published package, with the\neditor wired up and the full component set ready to import.\n\n`npx @motion-proto/live-tokens create my-app` runs the same scaffold without\nthe initialiser package.\n\n### What the scaffold gives you\n\nEvery editable file lives under `src/` and is committed, so `npm install` and\nversion upgrades never touch your styles. The package code stays in\n`node_modules`.\n\n| Path | What it is |\n|------|------------|\n| `src/pages/Home.svelte` | The starter page. Replace it with your own content. |\n| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds dev-only routes under a reserved `/live-tokens/*` namespace: `/live-tokens/editor`, `/live-tokens/components`, and `/live-tokens/docs`. |\n| `src/system/styles/tokens.css` | Your base token vocabulary, hand-authored. |\n| `src/styles/site.css` | Themed page typography, yours to edit. |\n\n## Your first edit\n\n1. Run `npm run dev` and open the home page.\n2. Click **Open Token Editor**, or visit `/live-tokens/editor`. The editor opens beside\n   the page.\n3. Open **Palettes**, pick **Brand**, and change the base hex. The page\n   repaints as you type.\n4. In the **Theme** panel at the foot of the sidebar, choose **Save As**. Your\n   theme appears as JSON under `src/live-tokens/data/themes/`.\n5. Reload. The editor reopens on your theme, so the page returns as you left\n   it.\n\n## What you just changed\n\nEvery edit sets a CSS custom property on `:root`. Your components read those\nproperties through `var(--...)`. There is no token build step and no\npreprocessor rewriting your code: the page renders against plain CSS variables\nthe editor swaps live.\n\nTo ship, click **Adopt** in the Theme panel. That saves the open theme and bakes\nit into `src/live-tokens/data/tokens.generated.css`, which your build bundles\nalongside `tokens.css`. Adopt is the only action that changes what your site\nships, so try any theme you like first. The editor itself never reaches\nproduction.\n\nAlready have a Svelte 5 + Vite app? The\n[README](https://github.com/motionproto/live-tokens#readme) covers installing\ninto an existing project.\n\n## Where to go next\n\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own component\n  editable.\n",
   "light-and-dark": "# Light and dark\n\nSome things on a page cannot be written as a token. A wordmark drawn in white\ndisappears on a pale theme. Ink that multiplies onto paper vanishes on a dark\none. A photograph behind a headline is dark no matter what the palette says.\n\nEach of those needs the same fact first: which way does the surface behind this\nthing lean? One attribute carries it.\n\n## The attribute\n\n`data-backdrop` is either `light` or `dark`, and it does two things at once: it\nselects, so a rule can key on it, and it sets `color-scheme`, so every\n`light-dark()` under it resolves the half that reads.\n\n```css\n.title {\n  color: light-dark(var(--color-black), var(--color-white));\n}\n```\n\nThat line is right on both sides of the theme, and it is right inside a dark\nband on a pale page, because the nearest `color-scheme` wins.\n\n## Stating it\n\nPut it in the markup when the surface knows its own tone — a hero over a\nphotograph, a plate that stays pale in every theme:\n\n```svelte\n<div class=\"hero-panel\" data-backdrop=\"dark\">\n```\n\nA stated tone beats any measurement, and it inherits, so everything inside the\npanel resolves against it.\n\n## Measuring it\n\nWhere the tone is a property of the theme rather than of the markup, let it be\nmeasured:\n\n```svelte\n<script>\n  import { backdrop } from '@motion-proto/live-tokens/backdrop';\n</script>\n\n<section use:backdrop>\n```\n\nThe action reads whatever actually paints behind the element — the nearest\nancestor with an opaque fill, averaged across its gradient stops, falling back\nto the theme's `--page-bg` — and stamps the answer. It re-reads when the theme\nchanges, which the editor does by rewriting custom properties with no reload,\nso the stamp follows a live edit.\n\nThe page itself is stamped for you: the build bakes the production theme's\npolarity into `tokens.generated.css`, so the first paint is already right, and\n`syncDocumentBackdrop()` keeps `<html>` current as themes switch.\n\n```ts\nimport { syncDocumentBackdrop } from '@motion-proto/live-tokens/backdrop';\n\nsyncDocumentBackdrop();\n```\n\n## Reading it from JavaScript\n\nAnything that paints outside CSS — a canvas, a WebGL uniform, an `<img>` that\ncomes in two versions — asks the same question through the same module:\n\n```ts\nimport { isLightBackdrop, watchBackdrop, cssColorToHex } from '@motion-proto/live-tokens/backdrop';\n\nconst stop = watchBackdrop(logoEl, {\n  stamp: false,\n  onChange: (polarity) => (src = polarity === 'light' ? darkMark : lightMark),\n});\n```\n\n`isLightBackdrop(el)` answers once. `watchBackdrop` keeps answering and returns\na stop function. `cssColorToHex` resolves any CSS colour — including the\n`oklch()` a token holds — to a hex a non-CSS consumer can take.\n\n## What it does not do\n\nPolarity is a property of a surface, not of a component, so nothing is stamped\nfor you below `<html>`: a section that needs an answer either states one or asks\nfor one. And a measurement reads the paint at the moment it runs — an element\nthat scrolls from a pale band onto a dark one keeps the answer it was given.\nState the tone on each band instead.\n",