altitude-design 0.3.2 → 0.4.0

package/dist/guidance/components/PageHeader/README.md

@@ -0,0 +1,29 @@
+# PageHeader
+
+The block every page opens with: breadcrumb, title, a line of description, the page's actions, and sometimes tabs.
+
+**Elevation.** The page's name is the record, so the block lies on the ground. Only its actions are live: secondaries at level 1, ghosts at 0, and **one primary at level 2, in its own slot**. "The primary action rests at level 2" (law 1) becomes structural: `primary` takes one element, and a `variant="primary"` button put in `actions` logs a development warning naming law 1. Actions that don't need to be seen go in `overflow`, a "More actions" menu (`DropdownMenu`, level 3). With `sticky`, the header stays at the top and **rises one level when content passes under it** (`surface-raised`, `elev-1`), as `ScrollArea`'s header does.
+
+**Layout.** The breadcrumb sits above, the title and description on the left, and the actions on the right (the primary last, nearest the reading edge). Tabs go underneath. Everything wraps on narrow screens. Set `--alt-page-pad` to the page's side padding (`AppShell` does) and the header reaches through it, so a sticky header's rise spans the page.
+
+**Accessibility.** A `<header>` with the page's `h1` (`PageHeaderTitle`). The tab order is breadcrumb, actions, tabs. "More actions" is a [menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/). Under forced colours a risen sticky header gets a bottom border.
+
+**Props.** `PageHeader`: `breadcrumb`, `primary`, `actions`, `overflow` (`DropdownMenu` entries), `tabs`, `sticky`. Inside it go `PageHeaderTitle` (an `h1`) and `PageHeaderDescription`.
+
+**You provide:** the page's name, what it's for in one line, and its actions, with the one that matters most as `primary`.
+
+```tsx
+<PageHeader sticky
+  breadcrumb={<Breadcrumb items={[{ label: 'Settings', href: '/settings' }, { label: 'Members' }]} />}
+  primary={<Button variant="primary">Invite members</Button>}
+  actions={<Button variant="secondary">Export list</Button>}
+  overflow={[{ label: 'Download audit log', onSelect: download }]}>
+  <PageHeaderTitle>Members</PageHeaderTitle>
+  <PageHeaderDescription>People who can see and edit this workspace.</PageHeaderDescription>
+</PageHeader>
+```
+
+- Do give a page at most one primary action; put the rest in `actions` or `overflow`.
+- Do keep the description to one line about what the page is for.
+- Don't put a PageHeader inside a `Card`; that's `CardHeader`.
+- Don't make the whole header a raised card. It lies on the ground, and only rises while content passes under it.

package/dist/guidance/components/Pagination/README.md

@@ -0,0 +1,25 @@
+# Pagination
+
+Moves through pages of a collection the server pages: invoices, members, audit events.
+
+**Elevation: one thumb that travels.** The page numbers sit in a trench (`surface-well`), and **the current page is one raised thumb that travels to it** on `ease-glide`, as `RadioGroup`'s does. That reads as "you are here, among these", where a row of buttons reads as "any of these does something". Pointing at another page shows a ghost of the thumb there (feedforward). While the next page loads (`loading`), the thumb is held pressed until the rows arrive. Previous and Next are ghost buttons, flush and `ink-faint` at the ends.
+
+**Pages.** It shows the first page, the last, and the current one with `siblings` either side, with "…" where pages are skipped. A gap of a single page shows that page instead, because "…" would take as much room. `pageRange()` gives the same list. **Cursor paging:** leave out `pageCount` and you get Previous, Next (disabled once `hasNext` is false) and "Page 3".
+
+**Summary.** With `total` and `pageSize` it says "41–60 of 214 invoices" (`noun`) in a polite live region, so the change is announced after a page change.
+
+**Accessibility.** A `nav` labelled "Pagination", with links when `hrefFor` gives pages URLs, or buttons otherwise. **They stay in plain Tab order:** these are links drawn like a radio group, not a radio group, so there's no roving focus. The current page has `aria-current="page"`. Pages are named "Page 3", and the steps "Previous page" and "Next page", with `aria-disabled` at the ends. Below 480px the steps show only their chevrons. Under forced colours the trench is dashed and the thumb has a 1px border. Under `contrast="more"` the thumb gets a 2px slab. Under reduced motion the thumb appears in place.
+
+**Props:** `page` (from 1); `pageCount`; `onPageChange`; `total`, `pageSize`, `noun`; `hrefFor`; `hasNext`; `siblings` (default 1); `loading`; `locale`; `aria-label`.
+
+**You provide:** the current page, how many there are (or whether there's a next one), and what happens on a change.
+
+```tsx
+<Pagination page={page} pageCount={11} onPageChange={setPage} total={214} pageSize={20} noun="invoices" />
+<Pagination page={page} onPageChange={setPage} hasNext={!!cursor.next} />   // cursor paging
+```
+
+- Do use `hrefFor` when pages have URLs, so they can be opened in a new tab.
+- Do show the summary; "Page 3 of 11" says less than "41–60 of 214".
+- Don't page short lists; show them whole.
+- Don't use it for steps in a process; that's a `Stepper`.

package/dist/guidance/components/PasswordInput/README.md

@@ -0,0 +1,34 @@
+# PasswordInput
+
+A password field: signing in, signing up, a reset, "change password" in settings.
+
+**Elevation.** It's an `Input`, so it's an opening that fills. In its end cap sits a reveal `Toggle`. While the password shows, the toggle is on: sunk and filled, as every Toggle is. Its name ("Show password") never changes; `aria-pressed` says whether it's on.
+
+**Strength is a reading.** When you pass `strength`, the score (0–4, from your scoring: zxcvbn or your own rules) is shown as a `Meter`: a flush track with flat ink, never `Progress`'s raised fill, because a password's strength is a reading, not a task moving toward done (see [Charts](../../visual/Charts.md)). The word ("Weak", "Good", "Strong") sits beside the label and carries the meaning. The fill stays the meter's own colour: Meter's thresholds mean "higher is worse", which is backwards for strength.
+
+**Requirements** are stamped as they're met, like a done `Checklist` item: muted, with a check pressed into a small well. Unmet ones keep an empty ring.
+
+**Caps Lock.** While the field is focused and Caps Lock is on, a caption with an icon says "Caps Lock is on".
+
+**Accessibility.** A plain `<input type="password">`, with `autocomplete="new-password"` when there's a strength meter or requirements, and `"current-password"` otherwise (pass `autoComplete` to say otherwise). The reveal toggle is a separate tab stop after the field, and revealing doesn't move focus. Strength, requirements and the caps-lock notice describe the field (`aria-describedby`). Strength and unmet requirements are announced politely once typing pauses (0.9s), not on every key. The meter's value text is the word. Under forced colours the requirement stamps and the caps-lock icon are `CanvasText`.
+
+**Props:** `strength` (`(value) => 0–4`); `strengthLabels`; `requirements` (`{ label, test }[]`); `revealLabel` (default "Show password"); and every `Input` prop except `type` and `trailing`.
+
+**You provide:** the scoring and the rules, when people are creating a password. For signing in, nothing more than a label.
+
+```tsx
+<Field label="New password">
+  <PasswordInput
+    strength={(v) => zxcvbn(v).score}
+    requirements={[
+      { label: 'At least 12 characters', test: (v) => v.length >= 12 },
+      { label: 'Not a common password', test: notCommon },
+    ]}
+  />
+</Field>
+```
+
+- Do let people reveal what they typed; masking alone causes errors.
+- Do say your rules before someone breaks them, as requirements.
+- Don't draw strength as a progress bar.
+- Don't show a strength meter when signing in; it's for creating a password.

package/dist/guidance/components/PermissionMatrix/README.md

@@ -0,0 +1,28 @@
+# PermissionMatrix
+
+Roles against permissions: "Admins can manage billing, Members can invite, Viewers can only read". The same grid serves notification preferences (events against channels).
+
+**Elevation.** The grid is settled: the record of who can do what, on the ground with `line` dividers.
+- **An editable grant is a choice**, built like a `Checkbox`: an empty trench that the accent pours into when granted.
+- **An inherited or fixed grant is already decided**, so it's a flush stamped check (or a dash when not granted), muted, like a done `Checklist` item. It's pressed into the record, not drawn as a disabled checkbox, because it isn't unavailable. A `locked` role (an owner) has every permission, stamped.
+- **The active cell** is a 2px `accent-ink` ring, never a height, as in `DataGrid`.
+- **Saving:** a toggled cell whose `onChange` returns a promise hovers as pending until it settles, then takes the afterglow. A rejection reverts it.
+
+**Accessibility.** The [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) with checkbox cells. Arrow keys move, Home and End go along the row, Ctrl+Home and Ctrl+End go to the corners, and Space or Enter toggles. Each cell reads "Manage billing, Admin, checked". A stamped cell is `aria-readonly` and says why ("Granted, inherited from Everyone", "Always granted to Owner"): it's reachable, and toggling it says it can't be changed here. Changes are announced ("Create projects granted to Viewer"). Group headings head their rows. Under forced colours the ring is `Highlight` and stamped cells keep their glyph. Under `contrast="more"` the ring is 3px.
+
+**Props:** `roles` (`{ id, name, locked? }[]`); `permissions` (`{ id, name, group? }[]`); `value` (`{ [roleId]: { [permissionId]: boolean } }`); `inherited(roleId, permissionId)` (→ `{ granted, from }` or undefined); `onChange(roleId, permissionId, granted)` (may return a promise); `aria-label`.
+
+**You provide:** the roles, the permissions, who has what, and where inherited grants come from.
+
+```tsx
+<PermissionMatrix aria-label="Role permissions"
+  roles={[{ id: 'owner', name: 'Owner', locked: true }, { id: 'admin', name: 'Admin' }]}
+  permissions={[{ id: 'billing.manage', name: 'Manage billing', group: 'Billing' }]}
+  value={grants} inherited={(role, perm) => inheritFrom(role, perm)}
+  onChange={(role, perm, granted) => saveGrant(role, perm, granted)} />
+```
+
+- Do say where an inherited grant comes from.
+- Do return a promise from `onChange` so a cell shows it's saving.
+- Don't draw inherited grants as disabled checkboxes.
+- Don't lift the active cell; it's a ring.

package/dist/guidance/components/Pile/README.md

@@ -0,0 +1,12 @@
+# Pile
+
+Shows a group of items as a stack. Its thickness says roughly how many; click it and the items fan out over the page.
+
+**Closed.** The top card is raised (level 1). Beneath it sit 0–3 sheets: none for one item, one for 2–3, two for 4–9, three for 10 or more. Thickness is read in bins, so the count badge carries the number. On hover or focus the top lifts and the sheets beneath fan a little, a preview of what's underneath; nothing moves before the pointer is on it.
+
+**Open.** Give the pile `items` and `renderItem` and its top card becomes a toggle. Clicking it (or Enter/Space) slides the items out from under the top card, one after another, into a column that **floats over the page below**: nothing on the page moves. Each item is its own card with its own shadow (`elev-2`, `elev-3` under the pointer); the scroll area itself has none, and its top and bottom edges fade out rather than cutting the shadows off. Click an item to choose it (`onSelect`). Click the top again, press Escape or click anywhere else and the items slide back under. Long piles scroll after `maxHeight`.
+
+**You provide:** `items`, `renderItem(item, { index })`, `onSelect`, the top card's content as children, optionally `getKey`, `maxHeight` and `open`/`onOpenChange` (for example, to close it after a choice). For a pile that only shows quantity, pass `count` instead of `items`.
+
+- Leave room below a pile, or near the bottom of the viewport the list may run off-screen.
+- Use piles for collections people triage: review queues, inboxes, stacks of drafts.

package/dist/guidance/components/PlanPicker/README.md

@@ -0,0 +1,25 @@
+# PlanPicker
+
+Choose a plan (Free, Pro, Business) in sign-up, upgrade and downgrade flows, with a Monthly / Annually switch, prices, and what each plan includes.
+
+**Elevation: one choice, one mark.** "A radio group is one switch with several positions, so its single thumb slides to the chosen option." The plan cards are positions in one group: they lie flush on the ground with a `line` rim, and **one raised mark travels to the chosen card's corner** on `ease-glide`. The chosen card also takes an `accent` rim. Pointing at another card shows a ghost of the mark there.
+
+**No lifted "most popular" card.** Pricing pages usually raise and glow the plan they want you to pick. Marketing emphasis isn't importance *right now*, so it isn't height. **"Recommended" and "Current plan" are flush `Badge` plates.** The only level-2 slab is your Continue button beside the picker (law 1), and its label should name the outcome ("Continue to Pro").
+
+**Prices** come in minor units and are formatted by `FormattedNumber`, so changing the period cross-fades them and never counts. Annual prices are shown per month, "billed annually". A plan with `price: null` says "Contact sales". A plan with `unavailable` can't be chosen and says why.
+
+**Accessibility.** A [radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/): one tab stop, and arrows move and choose (skipping unavailable plans). Each plan reads its name, price and period ("Pro, €20.00 per seat per month, billed annually, recommended"), with its features as the description. The period switch is a single-choice `ToggleGroup`. Under forced colours the chosen card has a 2px border and the mark keeps a `CanvasText` outline. Under `contrast="more"` the mark gets a hard slab. Under reduced motion the mark appears in place.
+
+**Props:** `plans` (`{ id, name, description?, price ({ month, year } | number | null), currency?, unit?, features?, unavailable? }[]`); `value`, `defaultValue`, `onValueChange`; `current`; `recommended`; `period`, `onPeriodChange`; `locale`; `aria-label`.
+
+**You provide:** the plans and their prices, the current plan, and the Continue button. The flow around it (proration, downgrade consequences) is the billing pattern.
+
+```tsx
+<PlanPicker plans={plans} value={plan} onValueChange={setPlan} current="free" recommended="pro" period={period} onPeriodChange={setPeriod} />
+<Button variant="primary" onClick={next}>Continue to {planName}</Button>
+```
+
+- Do name the outcome on the Continue button.
+- Do say why a plan can't be chosen.
+- Don't lift or glow a recommended plan.
+- Don't animate prices counting up when the period changes.

package/dist/guidance/components/Popover/README.md

@@ -0,0 +1,12 @@
+# Popover
+
+Shows rich, interactive content anchored to a trigger, floating at level 3.
+
+It grows from the trigger's edge (`transform-origin` on that side), rising 6px from 96% scale while its shadow climbs to `elev-3`. Focus moves to the first control inside; Escape or a click outside closes it and returns focus to the trigger.
+
+**On a narrow screen.** It opens where its `side` and `align` put it, then shifts sideways to stay 8px inside the screen, and it's never wider than the screen less 16px.
+
+**You provide:** `trigger` (a Button), children (padding is `space-4`), `side`, `align`, an `aria-label`, and `open`/`onOpenChange` if you need control.
+
+- Do use it for small forms and pickers that belong to one control.
+- Don't use it for a decision that blocks the page; that's a Dialog.

package/dist/guidance/components/Progress/README.md

@@ -0,0 +1,10 @@
+# Progress
+
+Shows how far along a task is: a raised fill rising out of a trench.
+
+Determinate progress glides between values on `ease-glide` (`dur-travel-3`). Without a `value` it's indeterminate: a third-width fill travels across the track every `dur-sweep`, and stops under reduced motion.
+
+**You provide:** `value` (0–`max`) or nothing, and an `aria-label` or a visible label nearby.
+
+- Do switch from indeterminate to determinate as soon as you know the total.
+- Don't use it for a reading such as storage used of a quota: that's the record, not a task, so it's a [`Meter`](../Meter/README.md).

package/dist/guidance/components/PromptInput/README.md

@@ -0,0 +1,40 @@
+# PromptInput
+
+Where a person writes to an assistant or agent: a textarea that grows, attachments as chips, optional tools or a model picker, Send, and Stop while a response is generating.
+
+**Elevation: an opening.** The whole composer is the `Input` well. Empty, its back wall shows and it deepens as the pointer nears; once it holds text its floor rises flush (Completeness and Anticipation, as `Textarea`).
+- **Send is the level-2 primary.** With nothing to send (no text, or a file still uploading) it's flush and faint, but stays focusable (`aria-disabled`).
+- **While generating, Send becomes Stop in the same slot and size**, held as the live action. Its icon cross-fades without travel, so nothing moves.
+- **Attachments are `Tag` plates** above the text. One being uploaded (your `onAttach` returned a promise) hovers as pending, "Uploading". A rejection removes it and says so.
+- **Dragging a file over** drops the well to a trench, "Drop to attach", as `DropZone` does. It opens only while something could be dropped.
+
+**Keyboard.** Enter sends. Shift+Enter adds a line. **Enter during IME composition never sends**, because it confirms the composition (Japanese, Chinese, Korean input). Escape stops generating. ⌘U or Ctrl+U attaches. Pasting a file attaches it. After sending, focus stays in the composer.
+
+**Accessibility.** Plain HTML: a `<form>` with a labelled `<textarea>` ("Message" unless you name it) and buttons named "Send message", "Stop generating" and "Attach files". Sending isn't announced, because the conversation announces the response. Stopping is ("Generating stopped"), and so are attachments added and removed. Under forced colours the empty well is dashed and a drop target dashed thick. Under reduced motion the composer grows without gliding.
+
+**Parts:** `PromptInput` (`onSubmit({ text, files })`, `status` (`'ready' | 'submitted' | 'streaming' | 'error'`), `onStop`, `value`, `onValueChange`, `onAttach`, `accept`); `PromptInputAttachments`; `PromptInputTextarea` (`placeholder`, `maxHeight`); `PromptInputToolbar`; `PromptInputAttach`; `PromptInputSubmit`.
+
+**Queueing.** With `onQueue`, Enter while the agent works queues the message instead of doing nothing: the button stays Stop, the composer empties and keeps focus, and "Message queued. It will be sent when the assistant finishes." is announced. Show the queue with `ConversationQueue`, and send the first one when the turn ends.
+
+**Context and commands.** With `mentionable(query)`, typing @ opens a list of matches above the composer, grouped by kind (Files, Records, People), ranked as you return them; a promise shows "Searching…". Choosing one puts "@label" in the text and a plate in the composer's context row; Backspace right after it removes it whole, and its plate's remove button does the same. With `commands`, / at the start of an empty composer lists them (best match first). `onSubmit` gets `mentions` and `command` separately; the command is taken out of `text`. The text is a combobox (arrows, Enter or Tab to choose); while generating, the first Escape closes the list and only a second one stops. IME composition never opens or drives it.
+
+**Dictation.** `PromptInputDictate` (in the toolbar) is a microphone toggle; your app supplies the speech recognition (the Web Speech API or a server transcriber) and passes `status`, `interim` and `final`. Listening is latched like a Toggle that's on (a shallow well with accent-soft poured in) with "Listening" and a steady lamp: no pulse, no waveform. Interim words are a ghost under the text in `ink-faint`, like a suggestion, never in the value; `final` words go in at the caret. ⌘D / Ctrl+D toggles from the text; Escape stops listening before it stops generating. "Listening" and "Stopped listening" are announced; interim words aren't. Blocked or unavailable stays focusable and says why.
+
+**You provide:** sending, stopping, uploading, and the `status` of the response. Leave out `accept` and there are no attachments.
+
+```tsx
+<PromptInput onSubmit={(msg) => send(msg)} status={status} onStop={stop} accept="image/*,.pdf">
+  <PromptInputAttachments />
+  <PromptInputTextarea placeholder="Ask about this workspace" />
+  <PromptInputToolbar>
+    <PromptInputAttach />
+    <Select size="sm" aria-label="Model" items={models} />
+    <PromptInputSubmit />
+  </PromptInputToolbar>
+</PromptInput>
+```
+
+- Do keep Stop where Send was.
+- Do return a promise from `onAttach` so an upload shows it's in flight.
+- Don't send on Enter during IME composition (it's handled; don't override `onKeyDown` to send).
+- Don't announce "Message sent".

package/dist/guidance/components/PropertyList/README.md

@@ -0,0 +1,57 @@
+# PropertyList
+
+One record's properties as label–value pairs, each editable where it sits: an issue's sidebar (status, assignee, priority, estimate), a customer's details, a settings summary, a “Check your answers” page. It's GOV.UK's summary list and Ant Design's Descriptions, with Linear-style editing: each editable value is an [InlineEdit](../InlineEdit/README.md) with any control, and “Edit all” is one [EditRegion](../EditRegion/README.md).
+
+```tsx
+<PropertyList aria-label="Issue details" shortcuts>
+  <PropertyListItem label="Status" value={issue.status} shortcut="s"
+    renderValue={(s) => <Badge tone={toneFor(s)}>{labelFor(s)}</Badge>}
+    editor={(control) => <Select {...control} items={statuses} />} commit="on-choose"
+    onSave={(draft) => api.patch(issue.id, { status: draft }, issue.revision)}
+    onValueChange={(status) => setIssue({ ...issue, status })} />
+  <PropertyListItem label="Priority" value={issue.priority} emptyLabel="Add priority" … />
+  <PropertyListItem label="Created" value={formatDate(issue.createdAt)} />      {/* read-only: no onSave */}
+</PropertyList>
+```
+
+`onSave` makes an item editable, with InlineEdit's whole contract (`editor`, `commit`, `validate`, `required`, `isEqual`, retained input on failure, conflict latching). Without it the value is read-only text.
+
+## Elevation
+
+- **Properties** are the record, on the ground: a `dl`, labels `ink-muted` above (`layout="stacked"`, a sidebar) or beside (`layout="inline"`, a summary, with `line` rules) their values.
+- **An editable value** is one plate, the InlineEdit trigger, that lifts one level (`elev-1`) when pointed at, because clicking it opens its editor. Read-only values never lift, so editability shows without a pencil per row (hover is a promise).
+- **An unset value** is a small opening: a dashed well, the empty field's treatment at plate size, naming what to add (“Add priority”), so a half-filled record reads at a glance. Setting it fills it.
+- **Editing** opens InlineEdit's well in the value's place, under its own text, so the value doesn't move; with `commit="on-choose"` the picker's list rises from it and there's no Save. Pending, failed and accepted are InlineEdit's.
+- **Edit all** (`editAll`) lifts the whole list into one raised `EditRegion`, for records with cross-field rules (a last day on or after the first).
+- **A proposed change** (an item's `proposed`: an agent read an email and suggests "Stage: Qualified → Proposal", or a teammate's suggested edit) is status that asks for action, so that field is **raised one level** (as `Confirmation`). It shows the current value struck through beside the proposed one (`DiffView`'s property change), "Proposed by Assistant", and Reject and Accept. **Nothing touches the record until it's accepted.** Accepting saves through `onSave`, hovering as pending ("Saving…") and settling with the afterglow (staggered for Accept all, at most four at once). A failed save drops to a trench with the reason and Retry. A raised summary above the list counts the proposals ("3 proposed changes by Assistant") with Accept all and Reject all.
+
+Each editable value is a button named by the label, the value and the verb (“Status: In review. Change status”), as GOV.UK's visually hidden “Change name” guidance asks, so it makes sense out of context. Each change is announced (“Status set to Done”). Proposals are a labelled group (“3 proposed changes”); each Accept and Reject names its field (“Accept new amount”), the old and new values are read as “Current” and “Proposed”, and outcomes are announced (“New amount saved”, “Rejected the new stage”). Forced colours: unset values dashed, the hover plate outlined. `contrast="more"`: the hover plate gets the level-1 ink slab.
+
+## Keyboard
+
+Tab moves through the editable values; Enter or Space opens one, and the editor behaves as InlineEdit (Escape cancels, focus returns to the value). With `shortcuts` on the list, an item's `shortcut` key opens it while focus is in the list and not in a field (`s` for status, as Linear does), and the value announces it with `aria-keyshortcuts`. Shortcuts are off by default: WCAG 2.1.4 asks that single-key shortcuts can be turned off or remapped, so offer a setting before turning them on.
+
+## Props
+
+| | |
+|---|---|
+| `PropertyList` | `layout` (`'stacked'` or `'inline'`), `shortcuts`, `editAll` (`{ value, onValueChange, onSave, validate?, renderEditor, label? }`), `proposedBy`, `aria-label`/`aria-labelledby` |
+| `PropertyListItem` | `label`, `value`, `renderValue`, `emptyLabel`; editable with `onSave`, `onValueChange`, `editor`, `commit`, `validate`, `required`, `isEqual`, `shortcut`; `proposed` and `onProposalResolved(accepted, value)` (clear `proposed` there) |
+
+InlineEdit gains `trigger="value"` (read mode as one value plate), `emptyLabel` and `shortcut` for this; they're available on their own too.
+
+## You provide
+
+The record and each property's write, and for Edit all the whole-record write and its cross-field rules.
+
+## Do and don't
+
+- **Do** use `emptyLabel` to name what's missing (“Add due date”), not just “Not set”.
+- **Do** keep Edit all for records with rules across fields; otherwise edit each property where it sits.
+- **Don't** turn on shortcuts without a way to turn them off.
+
+## Demo and verification
+
+The `PropertyList` section of `build/previews.txt` shows an issue sidebar (status, assignee, priority unset, estimate, created) with shortcuts on, and a “Check your answers” summary with an unset phone number and Edit all. `node checks/property-list.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers the `dl` structure, value buttons and their names, read-only text, unset openings, on-choose saves and announcements, filling an unset value, validation and Escape, shortcuts, Edit all with a cross-field rule and focus return, and 320/960px layouts in both schemes under reduced motion, forced colours and `contrast="more"`.
+**Narrow.** Under 480px of its own width, an inline list stacks each label over its value, and a proposed change stacks its values, who proposed it and its Reject and Accept.
+

package/dist/guidance/components/Question/README.md

@@ -0,0 +1,27 @@
+# Question
+
+An agent asks the person something before it carries on: "Which environment should I deploy to?", "Keep the old column or drop it?". The person picks one or several options, or writes their own answer, and the run continues. This is the elicitation half of human-in-the-loop (MCP elicitation, Claude Code's AskUserQuestion); `Confirmation` is the approval half.
+
+**Elevation: status that asks, until it's answered.**
+- **Asking** is `Confirmation`'s requested card: raised at level 1 ("The assistant is asking", the question as its title). Nothing has been dispatched, so it's raised, not pending. It arrives with the afterglow.
+- **Options** are trenches: a radio group for one, checkboxes for several, with descriptions. **Your own answer** is a field (a well).
+- **Answer** is the one primary; **Skip** (`skipLabel`) is a ghost button.
+- **Answered**, it presses to the ground as one muted line in the record: "Which layout…? · You chose: Compact · 3 minutes ago". **Expired** says "No longer needed".
+
+**Accessibility.** A section labelled by its question, holding a radio group (arrows) or a group of checkboxes; not a dialog. There's no default answer and nothing is focused for you; the composer keeps focus. Asked, it's announced assertively once ("The assistant is asking: …"), because the run is waiting on it; answered, politely ("Answered: Staging"). Enter in your own answer doesn't submit.
+
+**Props:** `Question`: `title`, `state` (`'asking' | 'answered' | 'expired'`), `multiple`, `allowOther`, `otherLabel`, `answerLabel`, `skipLabel`, `onSkip`, `onAnswer({ values, other })`, `answer`, `answeredAt`, `requestedBy`, `name` (its key in a set). `QuestionOption`: `value`, `label`, `description`. `QuestionSet`: `state`, `onAnswer(answers by name)`, `answerLabel`, `skipLabel`, `onSkip`: several questions answered by one button.
+
+**You provide:** the options, what answering does, and the answer to show once it's answered.
+
+```tsx
+<Question title="Which environment should I deploy to?" state={q.state} answer={q.answer} allowOther
+  answerLabel="Deploy" skipLabel="Let the assistant decide" onAnswer={(a) => respond(q.id, a)} onSkip={() => skip(q.id)}>
+  <QuestionOption value="staging" label="Staging" description="Resets nightly. Safe to try things." />
+  <QuestionOption value="production" label="Production" description="Customers will see it immediately." />
+</Question>
+```
+
+- Do describe what each option means for the run.
+- Do offer a way to let the assistant decide when a default exists.
+- Don't preselect an option or move focus to the question.

package/dist/guidance/components/RadioGroup/README.md

@@ -0,0 +1,10 @@
+# RadioGroup
+
+Chooses exactly one option. A radio group is built like the Switch with more positions: **one switch, several positions, one thumb**.
+
+Each option is a round trench, the same as the switch track. The group owns a single raised thumb; choosing an option slides it to that track on `ease-settle`, and the accent pours into the track from under the thumb as it arrives while the old one drains. Because there's only one thumb, the choice can't be in two places, and its movement shows where it came from. Hovering an unchosen option shows a faint ghost of the thumb where it would land (feedforward); hovering the chosen option lifts the thumb; pressing it stretches the thumb, like a switch. Arrow keys move the choice, as native radios do, and the thumb follows.
+
+**You provide:** `Radio` children with `value`, `label` and optional `description`; `value`/`onValueChange` or `defaultValue`; an `aria-label` for the group if there's no visible heading; `orientation="horizontal"` for two or three short options.
+
+- Default to a sensible choice; a group with no thumb is rarely what you want.
+- Don't use radios for more than about six options; use a menu.

package/dist/guidance/components/RelativeTime/README.md

@@ -0,0 +1,26 @@
+# RelativeTime
+
+A moment shown as "3 minutes ago", for activity feeds, audit logs, comments and "last edited". `formatRelativeTime()` gives the same words as a string.
+
+**Elevation.** A timestamp is part of the record, so it's plain text on the ground. **Ticking forward is not a change to the record:** "3 minutes ago" becoming "4 minutes ago" swaps the words with no transition and no afterglow. When the moment itself changes (the record was edited again), that is a change, and the time takes the same ground-level tint as a changed `FormattedNumber`, decaying over `dur-settle`.
+
+**Refreshing.** Every RelativeTime on the page shares one timer (every 15 seconds). It stops while the page is hidden and catches up as soon as the page is visible again. Words come from `Intl.RelativeTimeFormat` with `numeric: "auto"`, so you get "now", "yesterday" and "last month", pluralised for the locale.
+
+**Formats.** `relative` (default) always says how long ago or until. `auto` is relative within `threshold` (an ISO 8601 duration such as `"P7D"` or `"PT12H"`, or milliseconds; default 7 days), then a date ("Mar 4", or "Mar 4, 2025" in another year). `tense="past"` never says "in 2 minutes", even when a client's clock runs ahead, and `tense="future"` never says "ago".
+
+**Accessibility.** It renders a `<time dateTime="…ISO…">`. With `tooltip` (on by default) it's focusable, and the exact date, time and zone ("Wednesday, October 29, 2026 at 3:04:12 PM EDT") is shown in a `Tooltip` on hover and focus and attached with `aria-describedby`. With `tooltip={false}` the exact time is its `title`. Ticking is never a live region. Under forced colours a new moment's tint is a `Highlight` outline.
+
+**Props:** `date` (a `Date`, ISO string or epoch ms); `format` (`'relative' | 'auto'`); `threshold`; `tense` (`'auto' | 'past' | 'future'`); `locale`; `tooltip` (default true).
+
+**You provide:** the moment, and whether old moments should become dates (`format="auto"`).
+
+```tsx
+<RelativeTime date={event.createdAt} />                    // "3 minutes ago"
+<RelativeTime date={due} format="auto" threshold="P7D" />   // relative within 7 days, then "Mar 4"
+<RelativeTime date={d} locale="fr" tense="past" />          // "il y a 3 minutes"
+```
+
+- Do use `format="auto"` in logs and feeds that reach back further than a week.
+- Do keep the tooltip on wherever the exact time matters (audit logs, billing).
+- Don't put a RelativeTime in a live region, or announce it ticking.
+- Don't format times by hand with string concatenation.

package/dist/guidance/components/RemovalReceipt/README.md

@@ -0,0 +1,34 @@
+# RemovalReceipt
+
+The slot of an item that can leave its list: a file archived, a webhook removed, an invitation revoked. When the item goes, its result shows in its own slot, at the height it had, so nothing on the page moves while it's read. The slot holds, lifts its receipt off, and only then glides the gap closed. Use it instead of removing the row at once and adding an Alert below the list, which reshapes the page twice and puts the feedback away from where the person acted.
+
+**Left in place, then closed.** With `removed`, the item's content cross-fades (`dur-travel-2`) to the receipt: a check (or, with `tone="critical"`, an alert icon), your `title`, and your `action`. While `pending`, the write isn't confirmed: the receipt shows a spinner in place of the check, the slot hovers as pending only after `dur-grace` (a fast write never flickers), and the hold hasn't started. Once confirmed, the receipt holds for `dur-linger` (2000ms), then lifts off as an Alert does (8px, in 70% of `dur-travel-3`, `ease-sink`), and the gap glides shut (`dur-travel-3`, `ease-glide`). The rows below are pushed by the height, not animated on their own. `onClosed` is called once the gap has closed: drop the item from your list there.
+
+**The hold waits for the person.** It pauses while the receipt is pointed at or focused, and while a modal owns the document. When it's due and a mouse is still over the list (the slot's parent), it waits for the pointer to leave, up to `dur-settle`, so the next row doesn't slide under a pointer reaching for it. Touch has no hover, so on touch it closes when the hold ends. Receipts due within 250ms of each other close together, as one change.
+
+**Why it's on the ground.** The receipt is a trace of what happened to the record, not a live surface, so it doesn't rise for attention: muted ink on the ground. Only its exit lifts off. Pending uses the shared pending signal (`surface-lifted`, `elev-2`, breathing over `dur-hover`). An item brought back from elsewhere (`arrive`) glides its slot open and settles with an afterglow; an item restored while its receipt is still held (`removed` back to false) returns in place with an afterglow.
+
+**Accessibility.** The receipt's text is a polite live region (`role="status"`) present from the slot's first render, so the result is announced when it appears. Put Undo in `action` and name it fully (`aria-label="Undo archive of Brand guidelines.pdf"`). Before the slot closes, focus inside it moves to the first focusable control of the next slot, else the previous one, else `focusFallback()`. Under reduced motion the receipt still fades and holds, nothing travels, and the gap closes at once. Under forced colours the receipt is outlined in `CanvasText`.
+
+**Props:** `removed`; `pending`; `title`; `action`; `tone` (`neutral` | `critical`); `icon`; `hold` (ms, default `dur-linger`); `onClosed`; `focusFallback`; `arrive`; `settle`; `as` (`div` | `li` | `section` | `article`, default `div`). Other props go to the slot's element, and the item's own content (`children`) keeps the slot's layout (its wrapper is `display: contents`).
+
+**You provide:** the item, whether it's removed and whether that's confirmed, the words and the actions, and what happens next. Undo has to call your real inverse operation. After the slot closes, offer Undo in a `toast` if you like, but keep a durable recovery route (Archived → Restore), and withdraw a toast's Undo (`toast.dismiss(id)`) once a newer revision makes it invalid. See [Actions in place](../../visual/ActionsInPlace.md) for the full recipe: pending, failure, conflict, late receipts and focus.
+
+```tsx
+<ul>
+  {files.map((file) => (
+    <RemovalReceipt as="li" key={file.id} removed={!!receipts[file.id]} pending={receipts[file.id]?.pending}
+      title={`${file.name} archived.`}
+      action={<Button size="sm" aria-label={`Undo archive of ${file.name}`} onClick={() => restore(file)}>Undo</Button>}
+      onClosed={() => { dropReceipt(file.id); toast({ title: `${file.name} archived.`, action: { label: 'Undo', onClick: () => restore(file) } }); }}>
+      <FileRow file={file} onArchive={() => archive(file)} />
+    </RemovalReceipt>
+  ))}
+</ul>
+```
+
+- Do keep the item in its slot until its removal is confirmed; show a failure in the restored row, not somewhere else.
+- Do put Undo where the removing action was, so a second click under the pointer reverses rather than navigates.
+- Don't hold the receipt for longer to "make sure": the person can stop it by pointing at it or focusing it.
+- Don't use it for a line removed while typing (an empty `Checklist` line); nothing was lost, and the hold would sit in the way. Checklist glides the line shut instead.
+- Don't use it for permanent deletion without saying so: a deletion's receipt has no Undo.

package/dist/guidance/components/Resizable/README.md

@@ -0,0 +1,36 @@
+# Resizable
+
+Panes side by side, with a divider you drag: an inbox, a ticket queue, a file browser, a record beside its list, an agent's chat beside its artifact.
+
+**Elevation.** The panes are settled, on the ground. **They never lift**: a detail pane opening beside its list stays on the ground, unlike a `Sheet`, which lays a task over the page. The divider is 1px of `line`. Only the grip is live:
+- At rest it's a small `line-control` plate, flush.
+- Pointed at or focused, it lifts one level.
+- **While held, it floats at level 3** ("whatever is in a hand floats").
+
+Collapsing a pane changes its size on `ease-glide`, not its level.
+
+**Sizes** are percentages of the group. Panels without a `defaultSize` share what's left. Dragging and the keys keep each pane between its `minSize` (default 10) and `maxSize` (default 90). `autoSaveId` remembers the layout in this browser, and `onLayout` reports it.
+
+**Accessibility.** The [window splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/). Each handle is `role="separator"`, focusable, with `aria-valuenow`, `aria-valuemin` and `aria-valuemax` (the pane before it, in percent) and `aria-controls` naming that pane. It's named "Resize conversations" from the pane's label. Left and Right (or Up and Down when vertical) resize by 5% (10% with Shift), and Home and End go to the limits. **Enter collapses a `collapsible` pane and restores it.** A collapsed pane is inert and hidden from assistive technology, and its handle says "Conversations collapsed". Each pane is a named `region`. Under forced colours the divider is `CanvasText` and the grip has a 1px border (2px while held). Under `contrast="more"` the divider is `line-control` and a held grip gets a hard slab. Under reduced motion collapsing doesn't animate.
+
+**Parts:**
+- `ResizablePanelGroup`: `direction` (`'horizontal' | 'vertical'`), `autoSaveId`, `onLayout`.
+- `ResizablePanel`: `defaultSize`, `minSize`, `maxSize`, `collapsible`, `aria-label`.
+- `ResizableHandle`: `withGrip` (default true), `label`.
+
+**Narrow.** Under 480px of its own width, `narrow="stack"` (the default) shows one pane at a time: `narrowPanel` picks it (default the first), and `onNarrowChange` tells you when to show a way back, the list-and-detail pattern on phones. `narrow="vertical"` stacks the panes with a horizontal grip instead, and `narrow={false}` keeps them side by side.
+
+**You provide:** the panes and their names, and sensible limits.
+
+```tsx
+<ResizablePanelGroup direction="horizontal" autoSaveId="inbox">
+  <ResizablePanel defaultSize={35} minSize={20} collapsible aria-label="Conversations">{list}</ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel aria-label="Conversation">{detail}</ResizablePanel>
+</ResizablePanelGroup>
+```
+
+- Do name every pane, so its handle has a name.
+- Do set a `minSize` that keeps a pane usable.
+- Don't use it for a task that sits on top of the page; that's a `Sheet`.
+- Don't raise a pane into a card.

package/dist/guidance/components/SaveBar/README.md

@@ -0,0 +1,27 @@
+# SaveBar
+
+Unsaved changes on a settings page or a long record form, held above the page until they're saved or discarded. People scroll past a Save button, navigate away and lose work, or don't notice there's anything unsaved. Polaris's contextual save bar solves the same problem.
+
+**Elevation: an unsaved draft at page scope is something in your hand.** "Editing is temporary local input; it isn't a pending write." So the bar floats at level 3, docked to the bottom edge. That's below a `Sheet` or `Dialog`, so it never competes with them.
+- **It appears once a change has settled into the draft** (600ms without another), not on the first key: "spend rises carefully".
+- **Save** turns it into a commitment: it hovers as a pending write ("Saving…"). Saved, it lowers away while the saved fields settle with the afterglow.
+- **A failed save drops the bar to a trench** ("We couldn't save. Your changes are kept.") with Retry, and keeps the draft.
+- **Invalid** says "2 fields need attention". Save stays enabled, so pressing it shows the errors.
+
+**With useEditRecord.** `<SaveBar record={record} />` reads `dirty`, `phase`, `errors` and the changed field count from a `useEditRecord` result, and its buttons call `submit` and `reset`. Leaving while dirty uses `useEditRecord`'s own leave handling. Without a record, pass `dirty`, `saving`, `error`, `invalidCount`, `changedCount`, `onSave` and `onDiscard`.
+
+**Accessibility.** A region labelled "Unsaved changes". It doesn't take focus when it appears, and "Unsaved changes" is announced once when the draft first becomes dirty, not on every key. ⌘S or Ctrl+S saves while it's shown. Outcomes ("Saved", or the failure) are announced politely. Under forced colours it has a 2px border, dotted while saving and a thick dash when failed. Under `contrast="more"` it gets a hard slab. Under reduced motion it fades in and out without travelling.
+
+**Props:** `record`, or `dirty`, `saving`, `error`, `invalidCount`, `changedCount`, `onSave`, `onDiscard`; `delay` (default 600); `saveLabel`, `discardLabel`.
+
+**You provide:** the record or its state, and the save.
+
+```tsx
+const record = useEditRecord({ initialValue: settings, validate, validationMode: 'submit', save: saveSettings });
+<SaveBar record={record} />
+```
+
+- Do use it for pages that collect several changes before one save.
+- Do keep the draft when a save fails.
+- Don't use it beside an `EditRegion`, which has its own Save.
+- Don't show it on the first keystroke.

package/dist/guidance/components/SavedViews/README.md

@@ -0,0 +1,24 @@
+# SavedViews and useSavedViews
+
+Named combinations of a filter, a sort and the columns, kept as tabs above a table: "My open deals", "Enterprise churn risk", "Unassigned this week".
+
+**Elevation.** The views are folder `Tabs`: the active tab and the sheet beneath it, which holds the `FilterBar` and the `DataTable`, are one raised piece. **A view you've changed is a draft.** Its tab carries an `accent` dot and "modified" in its name, and Save view (secondary), Save as new view and Reset appear beside the tabs. That's the `SaveBar`'s reading, local to the tab. Switching views uses what's already there: the table's re-sort glide and the filter's relevance motion.
+
+**The hook.** `useSavedViews({ views, defaultViewId, onSave, onCreate })` holds each view's draft (its filters, match, sort, column visibility and order). Switching away and back doesn't lose work. `modified` says when a draft differs from what's saved. Spread `filterBarProps` onto `FilterBar` and `tableProps` onto `DataTable`. `save()` hands `onSave` the view with its changes, `saveAsNew(name)` hands `onCreate` a new view, and `reset()` drops the draft. You store the views.
+
+**Accessibility.** The tabs are `Tabs` (`aria-selected`). "Modified" is part of a changed tab's name, and announced once when the view first diverges. Save as new view asks for a name in a `Popover` with a labelled field. Below 640px the actions sit above the tabs. Under forced colours the dot is `CanvasText`.
+
+**Props.** `useSavedViews(options)` returns `SavedViewsApi`. `SavedViews`: `views` (the API), `children` (the filters and table), `aria-label`. `SavedView` is `{ id, name, filters?, match?, sort?, columnVisibility?, columnOrder? }`.
+
+```tsx
+const views = useSavedViews({ views: saved, onSave, onCreate });
+<SavedViews views={views} aria-label="Deal views">
+  <FilterBar fields={fields} {...views.filterBarProps} />
+  <DataTable columns={columns} rows={rows} getRowId={(r) => r.id} {...views.tableProps} />
+</SavedViews>
+```
+
+- Do let people save a view under their own name.
+- Do keep the default view ("All deals") unfiltered.
+- Don't save a view on every change; a draft is saved when someone says so.
+- Don't use segmented tabs; the views own the table beneath them, so they're folder tabs.

package/dist/guidance/components/ScatterChart/README.md

@@ -0,0 +1,41 @@
+# ScatterChart
+
+Two measures per record, to see whether they move together and to spot the ones that don't: response time against payload per endpoint, spend against seats per customer. It's the form for relationships, and nothing else does it. It renders inside a [`ChartContainer`](../ChartContainer/README.md), whose `config` names and formats the two measures.
+
+**Why it's flat.** Dots are the record, so they lie on the plot: at least 8px (squares and triangles are drawn a little larger so they're 8px too), a `data-*` fill, and a 2px ring of the plot's own colour, so dots that overlap stay apart. No shadow, no sheen, no glow, no lift.
+
+**Groups.** `group` sorts records into at most three groups, each a colour (`data-1` to `data-3`) and a marker shape (circle, square, triangle). It's three because any two dots can be neighbours, so every pair of colours has to stay apart for colour-blind readers, and the palette's first three slots are the ones validated that way. With more than three it warns, and the rest share `data-other`: show them as small multiples instead. A `ChartLegend` keys each group by its marker, and with `toggle` hides and shows groups. A hidden group leaves the plot and the keyboard path.
+
+**Both axes are measures**, so neither has to include zero, both start and end on a tick, and each is named: y over its axis, x under its own.
+
+**Labels and trend.** `label={(d) => d.p95 > 400 ? d.name : null}` names a few dots in `ink` on a halo of the plot's colour, with a 1px `ink-muted` leader. Each label goes to the first spot that clears the plot's edges and the words already placed: above right, above left, beside, then below. A label with nowhere to go is left out, and is still in the summary and the readout. `trend` draws the least-squares line as 1px `ink-muted`, named "Trend" (or the words you pass) at its right end.
+
+**Reading a dot.** There's no crosshair: the pointer reads the nearest dot within 48px, the Voronoi cell it's in, so a dense cloud is still easy to read. The readout sits beside the dot and gives its name, both measures and its group, keyed by the group's colour. The dot under it is drawn again on top, so a dot that's overlapped can be seen whole.
+
+**Without colour.** Under forced colours the dots are `CanvasText` ringed in `Canvas`, and the shapes carry the groups. With `contrast="more"` each dot is ringed in 1px `ink`.
+
+**Motion.** With a stable `id`, dots glide to their new places when the data changes, at one level on `ease-glide`, after any rescale. Without one, a record has no identity to follow, so the plot cross-fades instead ([Motion](../../visual/Motion.md), "Charts").
+
+**Accessibility.** The keyboard path is one Tab stop. Enter goes from the summary to the leftmost dot. ← and → step through the dots in x order, ↑ and ↓ go to the nearest dot above or below, Home and End go to the first and last along x, and Page Up and Page Down move a tenth of the way. That's after Data Navigator (Elavsky, Nadolskis & Moritz, 2023). Each dot is named "Checkout list, Checkout. Payload 120 KB, p95 180 ms." Without a written `summary`, the generated one says how the measures relate ("p95 rises strongly with Payload (r = 0.78)"), their ranges, and the labelled dots. The table view has a row per record: its name, its group and both measures.
+
+**Props:** `data`, `x`, `y`; `group`; `id` and `name` (a key or a function); `label`; `trend`; `size`; `tooltip`.
+
+**Selecting, drilling and filtering.** `selected` (the record or its id) and `onSelect`, `drill`, and `relevance` (with `rescale`) work as on every chart: the chosen dot keeps its colour, the rest recede to 35%, and the frame says "Filtered to Vandelay". See [ChartContainer](../ChartContainer/README.md).
+
+**Focus.** `focus={['Search']}` keeps those groups' colours (and every shape) and draws the rest in `data-context`; `focus={(d) => d.p95 > 250}` picks out dots instead. See [ChartContainer](../ChartContainer/README.md), "Focus".
+
+**You provide:** a `ChartContainer` whose `config` names and formats both measures, the records, and usually a `summary` that says what the relationship means.
+
+```tsx
+<ChartContainer config={{ kb: { label: 'Payload', format: (v) => `${v} KB` }, ms: { label: 'p95', format: (v) => `${v} ms` } }}>
+  <ScatterChart data={endpoints} x="kb" y="ms" group="service" id="path" name="path" label={(d) => (d.ms > 400 ? d.path : null)} trend>
+    <ChartLegend content={<ChartLegendContent toggle label="Services" />} />
+  </ScatterChart>
+</ChartContainer>
+```
+
+- Do give records a stable `id` if the data updates, so dots glide instead of blinking.
+- Do label only the dots worth a word; the rest are in the readout and the table.
+- Do say what a correlation means in the `summary`; don't let a trend line stand in for a cause.
+- Don't use more than three groups; split into small multiples.
+- Don't size dots by a third measure; it's two measures per record, read by position.