division-ds 0.1.2 → 0.2.1

package/public/docs/components/auth-form.md

@@ -0,0 +1,132 @@
+# AuthForm
+
+> One form with four modes: sign in, create an account, reset a password, or enter a two-step code. It's built so password managers, pasting and keyboards all just work.
+
+- **Best for:** Sign in, create an account, reset a password or enter a two-step code.
+- **Not for:** A newsletter sign-up: use NewsletterForm. Any other form: build it from FormField controls.
+- Organism. Source: `src/components/organisms/auth-form/AuthForm.tsx`
+- Rendered docs page: `/components/auth-form`
+
+## Import
+
+```tsx
+import { AuthForm } from 'src/components/organisms/auth-form/AuthForm'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `'sign-in' \| 'create-account' \| 'reset-password' \| 'verify-code'` |  | Required. Which form shows. |
+| `onSubmit` | `(values: AuthValues, mode: AuthMode) => void \| AuthErrors \| Promise<void \| AuthErrors>` |  | Required. Runs once every field passes its checks. Resolve with errors keyed by field name to show them. If it rejects, a general alert for the whole form appears, so the failure isn't lost. |
+| `onModeChange` | `(mode: AuthMode) => void` |  | Offers the other modes and reports when someone switches. |
+| `headingLevel` | `2 \| 3 \| 4` | `2` | Match the page's heading outline. The error summary sits one level below. The exception is 4, the lowest heading this system uses: there the summary stays an h4 (a level-4 heading) too. |
+| `className` | `string` |  | Merged with the root classes. Later Tailwind utilities win. |
+| `ref` | `Ref<HTMLFormElement>` |  | The form. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type AuthMode = 'sign-in' | 'create-account' | 'reset-password' | 'verify-code'
+```
+
+```ts
+export type AuthField = 'name' | 'email' | 'password' | 'code'
+```
+
+```ts
+export type AuthValues = Record<AuthField, string>
+```
+
+```ts
+export type AuthErrors = FieldErrors<AuthField>
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Sign in, with a server error, and the other modes
+
+```tsx
+const wait = (ms: number) => new Promise(resolve => window.setTimeout(resolve, ms))
+
+function AccountExample() {
+  const [mode, setMode] = useState<AuthMode>('sign-in')
+  const [signedIn, setSignedIn] = useState('')
+  const submit = async (values: AuthValues, current: AuthMode) => {
+    await wait(600)
+    if (current === 'sign-in' && values.password !== 'hexline') {
+      return { password: 'That email and password do not match.' }
+    }
+    if (current === 'sign-in' || current === 'create-account') setSignedIn(`Signed in as ${values.email}. This is a demo.`)
+    return undefined
+  }
+  return (
+    <div className="flex flex-col gap-3 w-full max-w-sm">
+      <p className="font-body text-sm text-[var(--color-text-secondary)]">
+        Demo: any email works, and the password <code className="font-mono">hexline</code> signs in.
+      </p>
+      <AuthForm
+        mode={mode}
+        onModeChange={next => {
+          setMode(next)
+          setSignedIn('')
+        }}
+        onSubmit={submit}
+        headingLevel={4}
+      />
+      <p role="status" className="font-body text-sm text-[var(--color-text-primary)]">
+        {signedIn}
+      </p>
+    </div>
+  )
+}
+
+<AccountExample />
+```
+
+### Two-step sign-in with a code
+
+```tsx
+const wait = (ms: number) => new Promise(resolve => window.setTimeout(resolve, ms))
+
+<AuthForm mode="verify-code" onSubmit={() => wait(600).then(() => undefined)} headingLevel={4} />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through the fields (the password field, then its Show password button), the submit button and the mode links. |
+| `Enter` | In a field, submits. On an error summary entry or a mode link, activates it. |
+| `Space` | On Show password, toggles it. On a mode link, activates it. |
+
+## Do
+
+- Let password managers work. Every field has its autocomplete token, and pasting is never blocked.
+- Resolve onSubmit with errors keyed by field (a wrong password, say), so they show in the summary and at the field.
+- Expect a rejected onSubmit to show up as its own alert instead of failing silently. There's no field to attach it to.
+- Keep the reset confirmation neutral. It never says whether an account exists.
+
+## Don't
+
+- Don't add a CAPTCHA, a puzzle or a copy-paste block. Signing in mustn't test memory or copying by hand (WCAG success criterion 3.3.8; WCAG is the Web Content Accessibility Guidelines, the public rulebook for usable websites).
+- Don't disable the submit button while fields are empty. The error summary says what's missing.
+- Don't validate on every keystroke.
+- Don't count on an error keyed to a field the current mode doesn't show (name while signing in, for example) landing where you'd expect. It's moved onto email, and a console.warn that only shows in development names it. Key it to a field the mode actually shows instead.
+
+## Anatomy
+
+- **Heading**: Names the form. Focus (the place your keyboard typing goes) moves here after a mode switch.
+- **Error summary**: Shows up when a submit fails and takes focus. Each entry jumps to its field. It waits for a real submit attempt: leaving a field (a blur) never brings it up, so it can't shove aside a field someone's about to click.
+- **Fields**: A FormField around each Input, with its help and error text connected to it.
+- **Show password**: An icon button inside the password field that shows the typed text. It uses Input's revealable option, reports on or off through aria-pressed (ARIA, Accessible Rich Internet Applications, is a set of attributes that tell screen readers what a control is doing), and keeps the same name either way. The text hides again on submit and on a mode switch.
+- **Submit**: A Button that stays focusable and shows it's busy while the caller works.
+- **Confirmation**: A status line that's always on the page. Reset mode uses it.
+- **Submit error**: An alert that's always present and gets its text when onSubmit rejects (the visible copy only appears then). It clears on the next submit and on a mode switch.
+- **Mode links**: Shown when onModeChange is given: forgot password, create an account, back to sign in. They're buttons, since they change the form in place, but they look exactly like Link: signal text, an underline that thickens on hover, a pointer cursor and a focus ring.

package/public/docs/components/avatar-group.md

@@ -0,0 +1,152 @@
+# AvatarGroup
+
+> Overlapping avatars (small profile pictures) with a “+N” for the rest. It’s a list named by its count, so a screen reader hears “6 members” and then each person. The people behind the “+N” are named in words, never only counted.
+
+- **Best for:** Several people in one place, with a count: a squad, the people on an order, who’s viewing.
+- **Not for:** Picking people: use MultiSelect.
+- Molecule. Source: `src/components/molecules/avatar-group/AvatarGroup.tsx`
+- Rendered docs page: `/components/avatar-group`
+
+## Import
+
+```tsx
+import { AvatarGroup } from 'src/components/molecules/avatar-group/AvatarGroup'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Requires
+
+- With overflowTooltip, the root <TooltipProvider>. AppShell and the demo layout each include one.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `people` | `AvatarGroupPerson[]` |  | Required. Everyone in the group, in the order shown. |
+| `max` | `number` | `4` | The most avatars drawn. The rest go into the +N chip. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Passed to every Avatar and to the chip. |
+| `label` | `string` |  | What the group is. The count is added on the end: “Alpha squad, 6 members”. |
+| `overflowTooltip` | `boolean` | `false` | Shows the hidden names in a Tooltip on the chip and lets the chip take keyboard focus. |
+| `className` | `string` |  | Merged with the list classes. Later Tailwind utility classes win. |
+| `ref` | `Ref<HTMLUListElement>` |  | Passed through to the list. |
+| `...rest` | `Omit<HTMLAttributes<HTMLUListElement>, 'children' \| 'aria-label'>` |  | Every standard ul prop except children (the people are the content) and aria-label (label builds it, with the count). |
+| `name (AvatarGroupPerson)` | `string` |  | Required. Passed to Avatar. |
+| `src (AvatarGroupPerson)` | `string` |  | Optional image, passed to Avatar. |
+| `status (AvatarGroupPerson)` | `'online' \| 'away' \| 'busy' \| 'offline'` |  | Optional presence (whether they’re online), passed to Avatar, which includes it in the name screen readers hear. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type AvatarGroupPerson = { name: string; src?: string; status?: AvatarStatus }
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Sizes: four people shown, and the rest counted in a small chip
+
+```tsx
+const ALPHA: AvatarGroupPerson[] = [
+  { name: 'Ilse Varga', status: 'online' },
+  { name: 'Ravi Okonkwo', status: 'away' },
+  { name: 'Mei Tanaka', status: 'busy' },
+  { name: 'Sana Idrissi', status: 'online' },
+  { name: 'Dana Iverson', status: 'offline' },
+  { name: 'Lin Moreau', status: 'online' },
+  { name: 'Tomas Reyes', status: 'offline' },
+]
+
+<div className="flex flex-col gap-4">
+  <AvatarGroup people={ALPHA} size="sm" label="Alpha squad" />
+  <AvatarGroup people={ALPHA} size="md" label="Alpha squad" />
+  <AvatarGroup people={ALPHA} size="lg" label="Alpha squad" />
+</div>
+```
+
+### Everyone fits: no chip
+
+```tsx
+const BRAVO: AvatarGroupPerson[] = [{ name: 'Noor Haddad' }, { name: 'Kai Lindqvist' }, { name: 'Ada Brennan' }]
+
+<AvatarGroup people={BRAVO} label="Bravo squad" />
+```
+
+### The hidden names in a tooltip (press Tab to reach the chip)
+
+```tsx
+const ALPHA: AvatarGroupPerson[] = [
+  { name: 'Ilse Varga', status: 'online' },
+  { name: 'Ravi Okonkwo', status: 'away' },
+  { name: 'Mei Tanaka', status: 'busy' },
+  { name: 'Sana Idrissi', status: 'online' },
+  { name: 'Dana Iverson', status: 'offline' },
+  { name: 'Lin Moreau', status: 'online' },
+  { name: 'Tomas Reyes', status: 'offline' },
+]
+
+<AvatarGroup people={ALPHA} max={3} label="Alpha squad" overflowTooltip />
+```
+
+### In a row, beside the words it summarises
+
+```tsx
+const ALPHA: AvatarGroupPerson[] = [
+  { name: 'Ilse Varga', status: 'online' },
+  { name: 'Ravi Okonkwo', status: 'away' },
+  { name: 'Mei Tanaka', status: 'busy' },
+  { name: 'Sana Idrissi', status: 'online' },
+  { name: 'Dana Iverson', status: 'offline' },
+  { name: 'Lin Moreau', status: 'online' },
+  { name: 'Tomas Reyes', status: 'offline' },
+]
+
+<div className="flex items-center gap-3">
+  <AvatarGroup people={ALPHA} max={3} size="sm" label="Watching this replica" />
+  <p className="text-sm text-[var(--color-text-secondary)]">7 people are watching this replica</p>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | With overflowTooltip, focuses the +N chip and opens the tooltip. Otherwise nothing in the group can take focus. |
+
+## Do
+
+- Give it a label that says who the people are: a squad, the people on an order, who’s viewing.
+- Keep max at four or fewer in dense rows. The chip covers the rest.
+- Put the full list somewhere people can reach (a dialog, a roster page) when they need to act on it.
+
+## Don't
+
+- Don't use it as a control. To pick people, use MultiSelect. To open the list, put a Button next to it.
+- Don't set overflowTooltip on every row of a long table, because each chip becomes a Tab stop.
+- Don't pass aria-label. The label plus the count is the name.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<div className="flex -space-x-2">{people.map(p => <Avatar name={p.name} />)}</div>
+```
+
+Right:
+
+```tsx
+<AvatarGroup people={people} label="Alpha squad" />
+```
+
+A hand-built stack has no count, no thin outline between the faces, and no words for the people a +N leaves out.
+
+## Anatomy
+
+- **List**: A ul (a bulleted list element) named “<label>, N members”, or just “N members” when there’s no label.
+- **Item**: One Avatar in a 2px (two pixel) frame in surface.base, cut to the same corner. Each one slides a quarter of its width under the one before.
+- **+N chip**: Shaped like an avatar, in monospaced text in text.secondary. The “+2” is aria-hidden (screen readers skip it), and hidden text reading “and 2 more: …” names the people it stands for.
+- **Tooltip**: Optional. Shows the hidden names on hover and on keyboard focus. The chip then becomes a Tab stop, with its focus ring drawn on an outer box that isn’t clipped.

package/public/docs/components/avatar.md

@@ -0,0 +1,179 @@
+# Avatar
+
+> A small square that shows who someone is. The name is required, because it's both the alt text (the description screen readers read for an image) and the source of the initials. Without one, an avatar is just an image nobody can identify.
+
+- **Best for:** Showing who a person is, next to their name, as in a roster row, a comment or an account menu.
+- **Not for:** Several people in one spot: use AvatarGroup.
+- Atom. Source: `src/components/atoms/avatar/Avatar.tsx`
+- Rendered docs page: `/components/avatar`
+
+## Import
+
+```tsx
+import { Avatar, avatarVariants, initialsFrom } from 'src/components/atoms/avatar/Avatar'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` |  | Required. The source of the fallback initials and the announced name. |
+| `src` | `string` |  | Optional image. If it can't load, the fallback takes its place without the layout jumping. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 24 / 36 / 48px. |
+| `status` | `'online' \| 'away' \| 'busy' \| 'offline'` |  | Whether the person is around. It adds the dot and adds the word to the announced name. Leave it out when you don't know. |
+| `className` | `string` |  | Merged with the component's classes. When Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLSpanElement>` |  | Passed through to the root element. |
+| `...rest` | `Omit<HTMLAttributes<HTMLSpanElement>, 'aria-label' \| 'children'>` |  | Every native span prop except aria-label and children. aria-label is removed from the types rather than quietly overwritten when the page runs. The announced name comes from the sr-only span, and an aria-label on the root would override it. children is removed because the component renders its own image/fallback/sr-only children, so anything passed as children would silently disappear. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+/** First letter of the first two words, uppercased.
+ *
+ *  `[...word][0]`, not `word[0]`: a string index yields a UTF-16 code unit, so a name whose first
+ *  character is outside the Basic Multilingual Plane (an emoji, an extended CJK ideograph, a
+ *  mathematical or historic-script letter) returns a lone high surrogate — an unpaired half of a
+ *  character, which renders as a replacement glyph. Spreading iterates by code point instead. */
+export function initialsFrom(name: string)
+```
+
+```ts
+export const avatarVariants = cva( …
+```
+
+```ts
+/** Every native span prop except `aria-label` is available — a molecule composing an Avatar can
+ *  attach a `data-testid` or extra `aria-*`/`data-*` attributes. `aria-label` is typed `never`
+ *  rather than merely omitted: Avatar's whole guarantee is that the announced name comes from the
+ *  `sr-only` span's content and is identical whether or not the image loads. An `aria-label` on
+ *  the root would silently outrank that content-derived name in the accessibility tree (an
+ *  element's `aria-label` always wins over its text content when the accessible name is
+ *  computed), defeating the one thing this component promises. `Omit<>` alone is a no-op here —
+ *  TypeScript's JSX checker never treats an `aria-*`/`data-*`-prefixed attribute as an
+ *  excess/unknown property — so the key must be redeclared with type `never` to actually be
+ *  enforced. Same remedy as `IconButton`'s `aria-label` exclusion (see `IconButton.tsx`).
+ *
+ *  `children` is excluded for a plainer reason: `HTMLAttributes` offers it, but this component
+ *  renders its own image/fallback/`sr-only` children, so JSX children on the element always win
+ *  and a `children` prop is silently discarded — reachable, typed, and dead. It is an ordinary
+ *  key, so the `Omit` does the rejecting and the declared `never` only makes the error legible;
+ *  both are shipped, matching `IconButton`. */
+export type AvatarStatus = 'online' | 'away' | 'busy' | 'offline'
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Sizes
+
+```tsx
+<Avatar name="Dana Iverson" size="sm" />
+<Avatar name="Dana Iverson" size="md" />
+<Avatar name="Dana Iverson" size="lg" />
+```
+
+### With an image
+
+```tsx
+const DEMO_IMAGE =
+  'data:image/svg+xml;utf8,' +
+  encodeURIComponent(
+    '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64">' +
+      '<rect width="64" height="32" fill="#7c9c6b"/>' + // token-discipline: allow, pixels of a sample photo, not interface colour
+      '<rect y="32" width="64" height="32" fill="#3f5a49"/>' +
+      '</svg>'
+  )
+
+<Avatar name="Dana Iverson" src={DEMO_IMAGE} size="lg" />
+```
+
+### Fallback initials
+
+```tsx
+<Avatar name="Dana Iverson" size="lg" />
+<Avatar name="Ravi Okonkwo" size="lg" />
+<Avatar name="Lin" size="lg" />
+```
+
+### Status: the dot is decoration, and the status word is part of the avatar's name
+
+```tsx
+const STATUS_TEAM = [
+  { name: 'Ilse Varga', status: 'online' },
+  { name: 'Ravi Okonkwo', status: 'away' },
+  { name: 'Mei Tanaka', status: 'busy' },
+  { name: 'Sana Idrissi', status: 'offline' },
+] as const
+
+<div className="flex flex-col gap-3">
+  {STATUS_TEAM.map(member => (
+    <div key={member.name} className="flex items-center gap-3">
+      <Avatar name={member.name} status={member.status} size="md" />
+      <div>
+        <p className="text-sm">{member.name}</p>
+        {/* Shown as text too, so a sighted user never has to decode the colour. Hidden
+            from assistive tech, which already heard it in the avatar's name. */}
+        <p aria-hidden="true" className="text-sm text-[var(--color-text-secondary)] capitalize">
+          {member.status}
+        </p>
+      </div>
+    </div>
+  ))}
+</div>
+```
+
+### A row
+
+```tsx
+const FIELD_TEAM = [
+  { name: 'Dana Iverson', role: 'Route Lead' },
+  { name: 'Ravi Okonkwo', role: 'Comms' },
+  { name: 'Mei Tanaka', role: 'Medic' },
+  { name: 'Sana Idrissi', role: 'Logistics' },
+]
+
+<div className="flex flex-col gap-3">
+  {FIELD_TEAM.map(member => (
+    <div key={member.name} className="flex items-center gap-3">
+      <Avatar name={member.name} size="md" />
+      <div>
+        <p className="text-sm">{member.name}</p>
+        <p className="text-xs text-[var(--color-text-muted)]">{member.role}</p>
+      </div>
+    </div>
+  ))}
+</div>
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Pass the full name, not the initials. The component works those out itself.
+- Let it fall back. The fallback is part of the design, not an error state.
+- Use sm inside dense rows and tables.
+- Set status only where presence is live and matters (a roster, a chat). A dot that's out of date is worse than no dot.
+
+## Don't
+
+- Don't round it. The system has no round corners, and an avatar isn't the place to start.
+- Don't add the cut corner to the sm avatar. It's 24px, the same size Kbd leaves out by name. An 8px cut takes a third of that edge, and it looks like a broken square instead of a shaped one.
+- Don't build an overlapping stack by hand. AvatarGroup does it, with a '+N' that's real text.
+- Don't explain the dot colours only in a legend. The status word is already in the name, so show it as text where sighted users need it too.
+- Don't use an avatar as the only label for a person. Put the name next to it in dense UI (user interface).
+- Don't pass aria-label. It's removed from the types so nothing can override it, and name already decides the one label that gets announced.
+
+## Anatomy
+
+- **Root**: A border.hairline-strong edge on the sunken surface, with overflow clipped and a cut bottom-right corner at md and lg.
+- **Image**: alt is empty on purpose, because the hidden name already does the announcing.
+- **Fallback**: Initials worked out from the name, aria-hidden, shown when there's no image or it fails to load. aria-hidden is an ARIA attribute (Accessible Rich Internet Applications, the labels that tell screen readers what things are) that hides something from screen readers.
+- **Hidden name**: sr-only (visible to screen readers only) and always there, so the announcement is the same either way. With a status it reads "Ilse Varga, online".
+- **Status dot**: Optional. A square in the top-right corner (the bottom-right is the cut), in accent.ok.text, accent.warning.text, accent.hostile.text or text.muted, with a 2px (pixel) surface.base keyline around it. It's aria-hidden because the status is announced in the name.

package/public/docs/components/badge.md

@@ -0,0 +1,178 @@
+# Badge
+
+> A small chip that shows a status. It comes in six tones and two emphases, and it always carries a word. A colour on its own isn't a status anyone can read.
+
+- **Best for:** You need to label a status with a word and a tone, like an order state or a sync result.
+- **Not for:** A filter or selection someone can remove. Use Tag for that.
+- Atom. Source: `src/components/atoms/badge/Badge.tsx`
+- Rendered docs page: `/components/badge`
+
+## Import
+
+```tsx
+import { Badge, badgeVariants } from 'src/components/atoms/badge/Badge'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tone` | `'neutral' \| 'signal' \| 'ok' \| 'warning' \| 'hostile' \| 'info'` | `'neutral'` | The status the badge shows. |
+| `emphasis` | `'solid' \| 'subtle'` | `'subtle'` | Solid uses the invariant fill (the same in light and dark themes) with its matching ink. Subtle is the outline badge: a 1px border and text in the tone’s theme-adaptive text token, with no fill. There's no separate outline emphasis, because it would be this same look under a second name. |
+| `size` | `'sm' \| 'md'` | `'sm'` | sm (small) is the chip for everyday interface: rows, cards, tables. md (medium) takes the small control height (32px) and the 14px text step. Use it for a badge next to display-size type, like a price. |
+| `dot` | `boolean` | `false` | Adds a marker next to the text. |
+| `icon` | `ReactNode` |  | An icon before the text, hidden from screen readers with aria-hidden and sized to the badge. It takes the badge’s colour, so the same contrast pair that covers the text covers it too. It adds to the word. It never replaces it. |
+| `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<HTMLSpanElement>` |  | Passed through to the span element. |
+| `...rest` | `HTMLAttributes<HTMLSpanElement>` |  | Any other span attribute. For example, aria-hidden on a count that a label next to it already reads out. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export const badgeVariants = cva( …
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Tones, subtle (the outline badge)
+
+```tsx
+const TONES = ['neutral', 'signal', 'ok', 'warning', 'hostile', 'info'] as const
+
+{TONES.map(tone => (
+  <Badge key={tone} tone={tone} emphasis="subtle">
+    {tone}
+  </Badge>
+))}
+```
+
+### Tones, solid
+
+```tsx
+const TONES = ['neutral', 'signal', 'ok', 'warning', 'hostile', 'info'] as const
+
+{TONES.map(tone => (
+  <Badge key={tone} tone={tone} emphasis="solid">
+    {tone}
+  </Badge>
+))}
+```
+
+### With a dot
+
+```tsx
+<Badge tone="ok" dot>
+  Nominal
+</Badge>
+<Badge tone="warning" dot>
+  Degraded
+</Badge>
+<Badge tone="hostile" dot>
+  Offline
+</Badge>
+```
+
+### With an icon
+
+```tsx
+<Badge tone="ok" icon={<Check />}>
+  In stock
+</Badge>
+<Badge tone="warning" icon={<Clock />}>
+  Backorder
+</Badge>
+<Badge tone="signal" emphasis="solid" icon={<Zap />}>
+  New
+</Badge>
+<Badge tone="info" size="md" icon={<Truck />}>
+  Ships today
+</Badge>
+```
+
+### Sizes
+
+```tsx
+<Badge tone="signal" emphasis="solid">
+  Sale
+</Badge>
+<Badge tone="signal" emphasis="solid" size="md">
+  Sale
+</Badge>
+<Badge tone="ok" dot>
+  In stock
+</Badge>
+<Badge tone="ok" dot size="md">
+  In stock
+</Badge>
+```
+
+### Size md, beside a price
+
+```tsx
+<p className="flex flex-wrap items-center gap-x-4 gap-y-2 font-mono text-4xl tabular-nums text-[var(--color-text-primary)]">
+  <span>€189.00</span>
+  <Badge tone="signal" emphasis="solid" size="md">
+    −39%
+  </Badge>
+</p>
+```
+
+### In a row
+
+```tsx
+<div className="flex flex-col gap-2 w-full max-w-xs">
+  <div className="flex items-center justify-between">
+    <span className="text-sm">Depot Relay</span>
+    <Badge tone="ok" emphasis="subtle">
+      Nominal
+    </Badge>
+  </div>
+  <div className="flex items-center justify-between">
+    <span className="text-sm">North Sensor Array</span>
+    <Badge tone="warning" emphasis="subtle">
+      Degraded
+    </Badge>
+  </div>
+  <div className="flex items-center justify-between">
+    <span className="text-sm">Northgate Beacon</span>
+    <Badge tone="hostile" emphasis="solid">
+      Offline
+    </Badge>
+  </div>
+</div>
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Give every badge a word.
+- Go easy on solid. One solid badge in a row reads as the exception. Six read as noise.
+- Keep the tone mapping the same across the product. ok is never ‘in progress’ on one screen and ‘done’ on another.
+- Use size md when the badge sits next to a headline figure, so the two read as one statement.
+
+## Don't
+
+- Don't build a badge that's colour only, even with a tooltip.
+- Don't put a badge inside a button. It muddies what the clickable target is.
+- Don't use hostile for something that's only pending.
+- Don't bevel it (give it a cut corner). At 22px a badge is chrome, the frame around content, not an object with its own footprint. Kbd follows the same rule for the same reason.
+- Don't resize a badge with height or text classes. The two sizes are the prop. A third size is a change to the system.
+- Don't use size md in a table row or on a card. It's as tall as a small button, so it starts to look like one.
+- Don't give one badge both an icon and a dot. Pick one marker. Two say the same thing twice.
+- Don't colour the icon yourself. It inherits the badge’s tone, and that's the pair the contrast gate (the automated colour-contrast check) measures.
+
+## Anatomy
+
+- **Chip**: Set in mono (a fixed-width typeface), uppercase. That's the tertiary type role. By default it's 22px tall with 11px text (px means pixels); at size md it's 32px tall with 14px text.
+- **Icon**: Optional, and placed before the text. It's aria-hidden (an ARIA attribute, from Accessible Rich Internet Applications, that hides it from screen readers) and uses the current text colour. It's 12px, or 14px at size md.
+- **Dot**: An optional square, also aria-hidden, in the current text colour. It's 6px, or 8px at size md.
+- **Label**: Required. The word is what makes the badge accessible.