division-ds 0.1.1 → 0.2.0

package/public/docs/components/avatar.md

@@ -0,0 +1,177 @@
+# 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'
+```
+
+## 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,176 @@
+# 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'
+```
+
+## 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.

package/public/docs/components/breadcrumbs.md

@@ -0,0 +1,110 @@
+# Breadcrumbs
+
+> Shows where this page sits among the pages above it. The last level is the current page, shown as text. Every level above it is a link.
+
+- **Best for:** Showing where a page sits in a hierarchy more than one level deep.
+- **Not for:** Steps in a sequence: use Stepper.
+- Molecule. Source: `src/components/molecules/breadcrumbs/Breadcrumbs.tsx`
+- Rendered docs page: `/components/breadcrumbs`
+
+## Import
+
+```tsx
+import { Breadcrumbs, collapseCrumbs } from 'src/components/molecules/breadcrumbs/Breadcrumbs'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `Crumb[]` |  | { label, href? }. A level with no href shows as plain text. |
+| `maxItems` | `number` |  | Collapse the trail when it has more levels than this. It never goes below 3. |
+| `label` | `string` | `'Breadcrumb'` | The name of the nav landmark. |
+| `className` | `string` |  | Merged onto the nav. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | How each linked level is drawn. Pass your router's link component to move between pages inside the app. |
+| `ref` | `Ref<HTMLElement>` |  | Passed through to the nav DOM element. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type Crumb = { label: string; href?: string }
+```
+
+```ts
+/** First item, a gap, then the last (maxItems - 1). Three is the floor: below it there is no
+ *  middle left to collapse and the gap would replace the only context the trail gives. */
+export function collapseCrumbs(items: Crumb[], maxItems?: number): (Crumb | 'gap')[]
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default
+
+```tsx
+const TRAIL = [
+  { label: 'Catalogue', href: '/catalogue' },
+  { label: 'Optics', href: '/catalogue/optics' },
+  { label: 'Holo sights', href: '/catalogue/optics/holo-sights' },
+  { label: 'Prism holo sight' },
+]
+
+<Breadcrumbs items={TRAIL} label="Breadcrumb, default example" />
+```
+
+### Collapsed
+
+```tsx
+const DEPOT_TRAIL = [
+  { label: 'Depot', href: '/depot' },
+  { label: 'Region: North', href: '/depot/north' },
+  { label: 'Site: Fell Beck', href: '/depot/north/fell-beck' },
+  { label: 'Building: Stores', href: '/depot/north/fell-beck/stores' },
+  { label: 'Bay 4', href: '/depot/north/fell-beck/stores/bay-4' },
+  { label: 'Crate 118' },
+]
+
+<Breadcrumbs items={DEPOT_TRAIL} maxItems={3} label="Breadcrumb, collapsed" />
+```
+
+### A level that is not a page
+
+```tsx
+const MID_LEVEL_TRAIL = [
+  { label: 'Catalogue', href: '/catalogue' },
+  { label: 'Optics' },
+  { label: 'Holo sights', href: '/catalogue/optics/holo-sights' },
+]
+
+<Breadcrumbs items={MID_LEVEL_TRAIL} label="Breadcrumb, mid-level example" />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through the linked levels in order. The current page isn't a stop. |
+
+## Do
+
+- Start from the top of the hierarchy, not from the home page, when the site has one obvious root.
+- Use the page's own heading text as its crumb.
+- Collapse long trails on narrow layouts with maxItems.
+
+## Don't
+
+- Don't use breadcrumbs for a sequence of steps. That's Stepper.
+- Don't make the current page a link.
+- Don't put a breadcrumb trail on a page that's only one level deep.
+
+## Anatomy
+
+- **nav**: A navigation landmark (a region screen readers can jump to) named 'Breadcrumb'.
+- **ol**: An ordered list, because the order is the information.
+- **Level**: A quiet Link.
+- **Current page**: Text with aria-current=page, which tells screen readers it's the page you're on. Never a link to itself.
+- **Separator**: A slash in monospaced type, marked aria-hidden so screen readers skip it.
+- **Gap**: An ellipsis (…) when the middle levels are collapsed, read out as 'more levels' by screen readers. It isn't a button.

package/public/docs/components/button.md

@@ -0,0 +1,202 @@
+# Button
+
+> The main control for taking an action. It comes in five variants (one of them a button that looks like a text link) and four sizes, with optional icons on either side of the label. It also draws its own focus ring, the outline that shows which control the keyboard is on. The component places that ring for you, because the bevel (the cut corners) would clip one placed anywhere else.
+
+- **Best for:** An action on this page, like submit, save or open a dialog.
+- **Not for:** Going somewhere (use Link, or Button asChild around an anchor), or an action with no visible word (use IconButton).
+- Atom. Source: `src/components/atoms/button/Button.tsx`
+- Rendered docs page: `/components/button`
+
+## Import
+
+```tsx
+import { Button, buttonVariants } from 'src/components/atoms/button/Button'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'primary' \| 'secondary' \| 'danger' \| 'ghost' \| 'link'` | `'primary'` | Which fill/border treatment to use. link looks like a Link (signal text, underline, no fill, no bevel, no fixed height) but it's still a button. Use it for an action inside a sentence, not for going to another page. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 24 / 32 / 40 / 48px (pixels). xs is exactly the 24px minimum target, the smallest area people can reliably click or tap. It isn't a token step (there is no xs control-height token) and it's meant for dense toolbars and table rows. Size has no effect on the link variant, which takes the size of the text around it. |
+| `fullWidth` | `boolean` | `false` | Stretches the wrapper as well as the button. |
+| `loading` | `boolean` | `false` | Sets aria-busy and aria-disabled, blocks the click and the form submit, and shows the spinner. The button stays focusable. |
+| `loadingLabel` | `string` | `'Working'` | Text that's hidden on screen but read aloud while loading. |
+| `iconStart` | `ReactNode` |  | An icon before the label, rendered aria-hidden and sized to the button. The spinner replaces it while loading. It isn't available with asChild: put the icon inside the child element instead. |
+| `iconEnd` | `ReactNode` |  | An icon after the label, rendered aria-hidden. It stays while loading. Not available with asChild. |
+| `asChild` | `boolean` | `false` | Renders the child element with the button's classes. Use it for links that look like buttons. Combining it with disabled, loading or loadingLabel is a type error, so the code won't compile, instead of quietly doing nothing. A link can't really be disabled or made busy, so those props are removed from the types rather than ignored when the page runs. |
+| `wrapperClassName` | `string` |  | Classes for the focus wrapper, not the button. |
+| `className` | `string` |  | Merged with the component's classes. When Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLButtonElement>` |  | Passed through to the button element. |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | A Button never submits a form by accident. Ask for submit on the one that should. |
+| `...rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'aria-busy' \| 'children'>` |  | Every native button prop except aria-busy. aria-busy is removed from the types rather than quietly overwritten when the page runs. loading is the only thing that sets it, and a loading button saying aria-busy="false" would be a spinning, aria-disabled control telling assistive tech (screen readers and other tools people with disabilities use) that it's idle. children is its own declared prop above, not part of rest. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export const buttonVariants = cva( …
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Variants
+
+```tsx
+<Button variant="primary">Dispatch team</Button>
+<Button variant="secondary">Save draft</Button>
+<Button variant="danger">Abort</Button>
+<Button variant="ghost">Cancel</Button>
+```
+
+### Sizes
+
+```tsx
+<Button size="xs">Dispatch team</Button>
+<Button size="sm">Dispatch team</Button>
+<Button size="md">Dispatch team</Button>
+<Button size="lg">Dispatch team</Button>
+```
+
+### States
+
+```tsx
+<Button>Dispatch team</Button>
+<Button loading loadingLabel="Dispatching">
+  Dispatch team
+</Button>
+<Button disabled>Dispatch team</Button>
+```
+
+### With icons
+
+```tsx
+<Button iconStart={<Plus />}>Add to loadout</Button>
+<Button variant="secondary" iconEnd={<ArrowRight />}>
+  Continue
+</Button>
+<Button variant="ghost" size="sm" iconStart={<Download />}>
+  Export
+</Button>
+<Button loading loadingLabel="Adding" iconStart={<Plus />}>
+  Add to loadout
+</Button>
+```
+
+### Link variant
+
+```tsx
+<p className="text-sm text-[var(--color-text-secondary)] max-w-md">
+  No replicas match these filters.{' '}
+  <Button variant="link">
+    Reset filters
+  </Button>{' '}
+  to see the full catalogue.
+</p>
+```
+
+### Full width
+
+```tsx
+<div className="w-80">
+  <Button fullWidth>Dispatch team</Button>
+</div>
+```
+
+### As a link
+
+```tsx
+<Button asChild>
+  <a href="/kits">Browse kits</a>
+</Button>
+```
+
+### Focus ring is never clipped
+
+```tsx
+<div className="flex flex-col gap-4">
+  <p className="text-sm text-[var(--color-text-secondary)] max-w-md">
+    Press Tab to focus the button below, in either theme. The focus ring (the outline
+    that shows which element the keyboard is on) draws a clean rectangle around the whole
+    bevelled shape. You'll never see it cut off, because the component draws it on the
+    outer wrapper, which isn't clipped, and not on the bevelled button itself.
+  </p>
+  <Button variant="primary">Dispatch team</Button>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to the button. The ring appears on the wrapper. |
+| `Enter` | Activates it. While loading it does nothing, and the caller's onClick doesn't run. |
+| `Space` | Activates it. While loading it does nothing, and the caller's onClick doesn't run. |
+
+## Do
+
+- One primary button per view. The signal colour only means something if it's rare.
+- Use asChild for a link that should look like a button, so it stays a real link.
+- Say what the button does: ‘Dispatch team’, not ‘Submit’.
+- Use loading instead of disabling the button and swapping the label yourself.
+- Use loading on a submit button. It keeps focus while the form works, so a keyboard user is never thrown back to the top of the page.
+- Pass icons through iconStart and iconEnd, not as children. That way they stay hidden from assistive tech and get sized with the button.
+- Use the link variant for an action that sits in running text or next to a heading (‘Reset filters’). Use Link for anything that goes somewhere.
+
+## Don't
+
+- Don't add bevel-* or an outline class yourself. You'll clip the ring off.
+- Don't use danger for anything that can be undone.
+- Don't put a ghost button next to a secondary one. People can't tell which matters more any more.
+- Don't disable a button without saying somewhere why it's disabled.
+- Don't use the link variant to go to another page. A control that goes somewhere is a Link, or a Button with asChild around an anchor.
+- Don't make an icon-only button by passing iconStart with no label. That's IconButton, which requires a name.
+- Don't use xs for a page's main actions. It's the minimum target size, for dense rows only.
+- Don't try to disable a link (asChild) or give it a loading state. Render the state you want directly instead (a plain span, or a real disabled button) rather than fighting the type error.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<div>
+  <Button variant="secondary">Cancel</Button>
+  <Button>Save</Button>
+</div>
+```
+
+Right:
+
+```tsx
+<div className="flex flex-wrap gap-3">
+  <Button variant="secondary">Cancel</Button>
+  <Button>Save</Button>
+</div>
+```
+
+Buttons render inline-flex, and JSX (the HTML-like syntax React components are written in) drops the whitespace between them, so buttons placed side by side touch. The parent sets the gap. npm run check:button-spacing fails if there isn't one.
+
+Wrong:
+
+```tsx
+<Button disabled={saving}>Save</Button>
+```
+
+Right:
+
+```tsx
+<Button loading={saving}>Save</Button>
+```
+
+A busy button stays focusable and tells people it's busy through loading. Native disabled is for an action that isn't available, and it takes the button out of the tab order, so the Tab key skips it.
+
+## Anatomy
+
+- **Focus wrapper**: A span that isn't clipped, carrying .bevel-focus-wrap. It draws the ring on :has(:focus-visible), so a mouse click doesn't show it, plus the reticle brackets (corner marks like a targeting sight) that close in on hover. It's always there and never optional.
+- **Button**: The clipped, bevelled control. It never carries its own outline.
+- **Spinner**: Decoration only, shown while loading. The hidden label is what screen readers announce.
+- **Label**: Oxanium semibold, uppercase: the display type role. The link variant switches to the body role, in the signal text colour, underlined.
+- **Icons**: Optional, before and after the label. Each sits in an aria-hidden slot sized to the button (14px at xs and sm, 16px at md, 20px at lg). aria-hidden is an ARIA attribute (Accessible Rich Internet Applications, the labels that tell screen readers what things are) that hides the icon from screen readers. While loading, the spinner takes the leading slot.