@parity-app/cli 0.0.0-stage → 0.1.0

package/skills/execute.md

@@ -0,0 +1,298 @@
+# The `execute` tool
+
+`execute` runs a JavaScript snippet against a working copy of one tab's designs. The functions below are globals.
+`await` works at the top level. When the snippet finishes, every change lands on the canvas as one step the person can
+undo; when it throws, nothing changes and you get an `editId` to fix it with.
+
+- Pass `description`: 3 to 8 words the person sees while it runs, such as "Add a pricing section".
+- `Print(...)` (or `console.log`) is how you see values. Objects print as JSON.
+- Values assigned without `const` or `let` carry over to your next snippet in the same tab.
+- A snippet has 5 seconds of computing time. Rendering (screenshots and checks) doesn't count against it.
+- To retry a failed snippet, send `editId` with `edits`, each an exact `{ find, replace }` on the snippet text (`all` to
+  replace every match).
+
+## API
+
+```ts
+// Reading
+Designs(): DesignSummary[]                       // every design: id, name, kind, states, what it shows, size
+GetDesign(design): Design                        // a whole design, as in document.md
+Get(path, { depth?, state? }?): Node             // a design's root or a node; depth cuts children off with "…"
+Get(path?, visit): any[]                         // walks nodes, collecting what visit returns
+Components(): string[]                           // the components designs can use
+Props(component, { all? }?): PropsInfo           // a component's props, from its source
+Icons(): IconSet[]                               // the project's icon sets, with their styles
+Icons(set, { search?, style?, limit? }): Icon[]  // async: a set's icons, as component nodes name them
+GetTokens({ category?, source?, search? }?): Token[]
+GetModes(): { settings, modes }                  // the project's modes, and each resolved
+Selection(): { design?, node?, mode? }           // what the person has selected
+
+// Designs
+CreateDesign({ name, kind?, root?, x?, y?, file?, baseState? }): string   // returns the new design's id
+UpdateDesign(design, { name?, kind?, x?, y?, mode?, showModes?, state?, allStates? }): void
+DeleteDesign(design): void
+
+// Nodes
+Insert(parent, node, { index?, slot? }?): string // returns the new node's id
+Update(path, change, { state? }?): void          // change: name, text, tag, hidden, props, args, style, component
+Replace(path, node): string
+Move(path, parent, { index?, slot? }?): void     // within one design
+Copy(path, parent, { index?, slot?, name? }?): string
+Delete(path): void
+Responsive(path, viewport, patch | null): void   // a patch for one viewport, or null to remove it
+
+// States
+AddState(design, { name, changes? }): string     // changes keyed by node id or name
+UpdateState(design, state, { name?, changes? }): void
+DeleteState(design, state): void
+
+// Components
+FindRepeats(design): Repeat[]                    // parts that repeat with the same structure
+ExtractComponent(design, nodes, { name, params?, file? }): string
+
+// Modes and tokens
+SetModes(settings): void                         // replaces the project's modes
+SetTokens({ name: value | { theme: value } }): void
+
+// Checking
+Screenshot(design, { state?, mode?, scale? }?): number
+Measure(design, { state?, mode? }?): Layout
+Problems(design, { state?, mode? }?): Problem[]
+Accessibility(design, { state?, mode? }?): Finding[]
+
+// The canvas
+FindEmptySpace({ width, height, direction?, near?, padding? }): { x, y }
+Overlaps(design?): Overlap[]
+Print(...values): void
+```
+
+## Paths
+
+A design is named by its id or its name. A node is named by `design/node`, where `node` is the node's id or its name, or
+by its id alone when only one design has that id. Names aren't unique, so prefer ids once you have them; `Insert`,
+`Copy` and `CreateDesign` return them, and nodes you create with a `name` are listed under "Created" in the result.
+
+## Reading
+
+### Designs
+
+Lists every design with its `id`, `name`, `kind` (`screen` or `component`), `states`, and `showing`: the state on the
+canvas, the main mode and the modes beside it. Start here to find ids.
+
+### Get
+
+`Get("dashboard", { depth: 2 })` returns the design's root with two levels of children; deeper ones show as `"…"`. Read
+a branch with a node path, as in `Get("dashboard/Stats", { depth: 2 })`. With `state`, the result shows the nodes as
+that state changes them.
+
+`Get(path, visit)` walks the nodes under `path`, or every design without one, and returns what `visit` returns for each.
+`visit(node, { design, path, depth, index, parent, skipChildren })`. Return `undefined` to collect nothing.
+
+```js
+// Every Button in the project, with where it is.
+Print(Get((node, at) => (node.type === "component" && node.component === "Button" ? at.path : undefined)))
+```
+
+### Components and Props
+
+`Components()` is everything a `component` node can name. `Props("Button")` returns the props found in the component's
+source: variants with their options (`variant`, `size`), its own props, and with `{ all: true }` the attributes it
+passes to its element. A prop that isn't listed, or a variant value outside its options, comes back as a warning.
+
+### Icons
+
+`Icons()` lists the project's icon sets: each one's `id`, `name`, `package`, `styles` (such as `outline` and `solid`,
+empty when it has one) and the `style` used when none is asked for. An icon is a component node named `<set>/<Icon>`,
+with no children. `await Icons("lucide", { search: "settings" })` finds icons by name, by the other names the set
+exports them under and by the tags it publishes, best first; each comes back with its `label` and the `component` (and
+`props`, for sets that take the style as a prop) to insert it with. Without `search` it lists the set's icons in order.
+It returns 50 unless `limit` says otherwise, in the set's default style unless `style` names another.
+
+```js
+// A settings button with the project's own settings icon.
+const [icon] = await Icons(Icons()[0].id, { search: "settings", limit: 1 })
+Insert("dashboard/Toolbar", {
+  type: "component",
+  component: "Button",
+  props: { variant: "ghost", "aria-label": "Settings" },
+  slots: { children: [{ type: "component", component: icon.component, props: icon.props }] }
+})
+```
+
+### GetTokens
+
+Each token has a `name`, a `category` (`color`, `font-size`, `radius`, `shadow`, `spacing`, `font`, `font-weight`,
+`leading`, `tracking` and others), a `source` (`semantic` for the project's own variables, `theme` for its styling
+framework's scale) and its `values` per theme. Filter with `GetTokens({ category: "color", source: "semantic" })` or
+`GetTokens({ search: "radius" })`.
+
+### Selection
+
+What the person has selected: the design's id, and the node and mode when they picked one. "This", "here" and "the
+selected one" usually mean it.
+
+## Designs
+
+### CreateDesign
+
+Makes a design and returns its id. Without `root` it starts as a page layout with padding, a gap and the background and
+foreground colours. Without `x` and `y` it goes into empty space. `kind: "component"` makes a component design, which
+screens place as instances; most component designs come from `ExtractComponent` instead, because that also gives them
+params.
+
+### UpdateDesign
+
+Renames or moves a design, or changes how it's shown: `mode` sets the main frame's mode, `showModes` the modes beside
+it, `state` the state on the canvas, and `allStates: true` shows every state in its own row. None of these change the
+design itself.
+
+## Nodes
+
+### Insert
+
+Adds a node, with everything inside it, as the last child of `parent` or at `index`. Into a component node, it goes into
+the `children` slot unless `slot` names another. Every node gets a fresh id; don't pass ids. `parent` can be a design,
+meaning its root.
+
+```js
+const form = Insert("settings/Content", {
+  type: "layout",
+  name: "Profile form",
+  style: { gap: 4, maxWidth: 120 },
+  children: [
+    { type: "component", component: "Label", props: { htmlFor: "name", children: "Name" } },
+    { type: "component", component: "Input", props: { id: "name", defaultValue: "Avery Chen" } },
+    { type: "component", component: "Button", props: { children: "Save changes" }, style: { self: "start" } }
+  ]
+})
+```
+
+### Update
+
+Changes a node. `change` takes `name`, `text`, `tag`, `hidden`, `props`, `args` (an instance's values), `style` and
+`component`. `props`, `args` and `style` merge with what's there; set a key to `null` to remove it.
+
+With `{ state: "loading" }` the change belongs to that state instead of the base design. A state can change only
+`hidden`, `text`, `props` and `style`.
+
+### Replace, Move, Copy and Delete
+
+`Replace` swaps a node for a new one in the same place and returns its id. `Move` reorders or reparents a node within
+its design; to move it to another design, `Copy` it there and `Delete` the original. `Copy` gives the copy fresh ids and
+returns the new id. A design's root can't be deleted; use `Replace`.
+
+### Responsive
+
+Patches a node in one viewport: `Responsive("dashboard/Stats", "mobile", { style: { columns: 1 } })`. The viewport is a
+viewport option's id from the modes (such as `desktop`, `tablet` and `mobile`), not a mode's id. Patches take `hidden`,
+`text`, `props` and `style`, and merge with the viewport's earlier patch. `null` removes it.
+
+## States
+
+A state is a situation the whole design is in, like a story: loading, empty, error, signed out. It stores only what
+differs from the base. `changes` maps node ids or names to patches (`hidden`, `text`, `props`, `style`); `null` clears a
+node's patch. The first state is the base.
+
+```js
+AddState("team-members", {
+  name: "Empty",
+  changes: {
+    "Members table": { hidden: true },
+    "Empty state": { hidden: false },
+    seats: { props: { children: "1 of 10 seats used" } }
+  }
+})
+```
+
+Put the parts only some states show into the base design with `hidden: true`, then show them in those states. A text
+node's words are its `text`; a component's are usually its `children` prop.
+
+## Components
+
+### FindRepeats
+
+Returns parts of a design that repeat with the same structure: each has the root ids of its occurrences (`nodes`), a
+starting `name`, and the `params`, which are what differs between occurrences (texts, props, whether a node shows).
+
+### ExtractComponent
+
+Turns occurrences into a component design and replaces each with an instance that keeps its own content as args. Returns
+the component's id. `params` renames the params found, by the name they were given. It refuses when the result wouldn't
+render the same in every state and viewport.
+
+Look at what `FindRepeats` found before extracting, because the params' names are only a start:
+
+```js
+repeats = FindRepeats("team-members")
+Print(repeats)
+```
+
+Then, in the next snippet, extract with names that say what each param is:
+
+```js
+const [rows] = repeats
+ExtractComponent("team-members", rows.nodes, { name: "Member row", params: { [rows.params[0].name]: "name" } })
+```
+
+## Modes and tokens
+
+`SetModes(settings)` replaces the project's modes: take `GetModes().settings`, change it, and pass it back. Modes are
+shared by every design.
+
+`SetTokens` changes token values in the project's stylesheets: `SetTokens({ primary: "oklch(0.55 0.2 260)" })` for every
+theme, or `SetTokens({ primary: { default: "…", dark: "…" } })` per theme. Every frame shows the new values at once, and
+saving writes them into the project's code, so do it only when the person asks to change the design system, not to style
+one design. They're undone with the call's other changes.
+
+## Checking
+
+`Screenshot` renders frames offscreen at their real widths and returns how many it took; the images come back with the
+result. `state` and `mode` take an id, a list, or `"all"`; `mode` also takes `"shown"`, the modes the design shows. The
+defaults are the state on the canvas and the main mode.
+
+`Measure` lays out one frame and returns its size, whether it overflows sideways, and every node's box (`clipped` when a
+parent cuts it off). `Problems` checks frames for render errors, overflow, clipping and unknown components.
+`Accessibility` returns axe-core's findings per node and frame, with the rule, its impact and what's wrong.
+
+## The canvas
+
+`FindEmptySpace({ width, height })` finds room for a new board, to the right of the others unless `direction: "below"`,
+or next to the design named in `near`. `Overlaps()` lists boards that collide, titles included; move one with
+`UpdateDesign(design, { x, y })`.
+
+## Examples
+
+A new screen, checked in every state and mode:
+
+```js
+const id = CreateDesign({ name: "Billing" })
+Insert(id, { type: "text", tag: "h1", text: "Billing", style: { size: "text-2xl", weight: 600 } })
+Insert(id, {
+  type: "component",
+  component: "Card",
+  name: "Plan",
+  slots: {
+    children: [
+      {
+        type: "component",
+        component: "CardHeader",
+        slots: {
+          children: [
+            { type: "component", component: "CardTitle", props: { children: "Pro plan" } },
+            { type: "component", component: "CardDescription", props: { children: "$24 per seat, billed monthly" } }
+          ]
+        }
+      }
+    ]
+  }
+})
+await Screenshot(id, { state: "all", mode: "shown" })
+Print(await Problems(id, { state: "all", mode: "shown" }))
+```
+
+A loading state that swaps content for skeletons:
+
+```js
+Update("dashboard/Stats loading", { hidden: true })
+AddState("dashboard", { name: "Loading", changes: { Stats: { hidden: true }, "Stats loading": { hidden: false } } })
+```

package/skills/guide/checking.md

@@ -0,0 +1,56 @@
+# Checking a design
+
+Parity renders every frame offscreen at its real width, with the project's real components, so checks see what the app
+would show. Run them after every change you make, and before you tell the person you're done.
+
+## Screenshots
+
+`screenshot`, or `Screenshot` in a snippet, returns the images. Look at them: text that wraps badly, a button pushed off
+the edge, a skeleton that doesn't match what it stands for, colours that disappear in dark mode. `scale: 2` helps with
+small details.
+
+## Layout problems
+
+`find_problems`, or `Problems` in a snippet, lists what's wrong in each frame without looking at it:
+
+- **Render errors.** A component threw. Usually a prop with the wrong type, or a part used outside its parent (a
+  `TabsTrigger` without `Tabs`). `parity components` lists the components failing anywhere on the canvas, with why.
+- **Overflow.** Content wider than the frame, usually a row that needs to wrap or stack on mobile.
+- **Clipping.** A node cut off by a parent with `overflow: hidden` or a fixed size.
+- **Unknown components.** A name that isn't in `Components()`; it draws as a placeholder.
+
+`Measure` gives every node's box in one frame, for checking alignment or sizes by numbers.
+
+## Accessibility
+
+`check_accessibility`, or `Accessibility` in a snippet, runs axe-core against WCAG 2.2 AA in each frame and reports each
+rule broken on the layers that break it, worst first. Fix what it finds within the design system:
+
+| Finding                    | Fix in the design                                                                 |
+| -------------------------- | --------------------------------------------------------------------------------- |
+| Text contrast too low      | A stronger token: `foreground` instead of `muted-foreground`, or a darker variant |
+| Button or link has no name | Visible text, or an `aria-label` prop on an icon-only button                      |
+| Form field has no label    | A `Label` with `htmlFor` matching the field's `id`, or an `aria-label`            |
+| Image has no alt text      | `alt` that says what it shows, or `alt: ""` when it's decoration                  |
+| ARIA reference to nothing  | Add what it points at, such as the `TabsContent` for each `TabsTrigger`           |
+| Heading level skipped      | Text tags that go down one level at a time: `h1`, then `h2`                       |
+| Target too small           | A bigger size variant, or more room around small controls                         |
+
+Automated checks find some problems, not all. A clean result doesn't make a design accessible; say so when you report.
+
+## The console
+
+`get_console` returns what the project's own components wrote to the console: errors, warnings and logs, from the
+person's canvas and from your offscreen renders. React warnings about props, keys and nesting show up here, often before
+they show on screen. `clear: true` empties it, so the next read shows only what's new.
+
+React's warnings keep their `%s` placeholders, with the values that fill them listed after the message.
+
+## Trying it
+
+Checks can't click. The person can: the Interact tool (I, or the pointing hand in the toolbar) hands their mouse and
+keyboard to the real components, so tabs switch, menus open and fields take typing. Escape steps out of a component, and
+a second Escape stops interacting; the design goes back to how it was. When behaviour matters (a menu, a dialog,
+keyboard order), ask them to try it, and read `get_console` afterwards for errors it caused.
+
+The Accessibility tab also shows the tab order on the canvas, numbered in the order the Tab key visits.

package/skills/guide/components.md

@@ -0,0 +1,48 @@
+# Components
+
+Two kinds of component show on the canvas, and they work differently.
+
+**The project's components** are its code: `Button`, `Card`, `Tabs`, and library ones such as `nova/Accordion`. A
+`component` node places one. You can't change what they look like from Parity, only choose their props and what goes in
+their slots. `Components()` lists them.
+
+**Component designs** are designs with `kind: "component"`: a stat card, a member row, a sidebar. They're made of the
+project's components and layouts, and screens place them as `instance` nodes. Change the component design and every
+instance follows.
+
+## Choosing a component
+
+- Look before you build. `Components()` usually has what a screen needs; shadcn-style projects split a card into `Card`,
+  `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` and `CardAction`.
+- Read its props with `Props("Badge")`. Variants and sizes come with their options; use those values exactly. A prop the
+  component doesn't declare comes back as a warning.
+- Compose the parts the way the library intends: `Tabs` holds a `TabsList` of `TabsTrigger`s and one `TabsContent` per
+  trigger; `Table` holds `TableHeader` and `TableBody`, each with `TableRow`s of cells.
+- Put children where they go. `slots.children` is what goes between the component's tags. Other slots, when a component
+  takes nodes as props, are named after the prop.
+
+## Icons
+
+Icons are components named after their library, as in `lucide/Search` or `lucide/ChevronRight`. Size them with the
+`size` prop (in pixels, 16 in most controls). Put an icon inside a button's `children` slot next to its text, or alone
+with an `aria-label` prop when the button has no text.
+
+## Component designs and instances
+
+Make a component design when something repeats with the same structure: rows in a list, cards in a grid, items in a
+feed. Let `FindRepeats` find the candidates and `ExtractComponent` do the work: it makes the component design, works out
+its params from what differs, and replaces each occurrence with an instance carrying its own values.
+
+- Give params names that say what they are (`name`, `email`, `role`), not where they are.
+- An instance's values are its `args`. Change them with `Update(instance, { args: { role: "Admin" } })`.
+- A component design can have states too, such as a row that's loading. An instance's `state` picks which one it shows.
+- A component design can have variants: choices each instance makes, like a size or a tone. Each option patches the
+  design the way a state does, and an instance picks one in its `args`: `Update(row, { args: { density: "compact" } })`.
+- An instance can override what's inside it, such as one copy's title or a hidden badge. `Get` shows these as the
+  instance's `overrides`. People make them on the canvas; `execute` can't edit overrides or add variants yet, so to
+  change one copy, give the component design a param for it.
+- A component design that needs a parent to render properly, such as a table row, is drawn inside that parent on its own
+  board. Rows extracted from a table get this automatically.
+- Place a new instance with `Insert(parent, { type: "instance", design: "member-row", args: { … } })`.
+
+Keep component designs in their own area of the canvas, away from screens, as `ExtractComponent` does.

package/skills/guide/design-system.md

@@ -0,0 +1,52 @@
+# Designing with the project's system
+
+The project already decided its colours, type, spacing and components. Your job is to compose them well, not to style
+around them. A design that only uses the system's pieces is one the code can build without new CSS.
+
+## Spacing
+
+Spacing is a scale of steps (`4` is 1rem in a default Tailwind project). Use a few steps consistently:
+
+| Between                                      | Steps   |
+| -------------------------------------------- | ------- |
+| An icon and its label, a label and its field | 1 to 2  |
+| Items in a list or fields in a form          | 3 to 4  |
+| Groups within a section                      | 6       |
+| Sections of a page                           | 8 to 12 |
+| A page's edge, desktop                       | 8       |
+| A page's edge, mobile                        | 4 to 5  |
+
+Space shows what belongs together: less inside a group than between groups. Let cards and other components keep their
+own padding; add gaps between them, not padding around them.
+
+## Type
+
+Use the type scale tokens (`text-sm`, `text-base`, `text-lg`, `text-2xl`) and weights 400 to 700. A page needs about
+three sizes: its title, section titles and body. Secondary text uses `muted-foreground`, not a smaller size alone. Pick
+the `tag` for meaning: one `h1` per screen, then `h2` for sections.
+
+## Colour
+
+Semantic tokens carry meaning and follow the theme:
+
+- `background` and `foreground` for the page; `card` and `card-foreground` for raised surfaces.
+- `muted` and `muted-foreground` for quiet surfaces and secondary text.
+- `primary` for the one main action on a screen, through a component's default variant rather than a raw background.
+- `destructive` for actions that delete or can't be undone.
+- `border` for dividers and outlines.
+
+Palette colours (`color-emerald-500`) don't change with the theme, so keep them for data, such as chart series and
+status dots, and check them in dark mode.
+
+## Composing
+
+- Start from the page's structure: a header with the title and its actions, then the content, then anything secondary.
+- Group with the components meant for it. A `Card` frames one subject; a `Table` shows records with the same fields; a
+  list of rows suits items people scan and act on; `Tabs` split one subject into views.
+- One primary button per view. Other actions use `outline`, `secondary` or `ghost` variants, and destructive ones the
+  `destructive` variant, usually behind a confirmation.
+- Align to one edge. Text and controls in a column share a left edge; actions sit together, at the end of a row or the
+  bottom of a form.
+- Show status with the system's pieces: `Badge` for a status or count, `Skeleton` for loading, `Empty` for nothing yet.
+- Fill designs with believable data: real names, dates, amounts and lengths. Include a long one; it finds layout
+  problems a short one hides.

package/skills/guide/mobile.md

@@ -0,0 +1,32 @@
+# Phones and small viewports
+
+In Parity a phone layout is the same design in a mobile viewport, patched where it needs to differ. Show a mobile mode
+beside the main frame (`UpdateDesign(design, { showModes: ["mobile-light"] })`) and fix what breaks there.
+
+## What usually changes
+
+| On desktop                           | On a phone                                         |
+| ------------------------------------ | -------------------------------------------------- |
+| A sidebar                            | Hidden, with navigation in a top bar or a menu     |
+| Rows of cards or columns of a grid   | One column: `columns: 1`, or `direction: "column"` |
+| A header row with actions at the end | Title above, actions below or in a menu            |
+| Page padding of 8 steps              | 4 to 5 steps                                       |
+| A wide table                         | Fewer columns, or each row as a stacked card       |
+| Side-by-side form fields             | Stacked, full width                                |
+
+Patch these with `Responsive(node, "mobile", patch)`. Hiding a column in a table means hiding its header cell and the
+matching cell in the row component design.
+
+## Touch
+
+- Controls need room for a finger. WCAG asks for targets of at least 24 by 24 pixels; phones are easier at about 44. Use
+  the components' default or large sizes, and keep small controls apart.
+- Put the main action where a thumb reaches it: full width at the bottom of a form, or at the bottom of the screen.
+- Nothing can depend on hover. Anything a hover shows on desktop needs another way in.
+
+## Content
+
+- Text wraps more. Check long names, emails and numbers in every state; `lines: 1` keeps a single line with an ellipsis
+  where wrapping would break a row.
+- Lead with less. A phone shows the first few items; put the most important ones first.
+- Check the mobile frame with `find_problems`: overflow there usually means a row that needs to stack.

package/skills/guide/states-and-modes.md

@@ -0,0 +1,55 @@
+# States and modes
+
+A design shows on the canvas as a grid of frames: its states down, and the modes it shows across. Both multiply what you
+have to check, and both are cheap to add, so use them instead of copying designs.
+
+## States
+
+A state is one situation the design can be in. Most screens need some of these:
+
+| State          | What changes                                                                 |
+| -------------- | ---------------------------------------------------------------------------- |
+| Loading        | Content swaps for skeletons of the same size, so nothing jumps when it loads |
+| Empty          | The list or table hides; an empty state says why and offers the next step    |
+| Error          | A message near what failed, saying what happened and what to do              |
+| Partly filled  | One item, a long name, a missing photo: the cases real data brings           |
+| Disabled, busy | A submit button that's disabled or shows progress while saving               |
+| Permissions    | What a viewer sees compared with an admin                                    |
+
+Build states from the base design. Put what only some states need (skeletons, an empty state, an error message) into the
+base with `hidden: true`, then show and hide things per state with `AddState(design, { name, changes })`. A state stores
+only its changes, so editing the base updates every state.
+
+Name states for the situation ("No members yet", "Invite failed"), not the change ("Table hidden").
+
+## Modes
+
+Modes are the project's, shared by every design. Each mode picks one option of each variable:
+
+- **Viewport:** a width, and a device. Desktop, tablet and mobile are typical.
+- **Theme:** a class on the frame, such as `dark`, that switches the project's tokens.
+- **Locale:** `lang` and `dir` attributes, for languages and right-to-left scripts.
+
+`GetModes()` lists them. A design shows its main mode and, beside it, any others you choose with
+`UpdateDesign(design, { showModes: ["desktop-dark", "mobile-light"] })`. Show the modes that matter for the design: a
+dashboard in desktop and mobile, a component in light and dark.
+
+## Viewports and responsive patches
+
+One design covers every viewport. Patch the differences with `Responsive(node, viewport, patch)` on the nodes that
+change:
+
+```js
+Responsive("dashboard/Sidebar", "mobile", { hidden: true })
+Responsive("dashboard/Stats", "tablet", { style: { columns: 2 } })
+Responsive("dashboard/Stats", "mobile", { style: { columns: 1 } })
+Responsive("dashboard/Content", "mobile", { style: { padding: [5, 4] } })
+```
+
+The viewport is the viewport option's id, not the mode's. A frame is as wide as its viewport and as tall as its content,
+unless the design sets a size for that viewport.
+
+## Checking them all
+
+After a change, screenshot every frame the design shows: `Screenshot(design, { state: "all", mode: "shown" })`. Check
+dark mode for colours that only worked on white, mobile for rows that don't fit, and each state for a layout that jumps.

package/skills/guide/web-app.md

@@ -0,0 +1,43 @@
+# Web app screens
+
+A web app is used, not read. People come to a screen to do something: check a number, find a record, change a setting.
+Design each screen around that job.
+
+## Before you design
+
+Answer three questions, from the request or by asking:
+
+1. **Who uses this screen, and what do they come to do?** The main task gets the most space and the first look.
+2. **What data does it show?** Real fields, typical amounts, and the extremes: none, one, thousands, a very long name.
+3. **What can go wrong?** Loading, empty, errors, no permission. Each is a state of the design.
+
+## Layout
+
+- **App shell.** Navigation in a sidebar or top bar, then the page. Make the shell a component design (`app-sidebar`,
+  `app-top-bar`) and place it as an instance on every screen, so it stays the same everywhere.
+- **Page header.** The page's title, a line saying what it's for when that isn't obvious, and its main actions at the
+  end of the same row.
+- **Content.** Lead with what the person came for. On a dashboard that's a few key numbers, then what changed, then
+  detail. On a list, the list, with search and filters above it.
+- **Width.** Forms and reading text work best narrow (a `maxWidth` around 160 steps); tables and dashboards use the
+  room.
+
+## Common screens
+
+- **Dashboard.** A row of stat cards (a component design), then a chart or a table of what needs attention. Every number
+  says what it is and, where it helps, how it changed.
+- **List and table.** A header with the count and the main action, search and filters, the table, and pagination or a
+  "load more". Row actions sit at the end of the row. Plan the empty state and the filtered-to-nothing state, which are
+  different.
+- **Detail.** The record's name and status at the top, its main facts in a card, then related lists in tabs.
+- **Settings.** Sections with a title and a line of explanation on one side and the fields on the other, or stacked on
+  mobile. Save per section, and show when it saved.
+- **Forms.** One column. Labels above fields, help text under them, errors under the field they're about, in
+  `destructive`. The primary button at the end; disable it or show progress while it saves.
+- **Sign in and onboarding.** One task per screen, centred, narrow, with the product's name or logo above it.
+
+## Behaviour
+
+Designs are static, but they should show behaviour as states: a menu open, a dialog over the page, a toast after saving,
+a row being edited. When you're unsure whether something works, ask the person to try it with the Interact tool; it uses
+the real components.