division-ds 0.1.2 → 0.2.1

package/public/docs/components/sidebar.md

@@ -0,0 +1,193 @@
+# Sidebar
+
+> The navigation down the side of an app. It holds groups of pages, each page with an icon and an optional count. Groups can fold away, and there is room for a header and an account line.
+
+- **Best for:** App navigation down the side: grouped pages with icons and counts.
+- **Not for:** A site header with a few links: use Navbar.
+- Organism. Source: `src/components/organisms/sidebar/Sidebar.tsx`
+- Rendered docs page: `/components/sidebar`
+
+## Import
+
+```tsx
+import { Sidebar } from 'src/components/organisms/sidebar/Sidebar'
+```
+
+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 |
+|---|---|---|---|
+| `label` | `string` |  | Required. The name screen readers give the navigation region. |
+| `groups` | `SidebarGroup[]` |  | Required. Each group has title, icon, items, collapsible and defaultOpen. |
+| `header` | `ReactNode` |  | Sits above the groups: a product name, a workspace switcher. |
+| `footer` | `ReactNode` |  | Pinned below the groups when the Sidebar has a height (h-full in a column layout): the signed-in account, a help link. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | Pass your router's link component here. Map href to its own prop, and pass className, aria-current and onClick through. |
+| `className` | `string` |  | Added to the root classes. Where two Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLElement>` |  | The nav element. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type SidebarItem = {
+  label: string
+  href: string
+  /** An icon, drawn aria-hidden; the label carries the meaning. */
+  icon?: ReactNode
+  current?: boolean
+  /** A number shown at the end of the item and read as part of its name ("Orders 12"). */
+  count?: number
+}
+```
+
+```ts
+export type SidebarGroup = {
+  /** Also the React key for this group; unique within a Sidebar. */
+  title: string
+  /** Drawn before the title, aria-hidden; the title alone names the group. */
+  icon?: ReactNode
+  items: SidebarItem[]
+  /** @default true */
+  collapsible?: boolean
+  /** Ignored when the group holds the current item, which always starts open. @default true */
+  defaultOpen?: boolean
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Dashboard navigation
+
+```tsx
+const GROUPS: SidebarGroup[] = [
+  {
+    title: 'Operations',
+    icon: <Warehouse />,
+    items: [
+      { label: 'Overview', href: '#overview', icon: <LayoutDashboard /> },
+      { label: 'Orders', href: '#orders', icon: <Package />, current: true, count: 12 },
+      { label: 'Shipments', href: '#shipments', icon: <Truck /> },
+      { label: 'Returns', href: '#returns', icon: <Inbox />, count: 3 },
+    ],
+  },
+  {
+    title: 'Catalogue',
+    icon: <Boxes />,
+    defaultOpen: false,
+    items: [
+      { label: 'Products', href: '#products', icon: <Box /> },
+      { label: 'Inventory', href: '#inventory', icon: <Map /> },
+    ],
+  },
+  {
+    title: 'Account',
+    icon: <UserCog />,
+    collapsible: false,
+    items: [
+      { label: 'Settings', href: '#settings', icon: <Settings /> },
+      { label: 'Team', href: '#team', icon: <Users /> },
+    ],
+  },
+]
+
+const HEADER = <p className="font-display font-semibold">Hexline ops</p>
+
+const FOOTER = <p className="text-xs text-[var(--color-text-secondary)]">Signed in as Ana Pop</p>
+
+<div className="max-w-64">
+  <Sidebar label="Dashboard navigation" groups={GROUPS} header={HEADER} footer={FOOTER} />
+</div>
+```
+
+### In a sheet on a narrow screen: picking a link closes the sheet, through renderLink
+
+```tsx
+const GROUPS: SidebarGroup[] = [
+  {
+    title: 'Operations',
+    icon: <Warehouse />,
+    items: [
+      { label: 'Overview', href: '#overview', icon: <LayoutDashboard /> },
+      { label: 'Orders', href: '#orders', icon: <Package />, current: true, count: 12 },
+      { label: 'Shipments', href: '#shipments', icon: <Truck /> },
+      { label: 'Returns', href: '#returns', icon: <Inbox />, count: 3 },
+    ],
+  },
+  {
+    title: 'Catalogue',
+    icon: <Boxes />,
+    defaultOpen: false,
+    items: [
+      { label: 'Products', href: '#products', icon: <Box /> },
+      { label: 'Inventory', href: '#inventory', icon: <Map /> },
+    ],
+  },
+  {
+    title: 'Account',
+    icon: <UserCog />,
+    collapsible: false,
+    items: [
+      { label: 'Settings', href: '#settings', icon: <Settings /> },
+      { label: 'Team', href: '#team', icon: <Users /> },
+    ],
+  },
+]
+
+const HEADER = <p className="font-display font-semibold">Hexline ops</p>
+
+const FOOTER = <p className="text-xs text-[var(--color-text-secondary)]">Signed in as Ana Pop</p>
+
+const closeOnChoose = ({ onClick, ...props }: LinkRenderProps) => (
+  <SheetClose asChild type={undefined}>
+    <a {...props} onClick={onClick} />
+  </SheetClose>
+)
+
+<Sheet>
+  <SheetTrigger asChild>
+    <Button variant="secondary">Open navigation</Button>
+  </SheetTrigger>
+  <SheetContent side="left" title="Navigation">
+    <Sidebar
+      label="Dashboard navigation, in a sheet"
+      groups={GROUPS}
+      header={HEADER}
+      footer={FOOTER}
+      renderLink={closeOnChoose}
+    />
+  </SheetContent>
+</Sheet>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through each group title that can fold, then each visible item. |
+| `Enter` | Follows an item, or folds and unfolds a group. |
+| `Space` | Folds and unfolds a group. |
+
+## Do
+
+- Only show counts for things that need attention: open orders, not total products.
+- Keep the group that holds the current page open.
+- On a narrow screen, put the whole sidebar in a Sheet behind a button.
+
+## Don't
+
+- Don't nest groups inside groups.
+- Don't show a count of zero. Leave it off.
+- Don't rely on icons alone. Every item keeps its label.
+
+## Anatomy
+
+- **nav**: The navigation region. Screen readers call it by the label prop.
+- **Group title**: A disclosure button (one that shows and hides the list) when the group can fold, plain text when it can't. It's text.secondary, so it still reads on a raised panel. Its list opens and closes by animating its height. Opening also fades and slides each item in, each one a little later than the one before (capped, so a long group never feels slow). Closing fades everything out together, all at once. If someone has asked their system for less motion (prefers-reduced-motion: reduce), both happen instantly.
+- **Item**: An icon, a label and an optional count. The current page gets the fill, plus aria-current, an ARIA attribute (Accessible Rich Internet Applications, the labels screen readers rely on) that tells screen readers this is the page you are on.
+- **Header**: Sits above the groups: a product name, a workspace switcher.
+- **Footer**: Pinned below the groups: the signed-in account, a help link.

package/public/docs/components/skeleton.md

@@ -0,0 +1,135 @@
+# Skeleton
+
+> A loading placeholder shaped like the content it stands in for: lines of text, a cut-corner block, or an Avatar’s footprint. The shapes themselves are silent. SkeletonGroup is what tells people the region is loading.
+
+- **Best for:** A region whose content is loading, shown as placeholders in its shape inside one SkeletonGroup.
+- **Not for:** A busy button: use Button loading. A wait under a few hundred milliseconds: show nothing.
+- Atom. Source: `src/components/atoms/skeleton/Skeleton.tsx`
+- Rendered docs page: `/components/skeleton`
+
+## Import
+
+```tsx
+import { Skeleton, SkeletonGroup } from 'src/components/atoms/skeleton/Skeleton'
+```
+
+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 |
+|---|---|---|---|
+| `shape` | `'text' \| 'block' \| 'avatar'` | `'text'` | What the placeholder stands in for. |
+| `lines` | `number` | `1` | Text only. The number of lines. Anything below 1 counts as 1. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar only. Matches Avatar’s size prop. |
+| `className` | `string` |  | Merged with the component classes. A block takes its width and height from here. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root element. |
+| `...rest` | `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` |  | Every native div prop except children, because a skeleton draws its own shapes. |
+| `label (SkeletonGroup)` | `string` | `'Loading…'` | The hidden words a screen reader hears instead of the shapes. |
+| `className (SkeletonGroup)` | `string` |  | Lay the placeholders out here, the way the real content will be laid out. |
+| `ref (SkeletonGroup)` | `Ref<HTMLDivElement>` |  | Passed through to the container. |
+| `...rest (SkeletonGroup)` | `HTMLAttributes<HTMLDivElement>` |  | Every native div prop. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Shapes: text lines, a block, the Avatar footprints
+
+```tsx
+<div className="flex w-full flex-col gap-6">
+  <Skeleton shape="text" lines={3} className="max-w-md" />
+  <Skeleton shape="block" className="h-24 w-full max-w-md" />
+  <div className="flex items-center gap-3">
+    <Skeleton shape="avatar" size="sm" />
+    <Skeleton shape="avatar" size="md" />
+    <Skeleton shape="avatar" size="lg" />
+  </div>
+</div>
+```
+
+### A card loading: image, title, two lines of copy
+
+```tsx
+<SkeletonGroup label="Loading replicas" className="grid w-full max-w-md gap-4 sm:grid-cols-2">
+  {[0, 1].map(i => (
+    <Card key={i}>
+      <CardBody className="flex flex-col gap-4">
+        <Skeleton shape="block" className="aspect-[4/3] w-full" />
+        <Skeleton shape="text" className="w-2/3" />
+        <Skeleton shape="text" lines={2} />
+      </CardBody>
+    </Card>
+  ))}
+</SkeletonGroup>
+```
+
+### Table rows loading
+
+```tsx
+<SkeletonGroup label="Loading orders" className="w-full max-w-xl">
+  <div className="flex flex-col divide-y divide-[var(--color-border-hairline)]">
+    {[0, 1, 2].map(i => (
+      <div key={i} className="grid grid-cols-[1fr_2fr_1fr] items-center gap-4 py-3">
+        <Skeleton shape="text" />
+        <Skeleton shape="text" className="w-4/5" />
+        <Skeleton shape="text" className="w-1/2 justify-self-end" />
+      </div>
+    ))}
+  </div>
+</SkeletonGroup>
+```
+
+### A profile row loading
+
+```tsx
+<SkeletonGroup label="Loading the squad roster" className="flex w-full max-w-sm items-center gap-3">
+  <Skeleton shape="avatar" size="md" />
+  <div className="flex flex-1 flex-col gap-2">
+    <Skeleton shape="text" className="w-1/2" />
+    <Skeleton shape="text" className="w-1/3" />
+  </div>
+</SkeletonGroup>
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Wrap one region’s placeholders in one SkeletonGroup, and remove it when the content arrives.
+- Name what’s loading in the group label: Loading orders, not just Loading.
+- Match the layout of the real content, so nothing jumps when it replaces the placeholder.
+- Use shape="avatar" with the size the real Avatar will have.
+
+## Don't
+
+- Don't round a skeleton or draw a circle. The system has square corners, and Avatar is a square too.
+- Don't put a skeleton on a busy button or control. A busy Button takes loading.
+- Don't nest one SkeletonGroup inside another. One busy region gets one announcement.
+- Don't show a skeleton for a wait under a few hundred milliseconds. The flash is worse than the wait.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<div><Skeleton lines={3} /></div>
+```
+
+Right:
+
+```tsx
+<SkeletonGroup label="Loading orders"><Skeleton lines={3} /></SkeletonGroup>
+```
+
+Every shape is aria-hidden, an ARIA (Accessible Rich Internet Applications) attribute that hides it from assistive tech. So without the group, a screen reader, the software that reads the page aloud, hears nothing at all while the region loads.
+
+## Anatomy
+
+- **Shape**: A border.hairline fill with a border.hairline-strong band sweeping across it every 1.6s. It’s see-through, so it reads on the page, a Card or an overlay. aria-hidden.
+- **Text lines**: 12px (pixel) bars, 8px apart, full width. When there are several, the last one is three fifths wide.
+- **Block**: Any rectangle, sized with className, with the 8px cut corner.
+- **Avatar**: An Avatar’s exact footprint: 24, 36 or 48px, with the corner cut at md and lg only.
+- **SkeletonGroup**: The container. It has aria-busy="true", which tells assistive tech the region is busy, and a visually hidden label that reads Loading… unless you name what’s loading.

package/public/docs/components/slider.md

@@ -0,0 +1,114 @@
+# Slider
+
+> A value or a range picked on a track. Each thumb (the handle you drag) gets its own name. If a range slider shared one name, a screen-reader user (someone using software that reads the page aloud) would get two controls called the same thing.
+
+- **Best for:** A value or range on a track, where the rough position matters and the value is shown.
+- **Not for:** A precise value with no other way to enter it. Use Input.
+- Atom. Source: `src/components/atoms/slider/Slider.tsx`
+- Rendered docs page: `/components/slider`
+
+## Import
+
+```tsx
+import { Slider } from 'src/components/atoms/slider/Slider'
+```
+
+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 |
+|---|---|---|---|
+| `label` | `string` |  | Required. Applied to each thumb. A single thumb gets it as-is, and a range adds "minimum" / "maximum" to the end. |
+| `value` | `number[]` |  | The value(s), when you control them from outside. One number makes a single slider; two make a range. |
+| `defaultValue` | `number[]` |  | The starting value(s), when the slider manages them itself (uncontrolled). |
+| `onValueChange` | `(value: number[]) => void` |  | Fires as the thumb moves. |
+| `min` | `number` | `0` | The lowest value. |
+| `max` | `number` | `100` | The highest value. |
+| `step` | `number` | `1` | The increment for both snapping while dragging and the arrow keys. |
+| `disabled` | `boolean` |  | Takes it out of the tab order and blocks input. |
+| `formatValue` | `(value: number) => string` |  | One function feeds both the readout and aria-valuetext (the ARIA, or Accessible Rich Internet Applications, attribute a screen reader speaks as the value). So the spoken value and the printed one can’t drift apart, whether the slider is controlled or not. |
+| `showValue` | `boolean` | `false` | Shows the current value(s) as a readout. |
+| `className` | `string` |  | Merged with the outer wrapper's classes. Later Tailwind utilities (Tailwind is the CSS framework the system uses) win. |
+| `ref` | `Ref<HTMLSpanElement>` |  | Passed through to the Radix Slider root. Radix is the library of accessible building blocks this sits on. |
+| `...rest` | `Omit<Slider.Root props, 'aria-label' \| 'aria-labelledby' \| 'children'>` |  | Every Radix Slider.Root prop except those three, spread onto the root. aria-label and aria-labelledby are left out because the accessible name lives on each thumb, where label puts it. One on the root would do nothing at all, not override anything. children is typed away because this component draws its own Track/Range/Thumbs, and a children prop would be thrown away without any warning. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Single value
+
+```tsx
+function SingleValueLive() {
+  const [weight, setWeight] = useState([8])
+  return (
+    <div className="w-full max-w-sm">
+      <Slider
+        label="Kit weight"
+        value={weight}
+        onValueChange={setWeight}
+        max={20}
+        formatValue={v => `${v} kg`}
+        showValue
+      />
+    </div>
+  )
+}
+
+<SingleValueLive />
+```
+
+### Range
+
+```tsx
+<div className="w-full max-w-sm">
+  <Slider label="Weight range" defaultValue={[4, 12]} max={20} />
+</div>
+```
+
+### Stepped
+
+```tsx
+<div className="w-full max-w-sm">
+  <Slider label="BB bottles" defaultValue={[5]} max={20} step={5} />
+</div>
+```
+
+### Disabled
+
+```tsx
+<div className="w-full max-w-sm">
+  <Slider label="Locked ration" defaultValue={[8]} max={20} disabled />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `→` `↑` | Goes up by one step. |
+| `←` `↓` | Goes down by one step. |
+| `Page Up` | Goes up by a bigger jump. |
+| `Page Down` | Goes down by a bigger jump. |
+| `Home` | Jumps to the minimum. |
+| `End` | Jumps to the maximum. |
+
+## Do
+
+- Use formatValue whenever the number has a unit.
+- Show the value. A slider with no readout asks people to guess.
+- Put a number input beside it when the exact value matters.
+
+## Don't
+
+- Don't use a slider where a precise value is required and nothing else lets people enter one.
+- Don't shrink the thumb below 24×24 of hit area.
+- Don't rely on dragging alone. Every slider here works fully from the keyboard, and it should stay that way.
+
+## Anatomy
+
+- **Label and readout**: An 11px (pixel) mono label, in a monospaced font, and a 24px Oxanium readout with tabular figures, digits that all take the same width. Unlike Progress, there are no dimmed leading zeros. min and max belong to the caller and formatValue can return anything, so a fixed digit width would be one the value doesn’t actually have.
+- **Track**: 4px tall, sunken, no border.
+- **Range**: The filled span, in accent.signal.indicator.
+- **Thumb**: A 20px square inside a 24px hit area, the region that responds to a click or tap. There’s one per value.

package/public/docs/components/sparkline.md

@@ -0,0 +1,128 @@
+# Sparkline
+
+> A small trend line with no axes. It sits beside a Stat or in a table cell. It's plain SVG (Scalable Vector Graphics, the web's format for drawn shapes): one image named by a sentence, with an optional safe band behind it and a square on the last value.
+
+- **Best for:** You want the shape of a recent series, not its values. Think of a reading over the last hour.
+- **Not for:** Values people need to read, compare or hover over. Use ChartPanel for those.
+- Atom. Source: `src/components/atoms/sparkline/Sparkline.tsx`
+- Rendered docs page: `/components/sparkline`
+
+## Import
+
+```tsx
+import { Sparkline } from 'src/components/atoms/sparkline/Sparkline'
+```
+
+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 |
+|---|---|---|---|
+| `values` | `readonly number[]` |  | Required. Oldest first. Non-finite values (such as NaN or Infinity) are dropped. |
+| `label` | `string` |  | Required. The chart as one sentence: "Temperature, last hour: 3.1 to 4.2 °C, rising". |
+| `tone` | `'neutral' \| 'signal' \| 'ok' \| 'warning' \| 'hostile' \| 'info'` | `'neutral'` | The line's colour. Each tone means what it means on Badge. |
+| `min` | `number` |  | A fixed bottom for the scale. Without it, the scale follows the data (and the band). |
+| `max` | `number` |  | A fixed top for the scale. Without it, the scale follows the data (and the band). |
+| `band` | `{ from: number; to: number }` |  | A range drawn behind the line. |
+| `showLast` | `boolean` | `false` | Puts a square on the last value. |
+| `width` | `number` | `96` | In CSS px, the pixel unit of Cascading Style Sheets. className="w-full" overrides it. |
+| `height` | `number` | `24` | In CSS px. |
+| `className` | `string` |  | Goes on the frame. |
+| `ref` | `Ref<HTMLSpanElement>` |  | Forwarded to the frame. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type SparklineTone = 'neutral' | 'signal' | 'ok' | 'warning' | 'hostile' | 'info'
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Beside the value it trends
+
+```tsx
+<div className="flex items-center gap-3">
+  <span className="font-mono text-sm tabular-nums">4.2 °C</span>
+  <Sparkline
+    values={[3.1, 3.2, 3.2, 3.4, 3.3, 3.6, 3.8, 3.7, 4.0, 4.2]}
+    label="Cold room 2, last hour: 3.1 to 4.2 °C, rising"
+    band={{ from: 2, to: 8 }}
+    showLast
+  />
+</div>
+<div className="flex items-center gap-3">
+  <span className="font-mono text-sm tabular-nums">412</span>
+  <Sparkline
+    values={[380, 365, 402, 398, 371, 420, 412]}
+    label="Orders, last 7 days: 365 to 420, steady"
+    tone="signal"
+    showLast
+  />
+</div>
+```
+
+### Tones
+
+```tsx
+<Sparkline values={[5, 6, 5, 7, 6, 8]} label="Neutral trend, rising" />
+<Sparkline values={[5, 6, 5, 7, 6, 8]} label="Healthy trend, rising" tone="ok" />
+<Sparkline values={[5, 6, 5, 7, 6, 8]} label="Degraded trend, rising" tone="warning" />
+<Sparkline values={[5, 6, 5, 7, 6, 8]} label="Failing trend, rising" tone="hostile" />
+<Sparkline values={[5, 6, 5, 7, 6, 8]} label="Informational trend, rising" tone="info" />
+```
+
+### Stretched to its container, with a safe band from 2 to 8 °C
+
+```tsx
+<div className="w-full max-w-md">
+  <Sparkline
+    values={[4.1, 4.3, 4.0, 5.2, 6.8, 8.4, 9.1, 8.7, 7.2, 5.9, 5.0, 4.6]}
+    label="Cold room 3, last 12 hours: 4.0 to 9.1 °C, above the safe band for 3 hours, now back inside it"
+    tone="warning"
+    band={{ from: 2, to: 8 }}
+    min={0}
+    max={10}
+    height={40}
+    className="w-full"
+    showLast
+  />
+</div>
+```
+
+### No values, one value, a flat run
+
+```tsx
+<Sparkline values={[]} label="No readings yet" />
+<Sparkline values={[12]} label="One reading: 12" showLast />
+<Sparkline values={[7, 7, 7, 7]} label="Flat at 7" showLast />
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Write the label as the reading a person takes from the shape: the range and the direction.
+- Fix min and max when several sparklines sit side by side and have to share a scale.
+- Put the current value beside it in text. The line shows the trend, not the number.
+- Use a tone for what the trend means (hostile for out of range), and say it in text too.
+
+## Don't
+
+- Don't use a sparkline where someone has to read values off it. That's a job for ChartPanel.
+- Don't leave the label as a title like "Temperature". It's the only thing a screen reader hears.
+- Don't colour every sparkline on a page. Neutral is the default for a reason.
+
+## Anatomy
+
+- **Frame**: An inline box. It's 96 x 24 by default, or the container's width with className="w-full".
+- **Image**: An svg with role="img", named by label. Screen readers (software that reads the page aloud) don't get the points one by one.
+- **Band**: Optional. A hairline-filled range behind the line, such as a safe range.
+- **Line**: 1.5px (pixels) in the tone colour. The stroke doesn't get thicker when the frame stretches.
+- **Last value**: An optional 6px square on the newest point. It's aria-hidden, a setting that hides it from screen readers.

package/public/docs/components/spinner.md

@@ -0,0 +1,98 @@
+# Spinner
+
+> A busy indicator for an indeterminate wait, meaning one with no known end or percentage. It comes in two forms. The ring has a lit arc that grows and slides as it turns. The conveyor is a row of shaded blocks, for a wait that sits inside a line of text.
+
+- **Best for:** A short wait with no known end, inside a control or a line of text.
+- **Not for:** Progress with a known amount (use Progress), or a wait for a whole page (use Skeleton or LoadingAnimation).
+- Atom. Source: `src/components/atoms/spinner/Spinner.tsx`
+- Rendered docs page: `/components/spinner`
+
+## Import
+
+```tsx
+import { Spinner, spinnerVariants } from 'src/components/atoms/spinner/Spinner'
+```
+
+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 |
+|---|---|---|---|
+| `variant` | `'ring' \| 'conveyor'` | `'ring'` | The rotating ring, or the block conveyor. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Ring: a 14px, 20px or 24px (pixel) box. Conveyor: 12px, 14px or 16px glyphs. |
+| `label` | `string` |  | Status text that's hidden on screen. Passing it makes the spinner a live region, an area whose changes screen readers announce on their own. |
+| `className` | `string` |  | Merged with the component's classes. Later Tailwind utilities (the small styling classes this system uses) win. |
+| `ref` | `Ref<HTMLSpanElement>` |  | Forwarded to the span element. |
+| `...rest` | `Omit<HTMLAttributes<HTMLSpanElement>, 'role'>` |  | Every native span prop except role, spread onto the span. role is removed from the type instead of being quietly overridden at runtime. Here's why: label is the only source of role="status", and a role in rest would silence the live region a caller asked for when they passed label. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export const spinnerVariants = cva(
+  // The arc takes `currentColor`, so a caller can recolour it with one text utility: Button does
+  // exactly that, so the arc matches whatever ink the button label is set in.
+  'inline-block shrink-0 text-[var(--color-accent-signal-indicator)]',
+  {
+    variants: {
+      size: { sm: 'w-3.5 h-3.5', md: 'w-5 h-5', lg: 'w-6 h-6' },
+    },
+    defaultVariants: { size: 'md' },
+  }
+)
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Ring, three sizes
+
+```tsx
+<Spinner size="sm" label="Loading field kits" />
+<Spinner size="md" label="Loading field kits" />
+<Spinner size="lg" label="Loading field kits" />
+```
+
+### Conveyor, three sizes
+
+```tsx
+<Spinner variant="conveyor" size="sm" label="Syncing manifest" />
+<Spinner variant="conveyor" size="md" label="Syncing manifest" />
+<Spinner variant="conveyor" size="lg" label="Syncing manifest" />
+```
+
+### Decorative, inside a control
+
+```tsx
+<span className="inline-flex items-center gap-2 border border-[var(--color-border-hairline-strong)] px-3 py-2">
+  <Spinner aria-hidden="true" />
+  <span className="text-sm">Dispatching…</span>
+</span>
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Pass label whenever the spinner is the only sign that something's happening.
+- Leave it decorative inside a control that already announces aria-busy, like Button. aria-busy is an ARIA (Accessible Rich Internet Applications) attribute that tells screen readers a part of the page is still loading.
+- Name what's loading, not the fact of loading: ‘Loading field kits’, not ‘Loading’.
+
+## Don't
+
+- Don't use it for progress with a known amount. That's Progress.
+- Don't rely on the rotation alone. It stops when someone has turned on reduced motion in their system settings, so the label carries the meaning.
+- Don't scale it past lg. A page-level wait needs a skeleton, not a bigger spinner.
+- Don't bevel it. It's the one round shape in the system. A cut corner on something that rotates would travel around the edge instead of marking one spot.
+
+## Anatomy
+
+- **span**: The root. It gets role="status" only when it's labelled.
+- **Ring (ring)**: An SVG (Scalable Vector Graphics) track at 20% of currentColor, which is the surrounding text colour, plus an arc in currentColor. That's accent.signal.indicator by default.
+- **Blocks (conveyor)**: Three block glyphs, from full to half shade, running over a ten-cell track in border.control.
+- **sr-only label**: The text a screen reader announces. sr-only means it's hidden on screen but still read aloud. It's only there when label is passed.