division-ds 0.1.2 → 0.2.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Division DS: instructions for coding agents
 
-A React 19 + Tailwind 4 + Radix design system: 67 components, tokens in three layers, light and
+A React 19 + Tailwind 4 + Radix design system: 68 components, tokens in three layers, light and
 dark themes, WCAG 2.2 AA. This file is the entry point. It is short on purpose; everything it
 points to is generated from the code, so it is current.
 
@@ -11,6 +11,7 @@ points to is generated from the code, so it is current.
 | The list of components, one line each | `public/llms.txt` |
 | One component: props, examples as code, keyboard, do and don't | `public/docs/components/<slug>.md` |
 | Every component's props in one compact file | `public/llms-components.txt` |
+| The whole system in one short file (for a tool that takes one design file) | `public/DESIGN.md` |
 | Which token to use for what | `public/llms-tokens.txt` |
 | Shared helpers: form errors, money, links, theme, streamed text | `public/docs/helpers.md` |
 | The same as data | `public/manifest/components.json`, `public/manifest/tokens.json` |
@@ -42,10 +43,17 @@ npx division-ds check <files or dirs>          (from npm; Node 22 or newer)
 node <path-to-division-ds>/scripts/division-ds.mjs check <files or dirs>   (the same, from a clone)
 ```
 
-It runs the colour and button-spacing gates and checks every Division DS element's props against
+It runs the colour, button-spacing and AI copy gates and checks every Division DS element's props against
 `public/manifest/components.json`: an unknown prop, or a value that is not in the prop's union.
 Exit 1 means a finding; each one says what to write instead. `division-ds rules --target <dir>`
 installs these rules into that project's `AGENTS.md`, `GEMINI.md` and Cursor rules.
+`division-ds skill --target <dir>` installs the skill into `.agents/skills/` (Codex, Cursor) and
+`.claude/skills/` (Claude Code).
+
+An agent that supports MCP can have the docs and the same checks as tools instead:
+`claude mcp add division-ds -- npx -y division-ds mcp` (`list_components`, `get_component`,
+`search`, `get_tokens`, `validate_code`, `check_contrast`, `get_add_command`,
+`get_review_checklist`).
 
 <!-- rules:start -->
 ## Rules
@@ -175,6 +183,12 @@ element arriving, `anim-draw-on` for a hairline) and the motion tokens (`--durat
 hover, `--duration-base` by default, `--duration-slow` for a larger change, `--ease-snap`).
 Anything you animate yourself stops under `prefers-reduced-motion` (`motion-reduce:` in
 Tailwind), and nothing moves on its own: no autoplay.
+
+<!-- topic: ai -->
+
+**Assistant copy.** A button names the action ("Summarize"), never "AI". Say "response", not
+"answer". No "please" or "!" in assistant labels. The interface says "Assistant"; only its own
+messages say "I".
 <!-- rules:end -->
 
 ## Changing the system itself

package/README.md

@@ -16,4 +16,15 @@ npx division-ds rules     # writes the Division DS rules into AGENTS.md / CLAUDE
 npx division-ds help
 ```
 
+## For agents: the MCP server
+
+```bash
+claude mcp add division-ds -- npx -y division-ds mcp
+```
+
+Any MCP client works the same way: the command is `npx -y division-ds mcp`, on stdio. It gives the
+agent eight tools: `list_components`, `get_component`, `search`, `get_tokens`,
+`validate_code` (the checks above, on code the agent just wrote), `check_contrast` (WCAG 2.2 AA,
+both themes), `get_add_command` and `get_review_checklist`.
+
 The components, the docs and the agent skill: https://github.com/Victor-Ilioiu/division-ds

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "division-ds",
-  "version": "0.1.2",
-  "description": "Checks a project that uses Division DS components: raw colours, invented tokens, touching buttons, unknown props.",
+  "version": "0.2.0",
+  "description": "Checks a project that uses Division DS components (raw colours, invented tokens, touching buttons, unknown props), and serves the docs and the same checks to agents over MCP.",
   "license": "MIT",
   "author": "Victor Ilioiu",
   "homepage": "https://victor-ilioiu.vercel.app/systems/division-ds/",

package/public/docs/components/accordion.md

@@ -0,0 +1,205 @@
+# Accordion
+
+> Sections that open and close in place, each under its own heading. You can allow one open at a time or several, and draw them as plain rows split by thin lines or as a panel per section.
+
+- **Best for:** Sections people scan by heading and open one or two of: frequently asked questions (FAQ), grouped settings, long specifications.
+- **Not for:** Steps in a sequence: use Stepper. Equal views of the same thing: use Tabs.
+- Molecule. Source: `src/components/molecules/accordion/Accordion.tsx`
+- Rendered docs page: `/components/accordion`
+
+## Import
+
+```tsx
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'src/components/molecules/accordion/Accordion'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `type` | `'single' \| 'multiple'` |  | Required on the root. single: opening one section closes the other. multiple: any number can be open. |
+| `collapsible` | `boolean` | `false` | single mode only. Lets the open section be closed again by its own trigger. You'll want it almost always. |
+| `variant` | `'plain' \| 'boxed'` | `'plain'` | plain: thin separator lines, for a long run of questions. boxed: a panel per section, for a few sections that each stand alone. |
+| `value (Root)` | `string \| string[]` |  | The open section when the page controls it: a string in single mode, an array in multiple mode. |
+| `defaultValue` | `string \| string[]` |  | The section or sections open at first, when the accordion keeps track itself (uncontrolled). Set on the root. |
+| `onValueChange` | `(value: string \| string[]) => void` |  | Called when a section opens or closes (on the root). The argument has the same shape as type. |
+| `value (Item)` | `string` |  | Required. The section’s own value. |
+| `disabled (Item)` | `boolean` | `false` | The section can't be opened or closed. |
+| `level (Trigger)` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | The level of the heading the trigger sits in. Pick one below the heading the accordion appears under. |
+| `forceMount (Content)` | `true` |  | Keeps a closed panel in the page's code (the DOM, the browser's live model of the page), so the browser's find-in-page search can reach its content. It then skips the closing animation. |
+| `className` | `string` |  | Merged with each part’s classes. On AccordionContent it goes on the inner padded box, not the animated clipping box around it. |
+| `ref` | `Ref<HTMLElement>` |  | Passed through to the DOM element. Every part has one; the trigger’s is the button. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type AccordionVariant = 'plain' | 'boxed'
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Frequently asked questions (FAQ): plain style, one answer open at a time, and the open one can be closed again
+
+```tsx
+<div className="w-full max-w-lg">
+  <Accordion type="single" collapsible>
+    <AccordionItem value="shipping">
+      <AccordionTrigger>How long does shipping take?</AccordionTrigger>
+      <AccordionContent>
+        Two to four working days inside the EU. Every parcel leaves the depot with a tracking
+        number, sent to you by email the same day.
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="returns">
+      <AccordionTrigger>Can I return a replica?</AccordionTrigger>
+      <AccordionContent>
+        Within 30 days, unfired and in its original box. Open a return from your order page and
+        print the label.
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="age">
+      <AccordionTrigger>Do I need to prove my age?</AccordionTrigger>
+      <AccordionContent>
+        Yes, once. We check an ID document at the first order of a replica; accessories need no
+        check.
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="custom" disabled>
+      <AccordionTrigger>Custom builds (paused)</AccordionTrigger>
+      <AccordionContent>The workshop takes no new builds this season.</AccordionContent>
+    </AccordionItem>
+  </Accordion>
+</div>
+```
+
+### Settings sections: boxed style, several open at once, and each section header is a level-2 heading (h2)
+
+```tsx
+function SettingRow({ id, label, defaultChecked }: { id: string; label: string; defaultChecked?: boolean }) {
+  return (
+    <div className="flex items-center justify-between gap-4 py-2">
+      <label htmlFor={id} className="text-sm text-[var(--color-text-primary)]">
+        {label}
+      </label>
+      <Switch id={id} defaultChecked={defaultChecked} />
+    </div>
+  )
+}
+
+<div className="w-full max-w-lg">
+  <Accordion type="multiple" variant="boxed" defaultValue={['notifications']}>
+    <AccordionItem value="notifications">
+      <AccordionTrigger level={2}>Notifications</AccordionTrigger>
+      <AccordionContent>
+        <SettingRow id="acc-set-shipping" label="Shipping updates" defaultChecked />
+        <SettingRow id="acc-set-restock" label="Restock alerts" />
+        <SettingRow id="acc-set-news" label="Monthly newsletter" />
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="privacy">
+      <AccordionTrigger level={2}>Privacy</AccordionTrigger>
+      <AccordionContent>
+        <SettingRow id="acc-set-profile" label="Show my squad profile" defaultChecked />
+        <SettingRow id="acc-set-history" label="Keep order history" defaultChecked />
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="display">
+      <AccordionTrigger level={2}>Display</AccordionTrigger>
+      <AccordionContent>
+        <SettingRow id="acc-set-motion" label="Reduce motion" />
+      </AccordionContent>
+    </AccordionItem>
+  </Accordion>
+</div>
+```
+
+### Controlled: the page keeps track of which sections are open
+
+```tsx
+function ControlledExample() {
+  const [open, setOpen] = useState<string[]>(['battery'])
+  return (
+    <div className="w-full max-w-lg">
+      <p className="mb-3 font-mono text-xs uppercase tracking-[0.18em] text-[var(--color-text-secondary)]">
+        Open: {open.length ? open.join(', ') : 'none'}
+      </p>
+      <Accordion type="multiple" value={open} onValueChange={setOpen}>
+        <AccordionItem value="battery">
+          <AccordionTrigger>Battery</AccordionTrigger>
+          <AccordionContent>11.1V LiPo, 1450mAh, with a deans connector.</AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="hop-up">
+          <AccordionTrigger>Hop-up</AccordionTrigger>
+          <AccordionContent>Rotary adjustment, 60 degree bucking.</AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  )
+}
+
+<ControlledExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves between triggers, and into an open section’s content. |
+| `Enter` `Space` | Opens or closes the focused section. |
+| `↓` `↑` | Goes to the next or previous trigger, wrapping round at the ends and skipping disabled ones. |
+| `Home` `End` | Goes to the first or last trigger. |
+
+## Do
+
+- Use it for content people scan by its headings and open one or two of: an FAQ, a group of settings, long specifications.
+- Write each trigger as the question or the section name, so the closed list reads like a table of contents.
+- Set collapsible in single mode.
+- Use boxed for a few sections that each hold controls, and plain for a long list of text answers.
+
+## Don't
+
+- Don't hide the one thing everyone needs inside a closed section. Show it.
+- Don't use it for steps in a sequence. That's Stepper.
+- Don't use it to switch between equal views of the same thing. That's Tabs.
+- Don't nest an accordion inside another accordion's content.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<Accordion type="single">
+```
+
+Right:
+
+```tsx
+<Accordion type="single" collapsible>
+```
+
+Without collapsible, a single-mode accordion can never be fully closed again once a section is open. That surprises people.
+
+Wrong:
+
+```tsx
+<AccordionTrigger>Shipping</AccordionTrigger> // under an h3 section title
+```
+
+Right:
+
+```tsx
+<AccordionTrigger level={4}>Shipping</AccordionTrigger>
+```
+
+Every trigger (the clickable section header) sits inside a heading, h3 (a level-3 heading) by default. Set level so the triggers nest one level below the heading they appear under.
+
+## Anatomy
+
+- **Accordion**: The root. It holds which sections are open and the variant, and every part below reads both.
+- **AccordionItem**: One section. plain: a thin line under it. boxed: its own raised panel with the cut corner. The panel is drawn on a backing layer marked aria-hidden (hidden from screen readers), so the item itself is never clipped.
+- **AccordionTrigger**: A button inside a heading of the level you choose. It uses the display typeface, has a chevron that turns half a revolution when the section is open, and is underlined on hover.
+- **AccordionContent**: A region labelled by its trigger, in secondary text. It grows open over the base duration and shrinks shut faster (M7). When someone has asked their device for reduced motion, it snaps open and shut instead.

package/public/docs/components/ai-label.md

@@ -0,0 +1,88 @@
+# AiLabel
+
+> Marks content as made by AI, and on request says why. Given an explanation, the mark is a button that opens a short note right under it, with an optional list of sources. It is a disclosure (a button that shows and hides a region), not a tooltip or a popover: a tooltip can't hold links and never shows on a touch screen, and the system has no popover.
+
+- **Best for:** Marking a block of text, a value or a field that an AI wrote, so the person knows to check it.
+- **Not for:** A status or a category: use Badge. A field the AI filled: give the field aiValue, which marks it itself.
+- Atom. Source: `src/components/atoms/ai-label/AiLabel.tsx`
+- Rendered docs page: `/components/ai-label`
+
+## Import
+
+```tsx
+import { AiLabel } from 'src/components/atoms/ai-label/AiLabel'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | `'Generated by AI'` | The mark's words, and the button's name. Say what the AI made: 'AI summary', 'AI draft'. |
+| `explanation` | `ReactNode` |  | Why this is AI content and what to do about it, in a sentence or two: what it was made from, and that it needs checking. Without it the mark is static text and nothing opens. |
+| `sources` | `AiLabelSource[]` |  | { label, href } for each thing the content was made from. Listed under the explanation; ignored without one. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | How each source link is drawn. Pass your router's link component for sources inside the app. |
+| `className` | `string` |  | Merged with the root's classes. When Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root div. |
+| `...rest` | `HTMLAttributes<HTMLDivElement>` |  | Every native attribute, onto the root div. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type AiLabelSource = { label: string; href: string }
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Static mark
+
+```tsx
+<AiLabel />
+```
+
+### With an explanation and sources
+
+```tsx
+<div className="flex flex-col gap-2 max-w-md">
+  <AiLabel
+    label="AI summary"
+    explanation="Summarised from the three most recent reviews of this replica. It can miss details or get them wrong: verify before you rely on it."
+    sources={[
+      { label: 'Review by Ilse Varga', href: '#review-1' },
+      { label: 'Review by Tomas Brandt', href: '#review-2' },
+    ]}
+  />
+  <p className="text-sm text-[var(--color-text-primary)]">
+    Reviewers find the gearbox quiet and the hop-up easy to tune; two mention a loose stock.
+  </p>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to the mark when it has an explanation, then into any source links once open. |
+| `Enter` `Space` | Opens or closes the explanation. Focus stays on the button. |
+
+## Do
+
+- Put it right above or beside the AI content it marks, not in a page header far away.
+- Say in the explanation what the AI used and that the person should check it, the way GitLab's 'Verify before use' does.
+- Name the sources when there are any. Showing where it came from is how a reader decides whether to trust it.
+
+## Don't
+
+- Don't put it inside a <label>. A button inside a label is read into the field's name; put it beside the label.
+- Don't mark everything. A label on every line is a label on nothing.
+- Don't rely on the colour. The words say AI; ai.text only helps you find them.
+
+## Anatomy
+
+- **Mark**: A sparkle and the label in uppercase mono, in ai.text. Static text when there is no explanation.
+- **Disclosure button**: With an explanation, the mark is a button with aria-expanded and a chevron that turns when open. Its name is the label.
+- **Explanation**: A region right under the button, edged in ai.border, in text.secondary. Hidden until asked for, then next in the reading order.
+- **Sources**: Optional. A list of links under the explanation, drawn through renderLink.

package/public/docs/components/alert-dialog.md

@@ -0,0 +1,290 @@
+# AlertDialog
+
+> Asks for confirmation before something with real consequences. It shows a question, says what will happen, and offers Cancel and the action. Screen readers announce it as an alert, a click outside won't dismiss it, and focus starts on Cancel. If the action returns a promise (a value that finishes later, such as a server call), the dialog stays open and shows it's busy until that work is done.
+
+- **Best for:** Confirming an action that matters and can't be undone, such as a delete.
+- **Not for:** Something that can be undone: just do it and offer Undo in a Toast. A form or a task: use Dialog.
+- Organism. Source: `src/components/organisms/alert-dialog/AlertDialog.tsx`
+- Rendered docs page: `/components/alert-dialog`
+
+## Import
+
+```tsx
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogFooter, AlertDialogTrigger } from 'src/components/organisms/alert-dialog/AlertDialog'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open (AlertDialog)` | `boolean` |  | Whether it is open, when your code controls that (controlled mode). |
+| `defaultOpen (AlertDialog)` | `boolean` | `false` | Whether it starts open, when the component tracks its own state (uncontrolled mode). |
+| `onOpenChange (AlertDialog)` | `(open: boolean) => void` |  | Called on every open and close. It isn't called when someone tries to close it while the action is busy. |
+| `asChild (Trigger)` | `boolean` |  | Uses its single child as the trigger instead of adding its own button. Pass a Button. |
+| `ref (Trigger)` | `Ref<HTMLButtonElement>` |  | The trigger button. |
+| `title (Content)` | `string` |  | Required. The question, and the name screen readers say. |
+| `description (Content)` | `string` |  | Required. What confirming does. Screen readers read it as the accessible description. |
+| `size (Content)` | `'sm' \| 'md'` | `'md'` | Maximum width: 24rem or 32rem (rem is a unit based on the root text size, usually 16 pixels). |
+| `className (Content)` | `string` |  | Added to the panel classes. Where two Tailwind utility classes clash, the later one wins. |
+| `ref (Content)` | `Ref<HTMLDivElement>` |  | The element with the role alertdialog. |
+| `onPointerDownOutside / onInteractOutside (Content)` | `—` |  | Not available: a click outside never dismisses an alert dialog. |
+| `className (Footer)` | `string` |  | Added to the button row classes. |
+| `children (Cancel)` | `ReactNode` | `'Cancel'` | The label. Name what the person keeps, for example Keep editing. |
+| `ref (Cancel)` | `Ref<HTMLButtonElement>` |  | The Cancel button, which gets focus when the dialog opens. |
+| `tone (Action)` | `'hostile' \| 'default'` | `'hostile'` | hostile (the danger button) for something that can't be undone. default (the primary button) for a confirm that's safe but still matters. |
+| `onClick (Action)` | `(event) => void \| Promise<unknown>` |  | Runs on confirm, then closes the dialog. If it returns a promise, the dialog stays open and busy until the promise settles: success closes it, failure keeps it open. Calling event.preventDefault() also keeps it open. |
+| `loading (Action)` | `boolean` | `false` | Marks it busy from outside, for work you track yourself. It holds the dialog open the same way a pending promise does. |
+| `loadingLabel (Action)` | `string` | `'Working'` | Text you can't see that screen readers announce while it's busy. |
+| `ref (Action)` | `Ref<HTMLButtonElement>` |  | The action button. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Delete while the request is still running: the action button shows it's busy and the dialog waits
+
+```tsx
+const request = (fail = false) =>
+  new Promise<void>((resolve, reject) =>
+    window.setTimeout(() => (fail ? reject(new Error('The server did not answer.')) : resolve()), 1000)
+  )
+
+function DeleteExample() {
+  const { toast } = useToast()
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="danger">Delete depot</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent
+        title="Delete Brasov north?"
+        description="Its 12 open manifests move to the unassigned queue. The depot cannot be restored."
+      >
+        <AlertDialogFooter>
+          <AlertDialogCancel />
+          <AlertDialogAction
+            loadingLabel="Deleting depot"
+            onClick={() => request().then(() => toast({ tone: 'ok', title: 'Depot deleted' }))}
+          >
+            Delete depot
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+
+<DeleteExample />
+```
+
+### A failed request: the dialog stays open and a toast says why
+
+```tsx
+const request = (fail = false) =>
+  new Promise<void>((resolve, reject) =>
+    window.setTimeout(() => (fail ? reject(new Error('The server did not answer.')) : resolve()), 1000)
+  )
+
+function FailureExample() {
+  const { toast } = useToast()
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="secondary">Revoke API key</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent
+        title="Revoke the warehouse key?"
+        description="Scripts that use it stop working at once. This demo always fails, to show the dialog staying open."
+        size="sm"
+      >
+        <AlertDialogFooter>
+          <AlertDialogCancel>Keep key</AlertDialogCancel>
+          <AlertDialogAction
+            loadingLabel="Revoking key"
+            onClick={() =>
+              request(true).catch((error: Error) => {
+                toast({ tone: 'hostile', title: 'Key not revoked', description: error.message })
+                throw error
+              })
+            }
+          >
+            Revoke key
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+
+<FailureExample />
+```
+
+### A safe confirm that still has consequences, with the default tone
+
+```tsx
+function DefaultToneExample() {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button>Publish prices</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent
+        title="Publish the autumn prices?"
+        description="Customers see them on every replica page as soon as you publish."
+        size="sm"
+      >
+        <AlertDialogFooter>
+          <AlertDialogCancel>Not yet</AlertDialogCancel>
+          <AlertDialogAction tone="default">Publish</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+
+<DefaultToneExample />
+```
+
+### Type the name to confirm, for the costliest actions
+
+```tsx
+const request = (fail = false) =>
+  new Promise<void>((resolve, reject) =>
+    window.setTimeout(() => (fail ? reject(new Error('The server did not answer.')) : resolve()), 1000)
+  )
+
+const ACCOUNT = 'northfield-supply'
+
+function TypeToConfirmExample() {
+  const [typed, setTyped] = useState('')
+  const matches = typed.trim() === ACCOUNT
+  return (
+    <AlertDialog onOpenChange={() => setTyped('')}>
+      <AlertDialogTrigger asChild>
+        <Button variant="danger">Delete account</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent
+        title="Delete the account?"
+        description="Its 212 orders, saved kit lists and team access are removed for good."
+      >
+        <FormField label="Account name" help={`Type ${ACCOUNT} to enable Delete account.`}>
+          <Input
+            value={typed}
+            onChange={event => setTyped(event.target.value)}
+            autoComplete="off"
+            spellCheck={false}
+            className="font-mono"
+          />
+        </FormField>
+        <AlertDialogFooter>
+          <AlertDialogCancel />
+          <AlertDialogAction disabled={!matches} loadingLabel="Deleting account" onClick={() => request()}>
+            Delete account
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+
+<TypeToConfirmExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves between Cancel, the action and any field, looping around inside the dialog. |
+| `Enter` | Presses the focused button. Focus starts on Cancel, so an accidental Enter cancels. |
+| `Esc` | Cancels and sends focus back to whatever opened it. It waits while the action is busy. |
+
+## Do
+
+- Write the title as the question, with the thing it's about: 'Delete Brasov north?', not 'Are you sure?'.
+- Say in the description exactly what will be lost or changed, with numbers where you have them.
+- Label the action with the verb and the thing: 'Delete depot', never 'OK' or 'Yes'.
+- Return the promise from onClick for anything that calls a server.
+- For something very costly, add a field asking for the name, and disable the action until it matches (see the last example).
+
+## Don't
+
+- Don't use it for something that can be undone. Do the thing and offer Undo in a toast.
+- Don't use it for a form or a task. That's a Dialog.
+- Don't add a close button or close it on a click outside. The only choices are Cancel or the action.
+- Don't open one from a dropdown menu item. The item is gone by the time the dialog closes, so focus has nowhere to go back to.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<Dialog>
+  <DialogContent title="Delete depot?">
+    <DialogFooter>
+      <DialogClose asChild><Button variant="secondary">Cancel</Button></DialogClose>
+      <Button variant="danger" onClick={remove}>Delete</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+Right:
+
+```tsx
+<AlertDialog>
+  <AlertDialogContent title="Delete depot?" description="Its open manifests move to the unassigned queue.">
+    <AlertDialogFooter>
+      <AlertDialogCancel />
+      <AlertDialogAction onClick={remove}>Delete depot</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+Dialog has the role dialog (the label screen readers use to describe it), closes when someone clicks the scrim behind it, and focuses the first control. A destructive confirm needs the role alertdialog, no dismissal from outside, and focus on Cancel. AlertDialog does all three.
+
+Wrong:
+
+```tsx
+const [busy, setBusy] = useState(false)
+<AlertDialog open={open} onOpenChange={next => { if (!busy) setOpen(next) }}>
+  ...
+  <AlertDialogAction loading={busy} onClick={async event => {
+    event.preventDefault(); setBusy(true); await remove(); setBusy(false); setOpen(false)
+  }}>Delete</AlertDialogAction>
+```
+
+Right:
+
+```tsx
+<AlertDialogAction onClick={() => remove()}>Delete</AlertDialogAction>
+```
+
+Return the promise. The action goes busy, Cancel and Escape wait, and the dialog closes when the work succeeds or stays open when it fails. You don't need any state of your own.
+
+Wrong:
+
+```tsx
+<AlertDialogAction onClick={() => remove()}>Delete</AlertDialogAction>
+// remove() rejects, and nothing tells the person
+```
+
+Right:
+
+```tsx
+<AlertDialogAction onClick={() => remove().catch(error => {
+  toast({ tone: 'hostile', title: 'Not deleted', description: error.message })
+  throw error
+})}>Delete</AlertDialogAction>
+```
+
+When the promise fails, the dialog stays open but shows nothing on its own. Report the failure, then throw the error again so the dialog stays open for a retry or a Cancel.
+
+## Anatomy
+
+- **Scrim**: The dimmed layer over the page, coloured surface.scrim. The page under it is inert (it can't be clicked or focused) and hidden from screen readers. Unlike Dialog, clicking it does nothing: the person has to choose.
+- **Surface**: The same panel as Dialog: surface.base, a strong hairline border, the corner crosshair and the M7 motion for opening and closing. Its role is alertdialog.
+- **Title**: Required. The question. It's an h2 (a second-level heading) and the dialog's accessible name, the name screen readers say for it.
+- **Description**: Required. What confirming does. Screen readers announce it with the title.
+- **Body**: Optional. A list of what will be lost, or a field to type a name into.
+- **Footer**: Cancel first, then the action. There's no close button.