division-ds 0.1.2 → 0.2.0

package/public/docs/components/status-tracker.md

@@ -0,0 +1,143 @@
+# StatusTracker
+
+> Health over time, drawn as a row of thin bars with one bar per period. The oldest is on the left. Each bar says its status in words and shows them in a tooltip when you hover over it or reach it with the keyboard. The whole row is a single Tab stop, and the arrow keys move along it.
+
+- **Best for:** The health history of one service or device, such as uptime over 30 or 90 days.
+- **Not for:** A current status: use Badge. A measured value: use Sparkline.
+- Molecule. Source: `src/components/molecules/status-tracker/StatusTracker.tsx`
+- Rendered docs page: `/components/status-tracker`
+
+## Import
+
+```tsx
+import { StatusTracker, statusTrackerText } from 'src/components/molecules/status-tracker/StatusTracker'
+```
+
+## Requires
+
+- The root TooltipProvider (AppShell and DemoLayout mount it).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. Names the row, for example "Uptime, last 30 days". |
+| `items` | `readonly StatusTrackerItem[]` |  | Required. Oldest first. |
+| `summary` | `ReactNode` |  | Shown on the right of the label row, for example "99.2% up". |
+| `statusLabels` | `Partial<Record<StatusTrackerStatus, string>>` |  | Replaces the status words: Operational, Degraded, Down, No data. |
+| `className` | `string` |  | Added to the root. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root. |
+| `id (StatusTrackerItem)` | `string` |  | Required. A key that never changes for that item. |
+| `status (StatusTrackerItem)` | `'ok' \| 'warning' \| 'hostile' \| 'neutral'` |  | Required. ok means up. warning means degraded. hostile means down or failed. neutral means no data. |
+| `label (StatusTrackerItem)` | `string` |  | Required. The period and what happened, for example "12 Oct: 2 alerts, 14 min degraded". |
+| `statusTrackerText()` | `(item, words?) => string` |  | Builds the text a bar uses for its name and tooltip, for example "Degraded. 12 Oct: 2 alerts". |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type StatusTrackerStatus = 'ok' | 'warning' | 'hostile' | 'neutral'
+```
+
+```ts
+export type StatusTrackerItem = {
+  /** Stable key. */
+  id: string
+  /** ok up or healthy; warning degraded; hostile down or failed; neutral no data. */
+  status: StatusTrackerStatus
+  /** The period and what happened in it: "12 Oct: 2 alerts, 14 min degraded". */
+  label: string
+}
+```
+
+```ts
+/** Text of one bar: the status word first, then the caller's label. Shared by the accessible name
+ *  and the tooltip, so what is heard and what is seen are the same sentence. */
+export function statusTrackerText(item: StatusTrackerItem, words: Record<StatusTrackerStatus, string> = STATUS_WORDS)
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Thirty days, with a summary
+
+```tsx
+const THIRTY: StatusTrackerItem[] = Array.from({ length: 30 }, (_, index) => {
+  const day = new Date(Date.UTC(2026, 8, 16 + index))
+  const date = day.toLocaleDateString('en-GB', { day: 'numeric', month: 'short', timeZone: 'UTC' })
+  if (index === 8) return { id: `d${index}`, status: 'warning', label: `${date}: 2 alerts, 14 min degraded` }
+  if (index === 19) return { id: `d${index}`, status: 'hostile', label: `${date}: 41 min down` }
+  if (index === 23) return { id: `d${index}`, status: 'warning', label: `${date}: 1 alert, 6 min degraded` }
+  if (index === 26) return { id: `d${index}`, status: 'neutral', label: `${date}: no readings` }
+  return { id: `d${index}`, status: 'ok', label: `${date}: no alerts` }
+})
+
+<div className="w-full max-w-xl">
+  <StatusTracker label="Uptime, last 30 days" summary="99.2% up" items={THIRTY} />
+</div>
+```
+
+### Ninety days in the same width
+
+```tsx
+const NINETY: StatusTrackerItem[] = Array.from({ length: 90 }, (_, index) => ({
+  id: `n${index}`,
+  status: index % 37 === 12 ? 'hostile' : index % 23 === 5 ? 'warning' : 'ok',
+  label: `Day ${index + 1} of 90`,
+}))
+
+<div className="w-full max-w-xl">
+  <StatusTracker label="Uptime, last 90 days" summary="99.6% up" items={NINETY} />
+</div>
+```
+
+### Other status words
+
+```tsx
+<div className="w-full max-w-xs">
+  <StatusTracker
+    label="Door sensor, last 8 hours"
+    statusLabels={{ ok: 'Closed', warning: 'Left open', hostile: 'Forced', neutral: 'Offline' }}
+    items={[
+      { id: 'h1', status: 'ok', label: '02:00 to 03:00' },
+      { id: 'h2', status: 'ok', label: '03:00 to 04:00' },
+      { id: 'h3', status: 'warning', label: '04:00 to 05:00, open 9 min' },
+      { id: 'h4', status: 'ok', label: '05:00 to 06:00' },
+      { id: 'h5', status: 'neutral', label: '06:00 to 07:00' },
+      { id: 'h6', status: 'ok', label: '07:00 to 08:00' },
+      { id: 'h7', status: 'ok', label: '08:00 to 09:00' },
+      { id: 'h8', status: 'ok', label: '09:00 to 10:00' },
+    ]}
+  />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves into the row, landing on the last bar that had focus (the newest one the first time), and moves out again. |
+| `ArrowLeft` `ArrowRight` | Moves one bar older or newer and shows its tooltip. |
+| `Home` `End` | Jumps to the oldest or the newest bar. |
+| `Escape` | Hides the tooltip. Focus stays on the bar. |
+
+## Do
+
+- Write each item label with its period and what happened, not just the status. The status word is added for you.
+- Put the headline figure in summary, so the row has a number people can read before they explore it.
+- Use neutral for periods with no data, so a gap looks like a gap and not like a healthy day.
+
+## Don't
+
+- Don't start an item label with the status word as well. It's already said first.
+- Don't use it for more than about 90 bars. At a 320px-wide screen the bars get thinner than 2px.
+- Don't make a bar do anything when clicked. It's a reading, not a control.
+
+## Anatomy
+
+- **Label row**: The label in a monospaced font on the left, and the optional summary on the right.
+- **List**: A ul (bulleted list element) named by the label, with one li (list item) per bar, so a screen reader hears how many bars there are and where each one sits.
+- **Bar**: A block 32px (pixels) tall in the status colour. It has role="img" and aria-roledescription="status bar", which tell screen readers what it is, and its name is the status word plus the label.
+- **Tooltip**: The same text as the name, shown on hover and on keyboard focus.

package/public/docs/components/stepper.md

@@ -0,0 +1,145 @@
+# Stepper
+
+> Shows where someone is in a flow of several steps. Finished steps get a check mark, the current one is filled with the signal colour, and the rest wait as outlines.
+
+- **Best for:** Showing where someone is in a flow of two to five steps.
+- **Not for:** Sections that are equally important: use Tabs. Also not for a single step.
+- Molecule. Source: `src/components/molecules/stepper/Stepper.tsx`
+- Rendered docs page: `/components/stepper`
+
+## Import
+
+```tsx
+import { Stepper } from 'src/components/molecules/stepper/Stepper'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `steps` | `Step[]` |  | Required. { label: string; description?: string }. |
+| `current` | `number` |  | Counts from 0. steps.length means every step is complete. |
+| `label` | `string` | `'Progress'` | The list's accessible name, the name screen readers announce. |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Horizontal runs in a row from sm up and stacks below it. Vertical is a column at every width, with connectors. |
+| `className` | `string` |  | Merged with the root classes. If two Tailwind utilities clash, the later one wins. |
+| `ref` | `Ref<HTMLOListElement>` |  | Passed through to the root ol. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type Step = { label: string; description?: string }
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Checkout
+
+```tsx
+const CHECKOUT_STEPS: Step[] = [
+  { label: 'Shipping' },
+  { label: 'Payment' },
+  { label: 'Review', description: 'Check the manifest' },
+]
+
+<div className="w-full">
+  <Stepper steps={CHECKOUT_STEPS} current={1} label="Checkout progress" />
+</div>
+```
+
+### Complete
+
+```tsx
+const CHECKOUT_STEPS: Step[] = [
+  { label: 'Shipping' },
+  { label: 'Payment' },
+  { label: 'Review', description: 'Check the manifest' },
+]
+
+<div className="w-full">
+  <Stepper steps={CHECKOUT_STEPS} current={3} label="Checkout progress" />
+</div>
+```
+
+### Vertical, with descriptions
+
+```tsx
+const SHIPMENT_STEPS: Step[] = [
+  { label: 'Ordered', description: 'Paid on 12 October' },
+  { label: 'Packed', description: 'At the Brasov depot' },
+  { label: 'Shipped', description: 'With the courier' },
+  { label: 'Delivered' },
+]
+
+<div className="w-full max-w-xs">
+  <Stepper steps={SHIPMENT_STEPS} current={2} orientation="vertical" label="Shipment progress" />
+</div>
+```
+
+### Live: move through the steps with Back and Continue
+
+```tsx
+const CHECKOUT_STEPS: Step[] = [
+  { label: 'Shipping' },
+  { label: 'Payment' },
+  { label: 'Review', description: 'Check the manifest' },
+]
+
+function LiveStepper() {
+  const [current, setCurrent] = useState(0)
+  return (
+    <div className="flex flex-col gap-6 w-full">
+      <Stepper steps={CHECKOUT_STEPS} current={current} label="Checkout progress" />
+      <div className="flex gap-3">
+        <Button
+          variant="secondary"
+          size="sm"
+          disabled={current === 0}
+          onClick={() => setCurrent(c => Math.max(0, c - 1))}
+        >
+          Back
+        </Button>
+        <Button
+          size="sm"
+          disabled={current >= CHECKOUT_STEPS.length}
+          onClick={() => setCurrent(c => Math.min(CHECKOUT_STEPS.length, c + 1))}
+        >
+          Continue
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+<LiveStepper />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+|  | Not interactive. Put Back and Continue buttons in the flow itself. |
+
+## Do
+
+- Keep it to five steps or fewer.
+- Name steps for what happens in them: 'Shipping', not 'Step 1'.
+- Label the list after the flow: 'Checkout progress'.
+- Use vertical beside other content, or when steps have descriptions, like a shipment on an order page.
+
+## Don't
+
+- Don't make steps clickable so people can skip ahead.
+- Don't use a Stepper for equally important sections. That's what Tabs is for.
+- Don't show a Stepper for a single step.
+
+## Anatomy
+
+- **List**: An ol (numbered list element) named by label.
+- **Marker**: A 28px (pixel) square. Done: signal fill with a check. Current: signal fill with its number, without leading zeros, because dimmed zeros can't keep enough contrast against the fill. Upcoming: an outline with the two-digit number, leading zero included.
+- **Connector**: A 2px line that turns the signal colour once the step before it is done. Horizontal: hidden when the steps stack, below the sm breakpoint (the small-screen width). Vertical: always shown, running down between the markers.
+- **Label**: In a monospaced font, with its status spelled out in words for screen readers.
+- **Description**: Optional, under the label. The vertical layout gives it the most room.

package/public/docs/components/switch.md

@@ -0,0 +1,151 @@
+# Switch
+
+> An on/off control that acts right away. The thumb's position shows the state, so the meaning still comes through with colour turned off. It takes effect the moment it's flipped.
+
+- **Best for:** An on/off setting that takes effect the moment it's flipped.
+- **Not for:** A choice in a form that needs a Save. Use Checkbox.
+- Atom. Source: `src/components/atoms/switch/Switch.tsx`
+- Rendered docs page: `/components/switch`
+
+## Import
+
+```tsx
+import { Switch } from 'src/components/atoms/switch/Switch'
+```
+
+## Requires
+
+- Its own label. A Switch isn't a FormField child (FormField takes Input, Textarea, Select or QuantityStepper). Give it an id and put a <label htmlFor> beside it.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean` |  | The checked state, when your code controls it. |
+| `defaultChecked` | `boolean` |  | The starting state, when the switch manages itself. |
+| `onCheckedChange` | `(checked: boolean) => void` |  | Fires the moment it's flipped. |
+| `disabled` | `boolean` |  | Takes it out of the tab order and blocks toggling. |
+| `required` | `boolean` |  | The browser's own form validation. |
+| `name` | `string` |  | The browser's own form field name. |
+| `value` | `string` |  | The browser's own form field value. |
+| `id` | `string` |  | Pair it with a real label through htmlFor. |
+| `className` | `string` |  | Merged with the control's classes. Later Tailwind utilities (the small styling classes this system uses) win. |
+| `ref` | `Ref<HTMLButtonElement>` |  | Forwarded to the root button from Radix, the open-source library this switch is built on. |
+| `...rest` | `ButtonHTMLAttributes<HTMLButtonElement>` |  | Every other Radix Switch.Root prop, which means every native button attribute, spread onto the root button. For example aria-describedby, or aria-label when no label element points at it. aria-* attributes are ARIA (Accessible Rich Internet Applications) settings that give screen readers extra information. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Off and on
+
+```tsx
+<div className="flex items-center gap-3">
+  <Switch id="state-off" />
+  <label htmlFor="state-off">Off</label>
+</div>
+<div className="flex items-center gap-3">
+  <Switch id="state-on" defaultChecked />
+  <label htmlFor="state-on">On</label>
+</div>
+```
+
+### Live
+
+```tsx
+function LiveExample() {
+  const [on, setOn] = useState(false)
+  return (
+    <div className="flex items-center gap-4">
+      <div className="flex items-center gap-3">
+        <Switch id="live-beacon" checked={on} onCheckedChange={setOn} />
+        <label htmlFor="live-beacon">Field beacon</label>
+      </div>
+      <p className="text-sm text-[var(--color-text-secondary)]">
+        {on ? 'Broadcasting position.' : 'Beacon is off.'}
+      </p>
+    </div>
+  )
+}
+
+<LiveExample />
+```
+
+### Disabled
+
+```tsx
+<div className="flex items-center gap-3">
+  <Switch id="state-disabled-off" disabled />
+  <label htmlFor="state-disabled-off">Disabled, off</label>
+</div>
+<div className="flex items-center gap-3">
+  <Switch id="state-disabled-on" disabled defaultChecked />
+  <label htmlFor="state-disabled-on">Disabled, on</label>
+</div>
+```
+
+### A settings row
+
+```tsx
+<div className="flex w-full items-start justify-between gap-4">
+  <div>
+    <label htmlFor="settings-offline-maps" className="font-medium">
+      Offline maps
+    </label>
+    <p className="text-sm text-[var(--color-text-secondary)]">
+      Download the current route area before you lose signal.
+    </p>
+  </div>
+  <Switch id="settings-offline-maps" defaultChecked />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to it. |
+| `Space` | Toggles it. |
+| `Enter` | Toggles it. Radix allows this on a switch, though not on a checkbox. |
+
+## Do
+
+- Use it only when flipping it takes effect right away.
+- Label it with the thing being switched, not with ‘on’ or ‘off’.
+- Show the result of the switch near it if the effect isn't visible.
+
+## Don't
+
+- Don't put a switch in a form that needs a Save. Use a Checkbox.
+- Don't put ‘on’/‘off’ text inside the track. The position already says it, and the text won't fit at 24px.
+- Don't make the thumb take longer than --duration-base (a timing token) to arrive. A slow switch feels broken. The settle after it arrives only changes its shape, and it ends within --duration-slow, because the state is already readable.
+- Don't use the squash on anything that isn't a small physical object under the user's finger. On a panel or a page it looks like a wobble.
+- Don't add a rebound to the thumb. It gives once against the edge and stops. A switch that keeps moving after the state has landed looks unsure.
+- Don't fill the track with the accent when it's on. Thumb and track changing colour together, mid-flight, is what made the flip look like a twitch.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<FormField label="Email notifications">
+  <Switch />
+</FormField>
+```
+
+Right:
+
+```tsx
+<div className="flex items-center gap-3">
+  <Switch id="notify" checked={on} onCheckedChange={setOn} />
+  <label htmlFor="notify">Email notifications</label>
+</div>
+```
+
+FormField passes its child an invalid prop, and Switch doesn't take one. A switch acts at once, so it has no error state to show.
+
+## Anatomy
+
+- **Root**: role=switch, which tells screen readers (software that reads the page aloud) what it is. A 44×24 track.
+- **Thumb**: A 16px (pixel) square, 3px from the track edge in both states, travelling 22px. Its position is the state signal. It's text.primary when off and accent.signal.fill when on. Held down, it stretches 4px away from the edge it rests on: to the right when off, to the left when on, so it never leaves the track. Flipped, it speeds up across the track, gets a little longer in flight and a little shorter against the far edge, then goes back to its own shape. One give, no bounce.
+- **Track fill**: The control fill, on and off. When it's on, only the border turns to signal.fill. The track doesn't fill with the accent, so the thumb is the one thing that changes colour during a flip.

package/public/docs/components/tabs.md

@@ -0,0 +1,178 @@
+# Tabs
+
+> Sections of one view, with only one visible at a time. The active tab is filled with the signal colour, the same way every other selection in the system is.
+
+- **Best for:** Switching between equally important sections of one view.
+- **Not for:** Steps in a sequence: use Stepper. Moving between pages: use links (Navbar, Sidebar).
+- Molecule. Source: `src/components/molecules/tabs/Tabs.tsx`
+- Rendered docs page: `/components/tabs`
+
+## Import
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from 'src/components/molecules/tabs/Tabs'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value (Root)` | `string` |  | The active tab, when the page controls it. |
+| `variant` | `'fill' \| 'line'` | `'fill'` | How the active tab is shown (Root). 'line' underlines it, for a row inside a panel that already has lots of fills. |
+| `defaultValue` | `string` |  | The tab that starts active, when the component manages it (Root). |
+| `onValueChange` | `(value: string) => void` |  | Called when the active tab changes (Root). |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Which arrow keys move between tabs (Root). Vertical also puts the list beside the panels. |
+| `activationMode` | `'automatic' \| 'manual'` | `'automatic'` | 'manual' waits for Enter or Space before switching, for panels that are slow to draw (Root). |
+| `value (Trigger)` | `string` |  | This tab's own value. |
+| `disabled` | `boolean` | `false` | Turns off one tab (Trigger). |
+| `icon (Trigger)` | `ReactNode` |  | A small symbol before the label, hidden from screen readers (aria-hidden). |
+| `count (Trigger)` | `number` |  | A number after the label, included in the name screen readers announce. |
+| `className` | `string` |  | Merged with the root classes. If two Tailwind utilities clash, the later one wins. Available on every part. |
+| `ref` | `Ref<HTMLElement>` |  | Passed through to the underlying page element. Available on every part. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default
+
+```tsx
+<div className="max-w-sm w-full">
+  <Tabs defaultValue="replica">
+    <TabsList aria-label="Kit sections">
+      <TabsTrigger value="replica">Replica</TabsTrigger>
+      <TabsTrigger value="optics">Optics</TabsTrigger>
+      <TabsTrigger value="parts">Parts</TabsTrigger>
+    </TabsList>
+    <TabsContent value="replica">Electric carbine replica.</TabsContent>
+    <TabsContent value="optics">Tube sight and holo sight.</TabsContent>
+    <TabsContent value="parts">Magazines, a battery and a charger.</TabsContent>
+  </Tabs>
+</div>
+```
+
+### With a disabled tab
+
+```tsx
+<div className="max-w-sm w-full">
+  <Tabs defaultValue="replica">
+    <TabsList aria-label="Kit sections">
+      <TabsTrigger value="replica">Replica</TabsTrigger>
+      <TabsTrigger value="optics">Optics</TabsTrigger>
+      <TabsTrigger value="parts" disabled>
+        Parts
+      </TabsTrigger>
+    </TabsList>
+    <TabsContent value="replica">Electric carbine replica.</TabsContent>
+    <TabsContent value="optics">Tube sight and holo sight.</TabsContent>
+    <TabsContent value="parts">Magazines, a battery and a charger.</TabsContent>
+  </Tabs>
+</div>
+```
+
+### Line, with icons and counts
+
+```tsx
+<div className="max-w-md w-full">
+  <Tabs defaultValue="open" variant="line">
+    <TabsList aria-label="Orders">
+      <TabsTrigger value="open" icon={<Inbox />} count={12}>
+        Open
+      </TabsTrigger>
+      <TabsTrigger value="packed" icon={<Package />} count={4}>
+        Packed
+      </TabsTrigger>
+      <TabsTrigger value="archived" icon={<Archive />} count={0}>
+        Archived
+      </TabsTrigger>
+    </TabsList>
+    <TabsContent value="open">Twelve orders waiting to be packed.</TabsContent>
+    <TabsContent value="packed">Four orders packed, waiting for the courier.</TabsContent>
+    <TabsContent value="archived">No archived orders yet.</TabsContent>
+  </Tabs>
+</div>
+```
+
+### Vertical, line
+
+```tsx
+<div className="max-w-md w-full">
+  <Tabs defaultValue="profile" orientation="vertical" variant="line">
+    <TabsList aria-label="Settings">
+      <TabsTrigger value="profile" icon={<User />}>
+        Profile
+      </TabsTrigger>
+      <TabsTrigger value="security" icon={<Shield />}>
+        Security
+      </TabsTrigger>
+    </TabsList>
+    <TabsContent value="profile">Callsign, squad and home field.</TabsContent>
+    <TabsContent value="security">Password and signed-in devices.</TabsContent>
+  </Tabs>
+</div>
+```
+
+### Controlled: the page keeps track of which tab is open
+
+```tsx
+function ControlledExample() {
+  const [value, setValue] = useState('replica')
+
+  return (
+    <div className="max-w-sm w-full">
+      <div className="flex gap-2 mb-4">
+        <Button size="sm" variant="secondary" onClick={() => setValue('replica')}>
+          Show replica
+        </Button>
+        <Button size="sm" variant="secondary" onClick={() => setValue('optics')}>
+          Show optics
+        </Button>
+      </div>
+      <Tabs value={value} onValueChange={setValue}>
+        <TabsList aria-label="Kit sections">
+          <TabsTrigger value="replica">Replica</TabsTrigger>
+          <TabsTrigger value="optics">Optics</TabsTrigger>
+        </TabsList>
+        <TabsContent value="replica">Electric carbine replica.</TabsContent>
+        <TabsContent value="optics">Tube sight and holo sight.</TabsContent>
+      </Tabs>
+    </div>
+  )
+}
+
+<ControlledExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves into the tab row, onto the active tab. Pressing Tab again moves into the panel. |
+| `ArrowLeft` `ArrowRight` | Previous or next tab. It wraps round at the ends and skips turned-off tabs. |
+| `ArrowUp` `ArrowDown` | The same, when orientation is vertical. |
+| `Home` `End` | First or last tab. |
+
+## Do
+
+- Keep tab labels to one or two words.
+- Use tabs for equals: sections a person would move between freely.
+- Give the tab row an aria-label that names the whole set.
+- Use the line variant inside a card or settings panel, and the fill variant at the top of a view.
+- Use a count for something a person would act on, like open orders or unread reports.
+
+## Don't
+
+- Don't use tabs for steps in a sequence. That's what Stepper is for.
+- Don't put a second row of tabs inside a panel.
+- Don't mix fill and line tabs on one page.
+- Don't give every tab an icon just because one has one. Icons go on all of them or none.
+- Don't use tabs to move between pages. A tab changes what's shown, not where you are.
+
+## Anatomy
+
+- **Tabs**: The root. Holds which tab is active, whether the page controls that or the component does.
+- **TabsList**: The tablist, the row of tabs. It needs an aria-label (a name read out by screen readers). On a narrow screen it scrolls sideways inside itself.
+- **TabsTrigger**: A single tab. Fill variant: the active tab is the signal fill with ink-coloured text, and hovering adds a 12% signal tint. Line variant: the active tab is primary text over a 2px (pixel) signal bar, which moves to the inline end (the side text runs towards) when the tabs are vertical.
+- **Icon**: Optional, before the label. aria-hidden, so screen readers skip it.
+- **Count**: Optional, after the label. You see it as a number, and screen readers read it as part of the name: Open (12).
+- **TabsContent**: A tabpanel, the area a tab shows. It's labelled by its tab and can take focus, so a keyboard user can reach panels that hold only text.