@motion-proto/live-tokens 0.94.2 → 0.95.0

package/src/editor/skill-atlas/SkillAtlas.svelte

@@ -1,7 +1,10 @@
 <script lang="ts">
   import { onMount, tick } from 'svelte';
+  import { MediaQuery } from 'svelte/reactivity';
   import { navigate, route } from '../core/routing/router';
+  import LabeledSelect from '../../demo/LabeledSelect.svelte';
   import Button from '../../system/components/Button.svelte';
+  import SegmentedControl from '../../system/components/SegmentedControl.svelte';
   import TabBar from '../../system/components/TabBar.svelte';
   import SourcePane from './SourcePane.svelte';
   import TreeCanvas from './TreeCanvas.svelte';
@@ -19,6 +22,8 @@
   let selection: Selection | null = $state(linked?.target ?? null);
   /** Which of the skill's documents the source pane shows. */
   let doc: string = $state(SKILL_DOC);
+  /** Which pane shows below the desktop lock, where the two would stack. */
+  let view: 'graph' | 'text' = $state('graph');
 
   let tree = $derived(skillTrees[active]);
   let docs = $derived(skillDocs[active]);
@@ -30,6 +35,13 @@
     label: `${t.title}\n${skillDocs[id][SKILL_DOC].length} lines`,
   }));
 
+  const skillItems = Object.entries(skillTrees).map(([id, t]) => ({ value: id, label: t.title }));
+
+  const views = [
+    { value: 'graph', label: 'Graph' },
+    { value: 'text', label: 'Text' },
+  ];
+
   let docTabs = $derived(
     Object.keys(docs).map((name) => ({
       id: name,
@@ -37,9 +49,19 @@
     })),
   );
 
+  // Matches the desktop lock in the styles: above it each pane scrolls on its
+  // own, below it the page does.
+  const locked = new MediaQuery('min-width: 64rem');
+
+  function toTop(pane: HTMLElement | undefined) {
+    if (locked.current) pane?.scrollTo({ top: 0 });
+    else window.scrollTo({ top: 0 });
+  }
+
   function openDoc(name: string) {
     doc = name;
-    sourcePane?.scrollTo({ top: 0 });
+    view = 'text';
+    toTop(sourcePane);
   }
 
   function selectTarget(key: string, label: string, range: LineRange) {
@@ -84,13 +106,26 @@
       ?.scrollIntoView({ block: 'center', behavior: 'smooth' });
   }
 
+  // A pane hidden behind the switch has no layout, so its scroll to the
+  // selection has to wait until it shows.
+  async function changeView(next: string) {
+    view = next as typeof view;
+    if (!selection) return;
+    if (view === 'graph') {
+      await tick();
+      scrollTreeTo(selection.key);
+    } else if (doc === SKILL_DOC) {
+      scrollSourceTo(selection.lines[0]);
+    }
+  }
+
   function changeTab(id: string) {
     active = id;
     selection = null;
     doc = SKILL_DOC;
     shareSelection();
-    treePane?.scrollTo({ top: 0 });
-    sourcePane?.scrollTo({ top: 0 });
+    toTop(treePane);
+    toTop(sourcePane);
   }
 
   function openLink(hash: string) {
@@ -129,18 +164,24 @@
 <div class="skill-atlas">
   <header class="masthead">
     <div class="masthead-top">
-      <h1>Skill Atlas</h1>
       <Button variant="primary" onclick={() => navigate('/')} icon="fas fa-arrow-left" iconPosition="left">
         Back to Demo
       </Button>
+      <h1>Skill Atlas</h1>
     </div>
   </header>
 
   <div class="tabs">
-    <TabBar {tabs} value={active} onchange={changeTab} />
+    <div class="tab-strip">
+      <TabBar {tabs} value={active} onchange={changeTab} />
+    </div>
+    <div class="picker">
+      <LabeledSelect label="Skill" items={skillItems} value={active} onchange={changeTab} />
+      <SegmentedControl segments={views} value={view} onchange={changeView} />
+    </div>
   </div>
 
-  <div class="split">
+  <div class="split" data-view={view}>
     <section class="pane" aria-label="{tree.id} decision tree">
       <div class="pane-head">
         <span class="pane-title">{tree.id}</span>
@@ -192,22 +233,18 @@
 
   .masthead-top {
     display: flex;
-    align-items: center;
-    /* Beside the title, not at the far right: the editor overlay pins top-right
-       and would cover a button parked there. */
-    gap: var(--space-24);
-    flex-wrap: wrap;
-    /* The row carries the heading's own margins; align-items centres the margin
-       box, so a margin left on the h1 offsets the title against the button by
-       half of it. */
+    flex-direction: column;
+    align-items: flex-start;
+    gap: var(--space-32);
   }
 
+  /* The home page's heading style, so the two pages title alike. */
   .masthead-top h1 {
-    font-family: var(--heading-xl-font-family);
-    font-size: var(--heading-xl-font-size);
-    font-weight: var(--heading-xl-font-weight);
-    line-height: var(--heading-xl-line-height);
-    letter-spacing: var(--heading-xl-letter-spacing);
+    font-family: var(--display-xl-font-family);
+    font-size: var(--display-xl-font-size);
+    font-weight: var(--display-xl-font-weight);
+    line-height: var(--display-xl-line-height);
+    letter-spacing: var(--display-xl-letter-spacing);
     color: var(--text-primary);
     margin: 0;
   }
@@ -223,9 +260,36 @@
     padding-bottom: var(--space-40);
     background: var(--page-bg);
     background-attachment: var(--page-bg-attachment, fixed);
+  }
+
+  /* Below the desktop lock a dropdown replaces the strip, which would scroll
+     sideways past most of the skills. */
+  .tab-strip {
+    display: none;
     overflow-x: auto;
   }
 
+  .picker {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: var(--space-16);
+  }
+
+  .picker :global(.labeled-select) {
+    align-self: stretch;
+    align-items: stretch;
+  }
+
+  .picker :global(.segmented-control) {
+    align-self: stretch;
+  }
+
+  .picker :global(.segment) {
+    flex: 1;
+    justify-content: center;
+  }
+
   /* The label carries its own newline, so the line count sits under the skill
      name instead of wrapping wherever the strip happens to run out. */
   .tabs :global(.tab span) {
@@ -239,13 +303,19 @@
     gap: var(--space-32);
   }
 
-  /* The reference tabs only exist on the source pane, so a body of its own
-     fixed height would leave the two panes ending at different places. */
+  .split[data-view='graph'] .pane-source,
+  .split[data-view='text'] .pane:not(.pane-source) {
+    display: none;
+  }
+
+  /* Below the desktop lock a pane grows to its content and the page scrolls:
+     a scroll area nested in a scrolling page traps a phone's swipe. Isolated,
+     so the cards' raised badges stay under the pinned strip. */
   .pane {
     display: flex;
     flex-direction: column;
-    height: 82vh;
     min-width: 0;
+    isolation: isolate;
     border: var(--border-width-1) solid var(--border-neutral-subtle);
     border-radius: var(--radius-3xl);
     background: var(--surface-neutral-lowest);
@@ -318,8 +388,7 @@
   }
 
   /* Desktop: the surface locks to the viewport and each pane scrolls on its
-     own, so nothing ever slides under the tab strip. Placed after the base
-     .pane rule: its 82vh would otherwise win on source order. The router wrapper
+     own, so nothing ever slides under the tab strip. The router wrapper
      assumes window-scroll pages (min-height + a 12rem bottom pad); the doubled
      .lt-app outranks its scoped rule on a specificity tie. The child
      combinator keeps the demo home out: it has an .atlas of its own. */
@@ -344,6 +413,18 @@
       flex: 0 0 auto;
     }
 
+    .tab-strip {
+      display: block;
+    }
+
+    .picker {
+      display: none;
+    }
+
+    .split[data-view] .pane {
+      display: flex;
+    }
+
     /* minmax(0, 1fr) pins the row to the remaining height; an auto row would
        grow to the panes' content and break their scroll. */
     .split {
@@ -359,6 +440,12 @@
     }
   }
 
+  @media (max-width: 600px) {
+    .skill-atlas {
+      padding-inline: var(--space-16);
+    }
+  }
+
   @media (prefers-reduced-motion: reduce) {
     .pane-body {
       scroll-behavior: auto;

package/src/editor/skill-atlas/TreeCanvas.svelte

@@ -128,7 +128,15 @@
         marker-end={wire.arrow ? 'url(#atlas-arrow)' : undefined}
       />
     {/each}
+  </svg>
 
+  <svg
+    class="wires wire-labels"
+    viewBox="0 0 {canvasSize.w} {canvasSize.h}"
+    width={canvasSize.w}
+    height={canvasSize.h}
+    aria-hidden="true"
+  >
     {#each labels as label, i (i)}
       <text
         class="wire-label"
@@ -200,6 +208,12 @@
   }
 
   /* The halo breaks the wire so the answer reads on its own ground. */
+  /* Sketch mode filters every inline svg as artwork, which smears type. The
+     labels get their own svg so the wires stay drawn and the answers crisp. */
+  .wire-labels {
+    --sketch-icon-off: none;
+  }
+
   .wire-label {
     font-family: var(--code-font-family);
     font-size: var(--font-size-sm);

package/src/editor/skill-atlas/skillSources.generated.ts

@@ -17,7 +17,7 @@ export const skillDocs: Record<string, Record<string, string[]>> = {
     "references/token-naming.md": ["# Suffix vocabulary","","The editor picker is chosen by suffix. There is no per-token override; if a","token renders with the wrong picker, rename it to one of these.","","`KIND_RULES` in `src/editor/core/components/aliasKinds.ts` is authoritative, and","`check-component` fails on a suffix outside it. `check:skills` holds this file","to that list, so the two cannot drift apart.","","## Color and surface","","| Suffix      | Meaning                                                       |","|-------------|---------------------------------------------------------------|","| `-surface`  | Fill / background color                                        |","| `-border`   | Border color                                                  |","| `-text`     | Text color                                                    |","| `-icon`     | Icon color                                                    |","| `-label`    | Label text color                                              |","| `-fill`     | Inner fill (distinct from outer surface)                      |","| `-color`    | A hairline rule's colour, or a color no role word above names |","| `-shadow`   | Box-shadow                                                    |","| `-blur`     | Backdrop or filter blur radius                                |","| `-tint`     | A wash over the surface, aliasing a `--tint-*` stop            |","| `-indicator` | The colour of the bar or stripe that marks an item             |","| `-thumb`    | A scrollbar or slider thumb's colour                           |","| `-title`    | Title text colour                                              |","| `-body`     | Body text colour                                               |","| `-eyebrow`  | Eyebrow text colour                                            |","| `-description` | Description text colour                                     |","| `-hint`     | Hint text colour                                               |","| `-error`    | Error text colour                                              |","| `-placeholder` | Placeholder text colour                                     |","| `-value`    | A displayed value's colour                                     |","","## Geometry","","| Suffix          | Meaning                                                       |","|-----------------|---------------------------------------------------------------|","| `-radius`       | Corner radius                                                 |","| `-border-width` | Stroke thickness (used even when CSS uses `outline:`)         |","| `-indicator-width` | An indicator's thickness                                  |","| `-hairline-width` | A hairline rule's thickness                               |","| `-dot-size`     | A dot indicator's diameter                                    |","| `-hairline-inset` | Inset trimmed from a stretched hairline                     |","| `-track-height` | A track's height (progress bar, slider)                       |","| `-icon-size`    | An icon's rendered size                                       |","| `-thumb-size`   | A thumb's rendered size                                       |","| `-height`       | A measured height (a track, a panel)                          |","| `-margin`       | Outer spacing, moved on the same scale as `-padding`          |","| `-duration`     | Motion duration                                               |","| `-easing`       | Motion easing curve                                           |","| `-scale`        | A transform scale factor                                      |","| `-width`        | Width dimension                                               |","| `-size`         | Square / uniform dimension                                    |","| `-padding`      | Internal spacing                                              |","| `-gap`          | Spacing between sibling elements                              |","","`-width`, `-height` and `-size` are the fall-through: any dimension with no","more specific name behind it. They read the `--space-*` scale through the same","picker `-gap` uses, and they match last, so `-border-width`, `-hairline-width`,","`-icon-size` and the rest claim their token first. Reach for the specific name","when one fits; a stroke is `-border-width` even where the CSS says `outline:`.","","## Typography","","| Suffix             | Meaning                  |","|--------------------|--------------------------|","| `-font-family`     | Font family reference    |","| `-font-weight`     | Font weight reference    |","| `-font-size`       | Font size reference      |","| `-line-height`     | Line height              |","| `-letter-spacing`  | Letter spacing           |","","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."],
   },
   "create-page": {
-    "SKILL.md": ["---","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. `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.","8. Add the route, with a lazy import and the source path.","9. Run `npx live-tokens check-page <file> --tests --strict --json` until it exits 0, then check the rendered page.","10. Reply with the sections and the layout each took, the components placed, the route, and the check-page 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.","","### 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.","","No scaffold collapses the page grid on a phone: the theme's own column gutter alone exceeds a phone's width at the full column count, so every page writes its own `@media (max-width: 767px)` rule setting `grid-template-columns: 1fr` and `column-gap: 0`, with each section's children spanning `grid-column: 1 / -1`. A section's columns then stack in reading order.","","### 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.","","## Components","","- Use a shipped component when one fits. Import it from `@motion-proto/live-tokens/components/<Name>.svelte`.","- `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","","- 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.","","The text styles fall into five usages, each a scale of seven steps from `2xs` to `2xl`: display for type outside the page outline, heading for the outline, body for interface text and short copy, editorial for long reading, and code. Each step is a style named `--{usage}-{step}-*`, such as `--body-sm-*`. Headings use the whole set. The other usages mostly take `md` and `sm`.","","| Element | Style |","|---|---|","| Page title | `h1` in `--heading-xl-*` |","| Section title | `h2` in `--heading-lg-*`, or `SectionDivider variant=\"sm\"` |","| Title inside a section | `h3` to `h6` in `--heading-md-*` to `--heading-2xs-*` |","| Card title | the Card `title` prop |","| Hero title | `--display-xl-*` |","| Big number | `--display-md-*` |","| 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` |","| Article copy | `p` in `--editorial-md-*` |","| Code block | `pre` in `--code-md-*` |","| Command or value in a line | `code`, at `0.875em` of the text around it |","","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 `h6`, `p`, `small`, `code`, `pre`, and list items from these styles, so the tag carries the style. It also gives every step a class of the same name, such as `.display-md` or `.body-sm`, that sets all five axes. Type an element only when the table gives its tag a different style, and type it with the step's class. 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. `check-page` reports a `size` attribute on a shipped component as `control-size`.","","### Emphasis","","`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.","","### 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 `npx live-tokens check-page <file> --tests --strict --json`. It applies every `auto` repair, runs the Playwright suite against the page's own route, and returns the fixes it applied and the findings that remain. The suite proves what only a rendered page can: the cascade leaves every component painting from its semantic properties, every run of text sits in one shipped text style, every text and surface pair meets AA, sections sit on the page grid, and nothing overflows. `--off=<rule>` silences a rule for one run, and `--no-fix` reports without editing.","","Each remaining finding carries a rule id, a line, and its `guidance`. Make each remaining repair from its guidance, and run the command again until it exits 0.","","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.","- 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.","- 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.","- 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."],
+    "SKILL.md": ["---","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. `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.","8. Add the route, with a lazy import and the source path.","9. Run `npx live-tokens check-page <file> --tests --strict --json` until it exits 0, then check the rendered page.","10. Reply with the sections and the layout each took, the components placed, the route, and the check-page 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.","","### Grid","","The page is the column grid: `display: grid`, `grid-template-columns: repeat(var(--columns-count), 1fr)`, `column-gap: var(--columns-gutter)`, `box-sizing: content-box`, `max-width: var(--columns-max-width)`, `margin: 0 auto`, and `padding-inline: var(--columns-margin)`. Each section spans it with `grid-column: 1 / -1`. The page sets its top and bottom space with `padding-block`.","","The columns span `--columns-max-width`, and the margin sits outside them, where `ColumnsOverlay` draws it. `box-sizing: content-box` keeps a project-wide `border-box` reset from narrowing the columns.","","The page keeps the grid at every width. `tokens.css` narrows `--columns-gutter` and `--columns-margin` at 767px and again at 480px, and `--columns-count` holds at every width, so the page grid itself takes no `@media` rule.","","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.","","Spans count twelfths of the page at every width, so `span 6` is half the page on a desktop and on a phone. Widen the spans on a narrow screen. In a `@media (max-width: 767px)` rule, give a child that spans 4 on a desktop `span 6`, or give each child `grid-column: 1 / -1` to stack the section in reading order. A column at 390px is about 15px wide, so in a `@media (max-width: 480px)` rule each child spans 12, 6, or 4 columns.","","### 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.","","## Components","","- Use a shipped component when one fits. Import it from `@motion-proto/live-tokens/components/<Name>.svelte`.","- `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","","- 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.","","The text styles fall into five usages, each a scale of seven steps from `2xs` to `2xl`: display for type outside the page outline, heading for the outline, body for interface text and short copy, editorial for long reading, and code. Each step is a style named `--{usage}-{step}-*`, such as `--body-sm-*`. Headings use the whole set. The other usages mostly take `md` and `sm`.","","| Element | Style |","|---|---|","| Page title | `h1` in `--heading-xl-*` |","| Section title | `h2` in `--heading-lg-*`, or `SectionDivider variant=\"sm\"` |","| Title inside a section | `h3` to `h6` in `--heading-md-*` to `--heading-2xs-*` |","| Card title | the Card `title` prop |","| Hero title | `--display-xl-*` |","| Big number | `--display-md-*` |","| 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` |","| Article copy | `p` in `--editorial-md-*` |","| Code block | `pre` in `--code-md-*` |","| Command or value in a line | `code`, at `0.875em` of the text around it |","","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 `h6`, `p`, `small`, `code`, `pre`, and list items from these styles, so the tag carries the style. It also gives every step a class of the same name, such as `.display-md` or `.body-sm`, that sets all five axes. Type an element only when the table gives its tag a different style, and type it with the step's class. 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. `check-page` reports a `size` attribute on a shipped component as `control-size`.","","### Emphasis","","`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.","","### 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 | `--columns-margin`, as the page grid's `padding-inline` |","","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 `npx live-tokens check-page <file> --tests --strict --json`. It applies every `auto` repair, runs the Playwright suite against the page's own route, and returns the fixes it applied and the findings that remain. The suite proves what only a rendered page can: the cascade leaves every component painting from its semantic properties, every run of text sits in one shipped text style, every text and surface pair meets AA, sections sit on the page grid, and nothing overflows. `--off=<rule>` silences a rule for one run, and `--no-fix` reports without editing.","","Each remaining finding carries a rule id, a line, and its `guidance`. Make each remaining repair from its guidance, and run the command again until it exits 0.","","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.","- 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.","- 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.","- 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."],
     "references/interaction-sources.md": ["# 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: `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: `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: `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. |","| 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"],
     "references/layout-sources.md": ["# 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/src/editor/skill-atlas/trees/create-page.ts

@@ -2,7 +2,7 @@ import type { SkillTree } from '../types';
 
 export const createPage: SkillTree = {
   "id": "live-tokens-create-page",
-  "digest": "sha256:dac3be326461ce44",
+  "digest": "sha256:a3d5c66949b280b6",
   "title": "create-page",
   "tagline": "Create a Page Using Live Tokens",
   "nodes": [
@@ -71,13 +71,13 @@ export const createPage: SkillTree = {
       "chips": [
         {
           "label": "Grid",
-          "lines": [39, 52],
+          "lines": [39, 56],
           "anchor": "### Grid",
-          "anchorEnd": "No scaffold collapses the page grid on a phone: the theme's "
+          "anchorEnd": "Spans count twelfths of the page at every width, so `span 6`"
         },
         {
           "label": "Separation",
-          "lines": [54, 71],
+          "lines": [58, 75],
           "anchor": "### Separation",
           "anchorEnd": "`references/layout-sources.md` names the sources for these l"
         }
@@ -94,27 +94,27 @@ export const createPage: SkillTree = {
       "chips": [
         {
           "label": "Stage",
-          "lines": [81, 81],
+          "lines": [85, 85],
           "anchor": "An empty stage shows a heading that names the condition and "
         },
         {
           "label": "Card",
-          "lines": [82, 82],
+          "lines": [86, 86],
           "anchor": "A container in a tool UI labels itself: `Card variant=\"bare\""
         },
         {
           "label": "Form",
-          "lines": [83, 83],
+          "lines": [87, 87],
           "anchor": "A row of fields is a flex row with `gap: var(--space-20)`; e"
         },
         {
           "label": "Buttons",
-          "lines": [84, 84],
+          "lines": [88, 88],
           "anchor": "A toolbar is a flex row of Buttons on the section's bottom e"
         },
         {
           "label": "Picker",
-          "lines": [85, 85],
+          "lines": [89, 89],
           "anchor": "For a `MenuSelect` picker, toggle it from a Button with a tr"
         }
       ]
@@ -130,7 +130,7 @@ export const createPage: SkillTree = {
       "chips": [
         {
           "label": "Components",
-          "lines": [73, 80],
+          "lines": [77, 84],
           "anchor": "## Components",
           "anchorEnd": "Text inside a `Card` or a `CollapsibleSection` takes the con"
         },
@@ -158,25 +158,25 @@ export const createPage: SkillTree = {
       "chips": [
         {
           "label": "Tokens",
-          "lines": [96, 101],
+          "lines": [100, 105],
           "anchor": "## Tokens",
           "anchorEnd": "A value that comes from data, such as a sheet's padding in p"
         },
         {
           "label": "Type",
-          "lines": [105, 127],
+          "lines": [109, 131],
           "anchor": "### Type",
           "anchorEnd": "Use the semantic element for each place: one `h1`, an `h2` f"
         },
         {
           "label": "Size and emphasis",
-          "lines": [129, 137],
+          "lines": [133, 141],
           "anchor": "### Size",
           "anchorEnd": "In a row of actions the primary sits last, on the right. Up "
         },
         {
           "label": "Spacing",
-          "lines": [139, 153],
+          "lines": [143, 157],
           "anchor": "### Spacing",
           "anchorEnd": "Every section after the first opens with a hairline: `paddin"
         }
@@ -193,12 +193,12 @@ export const createPage: SkillTree = {
       "chips": [
         {
           "label": "LiveTokensRouter",
-          "lines": [159, 159],
+          "lines": [163, 163],
           "anchor": "`<LiveTokensRouter pages={...}>`: add a `pages` entry with `"
         },
         {
           "label": "LiveEditorOverlay",
-          "lines": [160, 160],
+          "lines": [164, 164],
           "anchor": "Manual `<LiveEditorOverlay>`: dispatch with `$derived.by(() "
         }
       ]
@@ -209,7 +209,7 @@ export const createPage: SkillTree = {
       "kind": "cli",
       "title": "Run check-page",
       "desc": "check-page --tests --strict --json applies every auto repair, proves the rendered page at its own route, and returns the fixes beside the remaining findings.",
-      "lines": [177, 177],
+      "lines": [181, 181],
       "anchor": "Run `npx live-tokens check-page <file> --tests --strict --js"
     },
     {
@@ -218,7 +218,7 @@ export const createPage: SkillTree = {
       "kind": "gate",
       "title": "Repair from guidance",
       "desc": "Each remaining finding carries its guidance. Make each repair, then run check-page again.",
-      "lines": [179, 179],
+      "lines": [183, 183],
       "anchor": "Each remaining finding carries a rule id, a line, and its `g"
     },
     {
@@ -227,31 +227,31 @@ export const createPage: SkillTree = {
       "kind": "chipset",
       "title": "Check the page in the browser",
       "desc": "The checkers cannot see a layout. Open the page at its width and check each line.",
-      "lines": [181, 197],
+      "lines": [185, 201],
       "anchor": "The checkers cannot see a layout. Open the page at the width",
       "anchorEnd": "`references/interaction-sources.md` names the sources for th",
       "chips": [
         {
           "label": "Structure",
-          "lines": [183, 187],
+          "lines": [187, 191],
           "anchor": "The first section holds what the user came for.",
           "anchorEnd": "The containers in a section align at the bottom."
         },
         {
           "label": "Actions",
-          "lines": [188, 191],
+          "lines": [192, 195],
           "anchor": "The actions sit where the eye goes last, with the one primar",
           "anchorEnd": "An action that runs longer than a moment shows progress in a"
         },
         {
           "label": "Fields",
-          "lines": [192, 193],
+          "lines": [196, 197],
           "anchor": "Every field has a default, and Reset restores it.",
           "anchorEnd": "Secondary settings sit in a `CollapsibleSection`. Every cont"
         },
         {
           "label": "Words and access",
-          "lines": [194, 195],
+          "lines": [198, 199],
           "anchor": "Labels use the user's words, such as \"Export slices\".",
           "anchorEnd": "Every `img` has `alt` text. Focus order follows the reading "
         }
@@ -263,7 +263,7 @@ export const createPage: SkillTree = {
       "kind": "step",
       "title": "Read the page twice",
       "desc": "From a distance only the sections show. Up close, every border and bar earns its place or goes.",
-      "lines": [199, 199],
+      "lines": [203, 203],
       "anchor": "Then read the page from a distance: the sections and their e"
     },
     {