@parity-app/cli 0.0.0-stage → 0.0.0

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.