division-ds 0.2.0 → 0.3.0

package/public/docs/components/date-range-picker.md

@@ -0,0 +1,135 @@
+# DateRangePicker
+
+> A start and an end date in one field, an add-on to DatePicker. Type both, or open two months side by side: the first day you pick is the start, the band follows you to the second, which sets the end and closes the calendar. Put DatePresets in `aside` for one-click periods like Last 7 days. Installs DatePicker with it.
+
+- **Best for:** A booking, a report window, a leave request.
+- **Not for:** One day: DatePicker.
+- Molecule. Source: `src/components/molecules/date-range-picker/DateRangePicker.tsx`
+- Rendered docs page: `/components/date-range-picker`
+
+## Import
+
+```tsx
+import { DateRangePicker, EMPTY_RANGE, useDateRangePicker } from 'src/components/molecules/date-range-picker/DateRangePicker'
+```
+
+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. Names the field. Inside a FormField, FormField sets it. |
+| `value` | `{ start: string; end: string }` |  | Controlled range. Each end is 'YYYY-MM-DD' or ''. |
+| `defaultValue` | `{ start: string; end: string }` | `{ start: '', end: '' }` | Starting range when the picker holds it itself. |
+| `onValueChange` | `(range: DateRange) => void` |  | Fires when either end changes. Days picked in the calendar always arrive in order. |
+| `min` | `string` |  | Earliest date, 'YYYY-MM-DD'. |
+| `max` | `string` |  | Latest date, 'YYYY-MM-DD'. |
+| `isDateDisabled` | `(date: string) => boolean` |  | Days that cannot be picked. |
+| `locale` | `string` |  | Segment order, names and first day of the week. Defaults to the browser's. |
+| `weekStartsOn` | `number` |  | 0 Sunday to 6 Saturday. Defaults to the locale's. |
+| `aside` | `ReactNode` |  | Beside the months, in the popover. DatePresets reads and sets the range by itself here. |
+| `partLabels` | `[string, string]` | `['Start date', 'End date']` | The names of the two dates. |
+| `disabled` | `boolean` | `false` | Disables both dates and the button. |
+| `invalid` | `boolean` |  | Marks the field invalid. FormField sets it. |
+| `required` | `boolean` |  | Marks both dates required. FormField sets it. |
+| `name` | `string` |  | Submits name-start and name-end with a form. |
+| `id` | `string` |  | The field's id. FormField sets it. |
+| `aria-describedby` | `string` |  | The ids of the help and error text. FormField sets it. |
+| `className` | `string` |  | Combined with the field's classes. |
+| `ref` | `Ref<HTMLDivElement>` |  | The field's group element. |
+| `useDateRangePicker()` | `() => { value: DateRange; select: (range: DateRange) => void } \| null` |  | Inside the popover: the range, and a way to set it and close. For your own aside content. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+/** A start and an end, each 'YYYY-MM-DD' or '' while not chosen. */
+export type DateRange = { start: IsoDate | ''; end: IsoDate | '' }
+```
+
+```ts
+export const EMPTY_RANGE: DateRange = { start: '', end: '' }
+```
+
+```ts
+/** The open picker's range, and a way to set it and close. DatePresets reads it, so a preset in
+ *  `aside` needs no wiring. null outside a DateRangePicker. */
+export const useDateRangePicker = () => useContext(Context)
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default
+
+```tsx
+<div className="w-full max-w-sm">
+  <DateRangePicker label="Stay" />
+</div>
+```
+
+### With DatePresets beside the months
+
+```tsx
+<div className="w-full max-w-sm">
+  <FormField label="Report period" help="Pick a preset, or two days.">
+    <DateRangePicker label="Report period" aside={<DatePresets />} />
+  </FormField>
+</div>
+```
+
+### Controlled: the page holds the range
+
+```tsx
+function Controlled() {
+  const [range, setRange] = useState<DateRange>({ start: '2026-11-09', end: '2026-11-13' })
+  return (
+    <div className="flex w-full max-w-sm flex-col gap-2">
+      <DateRangePicker label="Leave" value={range} onValueChange={setRange} />
+      <span className="font-mono text-xs text-[var(--color-text-secondary)]">
+        start: {range.start || '—'}, end: {range.end || '—'}
+      </span>
+    </div>
+  )
+}
+
+<Controlled />
+```
+
+### Limits: November and December only
+
+```tsx
+<div className="w-full max-w-sm">
+  <DateRangePicker label="Rental" min="2026-11-01" max="2026-12-30" defaultValue={{ start: '2026-11-20', end: '2026-11-23' }} />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `0–9` `↑` `↓` | Types or steps the focused segment of either date. |
+| `←` `→` | In the field: the next segment, across both dates. In the calendar: the day before or after, moving the band. |
+| `Page Up` `Page Down` | A month earlier or later. With Shift, a year. |
+| `Enter` `Space` | Picks the start, then the end, which closes the calendar. |
+| `Esc` | Closes the calendar. A start picked without an end stays as the start. |
+
+## Do
+
+- Add DatePresets in aside when people mostly want the usual periods.
+- Validate the length yourself if a range has a limit (a 30-day report), and say so in help text.
+
+## Don't
+
+- Don't use two separate DatePickers for a start and an end: nobody sees the band.
+- Don't reorder a typed range for the user; the field marks it invalid so they can see what they typed.
+
+## Anatomy
+
+- **Field**: A group named by the label, holding two segmented dates (Start date, End date) and the calendar button. A typed end before the start marks it invalid.
+- **Calendar**: Two months, stacked on narrow screens. The ends are solid accent squares, the days between a light accent band.
+- **Hint**: "Pick the first day." or "Pick the last day.", under the months, announced when it changes.
+- **Aside**: An optional column beside the months, for DatePresets.

package/public/docs/components/description-list.md

@@ -13,6 +13,8 @@
 import { DescriptionList } from 'src/components/molecules/description-list/DescriptionList'
 ```
 
+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 |

package/public/docs/components/dialog.md

@@ -13,6 +13,8 @@
 import { Dialog, DialogClose, DialogContent, DialogFooter, DialogTrigger } from 'src/components/organisms/dialog/Dialog'
 ```
 
+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 |

package/public/docs/components/divider.md

@@ -13,6 +13,8 @@
 import { Divider } from 'src/components/atoms/divider/Divider'
 ```
 
+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 |

package/public/docs/components/dropdown-menu.md

@@ -13,6 +13,8 @@
 import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from 'src/components/molecules/dropdown-menu/DropdownMenu'
 ```
 
+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 |

package/public/docs/components/empty-state.md

@@ -13,6 +13,8 @@
 import { EmptyState } from 'src/components/molecules/empty-state/EmptyState'
 ```
 
+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 |

package/public/docs/components/footer.md

@@ -13,6 +13,8 @@
 import { Footer } from 'src/components/organisms/footer/Footer'
 ```
 
+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 |

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

@@ -4,6 +4,7 @@
 
 - **Best for:** The label, help and error for an Input, Textarea, Select, MultiSelect or QuantityStepper.
 - **Not for:** Search or RatingInput, which name themselves. Switch, Checkbox and Radio take an id and a label with htmlFor instead.
+- **Also on this page:** `ErrorSummary`
 - Molecule. Source: `src/components/molecules/form-field/FormField.tsx`
 - Rendered docs page: `/components/form-field`
 
@@ -14,6 +15,8 @@ import { FormField } from 'src/components/molecules/form-field/FormField'
 import { ErrorSummary } from 'src/components/molecules/form-field/ErrorSummary'
 ```
 
+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 |
@@ -22,7 +25,7 @@ import { ErrorSummary } from 'src/components/molecules/form-field/ErrorSummary'
 | `help` | `string` |  | Instruction text, read out before any error. |
 | `error` | `string` |  | Sets invalid on the control and adds the error line. |
 | `required` | `boolean` | `false` | Adds the asterisk (hidden from screen readers) and the built-in required attribute on the control. That attribute is what assistive technology actually announces. |
-| `children` | `ReactElement` |  | Exactly one control: Input, Textarea, Select or QuantityStepper. A label set on a Select or QuantityStepper child is replaced by the FormField label. |
+| `children` | `ReactElement` |  | Exactly one control: Input, Textarea, Select or QuantityStepper. A label set on a Select or QuantityStepper child is replaced by the FormField label. An id you give the control is kept (point an ErrorSummary entry at it); without one, FormField makes one up. |
 | `className` | `string` |  | Extra CSS classes, merged with the outer element's own. When two Tailwind classes clash, the later one wins. |
 | `ref` | `Ref<HTMLDivElement>` |  | Passed through to the outer element. |
 | `errors (ErrorSummary)` | `{ fieldId: string; message: string }[]` |  | What stopped the form from submitting, in the order of the fields. Each entry links to its field and moves focus there. An empty list shows nothing. |

package/public/docs/components/icon-button.md

@@ -13,6 +13,8 @@
 import { IconButton } from 'src/components/atoms/icon-button/IconButton'
 ```
 
+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 |

package/public/docs/components/input.md

@@ -13,6 +13,8 @@
 import { Input, inputVariants } from 'src/components/atoms/input/Input'
 ```
 
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
 ## Requires
 
 - A <FormField> around it. On its own the control has no label. FormField adds the label, the help text and the error, and connects their ids.

package/public/docs/components/kanban-board.md

@@ -13,6 +13,8 @@
 import { KanbanBoard, applyKanbanMove, groupKanbanItems, kanbanDragOver, kanbanDrop, kanbanMessages, kanbanPosition } from 'src/components/organisms/kanban-board/KanbanBoard'
 ```
 
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
 ## Requires
 
 - A parent that holds items in state and applies each onMove (applyKanbanMove does the update).

package/public/docs/components/kbd.md

@@ -13,6 +13,8 @@
 import { Kbd } from 'src/components/atoms/kbd/Kbd'
 ```
 
+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 |

package/public/docs/components/link.md

@@ -13,6 +13,8 @@
 import { Link, linkVariants } from 'src/components/atoms/link/Link'
 ```
 
+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 |

package/public/docs/components/list-item.md

@@ -4,6 +4,7 @@
 
 - **Best for:** A row people scan in a List: media, a title, meta and one or two actions.
 - **Not for:** Data in a table that people compare across columns: use DataTable.
+- **Also on this page:** `List`
 - Molecule. Source: `src/components/molecules/list-item/ListItem.tsx`
 - Rendered docs page: `/components/list-item`
 
@@ -13,6 +14,8 @@
 import { List, ListItem } from 'src/components/molecules/list-item/ListItem'
 ```
 
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
 ## Requires
 
 - A <List> around the rows (a ul with role="list"), or as="div" on a row that stands alone.

package/public/docs/components/loading-animation.md

@@ -13,6 +13,8 @@
 import { LoadingAnimation } from 'src/components/atoms/loading-animation/LoadingAnimation'
 ```
 
+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 |

package/public/docs/components/multi-select.md

@@ -13,6 +13,8 @@
 import { MultiSelect } from 'src/components/molecules/multi-select/MultiSelect'
 ```
 
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
 ## Requires
 
 - A <FormField> around it. FormField supplies the visible label, the help and the error, and replaces the label prop with its own.

package/public/docs/components/navbar.md

@@ -13,6 +13,8 @@
 import { Navbar } from 'src/components/organisms/navbar/Navbar'
 ```
 
+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 |

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

@@ -13,6 +13,8 @@
 import { NewsletterForm } from 'src/components/organisms/newsletter-form/NewsletterForm'
 ```
 
+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 |

package/public/docs/components/page-header.md

@@ -13,6 +13,8 @@
 import { PageHeader } from 'src/components/molecules/page-header/PageHeader'
 ```
 
+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 |

package/public/docs/components/pagination.md

@@ -13,6 +13,8 @@
 import { Pagination, paginationRange } from 'src/components/molecules/pagination/Pagination'
 ```
 
+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 |

package/public/docs/components/product-card.md

@@ -4,6 +4,7 @@
 
 - **Best for:** One product in a shop grid, where the whole card opens it and Add to cart sits on it.
 - **Not for:** A general content panel: use Card.
+- **Also on this page:** `ProductGrid`
 - Organism. Source: `src/components/organisms/product-card/ProductCard.tsx`
 - Rendered docs page: `/components/product-card`
 
@@ -13,6 +14,8 @@
 import { ProductCard, ProductGrid } from 'src/components/organisms/product-card/ProductCard'
 ```
 
+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 |

package/public/docs/components/progress.md

@@ -13,6 +13,8 @@
 import { Progress } from 'src/components/atoms/progress/Progress'
 ```
 
+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 |
@@ -21,7 +23,7 @@ import { Progress } from 'src/components/atoms/progress/Progress'
 | `value` | `number \| null` |  | null means indeterminate. The value is clamped to [0, max], so an out-of-range value shows as complete instead of overflowing the track. |
 | `max` | `number` | `100` | The value at which the bar is complete. |
 | `showValue` | `boolean` | `false` | Shows the percentage (or "In progress") as a readout. |
-| `tone` | `'signal' \| 'ok' \| 'warning' \| 'hostile'` | `'signal'` | The fill colour. signal paints accent.signal.fill to match Slider. On the track in light theme that’s a 2.15:1 contrast ratio, below the 3:1 a bar needs when it’s the only sign of progress. So set showValue there. |
+| `tone` | `'signal' \| 'ok' \| 'warning' \| 'hostile'` | `'signal'` | The fill colour. signal paints accent.signal.indicator to match Slider. On the track in light theme that’s a 2.15:1 contrast ratio, below the 3:1 a bar needs when it’s the only sign of progress. So set showValue there. |
 | `className` | `string` |  | Merged with the outer wrapper’s classes. Later Tailwind utilities (Tailwind is the CSS framework the system is styled with) win. |
 | `ref` | `Ref<HTMLDivElement>` |  | Passed through to the Radix Progress root, which is the bar itself. Radix is the library of accessible building blocks this component sits on. |
 | `...rest` | `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` |  | Every native div prop except children, spread onto the outer wrapper, so a molecule can attach a data-testid there. children is typed away because this component draws its own label row and track, and a children prop would be thrown away without any warning. |

package/public/docs/components/prompt-input.md

@@ -13,6 +13,8 @@
 import { PromptInput } from 'src/components/molecules/prompt-input/PromptInput'
 ```
 
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
 ## Requires
 
 - A parent that keeps the draft in state and clears it in onSubmit.

package/public/docs/components/quantity-stepper.md

@@ -13,6 +13,8 @@
 import { QuantityStepper, clampQuantity, gridMax } from 'src/components/molecules/quantity-stepper/QuantityStepper'
 ```
 
+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 |

package/public/docs/components/radio.md

@@ -13,6 +13,8 @@
 import { Radio, RadioGroup } from 'src/components/atoms/radio/Radio'
 ```
 
+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 |
@@ -123,7 +125,7 @@ const SPEEDS = ['standard', 'priority', 'overnight'] as const
 
 ## Do
 
-- Name the group with aria-label or a FormField legend.
+- Name the group: in a form, a fieldset legend that the RadioGroup points at with aria-labelledby; elsewhere, aria-label.
 - Offer a default when one option really is the norm.
 - Keep the set short. Past about seven options, use a Select.
 
@@ -133,6 +135,41 @@ const SPEEDS = ['standard', 'priority', 'overnight'] as const
 - Don't put a radio outside a RadioGroup. Both the roving focus and the value come from the group.
 - Don't make choosing an option perform the action. Put a button after the group.
 
+## Common mistakes
+
+Wrong:
+
+```tsx
+<FormField label="Difficulty" error={error}>
+  <RadioGroup>
+    <Radio value="easy" />
+  </RadioGroup>
+</FormField>
+```
+
+Right:
+
+```tsx
+<fieldset aria-describedby={error ? 'difficulty-error' : undefined}>
+  <legend id="difficulty-label" className="font-mono text-[11px] font-semibold uppercase tracking-[0.12em] text-[var(--color-text-primary)]">
+    Difficulty
+  </legend>
+  <RadioGroup aria-labelledby="difficulty-label" aria-required="true" value={value} onValueChange={setValue} className="mt-2">
+    {['easy', 'moderate', 'hard'].map(option => (
+      <div key={option} className="flex items-center gap-2">
+        <Radio id={`difficulty-${option}`} value={option} invalid={Boolean(error)} />
+        <label htmlFor={`difficulty-${option}`} className="font-body text-sm">{option}</label>
+      </div>
+    ))}
+  </RadioGroup>
+  {error ? (
+    <p id="difficulty-error" className="mt-1.5 font-body text-sm text-[var(--color-accent-hostile-text)]">{error}</p>
+  ) : null}
+</fieldset>
+```
+
+FormField clones one control and gives it an id and a label; a group of radios has neither. The fieldset and legend name the group, the label styles match FormField, and the error is linked through aria-describedby. Give ErrorSummary the id of the first Radio so its link lands in the group.
+
 ## Anatomy
 
 - **RadioGroup**: Has role=radiogroup, which tells assistive tech (screen readers and similar tools) this is a set of radios. It handles roving focus, where only one option is reachable by Tab and the arrows move between the rest, and it owns the value.

package/public/docs/components/rating.md

@@ -13,6 +13,8 @@
 import { Rating, RatingInput } from 'src/components/molecules/rating/Rating'
 ```
 
+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 |

package/public/docs/components/score-ring.md

@@ -13,6 +13,8 @@
 import { ScoreRing, scoreBand } from 'src/components/atoms/score-ring/ScoreRing'
 ```
 
+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 |

package/public/docs/components/search.md

@@ -13,6 +13,8 @@
 import { Search } from 'src/components/molecules/search/Search'
 ```
 
+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 |

package/public/docs/components/section-heading.md

@@ -13,6 +13,8 @@
 import { SectionHeading } from 'src/components/molecules/section-heading/SectionHeading'
 ```
 
+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 |

package/public/docs/components/segmented-control.md

@@ -13,6 +13,8 @@
 import { SegmentedControl } from 'src/components/molecules/segmented-control/SegmentedControl'
 ```
 
+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 |

package/public/docs/components/select.md

@@ -13,6 +13,8 @@
 import { Select } from 'src/components/atoms/select/Select'
 ```
 
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
 ## Requires
 
 - A <FormField> around it. On its own the control has no label. FormField supplies the label, the help text and the error, and connects their ids so assistive tech (screen readers and similar tools) reads them together.
@@ -216,7 +218,7 @@ const TERRAIN_OPTIONS = [
 - **Trigger**: Uses exactly the same frame and styling as Input, so a select and a text field line up in a form.
 - **Value**: Shows the placeholder until something’s chosen.
 - **Content**: Portalled and positioned by Radix, the library of accessible building blocks this sits on. It slides down out of the trigger as it opens (M7; Radix’s Select closes at once, with no exit animation). It’s the one atom that carries the corner crosshair, because it’s a surface framing other content, and that’s what the crosshair marks. It’s also the shape that can’t be cut, since clip-path would clip the crosshair’s arms and the last row’s selection fill along with them.
-- **Item**: Highlighted rows use signal.fill with signal.ink. That’s the fill-selection grammar, the system’s rule for how a selection looks.
+- **Item**: Highlighted rows use accent.signal.indicator with accent.signal.indicator-ink. That’s the fill-selection grammar, the system’s rule for how a selection looks.
 - **ItemIndicator**: A tick on the selected row, so selection isn’t shown by the highlight alone.
 - **Item icon**: Optional. Sits before the label and is aria-hidden, an ARIA (Accessible Rich Internet Applications) attribute that hides it from assistive tech. It follows the row colour, so it turns ink on the highlight. It isn’t shown in the trigger.
 - **Group label**: Used with groups: a mono (monospaced font) heading over its rows that names the group for screen readers. It can’t be selected. A hairline separates the groups.

package/public/docs/components/sheet.md

@@ -13,6 +13,8 @@
 import { Sheet, SheetClose, SheetContent, SheetTrigger } from 'src/components/organisms/sheet/Sheet'
 ```
 
+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 |

package/public/docs/components/sidebar.md

@@ -13,6 +13,8 @@
 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 |

package/public/docs/components/skeleton.md

@@ -13,6 +13,8 @@
 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 |

package/public/docs/components/slider.md

@@ -13,6 +13,8 @@
 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 |
@@ -108,5 +110,5 @@ function SingleValueLive() {
 
 - **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.
+- **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

@@ -13,6 +13,8 @@
 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 |

package/public/docs/components/spinner.md

@@ -13,6 +13,8 @@
 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 |
@@ -32,7 +34,7 @@ Exported beside the component, from the same file. Import a type with `import ty
 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)]',
+  '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' },
@@ -91,6 +93,6 @@ Not focusable. No keyboard behaviour of its own.
 ## 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.
+- **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.

package/public/docs/components/stat.md

@@ -13,6 +13,8 @@
 import { Stat } from 'src/components/molecules/stat/Stat'
 ```
 
+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 |