division-ds 0.1.1 → 0.2.0

package/public/docs/components/skeleton.md

@@ -0,0 +1,133 @@
+# 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'
+```
+
+## 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,112 @@
+# 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'
+```
+
+## 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 signal.fill.
+- **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,126 @@
+# 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'
+```
+
+## 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,96 @@
+# 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'
+```
+
+## 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-fill)]',
+  {
+    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.fill 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.

package/public/docs/components/stat.md

@@ -0,0 +1,104 @@
+# Stat
+
+> One number that matters, and how it has moved. The number is the star of the show. The label is small, set in a monospaced font and kept quiet.
+
+- **Best for:** One headline number and how it has moved. Up to four in a row.
+- **Not for:** A value that only makes sense as a chart: use ChartPanel.
+- Molecule. Source: `src/components/molecules/stat/Stat.tsx`
+- Rendered docs page: `/components/stat`
+
+## Import
+
+```tsx
+import { Stat } from 'src/components/molecules/stat/Stat'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | The stat's name, for example "Kits dispatched". |
+| `value` | `number \| string` |  | Whole numbers get padded. Anything else (for example "4.2k") is shown exactly as given. |
+| `unit` | `string` |  | Shown beside the value, for example "kg". |
+| `padTo` | `number` |  | Pads a whole-number value to this many digits with dimmed zeros that screen readers skip (aria-hidden). |
+| `delta` | `{ value: string; direction: 'up' \| 'down'; sentiment: 'positive' \| 'negative' \| 'neutral'; period: string }` |  | value comes already formatted (for example "12%"). direction picks the arrow. sentiment picks the colour, and it doesn't depend on direction: fewer failed syncs is down, and that's positive. period is what the number is compared with, for example "last week". It's both shown and spoken. |
+| `className` | `string` |  | Merged with the root classes. If two Tailwind utilities clash, the later one wins. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root div. |
+| `...rest` | `HTMLAttributes<HTMLDivElement>` |  | Any standard div attribute, applied to the root div. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type StatDelta = {
+  /** Already formatted, e.g. "12%". */
+  value: string
+  direction: 'up' | 'down'
+  /** Whether this movement is good. Independent of direction: fewer failed syncs is down AND good. */
+  sentiment: 'positive' | 'negative' | 'neutral'
+  /** What it is compared with, e.g. "last week". Spoken and shown. */
+  period: string
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A row of stats
+
+```tsx
+<div className="grid grid-cols-2 sm:grid-cols-4 gap-6 w-full">
+  <Stat
+    label="Kits dispatched"
+    value={18}
+    padTo={3}
+    delta={{ value: '12%', direction: 'up', sentiment: 'positive', period: 'last week' }}
+  />
+  <Stat
+    label="Failed syncs"
+    value={3}
+    delta={{ value: '40%', direction: 'down', sentiment: 'positive', period: 'last week' }}
+  />
+  <Stat
+    label="Depots offline"
+    value={2}
+    delta={{ value: '1', direction: 'up', sentiment: 'negative', period: 'last week' }}
+  />
+  <Stat label="Payload" value={24} unit="kg" />
+</div>
+```
+
+### Without a delta
+
+```tsx
+<div className="max-w-[10rem] w-full">
+  <Stat label="Kits dispatched" value={18} padTo={3} />
+</div>
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Lay several Stats out in a plain div grid. Each one renders its own dl (description list), so you don't need a list element around them.
+- Set sentiment by what the change means, not by its direction: fewer failed syncs is down, and that's positive.
+- Say what the delta is compared with.
+- Only pad when every value in a row has the same fixed width.
+
+## Don't
+
+- Don't pad a value whose width isn't fixed. The zeros would be made up.
+- Don't put more than four stats in a row.
+- Don't use a Stat for a value that only makes sense as a chart.
+
+## Anatomy
+
+- **Label**: A dt (the "term" element of an HTML description list), in text.secondary.
+- **Value**: A dd (the matching "description" element) at 36px (pixels), set in Oxanium with tabular figures, so every digit is the same width.
+- **Pad**: Optional leading zeros in numeral.pad. They're aria-hidden, so screen readers skip them, and they only appear when the width is real.
+- **Unit**: A short suffix beside the value, for example kg.
+- **Delta**: The change. An arrow shows the direction, colour shows whether it's good or bad, and a spoken sentence says both for screen reader users.