@motion-proto/live-tokens 0.74.0 → 0.76.0

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

@@ -1,6 +1,6 @@
 # Extension: intrinsics
 
-Some components expose **structural or display choices** that aren't token values: an alignment (start / center), an element's visibility (show / hide), a layout position. These ride a bespoke `<select>` or checkbox you author in an editor snippet, not the generic token grid, so they don't belong in `allTokens`. Toggle and most components have none. SectionDivider is the worked example (alignment, hairline position, eyebrow / description visibility).
+Some components expose **structural or display choices** that are not token values: an alignment (start / center), an element's visibility (show / hide), a layout position. These ride a custom `<select>` or checkbox authored in an editor snippet, outside the generic token grid, so they do not belong in `allTokens`. Toggle and most components have none. SectionDivider is the worked example (alignment, hairline position, eyebrow / description visibility).
 
 An intrinsic still cascades through a CSS custom property with a default in the runtime `:global(:root)`. The trap: that default now lives in two places, the runtime `:global(:root)` AND the editor's read-back getter. When they disagree the control displays a state the page never renders, and a native `<select>` won't even fire `onchange` to write the "change" the user thinks they made. `:global(:root)` is the source of truth.
 
@@ -57,4 +57,4 @@ Declare intrinsics so the editor and the contract test stay honest:
    });
    ```
 
-Use `normalize` only when two raw values render identically and the dropdown lists just one (SectionDivider folds `above-description` into `below-label`). Properties that look like intrinsics but aren't: preview-only props with no persistence (a size selector that only changes the demo), `setComponentConfig` editor metadata (Dialog's button variants), and token-valued selects (a control choosing between two tokens). None carry a duplicated runtime default, so none need an `IntrinsicSpec`.
+Use `normalize` only when two raw values render identically and the dropdown lists one (SectionDivider folds `above-description` into `below-label`). Properties that resemble intrinsics but are not: preview-only props with no persistence (a size selector that only changes the demo), `setComponentConfig` editor metadata (Dialog's button variants), and token-valued selects (a control choosing between two tokens). None carry a duplicated runtime default, so none need an `IntrinsicSpec`.

package/.claude/skills/live-tokens-create-component/references/linked-siblings.md

@@ -1,6 +1,6 @@
 # Extension: linked siblings
 
-Read this when your component has more than one variant and those variants share base properties (surface, radius, padding) that should move together. Toggle and SectionDivider have no linked tokens and skip all of it.
+Read this when the component has more than one variant and those variants share base properties (surface, radius, padding) that should move together. Toggle and SectionDivider have no linked tokens and skip all of it.
 
 Toggle's tokens are flat per state. Most multi-variant components (Badge, Card, SegmentedControl) share base properties across variants and surface that equality via a *linked block*: one edit propagates to every variant, while per-variant properties stay independent. Five additions to the Toggle pattern; see `BadgeEditor.svelte` in `node_modules` for the full file.
 
@@ -67,4 +67,4 @@ Toggle's tokens are flat per state. Most multi-variant components (Badge, Card,
    </ComponentEditorBase>
    ```
 
-Single-variant components with multi-state linked tokens still set `canBeLinked` + `linkableContexts`, but skip `buildSiblings` and the `{#each}` loop. Components with no linked tokens (Toggle, SectionDivider) skip all five steps — `ComponentEditorBase` renders fine without a `{linked}` prop.
+Single-variant components with multi-state linked tokens still set `canBeLinked` + `linkableContexts`, but skip `buildSiblings` and the `{#each}` loop. Components with no linked tokens (Toggle, SectionDivider) skip all five steps; `ComponentEditorBase` renders without a `{linked}` prop.

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

@@ -3,7 +3,7 @@
 Sketch mode blanks each part's real background and border and repaints them onto
 `::before`/`::after` through a shared noise field. It draws a fixed set of
 selectors: the shipped components, plus four classes reserved for everyone else.
-Your component is skipped until it opts in, so it stays crisp while the page
+A component is skipped until it opts in, so it stays crisp while the page
 around it goes hand-drawn.
 
 The whole contract is CSS. There is nothing to import and no function to call:
@@ -15,7 +15,7 @@ and naming five custom properties.
 An opted-in element is no longer painting itself. On every drawn part the layer
 forces:
 
-| It forces                                    | So you must                                              |
+| It forces                                    | So the component must                                              |
 |----------------------------------------------|----------------------------------------------------------|
 | `background: transparent !important`          | Name the fill again as `--sketch-fill`                    |
 | `border-color: transparent !important`        | Name the outline again as `--sketch-stroke`               |
@@ -40,8 +40,8 @@ A card and a modal are both containers; a badge and a pill are both chips.
 | `sketch-chip`       | A small box. Finer fill mask, more rotation, less travel.     |
 | `sketch-rule`       | A line rather than a box. No rotation, no rounded ends.       |
 
-The class opts you in and nothing more. It names no colour, so the layer emits
-no rule for it and whatever your component declares survives.
+The class opts the component in and nothing more. It names no colour, so the layer emits
+no rule for it and whatever the component declares survives.
 
 ```svelte
 <div class="mywidget sketch-container {variant}">…</div>
@@ -71,8 +71,8 @@ picks up the card's corners.
 
 ## Variants, states and inner parts
 
-Nothing competes with you for these values, so every case is one more
-declaration at the specificity you already use.
+Nothing competes for these values, so every case is one more
+declaration at the specificity already in use.
 
 ```css
 .mywidget.danger      { --sketch-fill: var(--mywidget-danger-surface); }
@@ -86,7 +86,7 @@ no hover at all once the real background is transparent.
 
 An inner part that carries its own surface (a header strip, a footer) takes its
 own class and its own five values. The class is easy to forget, because the part
-already has its own values and looks finished without it — a part carrying only
+already has its own values and looks finished without it. A part carrying only
 the values is left crisp, and reads as a hard-edged rectangle dropped inside a
 drawn box. No checker sees it. Where such a part draws no outline, bind the
 hatch ink to the ink its **parent** is outlined in, so the component reads as one
@@ -124,7 +124,7 @@ colour or an image, so `--sketch-fill` accepts either.
 - **An element that owns `::before` or `::after`.** The layer claims both. A
   shimmer, a caret or a decorative arrow on the opted-in element is gone.
 - **A shipped part's selector** (`.card`, `.panel`). Borrowing one to get drawn
-  works, but it hands your component that part's colours and its damping, and it
+  works, but it hands the component that part's colours and its damping, and it
   is package-internal. The reserved classes are the contract.
 
 ## Rules, which are not boxes
@@ -143,12 +143,12 @@ Make the rule an element, give it `sketch-rule`, and name its ink as the fill.
 }
 ```
 
-## Media inside your component
+## Media inside the component
 
 A drawn part's `overflow` is visible so the fill and outline can travel past the
 box. A background that bleeds is the effect working. An image that bleeds is
 not, since it keeps square corners while the part around it turns. Media running
-to your component's edge has to carry the corners itself:
+to the component's edge has to carry the corners itself:
 
 ```css
 .mywidget-cover {
@@ -166,7 +166,7 @@ high spread the crop is the mean rather than an exact trace of the drawn edge.
 
 Icons and inline SVG take the wobble directly, since a glyph has no box to
 redraw. Body type is left alone deliberately: an icon is a shape and survives a
-wobble, a paragraph is not. You opt into none of this; it applies to every
+wobble, a paragraph is not. Nothing opts into this; it applies to every
 `[class*="fa-"]` and every `svg` under the scope.
 
 `--sketch-icon-off` names what a subtree's glyphs are drawn with instead. It
@@ -190,7 +190,7 @@ soft bank before reaching for `none`.
 A component authored inside the package does not use the reserved classes. Add a
 `PartSpec` row to `PART_SPECS` in `src/editor/core/sketch/sketchLayer.ts`
 instead, which is keyed to the component's own token stem and gets the shipped
-damping. `sketchPartTokens.test.ts` then holds you to it: every colour the layer
+damping. `sketchPartTokens.test.ts` then holds the component to it: every colour the layer
 paints must be one the component itself assigns to that same element, checked
 against the compiled `<style>` block.
 

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

@@ -44,6 +44,7 @@ to that list, so the two cannot drift apart.
 | `-border-width` | Stroke thickness (used even when CSS uses `outline:`)         |
 | `-thickness`    | Alternative to `-width` when fallback siblings would collide  |
 | `-accent-width` | An accent bar's thickness                                     |
+| `-indicator-width` | An indicator's thickness, moved with `-accent-width`      |
 | `-hairline-thickness` | A hairline rule's thickness                             |
 | `-dot-size`     | A dot indicator's diameter                                    |
 | `-divider-width` | A divider's thickness                                        |
@@ -80,6 +81,6 @@ when one fits; a stroke is `-border-width` even where the CSS says `outline:`.
 | `-line-height`     | Line height              |
 | `-letter-spacing`  | Letter spacing           |
 
-A suffix you need that is not here is either a rename away from one that is, or
+A suffix that is not here is either a rename away from one that is, or
 an issue against `@motion-proto/live-tokens`. Inventing one costs the token its
 picker: the editor falls back to a plain text input.

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

@@ -0,0 +1,187 @@
+---
+name: live-tokens-create-page
+description: Create a page in a @motion-proto/live-tokens project from the shipped components at their defaults and the theme's text styles. Use when the user asks for a page or a route. Use when the user asks to change the layout of a page. Edits page files and the route table. For a choice between two components, read live-tokens-pick-component. For a component the catalogue lacks, read live-tokens-create-component. For a theme change, read live-tokens-create-theme.
+---
+
+# Creating a page in a live-tokens project
+
+Assemble the page from the shipped components at their defaults and the theme's text styles. A change to a component is made in the components editor at `/live-tokens/components` and reaches every page. A change to the theme is made with **live-tokens-create-theme**.
+
+## Workflow
+
+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.
+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.
+8. Add the route, with a lazy import and the source path.
+9. Run **live-tokens-check-compliance**, then check the rendered page.
+10. Reply with the sections and the layout each took, the components placed, the route, and the compliance result.
+
+## Layout
+
+### Page layouts
+
+Decide the sections before the columns. Read the page top to bottom and name each section by its purpose: what the user reads, types into, or presses. Each section is a row of the page grid. Take the column spans from the layout that matches the reader's task.
+
+| Layout | Use when | Column spans |
+|---|---|---|
+| Stacked sections | The reader moves top to bottom: an opening, one section per topic, a close; or a stage, its inputs, and a toolbar. | Each section spans all columns. Copy spans half (6 of 12). |
+| Main with a supporting pane | One region is the work and the other adjusts or describes it. | Main two thirds (8), pane one third (4). |
+| List with detail | The reader picks an item from a list and inspects it. | List one third (4), detail two thirds (8). |
+| Grid of equals | The reader compares or scans items of one kind. | Equal spans. Up to seven per section. |
+| Single column | The reader fills a form or reads at length. | Half the columns (6), centered. |
+
+The stage is the canvas, player, or strip the work is about. Stretch a section's containers to one height (`align-items: stretch`) so their bottom edges align. Below the scaffold's 768px breakpoint, a section's columns stack in reading order.
+
+### Grid
+
+The page is the column grid: `display: grid`, `grid-template-columns: repeat(var(--columns-count), 1fr)`, `column-gap: var(--columns-gutter)`, `max-width: var(--columns-max-width)`, `margin: 0 auto`. Each section spans it with `grid-column: 1 / -1`.
+
+To place a section's children at page-column positions:
+
+1. Read `--columns-count` in the project's `tokens.css`.
+2. Span the parent grid with `grid-column: 1 / -1`.
+3. Redeclare `repeat(var(--columns-count), 1fr)` with `column-gap: var(--columns-gutter)`.
+4. Place each child by page-column numbers.
+
+A grid that follows the page columns takes `var(--columns-count)` or a `calc()` of it as its count, so it stays in step with `ColumnsOverlay`. A local grid of two or three equal columns writes its own count. A column number in `grid-column` is fixed to the count read in step 1.
+
+### Separation
+
+The page shows one thing, and every other element stays out of its way. Each element that is not content costs attention: a hairline, a border, a header bar, a shadow. Keep an element only when it serves a purpose no other element serves.
+
+Separate elements with the smallest difference that separates them: space first, then a hairline, then a second surface. Use one separator at a time. Two heavy borders side by side make a third shape between them, and a section of containers with borders and header bars reads as a set of posters.
+
+Color each element by its layer.
+
+| Layer | Color |
+|---|---|
+| Content | `--text-primary`, or the color `site.css` gives the element |
+| Label | `--text-secondary` |
+| Chrome | `--border-neutral` |
+| Overlay on content, such as a grid or a selection | `--border-brand`, which stays visible on any pixel |
+
+Show related items side by side when the width permits. A line of copy runs 45 to 90 characters; the copy span in Page layouts holds that at body size. On a tool page the stage is the content and each control is chrome, so the stage takes the space.
+
+`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 usage comment. `--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}`.
+
+## Tokens
+
+- When a design token exists for a value, page CSS takes the token as `var(--token)`. That holds in the `<style>` block, an inline `style=` attribute, and a `style:` directive.
+- A width is a span of page columns. The Layout section gives the grid.
+- A height follows the content. A stage's `minHeight` is the one fixed height, set from what the stage must show.
+- A value that comes from data, such as a sheet's padding in pixels or a chart's scale, is set through a `{}` expression.
+
+## Hierarchy
+
+### Type
+
+One text style per element. A text style has five axes: `-font-family`, `-font-size`, `-font-weight`, `-line-height`, and `-letter-spacing`. Set all five from the one style.
+
+| Element | Style |
+|---|---|
+| Page title | `h1` in `--heading-xl-*` |
+| Section title | `h2` in `--heading-lg-*`, or `SectionDivider variant="sm"` |
+| Card title | the Card `title` prop |
+| Label above a group | `--body-sm-*` in `--text-secondary` |
+| Body | `p` in `--body-md-*` |
+| Secondary line | `--body-sm-*` in `--text-secondary` |
+| Count, status, read-out | `--body-sm-*` in `--text-primary` |
+| Command or value | `code` in `--code-*` |
+
+Use the semantic element for each place: one `h1`, an `h2` for each section, `h3` inside a section, `p` for copy. Heading levels run in order with no skipped level. `site.css` types bare `h1` to `h4`, `p`, `code`, `pre`, and list items from these styles, so the tag carries the style. Type an element only when the table gives its tag a different style. A weight alone, on `strong` or a list marker, is the one axis a page sets by itself. A page shows at most two weights.
+
+### Size
+
+Omit `size` on every control and container. The shipped default is the page's 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`.
+
+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.
+
+### Spacing
+
+Each position takes one step of the `--space-*` scale. Space inside a group is smaller than space between groups. A shipped component carries its own inner spacing; the table names the space the page draws.
+
+| Position | Step |
+|---|---|
+| Between controls in a row | `--space-8` |
+| Inside a wrapper the page draws | `--space-16` |
+| Between fields in a form | `--space-20` |
+| Between containers in a section | `--columns-gutter` across, `--space-24` down |
+| Between sections | `--space-16` above a hairline |
+| Page title to first section | `--space-24`, no hairline |
+| Page margin | `--space-32` |
+
+Every section after the first opens with a hairline: `padding-top: var(--space-16)` and `border-top: var(--border-width-1) solid var(--border-neutral)`. The hairline separates, so the gap between sections is smaller than the gap between the containers inside them. A section's edge is the hairline alone.
+
+## Routing
+
+Add the route the way `App.svelte` already wires routes.
+
+- `<LiveTokensRouter pages={...}>`: add a `pages` entry with `lazy: () => import('./YourPage.svelte')` and `source: 'src/...'`. Add `label` and `icon` to show the page in the nav rail; omit `label` to keep the route reachable by URL alone. For a `/:id`, a path prefix, or a gated page, add `resolve(path) => RouteEntry | null` beside `pages`. The entry fields are the same.
+- Manual `<LiveEditorOverlay>`: dispatch with `$derived.by(() => import(...))` and register the route's source in `pageSources={...}`.
+
+Import the page with `lazy`, so page CSS stays off the editor routes. Import `site.css` from each page's `<script>` block for the same reason. `source` is what makes Page Source work. A page route sits outside `/live-tokens/*`, the namespace of the package's own routes, where `Editor` and `ComponentEditorPage` mount.
+
+```svelte
+const pages = {
+  '/pricing': {
+    lazy: () => import('./pages/Pricing.svelte'),
+    source: 'src/pages/Pricing.svelte',
+    label: 'Pricing',
+    icon: 'fa-tag',
+  },
+};
+```
+
+## Verify
+
+Run **live-tokens-check-compliance**. Its report carries both checkers' findings by rule, and **live-tokens-fix-findings** takes the fix list. Repeat until the page is clean.
+
+The checkers cannot see a layout. Open the page at the width it is built for and check each line below.
+
+- The first section holds what the user came for.
+- One `h1`. Heading levels run in order with no skipped level.
+- No label is larger than the page's body copy.
+- A line of copy runs 45 to 90 characters.
+- The containers in a section align at the bottom.
+- Every control stays inside its wrapper. A `width: 100%` field takes `box-sizing: border-box`.
+- 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`.
+- 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.
+- Labels use the user's words, such as "Export slices".
+- Every `img` has `alt` text. Focus order follows the reading order.
+
+`references/interaction-sources.md` names the sources for these checks.
+
+Then read the page from a distance: the sections and their edges are the only shapes that show. Then read it closely. For each border, header bar, and container, ask whether the page loses information when the element is removed. When the answer is no, remove the element. Find the element a reader sees first, second, and third, and confirm that is the reading order the page needs.

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

@@ -0,0 +1,66 @@
+# Interaction sources
+
+Read this when a Verify check or an emphasis rule in SKILL.md needs its reason.
+Each principle below is held by one of three parties. A shipped component
+holds it when the component's own design answers it, so the page's rule is
+the component and pick-component names the test. The page holds it when only
+the page can get it right, so SKILL.md states a read or the checker a rule.
+The product holds it when no page decision touches it, and the row says so
+to keep a later edit from reopening it.
+
+## Jakob Nielsen, ten usability heuristics
+
+| Heuristic | Holder | Rule in SKILL.md, or the component |
+|---|---|---|
+| 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`. |
+| 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. |
+| 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`. |
+| Help users recognise, diagnose, and recover from errors | Component | `Input` carries the error line; `Callout variant="danger"` carries a section's. |
+| Help and documentation | Product | Contextual help is a product decision. |
+
+The complex-application version of the ten (Kaley, Nielsen Norman Group)
+describes a tool with a stage and controls, which is the tool page SKILL.md
+lays out. Its additions that the page holds: a wait past ten seconds shows
+steps done and steps left, and the stage is the live preview of every
+control. Undo, version history, and autosave are the product's.
+
+## Bruce Tognazzini, first principles of interaction design
+
+| Principle | Holder | Rule in SKILL.md, or the component |
+|---|---|---|
+| Anticipation | Page | Layout: show related items side by side. |
+| Colour | Component | `Callout`, `Badge`, and `Notification` carry an icon or text beside the colour. |
+| Consistency | Page | One size, one primary action. |
+| Defaults | Page | Verify: every field has a default and Reset restores it. |
+| 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`. |
+| 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. |
+| Aesthetics, Autonomy, Efficiency of the user, Human-interface objects, Latency reduction, Learnability, Metaphors, State | Product | Measured, engineered, or researched outside a page. |
+
+Sources:
+
+- Nielsen, 10 Usability Heuristics for User Interface Design (1994, updated 2024). https://www.nngroup.com/articles/ten-usability-heuristics/
+- Kaley, 10 Usability Heuristics Applied to Complex Applications. https://www.nngroup.com/articles/usability-heuristics-complex-applications/
+- Tognazzini, First Principles of Interaction Design (revised 2014). https://asktog.com/atc/principles-of-interaction-design/
+
+## W3C Web Accessibility Initiative
+
+| Guidance | Holder | Rule in SKILL.md, or the component |
+|---|---|---|
+| Headings: one `h1`, levels in order, no skipped level | Page | Type: use the semantic element for each place. Verify: one `h1`, levels in order. |
+| Images: text alternatives | Page | Verify: every `img` has `alt` text. |
+| Focus order follows the reading order | Page | Verify: focus order follows the reading order. |
+| Form labels and error messages | Component | `Input` carries its label, hint, and error line. |
+
+https://www.w3.org/WAI/tutorials/page-structure/headings/
+https://www.w3.org/WAI/tutorials/images/
+https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html

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

@@ -0,0 +1,87 @@
+# Layout sources
+
+Read this when a layout decision in SKILL.md needs its reason. Each law in the
+Layout section comes from one of these sources. The sources are for layout and
+hierarchy only. Do not take color or type opinions from them: the theme owns
+those.
+
+## Edward Tufte
+
+Tufte wrote about information graphics. His laws apply to a page because a page
+is an information display with controls on it.
+
+| Law | Statement | Rule in SKILL.md |
+|---|---|---|
+| Smallest effective difference | Make all visual distinctions as subtle as possible, but still clear and effective. | Separate with space first, then a hairline rule, then a second surface. |
+| 1+1=3 | Two heavy marks side by side make a third mark: the space between them. | A section of containers with borders and header bars reads as a set of posters. |
+| Layering and separation | Put data on top, labels next, and scaffolding faintest. | Content, labels, and chrome each take their own token. |
+| Administrative debris | The metaphor for the interface is the information. Remove the chrome that the tool adds for itself. | The stage takes the space. Controls take their shipped default. |
+| Spatial over temporal | Show information adjacent in space. A control that hides it stacks it in time. | Show related items side by side. Frames in a strip are small multiples. |
+| Erase non-data ink | Remove each mark that carries no information. | The Verify question: does the page lose information when this element is removed? |
+| Micro and macro readings | A good display reads at a distance and up close. | Verify from a distance, then closely. |
+
+Sources:
+
+- Envisioning Information (1990): layering and separation, small multiples, micro and macro. https://www.edwardtufte.com/book/envisioning-information/
+- The Visual Display of Quantitative Information (1983): data-ink, chartjunk.
+- iPhone interface design, edwardtufte.com notebook: administrative debris, spatial over temporal. https://www.edwardtufte.com/notebook/iphone-interface-design/
+
+## Josef Müller-Brockmann
+
+Grid Systems in Graphic Design (1981) is the discipline behind the page column
+grid. The grid does the separating, so an element needs no border to show
+where it sits. His stated aim is compact planning, intelligibility, and
+clarity. That is Tufte's aim in a typographer's words.
+
+## Refactoring UI
+
+Adam Wathan and Steve Schoger, Refactoring UI (2018), turns both into working
+rules for product screens:
+
+- Put more space around a group than within it.
+- Start with too much white space, then remove some.
+- Use fewer borders. Separate with space, a shadow, or a second background.
+- Emphasize by de-emphasizing the secondary content.
+- Labels are a last resort.
+- Keep a spacing scale where no two steps are closer than a quarter. The `--space-*` scale is that scale.
+
+https://www.refactoringui.com/
+
+## Material Design 3, canonical layouts
+
+The Page layouts table takes its rows from Material's canonical layouts.
+
+| Layout | Statement | Row in SKILL.md |
+|---|---|---|
+| Supporting pane | The primary area takes about two thirds of the window; the secondary pane takes the rest. At compact width the pane moves below the main content. | Main with a supporting pane, two thirds and one third; the stacking sentence. |
+| List-detail | The list and the detail of the selected item sit side by side at expanded width. | List with detail. |
+| Feed | Equivalent items in an adaptive grid. | Grid of equals. |
+
+https://m3.material.io/foundations/layout/canonical-examples/overview
+https://developer.android.com/develop/adaptive-apps/guides/canonical-layouts
+
+## Cloudscape patterns
+
+| Pattern | Statement | Rule in SKILL.md |
+|---|---|---|
+| Dashboard | Three areas top to bottom: overview, data, support. "Consider seven as the limit number for data representation." | Verify: the first section holds what the user came for. Grid of equals: up to seven per section. |
+| Single-page create | One container; the essential fields first and few; secondary inputs in an expandable section; cancel then submit at the bottom. | Containers: a form. Single column. |
+| Details page | The title with its actions, then a summary, then related blocks. | Stacked sections. |
+| Empty state | A heading, an optional line, and one action. "Always provide an action." Errors go elsewhere. | Containers: an empty stage. |
+
+https://cloudscape.design/patterns/general/service-dashboard/static-dashboard/
+https://cloudscape.design/patterns/resource-management/create/single-page-create/
+https://cloudscape.design/patterns/resource-management/details/details-page/
+https://cloudscape.design/patterns/general/empty-states/
+
+## Matthew Butterick, line length
+
+"45 to 90 characters per line, including spaces." The Separation paragraph and the Verify check carry the measure, and the half-width copy span holds it at body size.
+
+https://practicaltypography.com/line-length.html
+
+## Nielsen Norman Group, proximity
+
+"Proximity is one of the most important grouping principles and can overpower competing visual cues such as similarity of color or shape." Space inside a group is smaller than space between groups. An unrelated action inside a group is camouflaged, so a `danger` Button sits apart from the toolbar group.
+
+https://www.nngroup.com/articles/gestalt-proximity/

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

@@ -1,55 +1,59 @@
 ---
 name: live-tokens-create-theme
-description: Create a complete live-tokens theme from a natural-language request by stating one design direction and routing a color intent, a type intent, and a geometry intent to live-tokens-set-colors, live-tokens-set-type, and live-tokens-set-geometry. Use whenever the user asks for a theme, look, vibe, or brand feel by mood, style, era, season, holiday, or hue; when they name only a color and want a theme around it; or when they refine a look across more than one dimension. Not for a single token (use the editor), and not for one dimension alone: color is live-tokens-set-colors, type is live-tokens-set-type, geometry is live-tokens-set-geometry.
+description: Create or modify a complete live-tokens theme from a natural-language request. A theme has three dimensions: color, typography, and geometry. The skill adjusts design token values and their assignment to semantic properties to create a new theme. Derives one design direction and routes a color intent, a type intent, and a geometry intent to live-tokens-set-colors, live-tokens-set-type, and live-tokens-set-geometry. Use when the user asks for a theme, look, vibe, or brand feel by mood, style, era, season, holiday, or hue. Use when the user names only a color and wants a theme around it. Use when the user refines a theme across more than one dimension. For color, type, or geometry named on its own, read that set skill.
 ---
 
 # Creating a theme from a request
 
-A look is three decisions: color, type, and geometry. This skill reads the
-**request**, the user's own words, and states one **design direction**, a line
-or two that fixes all three. From it come three **intents**, one per dimension,
-each naming an outcome and never a value. Each goes to the contributing skill
-that owns that dimension, and their three reports come back as one **assembled
-report**, so the whole look comes from one reading.
+A theme is built of three dimensions: color, type, and geometry. This skill
+reads the user's prompt, the **request**, and derives the **design direction**,
+a short summary covering three **intents**, one per dimension, each naming an
+outcome rather than a value. Each set skill receives the design direction and
+the intent for its own dimension as a goal, and reports back. The three reports
+combine into one **assembled report** for the whole theme.
 
-Every contributing skill writes its dimension into the unsaved buffers the app
-already renders, and those three buffers are the **look**. This skill runs one
-CLI of its own, `save-theme`, which turns the look into the **theme**, the
-document at `themes/<slug>.json`, and opens it. Never hand-author theme JSON and
-never edit the data tree directly.
+One **anchor** carries the direction across all three dimensions. It is a row
+label that `references/design-directions.md` and each set skill list under the
+same names: a feeling, an idiom, or an occasion. Naming it once points every set
+skill at the same row of its own table.
 
-## Workflow
+Each set skill writes its dimension into the working buffers the app already
+renders. This skill runs one CLI of its own, `save-theme`, which composes those
+buffers into a **theme**, the document at `themes/<slug>.json`, and opens it.
+Never hand-author theme JSON and never edit the data tree directly.
 
-1. Read the request once and state the design direction to the user: the mood, the hue family, the scheme, and the type and geometry that mood implies. It fixes enough to derive the three intents in step 3, and it names the default where the request leaves a dimension open. Keep it to a line or two. Every step below keys off it.
-2. Read `references/design-directions.md` and name the **anchor** the request matches: a feeling, an idiom, or an occasion that reference lists, each one fixing color, type, and geometry together. An idiom sets constraints and a feeling moves dials inside them, so a request matching both reads the idiom first. A request matching none takes the design direction alone.
-3. State the three intents the design direction and the anchor imply, one line each: the color intent, the type intent, and the geometry intent. Each names an outcome. Pass the anchor's name with each one, because every contributing skill holds its own anchors for its own dimension under the same names. Never reach for an OKLCH triple, a font family, or a token on a contributing skill's behalf.
-4. Invoke **live-tokens-set-colors** with the color intent. This step never skips: a theme request names a color identity, so color is the one dimension every look fixes.
-5. Invoke **live-tokens-set-type** with the type intent. Skip only when the user asked to leave the type alone.
-6. Invoke **live-tokens-set-geometry** with the geometry intent. Skip when the geometry intent is to leave the geometry alone.
-7. Take the theme name from the design direction and run `npx live-tokens save-theme "<name>"`. It composes the three buffers into `themes/<slug>.json` and opens it, so nothing is left unsaved. `--dry-run` prints what it would write.
-8. Assemble the three reports into the assembled report: the design direction, what each contributing skill changed, the theme `save-theme` wrote, and anything one of them flagged. Tell the user to look at the running app. Offer refinements (see Refining a look).
+## Workflow
 
-A set of themes runs steps 4 to 7 once per theme, with `--no-activate` on every
-save but the last, so each theme starts from the same live look.
+1. Read the request once and generate the design direction based on the prompt: the mood, and the color, typography, and geometry that mood implies. It describes the three intents for each set skill, and it names a default where the request leaves a dimension open. Keep it brief and clear. Every step below keys off it.
+2. Read `references/design-directions.md` and name the **anchor** the request matches: a feeling, idiom, or occasion the reference lists, each one fixing color, type, and geometry. An idiom sets constraints and a feeling moves dials inside them, so a request matching both reads the idiom first. A request matching none takes the design direction alone.
+3. Generate the three intents the design direction and the anchor imply, one line each: the color intent, the type intent, and the geometry intent. Each names an outcome. Pass the anchor and the matching intent to each set skill, because every set skill holds its own anchors for its own dimension under the same names. Never specify an OKLCH value, a font family, or a token on a set skill's behalf.
+4. Invoke **live-tokens-set-colors** with the anchor and the color intent. Skip only when the user asked to leave the color alone.
+5. Invoke **live-tokens-set-type** with the anchor and the type intent. Skip only when the user asked to leave the type alone.
+6. Invoke **live-tokens-set-geometry** with the anchor and the geometry intent. Skip when the geometry intent is to leave the geometry alone.
+7. Take the theme name from the design direction and run `npx live-tokens save-theme "<name>"`. It composes the buffers into `themes/<slug>.json` and loads it. `--dry-run` prints the file path and the layers instead. `--no-activate` writes the theme without loading it. A blank name and the name `default` exit 1. A name whose slug exists overwrites that theme in place. Adopt, in the editor, ships the theme to the site.
+8. Assemble the three set skill responses into the assembled report: the design direction, what each set skill changed, any dimension left alone, and anything one of them flagged. Review the result in the running app. Offer refinements (see Refining a theme).
 
-## What each contributing skill owns
+## Set skill responsibilities
 
-Hand an outcome and the anchor's name. The mechanics stay where they are.
+Invoke set skills with the anchor and the matching intent.
 
-| Dimension | Contributing skill | It decides |
+| Dimension | Set skill | It decides |
 |---|---|---|
-| color | live-tokens-set-colors | ten base colors, the scheme, harmony, the canvas commitment, the contrast pass |
-| type | live-tokens-set-type | the two families, the form models behind them, the weights |
-| geometry | live-tokens-set-geometry | radius, padding, gap, and border-width moves, global or per component |
+| color | live-tokens-set-colors | ten base colors, the scheme, harmony, the Canvas base color and its gradient, the contrast pass |
+| type | live-tokens-set-type | the families for up to five slots, the form models behind them, the weights |
+| geometry | live-tokens-set-geometry | radius, padding, gap, and border-width |
+
+A dimension the request left open still gets an intent, taken from the anchor.
+A dimension the request excludes gets no invocation at all, and the assembled report says which.
 
-A dimension the request leaves open still gets an intent, taken from the anchor.
-A dimension the request rules out gets no invocation at all, and the assembled
-report says which.
+Component aliases and swatch gradients carry forward from the buffers by value
+into the theme `save-theme` writes. At a set-colors run, gradients tuned in the
+editor survive and stock ones rebuild from the new families.
 
-## Refining a look
+## Refining a theme
 
-A refinement arrives against a theme that is already open, and one adjective
-usually names one dimension. Route it rather than re-reading the whole look:
+A refinement operates on an existing theme, and one adjective usually names one
+dimension. Route it to the matching set skill:
 
 | The user says | Goes to |
 |---|---|
@@ -57,24 +61,24 @@ usually names one dimension. Route it rather than re-reading the whole look:
 | more editorial, friendlier, more technical, a serif for headings | live-tokens-set-type |
 | rounder, sharper, pill buttons, tighter, airier, thicker borders | live-tokens-set-geometry |
 
+The table gives examples. Route every refinement request, whether or not its
+words appear there.
+
+When no refinement is requested, the theme is complete.
+
 Keep this skill for a refinement that spans dimensions ("make it feel more
 serious"), or one that names no dimension at all. State a new design direction
 and route all three again.
 
-## Files each step writes
-
-Color, type, and geometry each write an unsaved buffer, which the page already
-runs. `save-theme` composes the three into `themes/<slug>.json` and opens it,
-which clears the buffers; Adopt then ships the theme. Opening a theme never
-changes what the site ships. Only Adopt, in the editor, does that. Component
-aliases and gradients carry forward from the live look into the theme
-`save-theme` writes; user-tuned gradients survive, stock ones rebuild from the
-new families.
+Feedback about a page or a component ("make the buttons bigger", "move the
+hero up") is not a theme change: read **live-tokens-create-page** or
+**live-tokens-create-component**. A request for the previous theme is met by
+loading it from the editor's Theme panel; loading clears the buffers.
 
 ## Verify
 
-- Each contributing skill reports back, and `set-colors` exits 0 with every check passing (auto-corrected is fine).
+- Each invoked set skill reports its result. When invoked, `set-colors` exits 0 with every check passing (auto-corrected is fine).
 - `save-theme` exits 0 and names the theme it wrote and opened.
-- The app (dev server running) shows the whole look after a reload, and the editor's Theme panel names that theme with no unsaved marker.
-- The assembled report names one design direction, and the three intents trace to it.
-- To return to the previous look, load the earlier theme from the Theme panel.
+- The app (dev server running) shows the whole theme, and the editor's Theme panel names that theme with no pending changes.
+- The assembled report names one design direction, and the three intents come from it.
+- To return to the previous theme, load it from the Theme panel; loading clears the buffers too.