division-ds 0.1.2 → 0.2.0

package/public/docs/components/kbd.md

@@ -0,0 +1,70 @@
+# Kbd
+
+> A small keycap that shows a key's name. Making shortcuts easy to find was one of the motifs from the G1 mood board (the project's first approval step) worth keeping: if a surface has a shortcut, the surface says so.
+
+- **Best for:** Showing a keyboard shortcut next to the action it triggers, with one Kbd per key.
+- **Not for:** Anything that isn't a key, such as a status: use Badge.
+- Atom. Source: `src/components/atoms/kbd/Kbd.tsx`
+- Rendered docs page: `/components/kbd`
+
+## Import
+
+```tsx
+import { Kbd } from 'src/components/atoms/kbd/Kbd'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` |  | The key's name, for example "Esc" or "⌘". |
+| `className` | `string` |  | Merged with the component's classes. When Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLElement>` |  | Passed through to the kbd element. |
+| `...rest` | `HTMLAttributes<HTMLElement>` |  | Every native attribute, passed onto the kbd element, such as a title, or an aria-label for a symbol key (aria-label is the name screen readers read out). |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Single keys
+
+```tsx
+<Kbd>Esc</Kbd>
+<Kbd>Tab</Kbd>
+<Kbd>Enter</Kbd>
+<Kbd>Space</Kbd>
+<Kbd>/</Kbd>
+```
+
+### A chord: one cap per key
+
+```tsx
+<span className="flex items-center gap-1">
+  <Kbd>Ctrl</Kbd>
+  <span className="text-[var(--color-text-muted)] text-sm">+</span>
+  <Kbd>K</Kbd>
+</span>
+<span className="text-sm text-[var(--color-text-secondary)]">Open the command palette</span>
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Use one Kbd per physical key, and put them side by side for a chord (keys pressed together).
+- Put it next to the action it triggers, in the same row or the same tooltip.
+- Write the key name the way the keyboard prints it.
+
+## Don't
+
+- Don’t bevel it. Cut corners are for surfaces and controls, not 24px chrome.
+- Don’t put a whole chord inside one Kbd ("Ctrl+K" in a single cap).
+- Don’t use it for anything that isn’t a key. It’s not a badge.
+
+## Anatomy
+
+- **kbd element**: The HTML element made for keys. Screen readers announce it as keyboard input.
+- **Hairline border**: A one-pixel border in border.hairline-strong, with no bevel (cut corners).
+- **Mono legend**: JetBrains Mono, uppercase, 11px (pixels): the tertiary type role.

package/public/docs/components/link.md

@@ -0,0 +1,96 @@
+# Link
+
+> A link inside text. It's underlined, because in a paragraph colour alone isn't enough to show that something is a link.
+
+- **Best for:** Text that takes you somewhere: another page, a section or another site.
+- **Not for:** Something that does an action. Use Button for that (its link variant if it's inside running text).
+- Atom. Source: `src/components/atoms/link/Link.tsx`
+- Rendered docs page: `/components/link`
+
+## Import
+
+```tsx
+import { Link, linkVariants } from 'src/components/atoms/link/Link'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tone` | `'signal' \| 'quiet'` | `'signal'` | Which colour treatment to use. |
+| `external` | `boolean` | `false` | Opens the link in a new tab. It adds target="_blank", the rel hardening (attributes that stop the new page reaching back into yours), a trailing icon and the hidden "(opens in a new tab)" warning. Using it together with target or rel is a type error, so it can't fail silently. external already sets those values, so those props are removed from the type instead of being quietly overwritten while the page runs. |
+| `href` | `string` |  | Where the link goes. |
+| `className` | `string` |  | Merged with the component classes. If two clash, the later Tailwind utility wins (Tailwind is the CSS framework this system styles with). |
+| `ref` | `Ref<HTMLAnchorElement>` |  | Passed through to the anchor element. |
+| `...rest` | `AnchorHTMLAttributes<HTMLAnchorElement>` |  | Every native anchor prop. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export const linkVariants = cva( …
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### In running text
+
+```tsx
+<p className="text-sm text-[var(--color-text-secondary)] max-w-md">
+  Check the <Link href="/kits">field kit index</Link> before you head out, and read the{' '}
+  <Link href="https://example.com" external tone="quiet">
+    supplier notes
+  </Link>{' '}
+  if the hop-up looks off.
+</p>
+```
+
+### Tones
+
+```tsx
+<Link href="/kits" tone="signal">
+  Field kits
+</Link>
+<Link href="/kits" tone="quiet">
+  Field kits
+</Link>
+```
+
+### External
+
+```tsx
+<Link href="https://example.com" external>
+  Supplier
+</Link>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to it. The focus ring (the outline that shows which element the keyboard is on) is drawn on the link itself, and nothing clips it here. |
+| `Enter` | Follows the link. |
+
+## Do
+
+- Keep the underline on links inside running text.
+- Put the destination in the link text: 'the field kit index', not 'click here'.
+- Set external on anything that leaves the app, so screen readers announce the new tab.
+- Use quiet in dense lists where every row is a link anyway.
+
+## Don't
+
+- Don't use a link for something that does an action. That's a Button.
+- Don't open a new tab without external. The rel hardening and the warning both come with it.
+- Don't remove the underline to make a paragraph look tidier.
+- Don't pass target or rel together with external. Those props are removed from the type, so you can't override them. If you need different values, render a plain anchor yourself.
+
+## Anatomy
+
+- **Anchor**: The browser's own <a> element. You can focus it and use it from the keyboard without any extra work.
+- **Underline**: 1px (pixel) thick, sitting 2px below the text. It gets thicker on hover in the signal tone.
+- **External icon**: Hidden from screen readers with aria-hidden (an ARIA attribute, from Accessible Rich Internet Applications). It only shows when external is set.
+- **Hidden warning**: ‘(opens in a new tab)’, added to the accessible name, which is what screen readers announce for the link.

package/public/docs/components/list-item.md

@@ -0,0 +1,238 @@
+# ListItem
+
+> One row of a list: something at the start (a picture or icon), a title and description, extra details on the right, and actions at the end. A row that goes somewhere is one real link or button stretched over the whole row. Its actions sit beside it, never inside it.
+
+- **Best for:** A row people scan in a List: media, a title, meta and one or two actions.
+- **Not for:** Data in a table that people compare across columns: use DataTable.
+- Molecule. Source: `src/components/molecules/list-item/ListItem.tsx`
+- Rendered docs page: `/components/list-item`
+
+## Import
+
+```tsx
+import { List, ListItem } from 'src/components/molecules/list-item/ListItem'
+```
+
+## Requires
+
+- A <List> around the rows (a ul with role="list"), or as="div" on a row that stands alone.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `ReactNode` |  | Required. The main line, and the name screen readers give the row’s link or button. |
+| `description` | `ReactNode` |  | A second line under the title, in secondary text. |
+| `media` | `ReactNode` |  | Something at the start of the row: an Avatar, an icon (hidden from screen readers with aria-hidden), a thumbnail. |
+| `meta` | `ReactNode` |  | Right-aligned monospaced text: a time, a price, a count. |
+| `actions` | `ReactNode` |  | Controls at the end. Each one can still be focused and clicked on its own. |
+| `href` | `string` |  | Makes the row one link to this address, named by the title. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain <a>` | Draws the row link when href is set. Pass your router's link here. It has to pass className through. |
+| `onActivate` | `() => void` |  | Makes the row one button, named by the title. Ignored when href is set. |
+| `as` | `'li' \| 'div'` | `'li'` | li inside a List. div for a row on its own. |
+| `dividers (List)` | `boolean` | `true` | A thin line between rows. |
+| `className` | `string` |  | Extra CSS classes, merged with the outer element's own classes on List or ListItem. |
+| `ref` | `Ref<HTMLElement>` |  | Passed through to the ul (List) or the row element (ListItem). |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Sessions: plain rows with one action each
+
+```tsx
+function DeviceIcon({ icon: Icon }: { icon: typeof Monitor }) {
+  return (
+    <span className="flex size-9 items-center justify-center border border-[var(--color-border-hairline-strong)] text-[var(--color-text-secondary)]">
+      <Icon aria-hidden="true" className="size-4" />
+    </span>
+  )
+}
+
+function SessionsExample() {
+  const [sessions, setSessions] = useState([
+    { id: 'win', device: 'Chrome on Windows', where: 'Brasov, Romania', when: 'Now', icon: Monitor },
+    { id: 'ios', device: 'Safari on iPhone', where: 'Brasov, Romania', when: '2 h ago', icon: Smartphone },
+    { id: 'tab', device: 'Firefox on Android tablet', where: 'Cluj-Napoca, Romania', when: '3 d ago', icon: Tablet },
+  ])
+  return (
+    <div className="w-full max-w-xl">
+      <List aria-label="Signed-in sessions">
+        {sessions.map(session => (
+          <ListItem
+            key={session.id}
+            media={<DeviceIcon icon={session.icon} />}
+            title={session.device}
+            description={session.where}
+            meta={session.when}
+            actions={
+              session.id === 'win' ? (
+                <Badge tone="ok">This device</Badge>
+              ) : (
+                <Button
+                  size="sm"
+                  variant="secondary"
+                  aria-label={`Sign out of ${session.device}`}
+                  onClick={() => setSessions(all => all.filter(s => s.id !== session.id))}
+                >
+                  Sign out
+                </Button>
+              )
+            }
+          />
+        ))}
+      </List>
+    </div>
+  )
+}
+
+<SessionsExample />
+```
+
+### Notifications: each row one link, with an archive action beside it
+
+```tsx
+<div className="w-full max-w-xl">
+  <List aria-label="Notifications">
+    <ListItem
+      className="px-2"
+      title="Order 1042 shipped"
+      description="Your carbine replica left the depot."
+      meta="09:14"
+      href="#order-1042"
+      actions={
+        <IconButton label="Archive: Order 1042 shipped" variant="ghost" size="sm">
+          <Archive />
+        </IconButton>
+      }
+    />
+    <ListItem
+      className="px-2"
+      title="Back in stock"
+      description="The holo sight on your wishlist is available again."
+      meta="Yesterday"
+      href="#wishlist"
+      actions={
+        <IconButton label="Archive: Back in stock" variant="ghost" size="sm">
+          <Archive />
+        </IconButton>
+      }
+    />
+    <ListItem
+      className="px-2"
+      title="Training moved"
+      description="Saturday’s training starts at 10:00, not 09:00."
+      meta="Mon"
+      href="#events"
+      actions={
+        <IconButton label="Archive: Training moved" variant="ghost" size="sm">
+          <Archive />
+        </IconButton>
+      }
+    />
+  </List>
+</div>
+```
+
+### Team members: avatars, the whole row a button
+
+```tsx
+function TeamExample() {
+  const [chosen, setChosen] = useState<string | null>(null)
+  const team = [
+    { name: 'Ilse Varga', email: 'ilse@hexline.example', role: 'Captain' },
+    { name: 'Tomas Reyes', email: 'tomas@hexline.example', role: 'Medic' },
+    { name: 'Ana Popescu', email: 'ana@hexline.example', role: 'Scout' },
+  ]
+  return (
+    <div className="w-full max-w-xl">
+      <List aria-label="Squad members">
+        {team.map(member => (
+          <ListItem
+            key={member.email}
+            className="px-2"
+            media={<Avatar name={member.name} />}
+            title={member.name}
+            description={member.email}
+            meta={member.role}
+            onActivate={() => setChosen(member.name)}
+          />
+        ))}
+      </List>
+      <p className="mt-3 text-sm text-[var(--color-text-secondary)]" aria-live="polite">
+        {chosen ? `Opened ${chosen}.` : 'Choose a member to open their profile.'}
+      </p>
+    </div>
+  )
+}
+
+<TeamExample />
+```
+
+### A standalone row, outside a List
+
+```tsx
+<div className="w-full max-w-xl">
+  <ListItem as="div" title="Spare magazine, 120 rounds" description="Mid-cap, steel" meta="€14.90" />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the row’s link or button, then to each of its actions, then to the next row. |
+| `Enter` | Follows the row’s link, or presses its button. |
+| `Space` | Presses the row’s button (a link row ignores Space, like any link). |
+
+## Do
+
+- Put rows in a List, and give the List an aria-label (a name only screen readers hear) when no heading names it.
+- Use href when the row opens a page, and onActivate when it does something right there.
+- Keep actions to one or two. Put the rest in a DropdownMenu.
+- When an action repeats on every row, name it after its row ("Sign out of Chrome on Windows"), with aria-label or the IconButton label.
+
+## Don't
+
+- Don't make a row clickable with onClick on the row. Use href or onActivate.
+- Don't wrap a ListItem in a link or a button.
+- Don't use it for data people compare across columns. That's what DataTable is for.
+- Don't put long paragraphs in description. People scan a row, they don't read it.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<li onClick={open}>…<Button>Remove</Button></li>
+```
+
+Right:
+
+```tsx
+<ListItem title="Ilse Varga" onActivate={open} actions={<Button>Remove</Button>} />
+```
+
+A clickable li isn't a control. It can't take keyboard focus, and screen readers read it as plain text. onActivate (or href) turns the title into a real button (or link) that covers the row, and Remove keeps its own tab stop.
+
+Wrong:
+
+```tsx
+<a href="/orders/1"><ListItem title="Order shipped" actions={<Button>Archive</Button>} /></a>
+```
+
+Right:
+
+```tsx
+<ListItem title="Order shipped" href="/orders/1" actions={<Button>Archive</Button>} />
+```
+
+A button inside a link is invalid HTML, and screen readers announce the two as one merged control. href stretches the link over the row without wrapping the actions.
+
+## Anatomy
+
+- **List**: A ul with role="list" written out, so screen readers announce how many items there are even without bullets. Thin dividers between rows by default.
+- **Media**: Optional, at the start: an Avatar, an icon, a thumbnail. Centred against the text.
+- **Title and description**: The title is primary text, semibold. With href or onActivate it becomes the row’s one link or button, stretched over the row and underlined on hover. The description is secondary text, 14px (pixels).
+- **Meta**: Optional, right-aligned monospaced text with tabular figures (digits all the same width, so numbers line up): a time, a price, a count.
+- **Actions**: Optional controls at the end, layered above the stretched link, each with its own tab stop. On a narrow screen, meta and actions wrap under the text.

package/public/docs/components/loading-animation.md

@@ -0,0 +1,70 @@
+# LoadingAnimation
+
+> A loading state that fills a whole panel, drawn as an animated instrument dial in WebGL (the browser's graphics engine for drawing with the graphics card). The three dials follow the same rules. They draw themselves from the outside in, and their structure drifts. One mechanism clicks to its next detent using the system's snap easing (the motion where things arrive a little large and settle), and the signal accent colour only appears on the part that shows progress.
+
+- **Best for:** A wait that takes over a whole panel or page, like a route loading, a report building or a first sync.
+- **Not for:** A wait inside a button or a line of text: use Spinner. A wait with a known end: use Progress.
+- Atom. Source: `src/components/atoms/loading-animation/LoadingAnimation.tsx`
+- Rendered docs page: `/components/loading-animation`
+
+## Import
+
+```tsx
+import { LoadingAnimation } from 'src/components/atoms/loading-animation/LoadingAnimation'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'aperture' \| 'gyro' \| 'reticle'` | `'aperture'` | Aperture: shaded blades stepping round a spinning core. Gyro: nested rings turning against each other. Reticle: a progress ring filling up from a marker at 12 o’clock. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | A 96px, 160px or 240px square (px means pixels). It shrinks with its container below that size, but never grows. |
+| `label` | `string` |  | Status text that is hidden on screen. Passing it turns the loader into a live region, an area screen readers announce when it changes. |
+| `className` | `string` |  | Merged with the component classes. If two clash, the later Tailwind utility wins (Tailwind is the CSS framework this system styles with). |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root div. |
+| `...rest` | `Omit<HTMLAttributes<HTMLDivElement>, 'role'>` |  | Every native div prop except role, for the same reason as Spinner: label is the only thing that sets role="status". |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Three dials, md
+
+```tsx
+<LoadingAnimation variant="aperture" label="Loading field kits" />
+<LoadingAnimation variant="gyro" label="Syncing manifest" />
+<LoadingAnimation variant="reticle" label="Acquiring position" />
+```
+
+### Aperture, three sizes
+
+```tsx
+<LoadingAnimation variant="aperture" size="sm" label="Loading field kits" />
+<LoadingAnimation variant="aperture" size="md" label="Loading field kits" />
+<LoadingAnimation variant="aperture" size="lg" label="Loading field kits" />
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Use it for a wait that takes over a panel or a page, like a route loading, a report building or a first sync.
+- Pass label, and say what is loading: ‘Loading field kits’, not ‘Loading’.
+- Pick one dial for each product surface and stick with it. The three are a family. They aren't meant to rotate.
+
+## Don't
+
+- Don't put it in a button or a line of text. That's Spinner, which doesn't use up a WebGL context.
+- Don't show more than a handful at once. Each one uses a WebGL context (one slot of the browser's graphics engine), and browsers cap how many you get.
+- Don't rely on the motion. When someone has reduced motion turned on, it shows one still frame, so the label has to carry the meaning.
+- Don't use it for a wait with a known end. That's Progress.
+
+## Anatomy
+
+- **div**: The root: a square box at the size you pick. It gets role="status", which makes screen readers announce it, only when it has a label.
+- **Stage**: A layer that holds the WebGL canvas, hidden from screen readers with aria-hidden (an ARIA attribute, from Accessible Rich Internet Applications). It fades in once the first frame is drawn.
+- **Dial**: Rings, tick crowns and arcs in text.primary, text.secondary, border.control and border.hairline.strong. One moving part is in accent.signal.fill.
+- **Fallback**: If WebGL isn't available, the Conveyor spinner shows in the same box. It's aria-hidden, so the label is still read only once.
+- **sr-only label**: The text screen readers announce (sr-only means it's for screen readers only). It's only there when you pass label.

package/public/docs/components/multi-select.md

@@ -0,0 +1,200 @@
+# MultiSelect
+
+> Pick several choices from a list. The chosen ones sit inside the field as tags you can remove, followed by a text field that filters the list as you type. It's the many-values version of Select.
+
+- **Best for:** Any number of choices, including none, from a list too long to show all at once.
+- **Not for:** A single choice: use Select, or Radio when there are fewer than about five options. A handful that all fit: use Checkbox.
+- Molecule. Source: `src/components/molecules/multi-select/MultiSelect.tsx`
+- Rendered docs page: `/components/multi-select`
+
+## Import
+
+```tsx
+import { MultiSelect } from 'src/components/molecules/multi-select/MultiSelect'
+```
+
+## Requires
+
+- A <FormField> around it. FormField supplies the visible label, the help and the error, and replaces the label prop with its own.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. The name screen readers give the text field and the list. FormField replaces it with its own label. |
+| `options` | `SelectOption[]` |  | { value, label, disabled? }, the same rows Select takes. |
+| `value` | `string[]` |  | The current selection when the page keeps track of it (controlled), as option values in the order they were chosen. |
+| `defaultValue` | `string[]` |  | The starting selection when the component keeps track itself (uncontrolled). |
+| `onValueChange` | `(value: string[]) => void` |  | Runs with the whole new array every time an option is added or removed. |
+| `placeholder` | `string` | `'Select…'` | Shown while nothing is chosen. |
+| `emptyMessage` | `string` | `'No matches'` | Shown in the panel when the typed text matches no option. |
+| `inputSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Matches Input and Select: a minimum height of 32, 40 or 48px (pixels), with text at size xs, sm or base. It also sets the size of the typed text and of the option rows in the list (28, 32 or 40px). The tags come in one size, so sm fits a single row of them snugly, and md and lg add room around it. The field grows past the minimum as tags wrap. |
+| `invalid` | `boolean` | `false` | Sets aria-invalid (which tells screen readers the value has a problem) and the invalid border. FormField sets it from error. |
+| `disabled` | `boolean` | `false` | Turns the field off. The chosen tags stay visible, without their remove buttons. |
+| `required` | `boolean` | `false` | Sets aria-required on the text field, so screen readers say it's required. |
+| `name` | `string` |  | Sends each chosen value with the form as its own hidden input under this name. |
+| `className` | `string` |  | Extra CSS classes, merged onto the field. |
+| `ref` | `Ref<HTMLInputElement>` |  | Passed through to the text field. |
+| `id` | `string` |  | The text field’s id. FormField sets it. |
+| `aria-describedby` | `string` |  | The ids of the help and error text, put on the text field so screen readers read them. FormField sets it. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default
+
+```tsx
+const LOADOUT = [
+  { value: 'mags', label: 'Spare magazines' },
+  { value: 'goggles', label: 'Full-seal goggles' },
+  { value: 'mesh', label: 'Mesh face guard' },
+  { value: 'radio', label: 'Team radio', disabled: true },
+  { value: 'gloves', label: 'Gloves' },
+  { value: 'loader', label: 'Speed loader' },
+  { value: 'tracer', label: 'Tracer unit' },
+  { value: 'pouch', label: 'Dump pouch' },
+]
+
+<div className="w-full max-w-md">
+  <FormField label="Loadout">
+    <MultiSelect label="Loadout" options={LOADOUT} placeholder="Choose your kit…" />
+  </FormField>
+</div>
+```
+
+### Controlled: the page holds the chosen options
+
+```tsx
+const LOADOUT = [
+  { value: 'mags', label: 'Spare magazines' },
+  { value: 'goggles', label: 'Full-seal goggles' },
+  { value: 'mesh', label: 'Mesh face guard' },
+  { value: 'radio', label: 'Team radio', disabled: true },
+  { value: 'gloves', label: 'Gloves' },
+  { value: 'loader', label: 'Speed loader' },
+  { value: 'tracer', label: 'Tracer unit' },
+  { value: 'pouch', label: 'Dump pouch' },
+]
+
+function ControlledExample() {
+  const [kit, setKit] = useState<string[]>(['mags', 'goggles', 'gloves'])
+  return (
+    <div className="flex flex-col gap-2 w-full max-w-md">
+      <FormField label="Loadout" help="Remove a tag and watch the others close the gap.">
+        <MultiSelect label="Loadout" options={LOADOUT} value={kit} onValueChange={setKit} />
+      </FormField>
+      <span className="font-mono text-xs text-[var(--color-text-secondary)]">value: [{kit.join(', ')}]</span>
+    </div>
+  )
+}
+
+<ControlledExample />
+```
+
+### Invalid
+
+```tsx
+const LOADOUT = [
+  { value: 'mags', label: 'Spare magazines' },
+  { value: 'goggles', label: 'Full-seal goggles' },
+  { value: 'mesh', label: 'Mesh face guard' },
+  { value: 'radio', label: 'Team radio', disabled: true },
+  { value: 'gloves', label: 'Gloves' },
+  { value: 'loader', label: 'Speed loader' },
+  { value: 'tracer', label: 'Tracer unit' },
+  { value: 'pouch', label: 'Dump pouch' },
+]
+
+<div className="w-full max-w-md">
+  <FormField label="Loadout" error="Pick eye protection.">
+    <MultiSelect label="Loadout" options={LOADOUT} defaultValue={['mags']} />
+  </FormField>
+</div>
+```
+
+### Sizes
+
+```tsx
+const LOADOUT = [
+  { value: 'mags', label: 'Spare magazines' },
+  { value: 'goggles', label: 'Full-seal goggles' },
+  { value: 'mesh', label: 'Mesh face guard' },
+  { value: 'radio', label: 'Team radio', disabled: true },
+  { value: 'gloves', label: 'Gloves' },
+  { value: 'loader', label: 'Speed loader' },
+  { value: 'tracer', label: 'Tracer unit' },
+  { value: 'pouch', label: 'Dump pouch' },
+]
+
+<div className="flex flex-col gap-3 w-full max-w-md">
+  <MultiSelect label="Small loadout" inputSize="sm" options={LOADOUT} defaultValue={['mags']} />
+  <MultiSelect label="Medium loadout" inputSize="md" options={LOADOUT} defaultValue={['mags']} />
+  <MultiSelect label="Large loadout" inputSize="lg" options={LOADOUT} defaultValue={['mags']} />
+</div>
+```
+
+### Disabled
+
+```tsx
+const LOADOUT = [
+  { value: 'mags', label: 'Spare magazines' },
+  { value: 'goggles', label: 'Full-seal goggles' },
+  { value: 'mesh', label: 'Mesh face guard' },
+  { value: 'radio', label: 'Team radio', disabled: true },
+  { value: 'gloves', label: 'Gloves' },
+  { value: 'loader', label: 'Speed loader' },
+  { value: 'tracer', label: 'Tracer unit' },
+  { value: 'pouch', label: 'Dump pouch' },
+]
+
+<div className="w-full max-w-md">
+  <MultiSelect label="Locked loadout" options={LOADOUT} defaultValue={['mags', 'gloves']} disabled />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `↓` `↑` | Opens the list, then moves the highlight, skipping rows that are turned off. |
+| `Enter` | Adds or removes the highlighted option. The list stays open. |
+| `Backspace` | When the text field is empty, removes the last tag. |
+| `Esc` | Closes the list. Press it again to clear the typed text. |
+| `Tab` | Moves through the tags’ remove buttons and the text field, and closes the list on the way out. |
+
+## Do
+
+- Use it when someone may pick any number of options, including none.
+- Wrap it in a FormField, like every other form control.
+- Keep option labels short. They become tags, and long tags wrap the field onto many lines.
+- Turn off (disable) an option that isn't available, instead of leaving it out.
+
+## Don't
+
+- Don't use it for a single choice. That's Select, or radios when there are fewer than about five options.
+- Don't use it for a handful of options that all fit on screen. Checkboxes show every choice at once.
+- Don't put actions in the list. It chooses values, and a command belongs in a DropdownMenu.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<Select label="Kit" options={kit} /> // then a second Select for the next item
+```
+
+Right:
+
+```tsx
+<MultiSelect label="Kit" options={kit} value={chosen} onValueChange={setChosen} />
+```
+
+Select holds one value. A list of picks is one MultiSelect, whose value is a string array (a list of text values).
+
+## Anatomy
+
+- **Field**: Looks like Input, but grows to fit: it wraps onto more lines as tags are added. Clicking anywhere on it puts focus in the text field and opens the list.
+- **Tag**: One for each chosen option, in the order they were chosen. Removing one fades it out and slides the tags after it into its place (M7). Focus goes back to the text field.
+- **Text field**: Has role="combobox", which tells screen readers it's a text field with a list attached. Typing filters the list. The placeholder only shows while nothing is chosen.
+- **Listbox**: The list, where several options can be chosen. It sits in a panel rendered in a portal (at the end of the page, so nothing clips it), with the same background as Select and the crosshair. It slides down out of the field and back up into it (M7). A tick marks every chosen row.