@motion-proto/live-tokens 0.73.0 → 0.75.0

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

@@ -0,0 +1,94 @@
+# Design directions: feelings, idioms, and occasions
+
+Read this once the request names a feeling, a design idiom, an era, a genre, a
+holiday, a season, or a natural scene. Each entry places the request and gives
+the direction the three intents come from.
+
+The mechanics live with the executors. Color anchors are in
+live-tokens-set-colors, type anchors in live-tokens-set-type, geometry anchors
+in live-tokens-set-geometry, each keyed on the same names as the tables below.
+Name the anchor in the intent, and the sibling reads its own column.
+
+Three axes place any request, including one no entry lists:
+
+| Axis | Reads as | Carried by |
+|---|---|---|
+| Valence | pleasant against unpleasant | lightness, above everything else |
+| Energy | aroused against calm | chroma, and hue distance on screen |
+| Dominance | assertive against yielding | surface contrast, type weight, border weight, tightness |
+
+An idiom sets constraints and a feeling moves dials, so a request that names
+both ("cozy brutalist", "clinical Swiss") reads the idiom first and lets the
+feeling move the dials inside it.
+
+## Feelings
+
+Valence and energy set the quadrant, and the table runs in quadrant order:
+pleasant-aroused, pleasant-calm, unpleasant-aroused, unpleasant-calm. Dominance
+separates confident from gentle inside one quadrant and lives almost entirely
+outside color.
+
+| Request | Placement | Direction |
+|---|---|---|
+| Joyful, exuberant, energetic | pleasant, high energy | warm and bright throughout, with nothing held back |
+| Playful, whimsical | pleasant, high energy, low dominance | four hue families at play, soft and generous |
+| Optimistic, hopeful | pleasant, moderate energy | a cool ground lit by one warm counterpoint, like sunrise |
+| Confident, bold | pleasant, high energy, high dominance | wide contrast, heavy weight, held tight |
+| Serene, tranquil | pleasant, low energy | cool and quiet, with nothing loud anywhere |
+| Tender, gentle, romantic | pleasant, low energy, low dominance | a soft warm ground, a narrow range, light weights |
+| Cozy, comforting | pleasant, low energy | warm through and through, nothing cool on screen |
+| Wistful, nostalgic, vintage, faded | pleasant, low energy | chroma withheld rather than light withheld |
+| Earthy, grounded, natural | pleasant, low energy, moderate dominance | warm mineral hues, nothing synthetic |
+| Clinical, sterile, precise | neutral, low energy, high dominance | an untinted ground, one cool hue, tightly set |
+| Contemplative, focused | neutral, low energy | one cool hue and almost nothing else |
+| Urgent, alarming | unpleasant, high energy, high dominance | a neutral ground so the alarm lands, heavy and tight |
+| Tense, anxious | unpleasant, high energy | an uncomfortable ground under a pair that vibrates |
+| Defiant, rebellious, loud | unpleasant, high energy, highest dominance | near-black under one acid hue, blunt everywhere |
+| Melancholy, moody, sad | unpleasant, low energy | dark and cool, holding one moment of color |
+| Somber, grave, mournful | unpleasant, low energy, high dominance | near-neutral dark, sharp and quiet |
+| Ominous, dramatic, haunted | unpleasant, low energy, high dominance | dark with one hot accent and real atmosphere |
+| Austere, severe, cold | unpleasant, lowest energy, highest dominance | monochrome at one extreme of lightness |
+
+## Idioms, eras, and genres
+
+The table runs modernist, digital, quiet, print, expressive.
+
+| Request | Placement | Direction |
+|---|---|---|
+| Swiss, International | neutral, low energy, high dominance | one hue on a near-white ground, rational, tight |
+| Bauhaus | pleasant, high energy, high dominance | primaries at full commitment on paper, geometric, square but for the circle |
+| Mid-century modern | pleasant, moderate energy | warm muted mid-tones, soft and open, no borders |
+| Art deco, opulent, luxurious | pleasant, low energy, high dominance | dark with one metal, high-contrast type, sharp |
+| Terminal, phosphor | neutral, moderate energy, high dominance | one phosphor hue on near-black, mono, bordered |
+| Cyberpunk, neon noir, futuristic | unpleasant, high energy, high dominance | dark with two neons and a glow, wide type, sharp |
+| Vaporwave | pleasant, moderate energy, low dominance | light sunset pastels with a gradient, retro display, soft |
+| Y2K, bubble | pleasant, high energy | a chrome ground under electric color, geometric, pills |
+| Blueprint | neutral, low energy, high dominance | a drafting ground with pale rules, technical type, gridded |
+| Scandinavian, hygge | pleasant, low energy, low dominance | a chalk ground and muted naturals, soft and open |
+| Japandi, wabi-sabi | pleasant, lowest energy | unbleached paper, near-monochrome, generous space, no borders |
+| Cottagecore, botanical | pleasant, low energy, low dominance | warm cream and garden hues, serif display, soft |
+| Editorial, magazine | neutral, low energy, high dominance | paper and ink with one strong hue, carried by rules |
+| Newsprint, broadsheet | neutral, low energy | grey-warm paper under near-black ink, serif throughout, tight |
+| Risograph, zine | pleasant, high energy, high dominance | two flat spot inks on paper, expressive display, heavy rules |
+| Corporate, professional, trustworthy | pleasant, low energy | cool near-white with navy and teal, conventional everywhere |
+| Brutalist | unpleasant, high energy, highest dominance | a pure ground, one alarming hue, heavy type, thick borders |
+| Memphis, postmodern | pleasant, highest energy | a pastel ground under four hue families, shapes set against each other |
+| Industrial, workshop, gritty | neutral, moderate energy, high dominance | concrete and steel with safety orange, condensed type, thick borders |
+
+## Occasions
+
+An occasion fixes color only, so its type and geometry intents come from the
+feeling it implies or from the generic tables in the sibling skills.
+
+Every occasion is a statement request: the named color goes on the ground
+rather than only on the buttons.
+
+| Request | Direction |
+|---|---|
+| Christmas | red and green with gold, one of the two owning the ground |
+| Halloween | pumpkin, violet, and poison green, dark either way |
+| St. Patrick's | green with gold over a pale ground |
+| Ocean | blues held to one narrow band |
+| Sunset | a hue sweep through red, falling in lightness |
+| Autumn | parchment under rust, gold, and moss |
+| Spring | pastels, greens and pinks over a mint ground |

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

@@ -1,89 +1,98 @@
 ---
 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).
+description: Fix every finding of check-page and check-component in an existing @motion-proto/live-tokens project until both exit 0. Called with the fix list by live-tokens-check-compliance. Use when the user asks to fix the project. Edits the files the checkers name. Updates tokens.css only through the migration command.
 ---
 
-# Fixing the checkers' findings
+# Fixing the findings of check-page and check-component
 
-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.
+Fix every finding of `check-page` and `check-component` until both exit 0. `check-page` checks pages. Every component comes from the catalogue, every prop is declared, and every value in page CSS is a design token. `check-component` checks authored components. Every token names a semantic property, and its default is the design token that property reads. Update `tokens.css` only through the migration command. That command also heals the data tree, and with `--write` rewrites the route references it lists. When live-tokens-check-compliance hands over a fix list, the user's choices in it stand.
 
 ## Workflow
 
-1. Run both checkers with `--json`. Each finding carries a stable `rule`, a file, and a line.
+When `check-page` is an unknown command, upgrade `@motion-proto/live-tokens` first.
+
+1. Run `npx live-tokens migrate --check` to see the plan, then `npx live-tokens migrate` to apply it. `--tokens <path>` names a tokens.css in an unusual place.
+2. Run both checkers with `--json`. Each finding carries a `rule`, a file, and a line.
    ```sh
-   npx live-tokens check-page --json           # every page under src/
-   npx live-tokens check-component --json      # every component authored under src/system/components
+   npx live-tokens check-page --json
+   npx live-tokens check-component --json
    ```
-   `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.
+3. Group the findings by rule.
+4. Take the largest error group first, then the remaining errors. Take warnings only when the repair scope includes warnings.
+5. Fix every finding in the group with its section: Color by role, Geometry by scale, or The remaining rules.
+6. Run both checkers again. When repairable findings remain in scope, return to step 3. When no token fits a remaining finding, leave it and continue to the reply with its reason.
+7. When the errors are clear, run both checkers with `--strict`. Report what `--strict` adds. Clear warnings within the existing request. Otherwise ask whether to clear the warnings now.
+8. When the repair scope includes warnings, return to step 3 with `--strict`. When strict checks pass or the user defers warnings, continue to the reply.
+9. Reply with:
+   - the changes by rule, each with its count and any visible shift
+   - the findings left, each with its reason and any config entry the user chose
+   - both checker commands with their exit codes
+
+`check-page <path>` scopes a run to one page. `check-component <id>` scopes a run to one component: its runtime, its editor, and its registration. The checkers read tokens.css from its default location.
 
-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"`.
+When `package.json` has no `check:design` script, add `"check:design": "live-tokens check-page && live-tokens check-component"`. When both checkers exit 0, prepend `npm run check:design &&` to the existing build command. Preserve its other build steps.
 
-## Three things the loop never does
+## Scope
 
-- **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.
+- Add no token to `tokens.css`. Map a literal with no matching token to the nearest existing token by role. When no token fits, leave the finding and say so.
+- When the user has chosen to lower a rule's severity, record it in `live-tokens.config.json` under `"checks": { "rules": { "<rule>": "warn" } }`. `--off=<rule>` silences a rule for one run only.
+- When the nearest token differs from the literal, use the token and name the shift in the report, such as `14px` to `--space-16`.
 
-## Colour by role, never by hue
+## Color by role
 
-`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.
+`color-literal` is a judgement finding. The replacement is the token for the role the color plays. The theme moves every role together. `npx live-tokens tokens --scale <name>` prints a scale's names and values, with `--json` for data.
 
-| The literal is | Token family | Notes |
+| Literal | Token | Notes |
 | --- | --- | --- |
-| Text on a surface | `--text-primary`, `-secondary`, `-tertiary`, `-muted`, `-disabled` | The neutral scale. Family colour is `--text-accent`, `--text-success`, and so on. |
-| Light text on a dark chip over the page | `--text-inverted` | The one flip; no AA guarantee. |
-| A box's fill | `--surface-<family>-<level>` | `neutral` for chrome; `brand`, `accent`, `special` for emphasis; `info`, `success`, `warning`, `danger` for status. |
-| A stroke | `--border-<family>-<level>` | `faint`, `subtle`, base, `medium`, `strong` in the neutral family. |
-| A translucent layer that dims what is behind it | `--scrim-low`, `--scrim`, `--scrim-high` | Behind a modal, under a floating control. |
-| A translucent wash on a surface | `--tint-low`, `--tint`, `--tint-high` | Hover, an active tab, a code chip's background. |
-| Fully transparent | `--color-transparent` | Never `transparent` inside a component default. |
+| Text on a surface | `--text-primary` through `--text-disabled` | The neutral text scale. `--text-<family>` for a family color. |
+| Light text on a dark chip | `--text-inverted` | No AA guarantee. |
+| A surface fill | `--surface-<family>-<level>` | The role names the family: `neutral` for chrome, `brand` for emphasis, `danger` for status. |
+| A stroke | `--border-<family>-<level>` | Levels run `faint` to `strong`. |
+| A translucent layer that dims what is behind it | `--scrim-low`, `--scrim`, `--scrim-high` | Behind a modal. |
+| A translucent wash on a surface | `--tint-low`, `--tint`, `--tint-high` | A hover state. |
+| Any other translucent color | The role's token at an opacity: `color-mix(in srgb, var(--surface-brand) 80%, transparent)` | The editor reads that form. |
+| Fully transparent | `--color-transparent` | |
 | A gradient | `--gradient-*` | Or compose one from surface tokens. |
 
-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` is a mechanical finding. A size, such as a hero's height, is layout. Leave it.
 
-| The literal is | Token | Notes |
+| Literal | Token | Notes |
 | --- | --- | --- |
-| Padding, margin, gap, an offset | `--space-<px>` | `npx live-tokens tokens --family space` prints the steps. Round to the nearest one and name the shift. |
+| Spacing | `--space-<px>` | `npx live-tokens tokens --scale space` prints the steps. Round to the nearest step. |
 | A stroke width | `--border-width-1`, `-2`, `-4` | Also for `outline`. |
-| A corner | `--radius-sm` through `-4xl`, `--radius-full` | |
-| A shadow | `--shadow-sm` through `-xl` | Replace the whole value, never one offset. |
+| A corner | `--radius-sm` through `--radius-4xl`, or `--radius-full` | |
+| A shadow | `--shadow-sm` through `--shadow-xl` | Replace the whole value. |
 | Part of a `calc()` | The token inside the calc | `calc(var(--space-64) * -2 + var(--space-8))` |
+| A duration or easing | `--duration-*`, `--ease-*` | No rule reports it. Fix it while in the file. |
+| A `blur()` | `--blur-*` | No rule reports it. Fix it while in the file. |
 
-While in the file, motion values take `--duration-*` and `--ease-*` even though no rule reports them, and a `blur()` takes `--blur-*`.
-
-## Every other rule
+## The remaining rules
 
 | Rule | Fix |
 | --- | --- |
-| `unknown-token` | A typo or a rename. Search `tokens.css` for the stem. A contract-family name (`--surface-…`, `--text-…`) that is gone was renamed: `npx live-tokens migrate --check` names the migration. |
-| `raw-text-axis` | Set the whole axis set from one text style: `--heading-xl` through `-sm`, `--body-md`, `--body-sm`, `--editorial-*`, `--eyebrow`, `--code`, each carrying `-font-family`, `-font-size`, `-font-weight`, `-line-height`, `-letter-spacing`. A `font:` shorthand is rewritten the same way. `em`, `%`, and a unitless line-height are relative and fine. |
-| `unknown-component` | Not in the catalogue. Read **live-tokens-pick-component** for the shipped one that fits, or author it with **live-tokens-create-component**. |
-| `unknown-prop` | The component drops it at runtime. `npx live-tokens components <id>` prints the props it declares and the values each union accepts; map the prop to one of them or delete it. A `class` on a component that declares none does nothing. |
-| `unknown-prop-value` | Pick a value from the union the message lists. |
-| `hardcoded-columns` | `repeat(var(--columns-count), 1fr)` for the page grid; `calc(var(--columns-count) - 2)` for a sub-grid spanning fewer page columns. A two-up or three-up is a layout and is not reported. |
-| `site-css-in-main` | Delete the import from `main.ts` and add it to each page's `<script>`, so page CSS never reaches the editor routes. |
-| `missing-source` | Add `source: 'src/...'` to the route entry so Page Source can open it. |
-| `reserved-route` | Move the route out of `/live-tokens/*`; the package owns that namespace. |
-| `deep-import` | Import from `@motion-proto/live-tokens` or `/component-editor` or `/components/<Name>.svelte`, never from `/src/`. |
-| `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. |
-| `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.
-
-## 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.
+| `unknown-token` | Search `tokens.css` for the stem. When a contract-family name is gone, `npx live-tokens migrate --check` lists the migration that adds the current name. |
+| `raw-text-axis` | Set every axis from one text style, `-font-family` through `-letter-spacing`. `npx live-tokens tokens --scale heading` prints one text style. The text styles are `heading`, `body`, `editorial`, and `code`. Rewrite a `font:` shorthand the same way. |
+| `unknown-component` | Read **live-tokens-pick-component** for the shipped component that fits. When none fits, author one with **live-tokens-create-component**. |
+| `unknown-prop` | `npx live-tokens components <id>` prints the declared props and their values. Map the prop to one of them, or delete it. |
+| `unknown-prop-value` | Use a value from the union the message lists. |
+| `control-size` | Delete the `size` prop. The shipped default is the page's size. When that default is wrong for the project, retune the component in `/live-tokens/components`. |
+| `multiple-primary` | Keep the action that completes the main task `primary`. A Button with no `variant` counts as `primary`. Use `secondary` for supporting or related actions and `outline` for unrelated or informational actions. |
+| `danger-without-dialog` | Open a `Dialog` from the danger Button or IconButton and run the action from the Dialog's confirm. The rule fires once per page, when the page imports no Dialog. For other actions, assign emphasis by the action's relationship to the main task. |
+| `hardcoded-columns` | `repeat(var(--columns-count), 1fr)` for the page grid. `calc(var(--columns-count) - 2)` for a sub-grid spanning fewer columns. |
+| `site-css-in-main` | Delete the import from `main.ts`. Add it to each page's `<script>`. Page CSS then stays off the editor routes. |
+| `missing-source` | Add `source: 'src/...'` to the route entry. |
+| `reserved-route` | Move the route out of `/live-tokens/*`. |
+| `deep-import` | Import from `@motion-proto/live-tokens`, `/component-editor`, or `/components/<Name>.svelte`. |
+| `fix: property-name` | Rename the token to the name a shipped component uses for the same role. The vocabulary and the state model are in **live-tokens-create-component**. |
+| `fix: property-token` | Make the `:global(:root)` default read a design token, composed when needed. Declare a structural keyword, such as `start`, in the editor's `intrinsics`. |
+| `fix: runtime` | Wire the component as the recipe in **live-tokens-create-component** wires it. |
+| `fix: runtime-defaults` | Make the `:global(:root)` default the value Reset should restore, per the Runtime component section of **live-tokens-create-component**. |
+| `fix: editor` | The editor names a token the runtime never declares, or a property targets the wrong part. Fix the editor's schema, states, or preview props by the Component editor section of **live-tokens-create-component**. |
+| `fix: registration` | Register the component in the shared module the Registration section of **live-tokens-create-component** wires up, importable by the app and by `check-component --tests`. |
+| `fix: sketch` | Add the missing Sketch part or marker, per the Sketch mode and overlays section of **live-tokens-create-component**. |
+| `fix: tooling` | Install the named package (`@playwright/test`, `vitest`, or `happy-dom`) as a devDependency, then `npx playwright install chromium` for a missing browser. A bad path or config is named in the message; fix it and rerun `check-component <id> --tests`. |
+| `fix: coverage` | A contract obligation never ran to a result. Add the missing contract, or find why the suite skipped it, then rerun. |
+
+A `tests-*` finding names a problem with the run itself: the tool, the path, or a missing contract. Fix what the message names and rerun `check-component <id> --tests --json` until every applicable rule passes with no rule left `--off`.

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

@@ -1,111 +1,96 @@
 ---
 name: live-tokens-pick-component
-description: Recommend which shipped @motion-proto/live-tokens component fits a UX need, with decision trees for the confusable pairs (SegmentedControl / TabBar / RadioButton / MenuSelect, Card / CollapsibleSection / Dialog, Callout / Notification / Tooltip, and others). Use when the user asks which component to use, should I use X or Y, what is the difference between two components, how do I show / let the user / capture some UX outcome, or starts authoring a custom component before checking the catalogue. Read this before live-tokens-create-component. Not for placing the chosen component on a page (see live-tokens-build-page).
+description: Recommend which shipped @motion-proto/live-tokens component fits a UX need, with a decision test for each confusable family. Called by live-tokens-create-page when more than one component could fit, and by live-tokens-create-component before it authors anything. Use when the user asks which component to use, or what the difference between two components is. Use when the user asks how to show or capture a UX outcome. Edits no file. For size, emphasis, or placement, read live-tokens-create-page. When the catalogue lacks a component with chrome, read live-tokens-create-component.
 ---
 
-# Picking the right live-tokens component
+# Picking a live-tokens component
 
-This skill helps you choose between shipped components when several could plausibly fit. The catalogue is small; the hard part is semantic intent. A `RadioButton` set and a `SegmentedControl` can render identical-looking UIs but communicate different things.
-
-For composing a page once you've picked components, see **live-tokens-build-page**. For authoring a brand-new component when nothing fits, see **live-tokens-create-component** (but read this skill first to confirm nothing in the catalogue fits).
+When more than one shipped component could fit, find the family below that names the candidates. Apply its test, which asks what the choice means to the reader.
 
 ## Catalogue
 
-Action: `Button`, `IconButton`, `InlineEditActions`. Input: `Input`, `Slider`. Selection: `SegmentedControl`, `TabBar`, `RadioButton`, `MenuSelect`, `Toggle`. Containers: `Card`, `CollapsibleSection`, `Dialog`, `Panel`. Messaging: `Callout`, `Notification`, `Tooltip`, `Badge`, `CornerBadge`. Display: `Table`, `Image`, `ImageLightbox`, `ProgressBar`, `SectionDivider`, `SideNavigation`, `CodeSnippet`.
+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.
 
-That line is the shipped set. A project can register components of its own,
-and those never appear in this file: run `npx live-tokens components` before
-choosing. It lists every component the project has, shipped and custom, with
-the variants each takes and the purpose its header comment states, so a custom
-component is weighed against the shipped set on the same footing.
-`npx live-tokens components <id>` prints one component's props, the values each
-union accepts, and its tokens with defaults; `--json` returns the same as data.
+## Action family
 
-## Action family: Button vs IconButton
+- The action needs a word to be unambiguous: `Button`.
+- The glyph alone is plain (close, edit, delete) and space is short: `IconButton`.
+- The pair that confirms or cancels an inline edit: `InlineEditActions`.
 
-Both trigger an action and share the same six variants (primary, secondary, outline, success, danger, warning), three states (default, hover, disabled) and two sizes (default, small). They differ only in content.
+## Single-selection family
 
-- `Button` carries a text label, optionally with a leading or trailing icon. Use it whenever the action needs a word to be unambiguous.
-- `IconButton` is icon-only and square. Use it for compact, space-constrained actions whose meaning is obvious from the glyph alone (toolbar controls, close/edit/delete affordances, card overflow menus). It has no text slot, so an `ariaLabel` is required for accessibility.
-- **Don't reach for `IconButton` when the icon's meaning isn't self-evident.** A labelled `Button` (or a `Button` with an icon) avoids the guessing game.
-- `InlineEditActions` is the confirm-and-cancel pair that follows an inline edit (rename a row, edit a value in place). Use it rather than two loose `IconButton`s so every inline edit on the page resolves the same way.
+Four components pick one option from a set. The test is the option count, whether the selection swaps the content below, and how much the choice asks of the reader.
 
-## Single-selection family: SegmentedControl vs TabBar vs RadioButton vs MenuSelect
+| Component | Test | Option count |
+|---|---|---|
+| `SegmentedControl` | An inline switch between views of the same data. It sits in a row of controls. | 2 to 4 |
+| `TabBar` | The content area below swaps. | 2 to 7 |
+| `RadioButton` | The reader reads every option as text inside a larger form. | any |
+| `MenuSelect` | The options would overflow a row. | any |
 
-All four pick one option from a set. The right one depends on **option count**, **whether the selection changes what's rendered below**, and **how much visual weight** you want.
+- When a label would wrap in a `SegmentedControl`, use `RadioButton` rows.
+- The URL changes: `SideNavigation`. Sections inside one page: `TabBar`.
 
-| Component         | Best for                                                                | Visual weight    | 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`      | A list of options, one checked; renders open, so a dropdown toggles it from a `Button` | Open list        | Any          |
+## Text entry
 
-- `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.
-- Use `MenuSelect` when options would overflow horizontally or there are too many to display at once.
-- **Don't pick `SegmentedControl` when option labels are long enough to wrap.** It loses its compactness; use `RadioButton` rows instead.
+The test is whether the answer comes from a predefined list of options.
 
-## Text entry: Input vs the selection family
+- 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"`.
 
-- `Input` takes an answer the page cannot enumerate: a name, an email, a search string, an amount. It ships the label, the hint line, and the error state as parts (`--input-label-*`, `--input-hint-*`, `--input-error-*`), so style those rather than stacking your own text under a bare field.
-- The boundary is whether you can list the answers. A short fixed set is the single-selection family above; a long fixed set is `MenuSelect`; anything you cannot write down is `Input`.
-- `Slider` takes a number inside a known range where the position carries the meaning: a volume, a price band, a percentage. Its `range` variant takes a low and a high bound on one track. A number the user knows exactly and would rather type is `Input` with `type="number"`.
-- **Don't use it for on/off.** That is `Toggle`, and a one-field form asking for yes or no is the usual way this goes wrong.
-- Its four variants are `default`, `focused`, `disabled`, and `error`. A validation message belongs in the `error` variant, not in a `Callout` next to the field.
+## On and off
 
-## Container family: Card vs CollapsibleSection vs Dialog
+Three components express a binary choice. The test is whether the two states have names of their own.
 
-| Component             | Modality            | Use for                                                     |
-|-----------------------|---------------------|-------------------------------------------------------------|
-| `Card`                | Inline, always open | Default container for grouped content                       |
-| `CollapsibleSection`  | Inline, toggleable  | Progressive disclosure inside a longer page                 |
-| `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     |
+| Component | Test |
+|---|---|
+| `Toggle` | A setting that takes effect at once. The label names the setting. The switch position is the state. |
+| `SegmentedControl` | Two named alternatives the reader compares (Light / Dark, List / Grid). Both labels show at once. |
+| `RadioButton` pair | A yes or no the reader answers inside a larger form. |
 
-- 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`.
+When the two states share the feature's one name, use `Toggle`. "Email notifications" has no "off" label.
 
-## Messaging family: Callout vs Notification vs Tooltip vs Badge
+## Container family
 
-| Component       | Scope          | Triggered by    | Dismissable | Use for                                              |
-|-----------------|----------------|-----------------|-------------|------------------------------------------------------|
-| `Callout`       | Section-inline | Always present  | No          | "Heads up about this section"                        |
-| `Notification`  | System-level   | Event / save    | Yes         | "Your changes were saved"                            |
-| `Tooltip`       | Element-inline | Hover / focus   | Auto        | Definition or hint anchored to an element            |
-| `Badge`         | Element-inline | Always present  | No          | Status pill ("Beta", "New", "v2")                    |
-| `CornerBadge`   | Element-corner | Always present  | No          | Position-anchored marker (count, status dot)         |
+Four components hold a block of content. The test is what the block is to the reader: one item, a section of the page, secondary content that stays collapsed until opened, or a decision.
 
-- `Callout` is *content*. Part of the section, written into the markup, says something important about what surrounds it. Variants (`info`, `success`, `warning`, `danger`) set the tone.
-- `Notification` is *feedback*. Appears in response to an action, then dismisses. **Don't use `Notification` for static content;** persistent messages belong in a `Callout`.
-- `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).
+| Component | Modality | Test |
+|---|---|---|
+| `Card` | Inline, always open | One item, or each item in a set: a product, a record, a plan. It has a title and can react to hover. |
+| `Panel` | Inline, always open | One section of the page's content in a frame: a stage, a list, a form, a block of copy. `minHeight` holds its height while the content changes. |
+| `CollapsibleSection` | Inline, collapsed until the reader opens it | Secondary content most readers skip. |
+| `Dialog` | Modal, blocks the page | A decision the page cannot continue without: a destructive confirmation, payment, sign-in. |
 
-## Display family: shown, not asked
+A set of items is one `Card` per item. A routine form goes inline in a `Panel`.
 
-- `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.
-- `Table` themes your own rows and cells without owning the data. Records go here; a set of *things the user acts on* is a stack of `Card`s instead.
-- `ProgressBar` reports progress against a labelled track. It is a read-out, never a control.
-- `CodeSnippet` is for a single-line command or value the reader is meant to copy back into a terminal (install commands, generated keys, ids), with click-to-copy and a brief "Copied" popover. Use it whenever the page asks the reader to *run* something rather than just *read* it.
-- `SectionDivider` separates sections of one page. `SideNavigation` moves between pages, driven by the current path. **Don't use `SideNavigation` to switch panels inside one page;** that is `TabBar`, and the difference is whether the URL changes.
+## Messaging family
 
-## Toggle vs SegmentedControl vs RadioButton (for on/off)
+Five components carry a message. The test is what the message is about, what brings it on, and whether the reader dismisses it.
 
-All three can express a binary choice. The right one depends on what the choice *is*.
+| Component | Scope | Trigger | Dismissable | Test |
+|---|---|---|---|---|
+| `Callout` | A section | Always present | No | Something the reader must know about the content around it |
+| `Notification` | The system | An action or event | Yes | Feedback about something that just happened |
+| `Tooltip` | An element | Hover or focus | On leave | A definition or hint the reader can do without |
+| `Badge` | An element | Always present | No | A standing label read at a glance ("Beta", "New", "v2") |
+| `CornerBadge` | A parent's corner | Always present | No | A count or status marker on the thing it describes |
 
-| Component          | Best for                                                                                                              |
-|--------------------|-----------------------------------------------------------------------------------------------------------------------|
-| `Toggle`           | A *setting* that's either on or off (notifications on/off, dark mode). The label names the setting; the switch shows the state. |
-| `SegmentedControl` | A *choice between two named alternatives* (Light / Dark, List / Grid). Both labels are visible at once.                |
-| `RadioButton` pair | A *form-style choice* where the user reviews both labels before committing (Yes / No questions, opt-in selections).    |
+`Badge` and `CornerBadge` differ in position only.
 
-- If the off and on states share a name (the feature itself), it's `Toggle`. "Email notifications" has no "off" label because the switch position is the state.
-- If the two states have different names you want users to compare, it's `SegmentedControl`.
-- `Toggle` flips immediately; `RadioButton` pair is for forms where the choice is part of a larger submission.
+## Display family
 
----
+Each pair holds a block the reader views and one the reader interacts with. The test is which of the two the page needs.
+
+- A picture the page shows: `Image`. A picture whose detail the reader must open, or a gallery: `ImageLightbox`.
+- Records the reader scans and compares: `Table`. A set of items the reader acts on: one `Card` per item.
+- A read-out of progress: `ProgressBar`. A number the reader sets: `Slider`.
+- Text the reader runs or pastes (an install command, a key, an id): `CodeSnippet`. Prose the reader only reads: a paragraph in its `Card` or `Panel`.
+- A titled break between the sections of one page: `SectionDivider`. Movement between pages: `SideNavigation`.
+
+## Nothing fits
+
+A native element with no chrome of its own needs no component: an `<input type="file">` behind a Button, a `<canvas>`, an `<img>` inside a stage. When nothing in the catalogue fits a piece with chrome (a `DatePicker`, a `Stepper`), author the component with **live-tokens-create-component**. Size, emphasis, and placement are **live-tokens-create-page**'s.
 
-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.
+`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.