division-ds 0.2.0 → 0.2.1

package/AGENTS.md

@@ -51,7 +51,7 @@ installs these rules into that project's `AGENTS.md`, `GEMINI.md` and Cursor rul
 `.claude/skills/` (Claude Code).
 
 An agent that supports MCP can have the docs and the same checks as tools instead:
-`claude mcp add division-ds -- npx -y division-ds mcp` (`list_components`, `get_component`,
+`claude mcp add division-ds -- npx -y division-ds@0.2.1 mcp` (`list_components`, `get_component`,
 `search`, `get_tokens`, `validate_code`, `check_contrast`, `get_add_command`,
 `get_review_checklist`).
 
@@ -116,7 +116,9 @@ The shell paints the page background (`surface.base`) and supplies the gutter; a
 own `max-w-*` and vertical spacing, and no page background. A form or an overlay is the
 exception: it paints `surface.base` on itself, so its field colours never depend on what is
 behind it. In a project that uses the components, your own root does this
-(step 4 of `install.md`).
+(step 4 of `install.md`). Toggle it with `setTheme()` from `src/lib/theme.ts`.
+
+**App navigation.** A few views: `Navbar` (`current: true` on the open one). Many: `Sidebar`.
 
 **Type.** Three families, as utilities: `font-display` (headings, figures), `font-body` (the
 default, set by the shell), `font-mono` (labels, code, tabular numbers). A page title is
@@ -151,6 +153,9 @@ bare and name it through its own `label` prop ("Role for Ilse Varga"). `Switch`,
 renders `ErrorSummary` at the top and focuses it; `useFieldErrors` holds the state (signature in
 `public/docs/helpers.md`).
 
+A `RadioGroup` in a form sits in a `<fieldset>` whose `<legend>` names it (code on the Radio
+page). A date is `<Input type="date">` in a `FormField`.
+
 **Buttons.** Two or more buttons side by side need a parent with a gap
 (`flex flex-wrap gap-3`); `DialogFooter` and `CardFooter` already are one. A `Button` is
 `type="button"` unless you say `type="submit"`. A busy button takes `loading`, not `disabled`.
@@ -188,7 +193,8 @@ Tailwind), and nothing moves on its own: no autoplay.
 
 **Assistant copy.** A button names the action ("Summarize"), never "AI". Say "response", not
 "answer". No "please" or "!" in assistant labels. The interface says "Assistant"; only its own
-messages say "I".
+messages say "I". Response feedback: `ResponseFeedback` in `actions`.
+A value the assistant filled is `aiValue` on that `Input` or `Textarea` only; leaving it accepts it.
 <!-- rules:end -->
 
 ## Changing the system itself

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "division-ds",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Checks a project that uses Division DS components (raw colours, invented tokens, touching buttons, unknown props), and serves the docs and the same checks to agents over MCP.",
   "license": "MIT",
   "author": "Victor Ilioiu",

package/public/docs/components/accordion.md

@@ -13,6 +13,8 @@
 import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'src/components/molecules/accordion/Accordion'
 ```
 
+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/ai-label.md

@@ -13,6 +13,8 @@
 import { AiLabel } from 'src/components/atoms/ai-label/AiLabel'
 ```
 
+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/alert-dialog.md

@@ -13,6 +13,8 @@
 import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogFooter, AlertDialogTrigger } from 'src/components/organisms/alert-dialog/AlertDialog'
 ```
 
+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/alert.md

@@ -13,6 +13,8 @@
 import { Alert } from 'src/components/molecules/alert/Alert'
 ```
 
+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/approval-request.md

@@ -13,6 +13,8 @@
 import { ApprovalRequest } from 'src/components/molecules/approval-request/ApprovalRequest'
 ```
 
+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 the state and sets it to approved or rejected in onApprove and onReject.

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

@@ -13,6 +13,8 @@
 import { AuthForm } from 'src/components/organisms/auth-form/AuthForm'
 ```
 
+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/avatar-group.md

@@ -13,6 +13,8 @@
 import { AvatarGroup } from 'src/components/molecules/avatar-group/AvatarGroup'
 ```
 
+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
 
 - With overflowTooltip, the root <TooltipProvider>. AppShell and the demo layout each include one.

package/public/docs/components/avatar.md

@@ -13,6 +13,8 @@
 import { Avatar, avatarVariants, initialsFrom } from 'src/components/atoms/avatar/Avatar'
 ```
 
+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/badge.md

@@ -13,6 +13,8 @@
 import { Badge, badgeVariants } from 'src/components/atoms/badge/Badge'
 ```
 
+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/breadcrumbs.md

@@ -13,6 +13,8 @@
 import { Breadcrumbs, collapseCrumbs } from 'src/components/molecules/breadcrumbs/Breadcrumbs'
 ```
 
+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/button.md

@@ -13,6 +13,8 @@
 import { Button, buttonVariants } from 'src/components/atoms/button/Button'
 ```
 
+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/card.md

@@ -13,6 +13,8 @@
 import { Card, CardActions, CardBody, CardDescription, CardFooter, CardHeader, CardMedia, CardTitle, cardLinkClass } from 'src/components/molecules/card/Card'
 ```
 
+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/carousel.md

@@ -13,6 +13,8 @@
 import { Carousel } from 'src/components/organisms/carousel/Carousel'
 ```
 
+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/cart.md

@@ -13,6 +13,8 @@
 import { Cart } from 'src/components/organisms/cart/Cart'
 ```
 
+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/chart-panel.md

@@ -13,6 +13,8 @@
 import { ChartPanel } from 'src/components/organisms/chart-panel/ChartPanel'
 ```
 
+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/chat-message.md

@@ -4,6 +4,7 @@
 
 - **Best for:** Each turn inside a ChatThread.
 - **Not for:** Comments or an activity history between people: use Timeline.
+- **Also on this page:** `ResponseFeedback`
 - Molecule. Source: `src/components/molecules/chat-message/ChatMessage.tsx`
 - Rendered docs page: `/components/chat-message`
 
@@ -14,6 +15,8 @@ import { ChatMessage } from 'src/components/molecules/chat-message/ChatMessage'
 import { ResponseFeedback } from 'src/components/molecules/chat-message/ResponseFeedback'
 ```
 
+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 ChatThread around it. Outside one, a message still shows, but nothing announces it when it finishes.

package/public/docs/components/chat-thread.md

@@ -13,6 +13,8 @@
 import { ChatThread } from 'src/components/organisms/chat-thread/ChatThread'
 ```
 
+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 height, because the thread scrolls and the page doesn't. Use h-[28rem], or flex-1 min-h-0 inside a column.

package/public/docs/components/checkbox.md

@@ -13,6 +13,8 @@
 import { Checkbox } from 'src/components/atoms/checkbox/Checkbox'
 ```
 
+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/checkout-form.md

@@ -13,6 +13,8 @@
 import { CheckoutForm, DELIVERY_OPTIONS } from 'src/components/organisms/checkout-form/CheckoutForm'
 ```
 
+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/command-palette.md

@@ -13,6 +13,8 @@
 import { CommandPalette, filterCommands, groupCommands } from 'src/components/organisms/command-palette/CommandPalette'
 ```
 
+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/data-table.md

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