@motion-proto/live-tokens 0.82.0 → 0.84.0

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

@@ -101,9 +101,9 @@ Name a role as the shipped component that paints the same thing names it. A fill
 
 ## Runtime component
 
-Create `src/system/components/StatCard.svelte`. `check-component` finds a runtime there only. A component in another directory is listed by `components` and `report` when that directory is named in `"componentDirs"` in `live-tokens.config.json`, and `check-component` does not check it. Use Svelte 5 props and snippets, semantic HTML, and the behavior the task requires.
+Create `src/system/components/StatCard.svelte`. A component in another directory is listed by `components` and `report`, and checked by `check-component <id>`, when that directory is named in `"componentDirs"` in `live-tokens.config.json`. Use Svelte 5 props and snippets, semantic HTML, and the behavior the task requires.
 
-Open the file with a `<script module lang="ts">` block that exports a `catalogue` entry in the shape every shipped component carries. `npx live-tokens components` prints it beside the id, and `components <id>` prints it with the props. Each field is `key: <string literal>`, in single, double, or backtick quotes; no `${}` interpolation, no concatenation, no identifier reference. An optional `props` map adds one line per prop whose values carry a choice, such as `variant`; each key names a prop the file declares, and the text says what the values mean.
+Open the file with a `<script module lang="ts">` block that exports a `catalogue` entry in the shape every shipped component carries. `npx live-tokens components` prints it beside the id, and `components <id>` prints it with the props. Every value is a literal: a string in single, double, or backtick quotes, an object of strings, or an array. No `${}` interpolation, no concatenation, no identifier reference. Each `whenNotToUse` row is `{ when, use? }`: `when` states the condition that rules this component out, and `use`, where a sibling covers it, names that sibling by its component id (`table`, never `Table`); `check-component` reports `missing-description` when no component has that id. An optional `constraints` array states each rule of use as one sentence. An optional `props` map adds one line per prop whose values carry a choice, such as `variant`; each key names a prop the file declares, and the text says what the values mean.
 
 ```svelte
 <script module lang="ts">
@@ -111,12 +111,24 @@ Open the file with a `<script module lang="ts">` block that exports a `catalogue
 
   export const catalogue = {
     description: 'A figure with its label.',
-    useFor: 'one number the reader takes in at a glance.',
-    notFor: 'a set of records (Table); a titled block of content (Card).',
+    whenToUse: 'one number the reader takes in at a glance.',
+    whenNotToUse: [
+      { when: 'the reader scans and compares many records.', use: 'table' },
+      { when: 'the figure belongs to a titled block of content.', use: 'card' },
+    ],
+    constraints: ['The label names the figure in the words the page uses for it.'],
   } satisfies CatalogueEntry;
 </script>
 ```
 
+An agent chooses by these sentences, so word them the way the shipped entries are worded:
+
+- `description` is one sentence that says what the component is.
+- `whenToUse` states the one condition that makes this component right.
+- Each `when` states one condition that rules this component out. It reads correctly after "do not use <Name> when".
+- A row takes a `use` when another component fits that condition, and no `use` when none does.
+- When the nearest sibling is one of the project's own components, give that sibling a row that names the new component. An agent reaches a component by following `use`.
+
 Declare every editable property in a literal `:global(:root)` block, each assigned a token. The plugin parses the Svelte source to seed `component-configs/<id>/default.json`, so the block holds plain declarations with no SCSS loop or interpolation.
 
 ```svelte

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

@@ -12,7 +12,7 @@ Assemble the page from the shipped components at their defaults and the theme's
 1. Read the project first: the existing pages and where they live, how `App.svelte` wires routes, `--columns-count` in `tokens.css`, and the catalogue from `npx live-tokens components`.
 2. Read the page top to bottom and name each section by its purpose. Take each section's column spans from the Page layouts table.
 3. Build the page grid and place each section on it. Separate the sections with the smallest difference that separates them.
-4. Give each section its container from the Containers by purpose list.
+4. Give each section its container. `npx live-tokens components <id>` prints a component's constraints.
 5. Match a shipped component to each need. When two could fit, read **live-tokens-pick-component**. When nothing in the catalogue fits, read **live-tokens-create-component**.
 6. Write the page CSS in design tokens.
 7. Set the hierarchy: one text style per element, the shipped size on every control, one primary action, and one space step per position.
@@ -70,26 +70,28 @@ Show related items side by side when the width permits. A line of copy runs 45 t
 
 `references/layout-sources.md` names the sources for these laws.
 
-## Containers by purpose
-
-- `Panel` is a stage: a canvas, a player, a preview. `minHeight` holds its height while what it shows changes.
-- An empty stage shows a heading that names the condition and one `secondary` Button that fills it. An error goes in a `Callout variant="danger"`.
-- `Card` is a titled block of content. Its `title` prop is the title, and the card's own tokens type it.
-- A container in a tool UI labels itself: `Card variant="bare"` with the label in the body as `--body-sm-*` in `--text-secondary`.
-- A form puts the essential fields first and the secondary fields in a `CollapsibleSection`. Its actions sit on the bottom edge.
-- A row of fields is a flex row with `gap: var(--space-20)`. Each field's wrapper takes `flex: 1`.
-- A toolbar is a flex row of Buttons on the section's bottom edge, with no container around it. Group the Buttons left and right with `justify-content: space-between`, the primary last. A `danger` Button sits apart from the group it could be mistaken for.
-- A vertical stack of Buttons sets `fullWidth` on each Button. A row omits it.
-- `MenuSelect` renders its list open. For a picker, toggle it from a Button with a trailing chevron (`icon="fa-solid fa-chevron-down" iconPosition="right"`) and position the list under the Button at `top: 100%` with a `--space-*` margin.
-
 ## Components
 
 - Use a shipped component when one fits. Import it from `@motion-proto/live-tokens/components/<Name>.svelte`.
-- `npx live-tokens components <id>` prints the declared props, the values each union accepts, and the catalogue entry. `--json` prints the same as data. The list includes the project's own components.
+- `npx live-tokens components <id>` prints a component's declared props, the values each union accepts, and its catalogue entry, including its constraints and when not to use it. `--json` prints the same as data. The list includes the project's own components.
 - Pass only the props a component declares.
 - A shipped component fills its parent. To size one, size the element the page wraps it in.
 - A native element with no chrome of its own needs no component: an `<input type="file">` behind a Button, a `<canvas>`, an `<img>` inside a stage.
 - Text inside a `Card` or a `CollapsibleSection` takes the container's type on nested `p`, `ul`, `ol`, and `li`. When the page owns that type, as full-bleed media does, pass `prose={false}`.
+- An empty stage shows a heading that names the condition and one `secondary` Button that fills it. An error goes in a `Callout variant="danger"`.
+- A container in a tool UI labels itself: `Card variant="bare"` with the label in the body as `--body-sm-*` in `--text-secondary`.
+- A row of fields is a flex row with `gap: var(--space-20)`; each field's wrapper takes `flex: 1`.
+- A toolbar is a flex row of Buttons on the section's bottom edge, with no container around it. Group the Buttons left and right with `justify-content: space-between`. A `danger` Button sits apart from the group it could be mistaken for. A vertical stack of Buttons sets `fullWidth` on each Button; a row omits it.
+- For a `MenuSelect` picker, toggle it from a Button with a trailing chevron (`icon="fa-solid fa-chevron-down" iconPosition="right"`) and position the list under the Button at `top: 100%` with a `--space-*` margin.
+
+## Rules the checker enforces
+
+`check-page` fixes what it can and reports the rest by rule id.
+
+- `multiple-primary`
+- `danger-without-dialog`
+- `control-size`
+- `native-control`
 
 ## Tokens
 
@@ -119,11 +121,11 @@ Use the semantic element for each place: one `h1`, an `h2` for each section, `h3
 
 ### Size
 
-Omit `size` on every control and container. The shipped default is the page's size.
+Omit `size` on every control and container. `check-page` reports a `size` attribute on a shipped component as `control-size`.
 
 ### Emphasis
 
-One `primary` Button per page: the action that completes the page's main task. An action that supports that task is `secondary`. An action unrelated to the task, or informational, is `outline`. An action that destroys saved work is `danger`.
+`npx live-tokens components button` names each `variant` and the role it carries.
 
 In a row of actions the primary sits last, on the right. Up to four actions are individual Buttons. Five or more collapse into a `MenuSelect` behind one Button.
 
@@ -178,7 +180,7 @@ The checkers cannot see a layout. Open the page at the width it is built for and
 - The containers in a section align at the bottom.
 - The actions sit where the eye goes last, with the one primary at the end.
 - Every row of actions holds an action that leaves without committing.
-- An action that destroys saved work confirms in a `Dialog`.
+- Every action that destroys saved work meets the Button constraint `danger-without-dialog`.
 - An action that runs longer than a moment shows progress in a `ProgressBar` or a `Notification`.
 - Every field has a default, and Reset restores it.
 - Secondary settings sit in a `CollapsibleSection`. Every control is in view.

package/.claude/skills/live-tokens-create-page/references/interaction-sources.md

@@ -14,9 +14,9 @@ to keep a later edit from reopening it.
 |---|---|---|
 | Visibility of system status | Page | Verify: an action that runs longer than a moment shows progress in a `ProgressBar` or a `Notification`. |
 | Match between system and the real world | Page | Verify: labels use the user's words. |
-| User control and freedom | Page | Verify: every row of actions holds an action that leaves without committing. Emphasis: an unrelated or informational action is `outline`. |
+| User control and freedom | Page | Verify: every row of actions holds an action that leaves without committing. Emphasis: `multiple-primary`. |
 | Consistency and standards | Page | One size, one primary action, one text style per element. The components carry the rest. |
-| Error prevention | Page | Verify: an action that destroys saved work confirms in a `Dialog`; the checker's `danger-without-dialog`. Verify: every field has a default and Reset restores it. |
+| Error prevention | Page | Verify: `danger-without-dialog`. Verify: every field has a default and Reset restores it. |
 | Recognition rather than recall | Component | `MenuSelect` lists the options; `Input` carries its label and hint; `Tooltip` defines in place. |
 | Flexibility and efficiency of use | Product | Shortcuts and customisation are product decisions. |
 | Aesthetic and minimalist design | Page | Layout: each element serves a purpose no other element serves. Verify: secondary settings sit in a `CollapsibleSection`. |
@@ -40,7 +40,7 @@ control. Undo, version history, and autosave are the product's.
 | Discoverability | Page | Verify: every control is in view. |
 | Explorable interfaces | Page | Verify: every row of actions holds an action that leaves without committing. |
 | Fitts's law | Component | The shipped default is the large target; SKILL.md's one-size rule keeps it. A toolbar sits on the section's bottom edge. |
-| Protect users' work | Page | Verify: an action that destroys saved work confirms in a `Dialog`. |
+| Protect users' work | Page | Verify: `danger-without-dialog`. |
 | Readability | Component | live-tokens-set-colors gates every text pair at WCAG AA. |
 | Simplicity | Page | Verify: secondary settings sit in a `CollapsibleSection`; no capability is removed for the sake of simplicity. |
 | Visible navigation | Component | `SideNavigation` follows the current path. |

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

@@ -1,96 +1,23 @@
 ---
 name: live-tokens-pick-component
-description: Recommend which shipped @motion-proto/live-tokens component fits a UX need, with a decision test for each confusable family. Called by live-tokens-create-page when more than one component could fit, and by live-tokens-create-component before it authors anything. Use when the user asks which component to use, or what the difference between two components is. Use when the user asks how to show or capture a UX outcome. Edits no file. For size, emphasis, or placement, read live-tokens-create-page. When the catalogue lacks a component with chrome, read live-tokens-create-component.
+description: Recommend which shipped @motion-proto/live-tokens component fits a UX need, by reading each component's catalogue entry. Called by live-tokens-create-page when more than one component could fit, and by live-tokens-create-component before it authors anything. Use when the user asks which component to use, or what the difference between two components is. Use when the user asks how to show or capture a UX outcome. Edits no file. For size, emphasis, or placement, read live-tokens-create-page. When the catalogue lacks a component with chrome, read live-tokens-create-component.
 ---
 
 # Picking a live-tokens component
 
-When more than one shipped component could fit, find the family below that names the candidates. Apply its test, which asks what the choice means to the reader.
+When more than one component could fit, read the catalogue entries. Each entry states the condition that makes the component right and the conditions that rule it out.
 
-## Catalogue
+## Procedure
 
-Before choosing, run `npx live-tokens components`. The list holds every component the project has, shipped and custom, with each one's variants and catalogue entry. The family tests below name the shipped set only. Weigh a custom component by the same tests.
-
-## Action family
-
-- The action needs a word to be unambiguous: `Button`.
-- The glyph alone is plain (close, edit, delete) and space is short: `IconButton`.
-- The pair that confirms or cancels an inline edit: `InlineEditActions`.
-
-## Single-selection family
-
-Four components pick one option from a set. The test is the option count, whether the selection swaps the content below, and how much the choice asks of the reader.
-
-| Component | Test | Option count |
-|---|---|---|
-| `SegmentedControl` | An inline switch between views of the same data. It sits in a row of controls. | 2 to 4 |
-| `TabBar` | The content area below swaps. | 2 to 7 |
-| `RadioButton` | The reader reads every option as text inside a larger form. | any |
-| `MenuSelect` | The options would overflow a row. | any |
-
-- When a label would wrap in a `SegmentedControl`, use `RadioButton` rows.
-- The URL changes: `SideNavigation`. Sections inside one page: `TabBar`.
-
-## Text entry
-
-The test is whether the answer comes from a predefined list of options.
-
-- A predefined list (a status, a currency, a size, a country): the single-selection family, by its own test. Up to four options sit in a row; more go in a `MenuSelect`, which scrolls.
-- No list (a name, a search string, an amount, a message, a street address): `Input`. Validation keeps a typed answer well-formed.
-- A long list the reader would rather filter by typing (a city): no shipped component filters a list. Use `Input` with validation, or author a filtering select with **live-tokens-create-component**.
-- A number where the position on a track carries the meaning (a volume, a price range, a percentage): `Slider`. A number the reader knows and would rather type: `Input` with `type="number"`.
-
-## On and off
-
-Three components express a binary choice. The test is whether the two states have names of their own.
-
-| Component | Test |
-|---|---|
-| `Toggle` | A setting that takes effect at once. The label names the setting. The switch position is the state. |
-| `SegmentedControl` | Two named alternatives the reader compares (Light / Dark, List / Grid). Both labels show at once. |
-| `RadioButton` pair | A yes or no the reader answers inside a larger form. |
-
-When the two states share the feature's one name, use `Toggle`. "Email notifications" has no "off" label.
-
-## Container family
-
-Four components hold a block of content. The test is what the block is to the reader: one item, a section of the page, secondary content that stays collapsed until opened, or a decision.
-
-| Component | Modality | Test |
-|---|---|---|
-| `Card` | Inline, always open | One item, or each item in a set: a product, a record, a plan. It has a title and can react to hover. |
-| `Panel` | Inline, always open | One section of the page's content in a frame: a stage, a list, a form, a block of copy. `minHeight` holds its height while the content changes. |
-| `CollapsibleSection` | Inline, collapsed until the reader opens it | Secondary content most readers skip. |
-| `Dialog` | Modal, blocks the page | A decision the page cannot continue without: a destructive confirmation, payment, sign-in. |
-
-A set of items is one `Card` per item. A routine form goes inline in a `Panel`.
-
-## Messaging family
-
-Five components carry a message. The test is what the message is about, what brings it on, and whether the reader dismisses it.
-
-| Component | Scope | Trigger | Dismissable | Test |
-|---|---|---|---|---|
-| `Callout` | A section | Always present | No | Something the reader must know about the content around it |
-| `Notification` | The system | An action or event | Yes | Feedback about something that just happened |
-| `Tooltip` | An element | Hover or focus | On leave | A definition or hint the reader can do without |
-| `Badge` | An element | Always present | No | A standing label read at a glance ("Beta", "New", "v2") |
-| `CornerBadge` | A parent's corner | Always present | No | A count or status marker on the thing it describes |
-
-`Badge` and `CornerBadge` differ in position only.
-
-## Display family
-
-Each pair holds a block the reader views and one the reader interacts with. The test is which of the two the page needs.
-
-- A picture the page shows: `Image`. A picture whose detail the reader must open, or a gallery: `ImageLightbox`.
-- Records the reader scans and compares: `Table`. A set of items the reader acts on: one `Card` per item.
-- A read-out of progress: `ProgressBar`. A number the reader sets: `Slider`.
-- Text the reader runs or pastes (an install command, a key, an id): `CodeSnippet`. Prose the reader only reads: a paragraph in its `Card` or `Panel`.
-- A titled break between the sections of one page: `SectionDivider`. Movement between pages: `SideNavigation`.
+1. Run `npx live-tokens components --json`. The list carries the catalogue entry of every shipped component and of each of the project's own components.
+2. Read each plausible candidate's `whenToUse`, `whenNotToUse`, and `constraints`.
+3. Drop a candidate whose `whenNotToUse` names a condition the requirement meets.
+4. When a dropped row names a `use`, weigh that component the same way.
+5. Choose the surviving candidate whose `whenToUse` condition the requirement meets.
+6. When no candidate fits, follow "Nothing fits".
 
 ## 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.
+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, such as a `DatePicker`, a search-filtered list, or a `Stepper`, author the component with **live-tokens-create-component**. No shipped component filters a list by typing, so a searchable picker takes this same route. Size, emphasis, and placement are **live-tokens-create-page**'s.
 
 `npx live-tokens components <id>` prints one component's catalogue entry, its declared props, and the values each union accepts. `--json` returns the same as data.

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.84.0 — A scrim's colour and strength are separate tokens
+
+### Added
+
+- **`--scrim-color` and `--scrim-opacity-low`, `--scrim-opacity`,
+  `--scrim-opacity-high`.** A theme holds one and moves the other: a light
+  `--scrim-color` gives a scrim that pales the page. The three `--scrim-*` stops
+  remain, composed from the two. The additive tokens-css migration
+  `2026-09-20-scrim-color-and-opacity` inserts the four names into an existing
+  `tokens.css`, and the dev plugin applies it on its own. The stops already in
+  that file keep their values; to have them follow `--scrim-color`, write each
+  as `color-mix(in srgb, var(--scrim-color) calc(var(--scrim-opacity) * 100%), transparent)`
+  with its own opacity stop.
+
+- **The editor picks an opacity from its stops.** A property whose name ends in
+  `-opacity` takes a picker of the three scrim strengths, low, medium, and high.
+  The suffix used to fall under the fill rule, which offered a palette and wrote
+  a colour into a number.
+
+### Changed (breaking)
+
+- **`--dialog-scrim-surface` and `--imagelightbox-scrim-surface` each split into
+  `-scrim-color` and `-scrim-opacity`.** Each screen mixes the pair where it
+  paints. ImageLightbox's `scrim` prop writes the colour and `scrimOpacity`
+  writes the strength, and the opacity now stands on its own. Migration
+  `2026-09-20-scrim-color-and-opacity` splits the old key in a saved component
+  config: a `--scrim-*` stop becomes that stop's opacity with `--scrim-color`,
+  and a hand-written fill becomes the colour at full strength. A project whose
+  `tokens.css` gave the scrim stops their own colour sets `--scrim-color` to it,
+  since Dialog and ImageLightbox now read that token.
+
+## 0.83.0 — The catalogue entry names what rules a component out
+
+### Added
+
+- **`ImageLightbox` takes per-instance tile and scrim props.** Any CSS fill, written into
+  `--imagelightbox-tile-surface` for that one tile, the way `fit` writes
+  `--imagelightbox-tile-object-fit`. A theme's value still governs every tile
+  that passes nothing, and the default stays transparent. Art with transparency
+  wants a ground: without one the page shows through the art's own gaps while a
+  `box` shadow still casts from the rectangle around them. The open stage is
+  unaffected — it sits on the scrim and paints no tile fill.
+
+  `border` and `borderWidth` do the same for `--imagelightbox-tile-border` and
+  `--imagelightbox-tile-border-width`. Both are needed where a theme leaves the
+  width at zero, since a colour alone paints nothing.
+
+  `scrim` and `scrimOpacity` set the layer behind the open image, writing
+  `--imagelightbox-scrim-surface`. An opacity is mixed into the colour, so
+  `scrimOpacity` needs `scrim` to have something to mix. This is the one
+  reachable way to set it per page: the modal portals to `<body>`, out of reach
+  of any wrapper around the tile.
+
+- **`CatalogueEntry` carries `constraints`.** `constraints` is an optional
+  `string[]` of rules of use, one sentence each. `components <id>` prints one
+  `Not for:` line per `whenNotToUse` row and one `Rule:` line per constraint.
+
+- **Skill Atlas: a "Measured value" tab.** It reports an eval of twelve component
+  choices, run with the skills and without. Both arms chose correctly; the
+  skills cut the turns and the time. `#measured-value` links to it.
+
+### Changed (breaking)
+
+- **`--imagelightbox-overlay-surface` is `--imagelightbox-scrim-surface`, and it
+  reads `--scrim-high`.** Dialog already called the layer that dims the page a
+  scrim and read the `--scrim-*` scale; ImageLightbox called it an overlay and
+  mixed its own colour, so a theme could not move both with one value. The
+  editor row reads "scrim color". Migration `2026-09-20-imagelightbox-scrim`
+  renames the key; the shipped presets carry the new one.
+
+- **`CatalogueEntry` requires `description`, `whenToUse`, and `whenNotToUse`.**
+  `notFor` is gone. `whenToUse` is a required string: the condition that makes
+  the component the right choice. `whenNotToUse` is a required array of
+  `{ when, use? }` rows,
+  each naming a condition that rules the component out and, where a sibling
+  fits instead, that sibling's component id. A component with no disqualifying
+  condition declares `whenNotToUse: []`. `constraints` is an optional
+  `string[]`. A runtime's `catalogue` export, and any consumer's, must supply
+  all three required fields; `missing-description` reports any as missing, or a
+  `whenNotToUse` row's `use` that names no component.
+- **`components` and `components --json` drop `tokens` from the list form.**
+  The id form (`components <id>`) is unchanged. The `--json` list drops from
+  ~179 KB to ~37 KB across the 26 shipped components.
+
 ## 0.82.0 — The demo ships from the package
 
 ### Added

package/README.md

@@ -366,7 +366,7 @@ A project created with `create` runs the forced form from `postinstall` and giti
 
 Ask "TabBar or SegmentedControl?", "how do I let someone pick one of four options?", or "what is the difference between a Callout and a Notification?".
 
-The skill holds the catalogue grouped by job (action, input, selection, containers, messaging, display) and a decision table for each confusable family: `SegmentedControl` vs `TabBar` vs `RadioButton` vs `MenuSelect`, `Card` vs `CollapsibleSection` vs `Dialog`, `Callout` vs `Notification` vs `Tooltip` vs `Badge`, `Button` vs `IconButton`, and the on/off case. It answers the question and writes nothing. Read it before authoring anything new.
+The skill runs `npx live-tokens components --json` and reads each candidate's catalogue entry: the condition that makes it the right component, the conditions that rule it out with the component to use in its place, and its rules of use. The entries hold the decision, so a component you author joins the same query. It answers the question and writes nothing. Read it before authoring anything new.
 
 ### `live-tokens-create-page`
 

package/bin/cli.mjs

@@ -21,7 +21,13 @@ import process from 'node:process';
 import { COMPONENT_RULES, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
 import { PAGE_RULES, checkPages, discoverPages } from './check-page.mjs';
 import { resolvePageTestTargets } from './lib/pageRoutes.mjs';
-import { describeComponents, describeTokens, formatComponents, formatTokens } from './lib/catalogue.mjs';
+import {
+  describeComponents,
+  describeTokens,
+  formatComponents,
+  formatTokens,
+  withoutTokens,
+} from './lib/catalogue.mjs';
 import { applyFixes } from './lib/fixers.mjs';
 import { buildReport, formatReport as formatProjectReport } from './lib/report.mjs';
 import { loadVocabulary } from './lib/tokenVocabulary.mjs';
@@ -58,11 +64,14 @@ Commands:
   create <dir> [--force]      Scaffold a new Svelte + Vite app wired up with
                               live-tokens (editor, components, design tokens)
   setup-claude [--force]      Install bundled Claude Code skills into ./.claude/skills/
-  components [id] [--json]    List every component the project has, shipped and
+  components [id] [--json]
+                              List every component the project has, shipped and
                               its own (src/system/components plus any
-                              "componentDirs" in live-tokens.config.json). With
-                              an id, that component's props, variants, tokens,
-                              and defaults
+                              "componentDirs" in live-tokens.config.json), each
+                              with its catalogue entry (description, whenToUse,
+                              whenNotToUse, constraints). The list form omits
+                              tokens. With an id, that component's
+                              props, variants, tokens, and defaults
   tokens [--scale <name>] [--json]
                               List every design token the project's tokens.css
                               declares, by scale, with its value
@@ -265,10 +274,14 @@ function formatFixes({ applied, skipped }) {
 
 if (command === 'components') {
   const opts = parseCheckFlags(rest);
-  const list = describeComponents(loadVocabulary());
   const id = opts.rest[0];
-  if (id && !list.some((c) => c.id === id)) fail(formatComponents(list, { id }));
-  writeOut(opts.json ? JSON.stringify(id ? list.find((c) => c.id === id) : list, null, 2) : formatComponents(list, { id }));
+  const list = describeComponents(loadVocabulary());
+  if (id) {
+    if (!list.some((c) => c.id === id)) fail(formatComponents(list, { id }));
+    writeOut(opts.json ? JSON.stringify(list.find((c) => c.id === id), null, 2) : formatComponents(list, { id }));
+    process.exit(0);
+  }
+  writeOut(opts.json ? JSON.stringify(withoutTokens(list), null, 2) : formatComponents(list, {}));
   process.exit(0);
 }
 

package/bin/lib/catalogue.mjs

@@ -47,9 +47,11 @@ function literalValue(raw) {
   return inner.replace(/\s+/g, ' ').trim();
 }
 
-// Brace matching skips over quoted literals so a `}` inside a description
-// (or a description containing a stray brace) never closes the object early.
-function findBalanced(text, openIndex) {
+// Brace/bracket matching skips over quoted literals so a closer inside a
+// description (or a description containing a stray brace) never closes the
+// group early. Shared by object literals (`{`/`}`) and array literals
+// (`[`/`]`).
+function findBalanced(text, openIndex, open = '{', close = '}') {
   let depth = 0;
   for (let i = openIndex; i < text.length; i++) {
     const ch = text[i];
@@ -59,8 +61,8 @@ function findBalanced(text, openIndex) {
       while (i < text.length && text[i] !== quote) i += text[i] === '\\' ? 2 : 1;
       continue;
     }
-    if (ch === '{') depth++;
-    else if (ch === '}') {
+    if (ch === open) depth++;
+    else if (ch === close) {
       depth--;
       if (depth === 0) return { content: text.slice(openIndex + 1, i), end: i + 1 };
     }
@@ -68,26 +70,127 @@ function findBalanced(text, openIndex) {
   return null;
 }
 
-function parseFieldObject(body) {
+function skipSeparators(text, i) {
+  while (i < text.length && /[\s,]/.test(text[i])) i++;
+  return i;
+}
+
+// The comma that ends the expression starting at `i`. A key or a literal
+// inside an expression the reader cannot read must stay unread with it.
+function expressionEnd(text, i) {
+  let depth = 0;
+  for (; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const quote = ch;
+      i++;
+      while (i < text.length && text[i] !== quote) i += text[i] === '\\' ? 2 : 1;
+    } else if ('([{'.includes(ch)) depth++;
+    else if (')]}'.includes(ch)) depth--;
+    else if (ch === ',' && depth === 0) return i;
+  }
+  return text.length;
+}
+
+function readWholeExpression(text, i) {
+  const end = expressionEnd(text, i);
+  const expression = text.slice(i, end);
+  const result = readValue(expression, 0);
+  const literal = result && !expression.slice(result.end).trim();
+  return { value: literal ? result.value : undefined, end };
+}
+
+/**
+ * One literal value starting at `text[i]`: a quoted string, a `[...]` array of
+ * values, or a `{...}` object of `key: value` pairs — the subset `catalogueOf`
+ * reads, recursively, so a key nested inside a `whenNotToUse` row, `props`, or a
+ * `{ rule, text }` constraint is read at its own depth and never mistaken for
+ * a top-level field. An identifier, a template with `${}`, a concatenation,
+ * or any other expression is outside the subset and reads as absent (`null`),
+ * the same tolerance `catalogueOf` always gave a non-literal field.
+ */
+function readValue(text, i) {
+  i = skipSeparators(text, i);
+  const ch = text[i];
+  if (ch === "'" || ch === '"' || ch === '`') {
+    const m = STRING_LITERAL.exec(text.slice(i));
+    if (!m || m.index !== 0) return null;
+    const value = literalValue(m[0]);
+    return value === undefined ? null : { value, end: i + m[0].length };
+  }
+  if (ch === '[') {
+    const balanced = findBalanced(text, i, '[', ']');
+    if (!balanced) return null;
+    const items = [];
+    let j = 0;
+    while (j < balanced.content.length) {
+      const item = readWholeExpression(balanced.content, j);
+      if (item.value !== undefined) items.push(item.value);
+      j = item.end + 1;
+    }
+    return { value: items, end: balanced.end };
+  }
+  if (ch === '{') {
+    const balanced = findBalanced(text, i, '{', '}');
+    if (!balanced) return null;
+    return { value: readObject(balanced.content), end: balanced.end };
+  }
+  return null;
+}
+
+/** `key: value` pairs read by depth: the scan resumes after each value's
+ *  whole expression, read or unread, so a key inside a value's own text is
+ *  never read as one of `body`'s own fields. */
+function readObject(body) {
   const fields = {};
-  const re = new RegExp(`([A-Za-z_$][A-Za-z0-9_$]*)\\s*:\\s*(${STRING_LITERAL.source})`, 'g');
+  const keyRe = /([A-Za-z_$][A-Za-z0-9_$]*)\s*:/g;
   let m;
-  while ((m = re.exec(body))) {
-    if (m[1] in fields) continue;
-    const value = literalValue(m[2]);
-    if (value !== undefined) fields[m[1]] = value;
+  while ((m = keyRe.exec(body))) {
+    const result = readWholeExpression(body, keyRe.lastIndex);
+    if (result.value !== undefined && !(m[1] in fields)) fields[m[1]] = result.value;
+    keyRe.lastIndex = result.end;
   }
   return fields;
 }
 
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** An object's own string-valued entries; a non-string value is dropped, key
+ *  by key, the same tolerance a top-level field gets. */
+function stringEntries(v) {
+  if (!isPlainObject(v)) return undefined;
+  const out = {};
+  for (const [key, value] of Object.entries(v)) if (typeof value === 'string') out[key] = value;
+  return out;
+}
+
+/** `whenNotToUse` entries: a `{ when, use? }` object with `when` a string and
+ *  `use`, if present, a string. A row whose `when` is not a string literal is
+ *  dropped from the array. */
+function whenNotToUseEntries(v) {
+  if (!Array.isArray(v)) return undefined;
+  const out = [];
+  for (const item of v) {
+    if (isPlainObject(item) && typeof item.when === 'string') {
+      out.push(typeof item.use === 'string' ? { when: item.when, use: item.use } : { when: item.when });
+    }
+  }
+  return out;
+}
+
+function constraintEntries(v) {
+  if (!Array.isArray(v)) return undefined;
+  return v.filter((item) => typeof item === 'string');
+}
+
 /**
- * Bounded, non-evaluating parse of the runtime file's `catalogue` export:
- * `key: <string literal>` pairs inside the `<script module>` block's
- * `export const catalogue = { ... }`, the same way `builtInIds` and
- * `componentProps` read the rest of the vocabulary without importing the
- * module. A field given as an identifier, a template with `${}`, or a
- * concatenation is not a string literal, so it is silently absent rather
- * than evaluated. Returns `null` when the file has no such export.
+ * Bounded, non-evaluating parse of the runtime file's `catalogue` export
+ * inside the `<script module>` block's `export const catalogue = { ... }`,
+ * the same way `builtInIds` and `componentProps` read the rest of the
+ * vocabulary without importing the module. Returns `null` when the file has
+ * no such export.
  */
 export function catalogueOf(source) {
   const moduleBlock = source.match(/<script\s+module[^>]*>([\s\S]*?)<\/script>/);
@@ -98,26 +201,16 @@ export function catalogueOf(source) {
   const balanced = findBalanced(moduleBlock[1], openIndex);
   if (!balanced) return null;
 
-  let body = balanced.content;
-  let props;
-  const propsMatch = /\bprops\s*:\s*\{/.exec(body);
-  if (propsMatch) {
-    const propsOpen = propsMatch.index + propsMatch[0].length - 1;
-    const propsBalanced = findBalanced(body, propsOpen);
-    if (propsBalanced) {
-      const parsedProps = parseFieldObject(propsBalanced.content);
-      if (Object.keys(parsedProps).length) props = parsedProps;
-      body = body.slice(0, propsMatch.index) + body.slice(propsBalanced.end);
-    }
-  }
-
-  const fields = parseFieldObject(body);
-  const catalogue = {
-    description: fields.description,
-    useFor: fields.useFor,
-    notFor: fields.notFor,
-  };
-  if (props) catalogue.props = props;
+  const fields = readObject(balanced.content);
+  const catalogue = {};
+  if (typeof fields.description === 'string') catalogue.description = fields.description;
+  if (typeof fields.whenToUse === 'string') catalogue.whenToUse = fields.whenToUse;
+  const whenNotToUse = whenNotToUseEntries(fields.whenNotToUse);
+  if (whenNotToUse) catalogue.whenNotToUse = whenNotToUse;
+  const constraints = constraintEntries(fields.constraints);
+  if (constraints && constraints.length) catalogue.constraints = constraints;
+  const props = stringEntries(fields.props);
+  if (props && Object.keys(props).length) catalogue.props = props;
   return catalogue;
 }
 
@@ -190,6 +283,11 @@ export function describeComponents(vocab, { root = process.cwd() } = {}) {
   return out.sort((a, b) => a.origin.localeCompare(b.origin) || a.id.localeCompare(b.id));
 }
 
+/** The list form's payload. `tokens` is most of a full listing's bytes, and the id form keeps it. */
+export function withoutTokens(list) {
+  return list.map(({ tokens, ...rest }) => rest);
+}
+
 export function describeTokens(vocab, { root = process.cwd() } = {}) {
   return {
     tokensCss: vocab.tokensCssPath ? relative(root, vocab.tokensCssPath) : null,
@@ -203,11 +301,12 @@ export function describeTokens(vocab, { root = process.cwd() } = {}) {
 
 function describeLines(c) {
   if (!c.catalogue) return [];
-  const { description, useFor, notFor, props } = c.catalogue;
+  const { description, whenToUse, whenNotToUse, constraints, props } = c.catalogue;
   const lines = [];
   if (description) lines.push(description);
-  if (useFor) lines.push(`Use for: ${useFor}`);
-  if (notFor) lines.push(`Not for: ${notFor}`);
+  if (whenToUse) lines.push(`When to use: ${whenToUse}`);
+  for (const row of whenNotToUse ?? []) lines.push(row.use ? `Not for: ${row.when} Use ${row.use}.` : `Not for: ${row.when}`);
+  for (const constraint of constraints ?? []) lines.push(`Rule: ${constraint}`);
   for (const [prop, text] of Object.entries(props ?? {})) lines.push(`${prop}: ${text}`);
   return lines;
 }