@milesroxas/design-hub 0.0.0-stage → 0.1.0

package/skills/miles-new-feature/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: miles-new-feature
+description: "Start a feature or a prototype: the folder, the README with its question and states, docs/sprints/<feature>/ with the design doc and the walkthrough. Load when the user names a new feature, page, flow or exploration, or asks for a new prototype. Triggers on: new feature, new prototype, start a prototype, scaffold, pnpm new, sprint, alternate, exploration, design doc, walkthrough, guide."
+---
+
+# New feature
+
+One feature is one slug used in two places: `docs/sprints/<slug>/` and the `feature:` line of every prototype that belongs to it. This skill makes both, in an order that puts the question before the code.
+
+## Procedure
+
+1. **Name the slug.** Kebab-case, the feature's name in the product's words (`bulk-export`, not `feature-2`). It never changes once a prototype carries it, because the index, the walkthrough route and the port report all key on it.
+2. **Which kind?** Walk this; the first match wins.
+   - The feature's main prototype, the one its walkthrough opens → `--sprint`. One per feature; `pnpm new` refuses a second.
+   - Another full take on the same flow, to compare against the primary → `--alternate`. Refused until the primary exists.
+   - A side question about one part (a menu's motion, a loading state) → exploration, the default.
+3. **Where does it stand?** `--app` when the question is about the feature in context (the shell from `DESIGN.md`, Shell); nothing when it is one thing alone in the Space.
+4. **Scaffold.** From the project root:
+   ```bash
+   pnpm new <slug> --app --sprint --feature <feature> --title "Title"
+   pnpm guide <feature>              # once per feature, for the sprint
+   ```
+   The scaffolder fills the frontmatter and refuses a bad slug, a second sprint, or an alternate without a primary. Never create the folder by hand: a folder without the README's frontmatter is invisible to the index.
+5. **Write the README before any code**, top to bottom:
+   - **Problem.** What is wrong or unknown today, and for whom. Two sentences.
+   - **Question.** The one decision the prototype exists to make. One sentence, a question mark. If there are two questions, there are two prototypes.
+   - **Flows** (app) or **Directions** (space). A table: each flow with where it starts and its edge cases; each direction with its name and the axis it varies on.
+   - **States.** Every state the prototype will hold and how to reach it. Start with the five fixture sets (`miles-get-hostile`); add the feature's own (selected, editing, a run in progress). The guard and `miles-port` read this table.
+   - **Fixtures.** Where `real` comes from and the design's maximum count.
+   - **Decision.** Empty.
+6. **Design doc.** `docs/sprints/<slug>/design-doc.md` holds what the prototype tests: the context, the proposal, the open decisions. Write it when the feature has more than one flow; a single exploration needs only its README.
+7. **Then build**, under `miles-prototype`.
+
+## The walkthrough
+
+`docs/sprints/<feature>/guide.md` is for the reviewer who has the password and not the repo. It is written from the States table: one section per workflow, then "Every state, and how to reach it" copied from the README, then what the prototype does not do, then what the review must settle. Screenshots go in `assets/guide/` beside it, named in order (`01-list.jpg`); a missing file fails the build. Write it before the share link goes out (`miles-deploy` checks it exists for a sprint).
+
+## When done means decided
+
+When the user picks: the Decision section gets what was chosen, its values, what was rejected and why; then the folder is deleted, or `status: archived` when the user wants it kept. A rule the decision made lands in `DESIGN.md` as a named rule the same day.

package/skills/miles-paper-to-prototype/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: miles-paper-to-prototype
+description: "Turn a Paper Desktop comp into prototype conventions: tokens into kit/tokens.css, the shell into kit/shell.ts, components onto @kit/ui, content into fixtures. Load on every Paper MCP read, not only the first. Triggers on: Paper, Paper Desktop, paper.design, comp, frame, artboard, get_jsx, get_computed_styles, get_tokens, from the design, match the comp, the design says."
+---
+
+# Paper to prototype
+
+Paper is the source of the design; the prototype is built from its values, never from its code. This skill loads on every Paper read, because the drift it prevents compounds: a size read off a screenshot is a few pixels out, and three components later the page is a different design.
+
+## Hard rules
+
+1. **Values come from the tools, never from a screenshot.** Sizes, spacing, colours and type come from `get_computed_styles`, `get_tokens` and `get_font_family_info`; structure from `get_jsx` and `get_tree_summary`. `get_screenshot` is for seeing the whole, never for measuring. Why: screenshot values drift by a few pixels and the drift compounds across components.
+2. **Never paste Paper JSX.** It is a reference for structure and values. The prototype is written in `@kit/ui` and the feature's own CSS on `kit/tokens.css` variables. Why: pasted JSX carries inline values and Paper's class names, which is a second design system beside the kit's.
+3. **Tokens land once.** A value the design uses in two places becomes a token in `kit/tokens.css` under the kit's existing name, and `DESIGN.md`'s frontmatter gets the same value. A value used once stays a raw value in the feature's CSS, named in the README.
+4. **The comp decides, the kit draws.** Where the comp and `@kit/ui` disagree on a control, the comp wins inside the feature folder (fork the control there); the kit changes only when the shell or a second feature needs it too.
+
+## Procedure
+
+1. **Open the file.** `get_basic_info` for the artboards and their sizes; `get_selection` when the user is pointing at something. Omit `fileId` to read the file the user has open.
+2. **Fonts first.** `get_font_family_info` before any type is styled. Write the family to `--font` in `tokens.css`; add the `@font-face` there if the design names a file. Do this once per project.
+3. **Tokens.** `get_tokens` for the project's palette, spacing and radii. Map each onto the kit's names (the table below). Write `tokens.css` light and dark, and `DESIGN.md` frontmatter, in one change. A design with no dark values gets the kit's dark derived by the same steps (neutral surfaces step down, brand lifts one step). When the repo has `design-system/` (the Elyx add-on), run `pnpm elyx` in the same change and never edit that folder: it is generated from `tokens.css`, and an edit there is lost on the next run.
+4. **The shell.** Read `DESIGN.md`, Shell. If it names frames, `get_computed_styles` on each and fill `kit/shell.ts` (brand, nav, footer) and the shell CSS in `kit/`. If it is empty, prototypes stand in the Space and the shell is not built.
+5. **The feature frame.** `get_tree_summary` for the structure, `get_computed_styles` on each component node for its values. Build top down in `@kit/ui` and the feature's CSS. Content on the frame goes to `fixtures.json` `real`, word for word (`miles-get-hostile`).
+6. **Compare.** `get_screenshot` of the frame beside the prototype at the same width. Fix what differs by measuring the node again, never by eye.
+7. **Visual match, only with TypeSafe on.** Export the frame as PNG and screenshot the prototype in the same state, both between 280 and 1568 px a side, then `pnpm visual-match <slug> --comp <png> --shot <png>`. It answers three questions: an element missing, an element added, a changed order. Treat a finding as a place to look, then measure the node; never act on it for a size or a colour. Why: Jev reads images in an experimental mode and is weak on numbers, so it can point at a difference but never measure one.
+
+## Token map
+
+Kit names stay; values change. The common Paper names and where they land:
+
+| In the design | In the kit |
+| --- | --- |
+| primary, accent, brand | `--brand-*` and the `--bg-brand-*`, `--button-primary-*`, `--border-brand`, `--fg-brand-*` tokens |
+| text, foreground, ink | `--text-primary`, `--text-secondary`, `--text-tertiary`, `--text-quaternary` |
+| background, surface, canvas | `--bg-primary`, `--bg-secondary`, `--bg-tertiary` |
+| border, stroke, divider | `--border-primary`, `--border-secondary` |
+| radius | `--radius-xs` to `--radius-2xl` |
+| shadow, elevation | `--shadow-xs` to `--shadow-xl` |
+| font family, weight, size | `--font`, and the hierarchy in `DESIGN.md`, Typography |
+| easing, duration | `--ease-*`, `--dur-*`; a curve the design names and the kit lacks is added once with a comment |
+
+A design value with no kit name is added to `tokens.css` under a kit-shaped name (`--bg-brand-subtle`), noted in `DESIGN.md`, and never written raw in two places.
+
+## Done
+
+The feature's values are in `tokens.css` and `DESIGN.md` and nowhere else; the shell, when there is one, is in `kit/shell.ts`; the prototype's CSS uses only `var(--…)` and the raw values its README names; `pnpm check` passes.

package/skills/miles-port/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: miles-port
+description: "Turn an approved prototype into production: in Webflow (variables, CMS, conditional visibility, interactions) or in another codebase (its tokens, components, tests or stories). The prototype is a spec, never code to paste. Load when the user asks to build, ship, port, hand off or implement an approved prototype. Triggers on: port, hand off, handoff, implement, build it for real, into Webflow, into the codebase, production, engineers, state map, port report."
+---
+
+# Port
+
+An approved prototype is a spec. It is never pasted: pasted prototype code carries the kit, DialKit and the fidelity-ceiling shortcuts into production, which is the rebuild this hub exists to prevent. The port reads the feature folder, writes a state map, builds in the target's own materials, and writes a report the user reads before anything goes live.
+
+## Input: the feature folder is complete, or the port does not start
+
+Read `prototypes/<slug>/`, never the running prototype. Refuse to start, naming what is missing, unless all five hold:
+
+1. The README's `## States` table lists every state (a dial option, a route, a click) the prototype holds.
+2. Final dial values are committed as defaults in the code (`useDials` and `DialVars` configs) and in the README's Decision. A live dial value never written down does not exist to the port.
+3. `fixtures.json` holds `real` and `missing`, and the component's `max` is in the code, so `@kit/fixtures` can derive the rest.
+4. The CSS references tokens by name. A raw value is allowed only where the README names it.
+5. No open `bug` comment on the feature. Run `pnpm comments pull` and read `docs/sprints/<feature>/comments.md`; an open bug is fixed first (`miles-review`), or the user says in so many words that it ships as is, and the report lists it. Why: a bug a reviewer already found and nobody fixed is the cheapest bug the port can stop.
+
+## Branch: where is it going?
+
+Ask one question first: Webflow, or a codebase (the path to its repo)? Then walk one branch. Both follow three rules:
+
+- **The target's conventions win.** Where a token or component has no match in the target, list it in the port report. Never invent one in the target.
+- **Dials become fixed values.** DialKit never ships. Each dial's committed default is the value; the README's Decision is the source.
+- **The state map comes before any build.** One row per README state: the state, the mechanism that carries it in the target, and where. A state with no mechanism is a bug found before build instead of after launch; it goes in the report as unmapped and the user decides.
+
+### Webflow
+
+1. **Tools.** Call `webflow_guide_tool` once. Check whether the Designer tools are connected (`designer_tool`, `data_variable_tool`, `data_style_tool`, `data_element_tool`). If they are, layout, classes and variables are built over MCP; if not, step 4 writes the build spec for a person in the Designer.
+2. **Tokens → variables.** Each token the feature uses becomes a Webflow variable with the same name (`bg-primary`, `radius-md`). Existing variables with the same meaning are reused, named in the report.
+3. **States → mechanisms.** Walk each README state:
+   - empty, missing → conditional visibility on a CMS field
+   - a visual variant (compact, selected) → a combo class
+   - motion, open and close → an interaction, with the committed durations and curves
+   - anything else → unmapped, in the report
+4. **CMS.** Collection fields from the shape of `real` (one field per rendered key, typed from the value). Then the `real` items as drafts through the CMS tool's create-item action. Never the `_live` variants, never a site publish: publishing a client site is the user's call. Hostile sets stay in the prototype; draft test items in a client CMS get published by accident.
+5. **Layout, classes, interactions.** Over MCP when the Designer tools are connected, otherwise from the build spec in the report, by a person.
+
+### Codebase
+
+1. **Read the target first.** Framework, styling, component library, tokens, and its `AGENTS.md` or `CLAUDE.md`. Its rules bind the port.
+2. **Map tokens and components by name** onto the target's. Unmatched ones go in the report, never into the target as new ones.
+3. **Fixtures travel.** Each fixture set becomes a test fixture or a story in the target's own convention, and each README state a test or a story. Why: the hostile sets are where QA catches the edge cases, so they go with the feature.
+4. **A new branch**, never the target's main. Name it after the feature slug.
+
+Read the reference for the target's stack before step 2, when there is one: `references/next.md` for Next.js, `references/astro.md` for Astro. The target's own `AGENTS.md` still wins over both. For any other stack, the target's docs are the reference.
+
+## Output: the port report
+
+`docs/sprints/<feature>/port.md`, written before the user is told the port is done:
+
+- **State map.** The table from the branch step, every README state, with its mechanism or `unmapped`.
+- **Mapped.** Tokens and components with their target names.
+- **Not mapped.** Tokens with no target, states with no mechanism, and what the user has to decide for each.
+- **Webflow build spec** (Webflow branch): the structure, classes, variables and interactions a person builds in the Designer, in build order.
+- **Where it is.** The branch, the collection, the draft items.
+
+The report is the review surface. Nothing goes live until the user has read it.

package/skills/miles-port/references/astro.md

@@ -0,0 +1,35 @@
+# Porting into Astro
+
+Read the target first; where it already decides something below, it wins. This file decides only what the target leaves open.
+
+## Where each piece goes
+
+| Prototype | Astro |
+| --- | --- |
+| `kit/tokens.css` values | The target's tokens: CSS variables in its global stylesheet, or its Tailwind theme, under the target's names. Never a second token file. |
+| A hash route (`#/items/42`) | A page: `src/pages/items/[id].astro` with `getStaticPaths`, or an on-demand route if the target renders on request. |
+| `fixtures.json` `real` | A content collection (`src/content.config.ts`) when the content is the site's own; the CMS loader when it comes from a CMS. The fixture shape is the collection's schema. |
+| The hostile sets | Test fixtures for the component tests, plus one collection entry per hostile case in a draft or test collection that never builds into production. |
+| A dial's committed default | A prop default or a constant. |
+| `notInPrototype()` and scope toasts | Deleted. Each one is a feature the port report lists as not built. |
+
+## Astro component or island
+
+```
+Does the state change after the page loads (a click, a toggle, an animation on interaction)?
+├── No  → an .astro component. Every static state (empty, missing, longest) renders on the server.
+└── Yes → an island in the target's UI framework, hydrated with the lightest directive that works:
+          client:visible below the fold, client:idle above it, client:load only for what the first interaction needs.
+```
+
+Why the lightest directive: each island ships its framework and code to the browser, and the prototype hydrated everything because it was one React app.
+
+## States
+
+- **Empty and missing** branch in the `.astro` template on the collection's data; the README's copy for each state ships as written.
+- **Motion** keeps the README's committed durations and curves as CSS. Page-to-page motion is the target's View Transitions setup when it has one; never add it for one feature.
+- **Errors and loading** exist only for on-demand routes and islands that fetch. Each one is new and listed in the report.
+
+## Tests
+
+Each README state becomes one test with its fixture set, in the target's runner (Vitest with the Astro container API for `.astro` components, the framework's own for islands). Never add a runner the target does not have; list the gap in the report.

package/skills/miles-port/references/next.md

@@ -0,0 +1,36 @@
+# Porting into Next.js (App Router)
+
+Read the target first; where it already decides something below, it wins. This file decides only what the target leaves open.
+
+## Where each piece goes
+
+| Prototype | Next.js |
+| --- | --- |
+| `kit/tokens.css` values | The target's tokens. CSS variables in `app/globals.css`, or `@theme` in Tailwind v4, under the target's names. Never a second token file. |
+| A hash route (`#/items/42`) | A segment: `app/items/[id]/page.tsx`. A hash route was the prototype's shortcut, never the product's URL. |
+| `fixtures.json` `real` | The target's data layer: a fetch in a Server Component, a CMS query, or a route handler. The fixture shape is the props contract the data must meet. |
+| The hostile sets | Test fixtures beside the component: `<Component>.fixtures.ts`, used by its tests and stories. |
+| A dial's committed default | A constant or a prop default. Never `useState` for a value the README decided. |
+| `useStoredState` | Only if the README says the preference persists in the product; then the target's own persistence. Otherwise drop it. |
+| `notInPrototype()` and scope toasts | Deleted. Each one is a feature the port report lists as not built. |
+
+## Server or client
+
+```
+Does the component hold state, handle an event, or animate on interaction?
+├── No  → Server Component (the default). It renders the README's static states from props.
+└── Yes → the smallest leaf that needs it gets 'use client'; its parent stays on the server.
+```
+
+Why the smallest leaf: `'use client'` pulls everything the file imports into the browser bundle, and the prototype's fidelity shortcuts make that bundle large.
+
+## States
+
+- **Empty and missing** come from the data: the Server Component branches on an empty array or a null field. The README's copy for each state is the copy that ships.
+- **Loading** is `loading.tsx` or a `<Suspense>` boundary with a skeleton the same size as the loaded row, so the layout never moves. A prototype that had no loading state gets one here, and the report says so.
+- **Errors** are `error.tsx` at the segment. The prototype never had error handling (it had no backend), so each error state is new and listed in the report.
+- **Motion** keeps the README's committed durations and curves as CSS. `motion` only where the prototype used it, imported in the client leaf.
+
+## Tests and stories
+
+Each README state becomes one test or one story with its fixture set: `real`, `longest`, `empty`, `max`, `missing`, plus the feature's own. Use the target's runner (Vitest, Jest, Playwright) and Storybook if it has one. Never add a runner the target does not have; list the gap in the report.

package/skills/miles-prototype/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: miles-prototype
+description: "The rules for writing or changing any prototype code under prototypes/: low gravity, the fidelity ceiling, DialKit patterns, the scope toast, and the binding motion, accessibility and performance rules in references/. Load before the first line of prototype code in a session and again whenever a change touches kit/. Triggers on: prototype, prototyping, build the state, add a dial, DialKit, variant, fixture set, fidelity, too much code, kit, AppShell, SiteShell, Space, motion, animation, accessibility, performance."
+---
+
+# Prototype
+
+A prototype here answers one written question with the least code that can answer it, in the project's real materials, with every state reachable from a dial. This skill holds the ceiling. `AGENTS.md` holds the stack and the layout; `prototypes/sample-list/` is the worked example and wins over any description of it here.
+
+## Before the first line
+
+1. Read the feature's `README.md`. If it has no Problem, Question and States, stop and write them with `miles-new-feature`. Code written before the question is code that answers a different question.
+2. Decide where it stands: `AppShell` or `SiteShell` when the question is about the feature in context, `Space` when it is about one thing alone. Never both in one prototype.
+3. Read `prototypes/sample-list/index.tsx` once per session. It is the reference for every pattern below.
+
+## The fidelity ceiling
+
+The guard (the `design-hub hook fidelity-guard` hook in `.claude/settings.json`) names these rules when a write goes over them; the headings are the names it uses. It speaks at two levels, with thresholds in `.design-hub/checks.json`:
+
+- **A warning** arrives as context. Fix it, or say in one sentence why this write earns it.
+- **A block** stops the turn until you answer it: an import that leaves the feature folder, or a Jev judgment over `fidelity.blockAt`. Undo the write, or tell the user why it must stay and wait for their answer. Never write around a block.
+
+A finding with a log id (`log 3f9a…`) was Jev's. When the user says it was wrong, run `pnpm calibrate --no <id>`; when right, `--yes <id>`. Why: the thresholds move only with labels, so an unlabelled false alarm keeps firing.
+
+### Low gravity
+
+A prototype imports only `@kit/*` and files in its own folder. Never another prototype, never the hub's own code in `node_modules/@milesroxas/design-hub`. Why: the moment two prototypes share a file, deleting one breaks the other, and a prototype that cannot be deleted is production.
+
+### Fork, don't flex
+
+A kit piece that needs to behave differently is copied into the feature folder and changed there. Never add a prop, a variant or a branch to `kit/` for one prototype. Promote on second use: when a second prototype copies the same thing, move it into `kit/` and point both at it, in one change that says so. A kit piece that lives in the package (`@kit/ui`, `@kit/dials`) is forked the same way: copy the file into `kit/` under the same name and every import takes the copy.
+
+### No new dependency without the user
+
+Adding a package needs the user's OK first, with the reason and the gzipped cost. Why: every prototype pays for every kit import, and a library brought in for one state stays for all of them.
+
+### Fixtures, never a backend
+
+Data is `fixtures.json` in the feature folder, bundled at build (`miles-get-hostile`). Never `fetch`, never a server module, never IndexedDB, never `localStorage` as a store (`useStoredState` is for a prototype preference, such as which fold is open). Latency, when it is part of the question, is a timer on a dial. Why: a prototype with a backend has a second thing that can be wrong, and a reviewer cannot tell which.
+
+### No abstraction for later
+
+No custom hook, context, generic component or utility module used in one place. Inline it. Why: an abstraction is a bet on a second use, and the second use is the one that moves it into `kit/`, not the first.
+
+### No handling a fixture cannot reach
+
+No error state, loading state or validation for a case none of `real`, `longest`, `empty`, `max`, `missing` exercises. If the case matters, add it to `fixtures.json` and the README's States first; then build the handling and put it on the dial. Why: handling nobody can reach is code nobody reviews.
+
+### Every state is in the README
+
+A user-visible state the README's `## States` table does not list does not exist. Add the row before the code, with how to reach it (a dial, a route, a click). Why: `miles-port` builds from that table, and a state missing there is a bug found after launch instead of before.
+
+### Scope, said in the prototype's voice
+
+Anything a control would do that the prototype does not build says so: `notInPrototype('Model history')` or `toast(message, { kind: 'scope' })`. Never a product toast with a green check for something that did not happen. Why: a reviewer who sees a success they did not get stops trusting the ones they did.
+
+## DialKit patterns
+
+Walk this for every number and every switch:
+
+```
+Is it a value CSS consumes (duration, distance, scale, colour)?
+├── Yes → <DialVars name config target={ref}> and read it as var(--key) with calc(var(--dur) * 1ms)
+│         Why: a slider tick re-renders nothing; React state per tick stutters at 60fps.
+└── No
+    ├── Does JS branch on it (which fixture set, which role, a count)?
+    │   └── Yes → useDials(name, config, { hints }); one panel per group a reviewer reaches for
+    └── Does code also set it (a reset, every toggle at once)?
+        └── Yes → useDialsController
+```
+
+- Every dial carries a hint: one sentence, the unit named. A reviewer never guesses what a slider does.
+- Panels register in the order a reviewer reaches for them: Review (fixtures, role, scenarios) first, then the feature's own numbers, then Motion. View is mounted by the shell.
+- Slider defaults are the comp's values. The decision is the number the user settles on; copy it into the README's Decision with the rejected range.
+- Never a control inside the product chrome. A sidebar item or a sheet that switches fixtures is a testing aid wearing the product's clothes.
+
+## Motion, accessibility, performance
+
+The references beside this skill (`references/motion.md`, `references/accessibility.md`, `references/performance.md`) are binding; the short rules: transform and opacity only, ease-out in and ease-in out, nothing over 300ms, nothing animates on a keyboard action, reduced motion keeps the fades, every control has a name, 40px targets, no state per frame.
+
+## Done
+
+Before reporting any change: `pnpm check` passes, the page loads with no console errors and no `[a11y]` lines, the main path works by keyboard, `?theme=dark` and `?motion=reduce` look right, and the README's States and Decision are current. Say what you could not verify.

package/skills/miles-prototype/references/accessibility.md

@@ -0,0 +1,48 @@
+# Accessibility
+
+The floor for every prototype, WCAG 2.2 AA. A prototype that only works with a mouse answers the wrong question.
+
+## Structure
+
+- Native elements first: `<button>` for actions, `<a href>` for navigation, `<label>` for every input, `<fieldset>`/`<legend>` for groups, `<table>` for tabular data, `<dialog>` or the kit dialog for modals.
+- One `<main>` and one `<h1>` per page; headings in order. `Space` and `AppShell` already provide the landmarks.
+- Every control has an accessible name. Icon-only buttons take `aria-label`; `<Icon label="…">` only when the icon itself carries meaning.
+- `aria-*` only where HTML has no equivalent, and then follow the [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) pattern exactly (menu button, listbox, dialog, tabs, combobox).
+
+## Keyboard
+
+- Everything a pointer can do, the keyboard can do, in a sensible tab order. No positive `tabindex`.
+- Focus is always visible: the kit's focus ring comes from `--focus-ring`; never remove it without a replacement.
+- Esc closes the topmost menu, popover, sheet or dialog, and focus returns to what opened it.
+- Dialogs and sheets trap focus while open and make the page behind inert.
+- Menus: arrows move, Home/End jump, typeahead finds, Enter/Space choose, Tab leaves.
+- A keyboard open never animates (see `motion.md`).
+
+## Perception
+
+- Text and icons meet AA contrast against their background in light and dark. Tokens do this; one-off colors must be checked.
+- Color is never the only signal: pair it with text, an icon or a pattern.
+- Status that changes without a page load (a run finishing, a toast, a save) goes through a live region: `role="status"` for polite, `role="alert"` only for errors that need action.
+- Respect `[data-motion="reduce"]` (see `motion.md`).
+- Works at 200% zoom and at 320px wide without horizontal scrolling of the page.
+- `forced-colors` keeps working: focus rings use a transparent outline under the shadow (kit base does this), borders stay borders.
+
+## Pointer and touch
+
+- Targets at least 24×24px, 40px or more for primary touch targets. Extend small hit areas with padding or a pseudo-element.
+- Hover-only affordances need a focus and touch equivalent.
+- Inputs use a 16px font on touch so iOS does not zoom.
+
+## Forms
+
+- Labels are visible; placeholders are examples, not labels.
+- Errors sit next to the field, name the fix, and link with `aria-describedby`; `aria-invalid` on the field.
+- Disabled actions are rare; prefer an enabled action that explains what is missing. If something is absent for a role (a Viewer), hide it, do not disable it.
+
+## How to check
+
+1. Watch the console: the shell runs axe in dev and logs `[a11y]` warnings with the failing selectors. Zero is the bar.
+2. `pnpm check`: Biome's a11y rules catch missing labels, wrong roles and click handlers without keys.
+3. Unplug the mouse: tab through the main path, open and close every popup, confirm focus lands somewhere sensible.
+4. Load with `?motion=reduce` and `?theme=dark`.
+5. For a new interaction pattern, a VoiceOver pass (⌘F5) on the main path.

package/skills/miles-prototype/references/motion.md

@@ -0,0 +1,59 @@
+# Motion
+
+Binding for every prototype. Curves and durations live in `kit/tokens.css` (`--ease-*`, `--dur-*`) and, for JS, `@kit/motion`.
+
+## Decide before you animate
+
+1. **How often is it seen?** A hundred times a day (keyboard shortcuts, command palette, list navigation): no animation. Tens of times (hover, tabs): barely any. Occasional (menus, dialogs, toasts, sheets): standard. Rare (first run, a celebration): room for delight.
+2. **What is it for?** Spatial consistency, a state change, feedback, or softening a jump. "It looks nice" is not a purpose for something seen often.
+3. **Which curve?** Entering or leaving: ease-out. Moving on screen: ease-in-out. Color and fill: `--ease-hover`. Constant motion: linear. Never `ease-in` on UI.
+4. **How long?** Press 100-160ms. Tooltip 125-200ms. Menu, select 150-250ms. Dialog, drawer 200-320ms. UI stays under 300ms; exits are faster than entrances.
+
+## Rules
+
+- Animate `transform` and `opacity`. Anything else (height, width, top, padding, filter on large areas) needs a reason written in the README.
+- Name exact properties: `transition: transform 180ms var(--ease-out)`, never `transition: all`.
+- Keyboard-initiated opens, closes and arrow moves are instant. Pointer-initiated ones may animate.
+- Press feedback on anything pressable: `:active { transform: scale(0.97) }`, 0.95 to 0.98.
+- Never enter from `scale(0)`. Start at 0.95 or higher with `opacity: 0`.
+- Popovers and menus grow from their trigger (`transform-origin` at the trigger edge). Modals scale from center.
+- Hover motion only under `@media (hover: hover) and (pointer: fine)`.
+- Stagger lists by 30-80ms, never block input while it plays.
+- Blur under 20px, and only to bridge a crossfade.
+
+## CSS first
+
+| Situation | Use |
+| --- | --- |
+| State that can flip mid-animation (open/close, toasts, toggles) | `transition`: it retargets from where it is |
+| Element entering the DOM | `@starting-style` with a transition |
+| Element leaving the DOM | keep it mounted with a closing state until `transitionend`, or `motion`'s `AnimatePresence` |
+| Loops, spinners, one-shot sequences nobody interrupts | `@keyframes` |
+| Values computed at runtime (measured heights, pointer positions) | WAAPI `element.animate()` |
+| Crossfading a whole view | View Transitions (`document.startViewTransition`) with a fallback |
+
+## When `motion` earns its place
+
+Reach for `motion/react` only for: springs that must keep velocity when interrupted, drag and gestures with momentum, layout animations (FLIP) between changing positions, exit animations in a list (`AnimatePresence`), shared-element transitions. Then:
+
+- Import from `motion/react`. Use `ease.*` and `spring.*` from `@kit/motion` so JS matches the CSS tokens.
+- Animate a `transform` string (`animate={{ transform: 'translateY(8px)' }}`) when the main thread may be busy; the `x`/`y` shorthands run on the main thread.
+- Springs: `{ type: 'spring', duration: 0.3, bounce: 0 }` by default; bounce 0.1-0.3 only for drag release and playful moments.
+- Drive per-frame values with motion values, not React state.
+
+## Reduced motion
+
+`[data-motion="reduce"]` on `<html>` is the one switch. The shell sets it from the OS setting, `?motion=reduce`, or the Space dial. Write reduced-motion CSS against it, not the media query:
+
+```css
+.menu { transition: opacity 180ms var(--ease-out), transform 180ms var(--ease-out); }
+:root[data-motion="reduce"] .menu { transition: opacity 120ms linear; transform: none; }
+```
+
+In JS, `useReducedMotion()` from `@kit/prefs`. Keep fades and color changes, drop movement and scale.
+
+## Tuning and review
+
+- Every number you are unsure of goes on a dial (`DialVars` for CSS, `useDials` for JS). The decision is the number the user settles on; copy it from DialKit into the README.
+- Watch at 0.25x: the Space speed dial, or `?lapse` for frame-by-frame takes, scrubbing and a jank report.
+- Test the interruption: open, then close mid-open. It should reverse from where it is.

package/skills/miles-prototype/references/performance.md

@@ -0,0 +1,45 @@
+# Performance
+
+A prototype that stutters gets judged on the stutter. The floor below keeps the question about the design.
+
+## Already handled by the shell
+
+- Each prototype is its own lazy chunk; the index loads none of them.
+- Dev-only tools (axe, Lapse) never ship in a build and load only when used.
+- `motion` and DialKit load only in prototypes that import them.
+
+## Rendering
+
+- Animate `transform` and `opacity`; they skip layout and paint. See `motion.md`.
+- CSS animations and transitions run off the main thread; prefer them to JS-driven motion.
+- No React state per animation frame or per slider tick. Use `DialVars` (CSS variables), motion values, or a ref.
+- Setting a CSS variable on a parent restyles every child. For per-frame values on one element, set `transform` on that element.
+- Read layout, then write it: never interleave `getBoundingClientRect()` or `offsetWidth` with style writes in a loop.
+- `will-change` only on elements that are about to move, and remove it after.
+- Keep `backdrop-filter` and `filter: blur()` to small areas; both are expensive, worst in Safari.
+
+## React
+
+- State lives where it is used. Lift it only as far as needed.
+- A module store read through `useSyncExternalStore` with a narrow selector beats context for values that change often; context re-renders every consumer.
+- `useDeferredValue` for filtering or searching over big lists.
+- Don't add `useMemo` and `useCallback` by reflex; add them when a profile shows the cost.
+- Stable `key`s from data, never array indexes for lists that reorder.
+
+## Content
+
+- More than ~200 rows: `content-visibility: auto` with `contain-intrinsic-size`, or window the list.
+- Images and media carry `width` and `height` (no layout shift), `loading="lazy"` below the fold, `decoding="async"`.
+- Fonts come from tokens (`--font`, `--font-voice`). Add a web font only in `tokens.css`, once, as the design names it.
+- Data is local: seed files in the prototype folder. Simulate latency with timers when latency is part of the question.
+
+## Dependencies
+
+- Each new dependency needs the user's OK (see `AGENTS.md`). Say what it costs gzipped and why CSS or the kit can't do it.
+- Nothing heavy goes in `kit/`: every prototype that imports the kit pays for it.
+
+## How to check
+
+1. Chrome Performance panel with 4x CPU throttling on the main interaction: no long tasks over 50ms during an animation.
+2. `?lapse`, record a take of the interaction: its report lists dropped frames, layout shifts and which properties animated on layout or paint.
+3. React DevTools Profiler, "Highlight updates": a slider or a tick should light up only what it changes.

package/skills/miles-review/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: miles-review
+description: "Work from review comments on the deployed prototypes: pull them into the repo, sort them by state and kind, act on each, resolve them, and manage who may comment. Load when the user mentions comments, feedback, review notes, a reviewer, an invite link, or asks what the client said. Triggers on: comments, feedback, review notes, client notes, what did they say, reviewer, invite, people, revoke, resolve, triage, pnpm comments, pnpm people."
+---
+
+# Review
+
+Each comment is pinned to a prototype, its state (the URL and every dial value) and, usually, an element. The repo gets them as `docs/sprints/<feature>/comments.md`, grouped by README state, then by kind. That file is generated: read it, never edit it, and close comments in the store.
+
+## Working from comments
+
+1. **Pull**, from the project root: `pnpm comments pull`. The JSON's `store` says which store it read: `deployed` when `.env` holds the store's credentials, `local` otherwise. Say which to the user, because local comments are only yours.
+2. **Sort what is unsorted.** With TypeSafe on, `pnpm comments triage` first. Without it, sort by reading, and set the kind and state in the panel so the next pull agrees.
+3. **Walk each open thread.** The first match wins:
+   ```
+   Does its state match no row of the README's States table?
+   └── Yes → the table is missing a state. Add the row (miles-prototype) before acting on the comment.
+   kind?
+   ├── bug   → reproduce it in that state: the line's URL, or Show state in the panel, which restores the dials.
+   │           Fix it under miles-prototype. Resolve after the fix is deployed.
+   ├── copy  → change fixtures.json or the copy. Resolve after it is deployed.
+   └── taste → change nothing. List it for the user with what each option costs.
+                Build an --alternate only when the user chooses to explore it.
+   ```
+   Why taste waits: one reviewer's preference, built at once, overwrites a decision the team made and the next reviewer argues the other way. The user decides taste; bugs and copy are not taste.
+4. **Resolve** with `pnpm comments resolve <id>`, or in the panel, only once the change is live. Why: a reviewer who opens a resolved comment and still sees the old state stops trusting the list.
+5. **Report** to the user: what was fixed, by comment id; the taste calls waiting for them; any comment with no state.
+
+## People
+
+- **Editors** resolve any thread, sort comments and invite people. **Reviewers** comment, reply, and resolve or delete their own. Give a client's stakeholders the reviewer role; editors are the studio.
+- **Team** is the company: `Studio`, or the client's name. It shows beside every name, so a reviewer reads who said what.
+- The first editor comes from `pnpm people invite --name <n> --team <t> --role editor --site <url>`; after that, editors invite from the People tab.
+- A link works for 14 days. `pnpm people reissue <id>` replaces it and signs that person out everywhere; `revoke` ends their access on their next page load.
+- Never paste an invite link into a commit, a document, a ticket or a comment. Why: anyone holding it signs in as that person.
+
+## The words in comments
+
+`comments.md` holds reviewers' names and their words. Commit it only to a private repository. Never quote a comment in public copy, and never send one outside the project.

package/templates/app/README.md

@@ -0,0 +1,41 @@
+---
+title: {{title}}
+summary: One line on what this explores.
+context: app
+status: exploring
+kind: {{kind}}
+feature: {{feature}}
+created: {{created}}
+---
+
+# {{title}}
+
+## Problem
+
+What is wrong or unknown today, and for whom. Write this before any code.
+
+## Question
+
+The one decision this prototype exists to make.
+
+## Flows
+
+| Flow | Starts from | Edge cases |
+| --- | --- | --- |
+| | | |
+
+## States
+
+Every state the prototype holds, one row each. The fidelity guard and `miles-port` read this table: a state that is not here does not exist to them.
+
+| State | How to reach it |
+| --- | --- |
+| | |
+
+## Fixtures
+
+`fixtures.json` holds `real` and `missing`; `@kit/fixtures` derives `longest`, `empty` and `max`. Say where `real` came from (which CMS collection, or the comp) and the design's maximum count.
+
+## Decision
+
+Empty until picked. What was chosen, its values, and what was rejected and why. Then delete the folder.

package/templates/app/index.tsx

@@ -0,0 +1,32 @@
+import { AppShell, PageHead } from '@kit/AppShell';
+import { useHashRoute } from '@kit/hooks';
+import { Button, toast } from '@kit/ui';
+import './styles.css';
+
+export default function Prototype() {
+  const { path } = useHashRoute('#/items');
+  return (
+    <AppShell active={path}>
+      <div className="page">
+        <PageHead
+          title="{{title}}"
+          desc="Replace with the question from README.md."
+          actions={
+            <Button
+              kind="primary"
+              label="Start"
+              icon="plus"
+              onClick={() => toast('Wire this to the flow under test.', { kind: 'scope' })}
+            />
+          }
+        />
+        <div className="card card-pad flow-body">
+          <h2 className="card-title">The page under test</h2>
+          <p className="card-sub">
+            Build the flow here with @kit/ui. Sub-pages are hash routes, read with useHashRoute.
+          </p>
+        </div>
+      </div>
+    </AppShell>
+  );
+}

package/templates/app/styles.css

@@ -0,0 +1 @@
+.flow-body { display: flex; flex-direction: column; gap: 4px; }

package/templates/conductor/settings.toml

@@ -0,0 +1,29 @@
+# Conductor shared repository settings: https://www.conductor.build/docs/reference/settings
+# Written by `design-hub bootstrap --conductor`. Personal overrides go in
+# .conductor/settings.local.toml (gitignored).
+"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
+
+# Each workspace installs the project and serves it on its own
+# $CONDUCTOR_PORT; the dev server reads that port before .env's PORT. No
+# secrets are copied in: the GATE_* values are for Vercel only.
+[scripts]
+setup = """
+git -C "$CONDUCTOR_ROOT_PATH" fetch --prune origin && git -C "$CONDUCTOR_ROOT_PATH" pull --ff-only || true
+pnpm install && pnpm bootstrap --no-install
+"""
+run_mode = "concurrent"
+
+# strictPort refuses a taken port instead of drifting away from the Open
+# button's URL; bootstrap names the process that holds it.
+[scripts.run.prototypes]
+command = "pnpm dev"
+default = true
+icon = "play"
+available_in = ["local"]
+
+[prompts]
+general = """Land work on `{{branch}}`: `git fetch origin && git rebase origin/{{branch}}`, run `pnpm check` if prototypes/ or kit/ changed, then push or open a PR as the project owner prefers. Prototype rules: AGENTS.md."""
+
+[[preview_urls]]
+name = "Prototypes"
+url = "http://localhost:$CONDUCTOR_PORT"