division-ds 0.3.0 → 0.4.0

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

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 
@@ -29,6 +29,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | `onSelect (Item)` | `(event: Event) => void` |  | Called when the item is chosen. |
 | `disabled (Item)` | `boolean` | `false` | The item can't be chosen, and typing letters (typeahead) skips it. |
 | `tone (Item)` | `'default' \| 'hostile'` | `'default'` | Use hostile for a destructive action: hostile-coloured text at rest, the hostile fill with ink text when highlighted. |
+| `asChild (Item)` | `boolean` | `false` | Makes the one child (a link) the item, for a menu of links. icon and shortcut are ignored then; put the content inside the link. |
 | `icon (Item)` | `ReactNode` |  | A small icon before the text, hidden from screen readers (aria-hidden). |
 | `shortcut (Item)` | `string` |  | Shown on the right and passed to screen readers as aria-keyshortcuts. It only displays the key: the menu never makes the key work. |
 | `checked (Checkbox item)` | `boolean` |  | Whether the tick shows. |

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

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

package/public/docs/components/footer.md

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

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

@@ -15,7 +15,7 @@ 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 
@@ -25,7 +25,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | `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. An id you give the control is kept (point an ErrorSummary entry at it); without one, FormField makes one up. |
+| `children` | `ReactElement` |  | Exactly one control: Input, Textarea, Select, MultiSelect, QuantityStepper, DatePicker, DateRangePicker or TimeField. The controls that name themselves (all but Input and Textarea) take the FormField label, so leave their own label out. 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,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

package/public/docs/components/input.md

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Requires
 

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

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Requires
 

package/public/docs/components/kbd.md

@@ -13,13 +13,15 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` |  | The key's name, for example "Esc" or "⌘". |
+| `size` | `'md' \| 'sm'` | `'md'` | md is 24px tall, for a cap beside text or in a menu row. sm is 20px tall, for a cap inside a 32px control: a small Button or a search field. |
+| `cut` | `boolean` | `false` | Cuts the bottom-right corner (5px at sm, 8px at md) so the cap nests in the corner of a bevelled control, its diagonal parallel to the control's. Only for a cap inside such a control. |
 | `className` | `string` |  | Merged with the component's classes. When Tailwind utility classes clash, the later one wins. |
 | `ref` | `Ref<HTMLElement>` |  | Passed through to the kbd element. |
 | `...rest` | `HTMLAttributes<HTMLElement>` |  | Every native attribute, passed onto the kbd element, such as a title, or an aria-label for a symbol key (aria-label is the name screen readers read out). |
@@ -49,6 +51,24 @@ Each is compiled and rendered on the docs page. Imports are omitted; see above.
 <span className="text-sm text-[var(--color-text-secondary)]">Open the command palette</span>
 ```
 
+### Sizes
+
+```tsx
+<Kbd>Esc</Kbd>
+<Kbd size="sm">Esc</Kbd>
+```
+
+### Small and cut, inside a small button
+
+```tsx
+<Button variant="secondary" size="sm" iconStart={<Search />} aria-keyshortcuts="Control+K">
+  Search
+  <Kbd aria-hidden="true" size="sm" cut className="-mr-1.5 ml-2 -translate-y-[var(--cap-shift,0px)]">
+    Ctrl K
+  </Kbd>
+</Button>
+```
+
 ## Keyboard
 
 Not focusable. No keyboard behaviour of its own.
@@ -58,15 +78,16 @@ Not focusable. No keyboard behaviour of its own.
 - Use one Kbd per physical key, and put them side by side for a chord (keys pressed together).
 - Put it next to the action it triggers, in the same row or the same tooltip.
 - Write the key name the way the keyboard prints it.
+- Inside a 32px control, use size="sm"; inside a bevelled one (a Button), add cut and place the cap at the end, near the cut corner.
 
 ## Don't
 
-- Don’t bevel it. Cut corners are for surfaces and controls, not 24px chrome.
+- Don’t set cut on a cap that stands alone in text or a menu row. The cut answers a bevelled corner around it; without one it reads as a button.
 - Don’t put a whole chord inside one Kbd ("Ctrl+K" in a single cap).
 - Don’t use it for anything that isn’t a key. It’s not a badge.
 
 ## Anatomy
 
 - **kbd element**: The HTML element made for keys. Screen readers announce it as keyboard input.
-- **Hairline border**: A one-pixel border in border.hairline-strong, with no bevel (cut corners).
-- **Mono legend**: JetBrains Mono, uppercase, 11px (pixels): the tertiary type role.
+- **Hairline border**: A one-pixel border in border.hairline-strong. Square corners by default; with cut, the bottom-right corner is cut at 45 degrees and the border follows the diagonal.
+- **Mono legend**: JetBrains Mono, uppercase, 11px (pixels): the tertiary type role, at both sizes.

package/public/docs/components/link.md

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

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

@@ -14,7 +14,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Requires
 

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

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

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

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Requires
 
@@ -23,7 +23,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `label` | `string` |  | Required. The name screen readers give the text field and the list. FormField replaces it with its own label. |
+| `label` | `string` |  | The name screen readers give the text field and the list. Leave it out inside a FormField, which sets it from its own label. Outside one it is required, and `division-ds check` flags a missing one. |
 | `options` | `SelectOption[]` |  | { value, label, disabled? }, the same rows Select takes. |
 | `value` | `string[]` |  | The current selection when the page keeps track of it (controlled), as option values in the order they were chosen. |
 | `defaultValue` | `string[]` |  | The starting selection when the component keeps track itself (uncontrolled). |
@@ -60,7 +60,7 @@ const LOADOUT = [
 
 <div className="w-full max-w-md">
   <FormField label="Loadout">
-    <MultiSelect label="Loadout" options={LOADOUT} placeholder="Choose your kit…" />
+    <MultiSelect options={LOADOUT} placeholder="Choose your kit…" />
   </FormField>
 </div>
 ```
@@ -84,7 +84,7 @@ function ControlledExample() {
   return (
     <div className="flex flex-col gap-2 w-full max-w-md">
       <FormField label="Loadout" help="Remove a tag and watch the others close the gap.">
-        <MultiSelect label="Loadout" options={LOADOUT} value={kit} onValueChange={setKit} />
+        <MultiSelect options={LOADOUT} value={kit} onValueChange={setKit} />
       </FormField>
       <span className="font-mono text-xs text-[var(--color-text-secondary)]">value: [{kit.join(', ')}]</span>
     </div>
@@ -110,7 +110,7 @@ const LOADOUT = [
 
 <div className="w-full max-w-md">
   <FormField label="Loadout" error="Pick eye protection.">
-    <MultiSelect label="Loadout" options={LOADOUT} defaultValue={['mags']} />
+    <MultiSelect options={LOADOUT} defaultValue={['mags']} />
   </FormField>
 </div>
 ```

package/public/docs/components/navbar.md

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 
@@ -21,11 +21,12 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 |---|---|---|---|
 | `label` | `string` |  | Required. The name screen readers give the navigation region. |
 | `brand` | `ReactNode` |  | Required. The wordmark or logo, usually a link to the home page. |
-| `items` | `NavbarItem[]` |  | Required. Each item has label, href and current. |
+| `items` | `NavbarItem[]` |  | Required. A link is { label, href, current }. A menu among the links is { label, menu, current }: menu lists { label, href, description } entries, opened from a dropdown on a wide bar and listed as a labelled group in the menu sheet on a narrow one. |
 | `actions` | `ReactNode` |  | Controls on the right: icon buttons, a cart link, an account menu. Keep them small, because they stay visible at every width. |
 | `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | Pass your router's link component here. Map href to its own prop, and pass className, aria-current and onClick through. |
 | `menuLabel` | `string` | `'Menu'` | The menu button's name for screen readers, and the sheet's title. |
-| `menuFooter` | `ReactNode` |  | Shown in the menu sheet under the links. Use it for an action that doesn't fit in actions on a narrow bar. Hide the matching copy in actions below the breakpoint by wrapping it in an element with the classes hidden @2xl:flex. |
+| `menuFooter` | `ReactNode` |  | Shown in the menu sheet under the links. Use it for an action that doesn't fit in actions on a narrow bar. Hide the matching copy in actions below the breakpoint by wrapping it in an element with the classes hidden @2xl:flex (hidden @4xl:flex when collapseBelow is '4xl'). |
+| `collapseBelow` | `'2xl' \| '4xl'` | `'2xl'` | The bar's own width below which the links fold into the menu sheet: 2xl is 42rem, 4xl is 56rem. Pick the one at which the brand, every link and the actions still fit on one row with room to spare. |
 | `className` | `string` |  | Added to the root classes. Where two Tailwind utility classes clash, the later one wins. |
 | `ref` | `Ref<HTMLElement>` |  | The header element. |
 
@@ -34,7 +35,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 Exported beside the component, from the same file. Import a type with `import type { ... }`.
 
 ```ts
-export type NavbarItem = { label: string; href: string; current?: boolean }
+export type NavbarItem = NavbarLink | NavbarMenu
 ```
 
 ## Examples
@@ -77,6 +78,56 @@ const ACTIONS = (
 <Navbar label="Store navigation" brand={BRAND} items={ITEMS} actions={ACTIONS} />
 ```
 
+### A menu among the links
+
+```tsx
+const ITEMS = [
+  { label: 'Replicas', href: '#replicas' },
+  { label: 'Optics', href: '#optics', current: true },
+  { label: 'Parts', href: '#parts' },
+  { label: 'Care', href: '#care' },
+  { label: 'Field notes', href: '#field-notes' },
+]
+
+const BRAND = (
+  <a
+    href="#home"
+    className="inline-flex items-center min-h-10 font-display font-bold uppercase tracking-[0.14em] text-[var(--color-text-primary)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-focus-ring)]"
+  >
+    Hexline
+  </a>
+)
+
+const ACTIONS = (
+  <>
+    <IconButton label="Search" variant="ghost">
+      <Search aria-hidden="true" className="w-5 h-5" />
+    </IconButton>
+    <IconButton label="Cart, 2 items" variant="ghost" asChild>
+      <a href="#cart">
+        <ShoppingBag aria-hidden="true" className="w-5 h-5" />
+      </a>
+    </IconButton>
+  </>
+)
+
+<Navbar
+  label="Store navigation with a menu"
+  brand={BRAND}
+  items={[
+    ...ITEMS.slice(0, 3),
+    {
+      label: 'Guides',
+      menu: [
+        { label: 'Sizing', href: '#sizing', description: 'Fit charts for every replica.' },
+        { label: 'Returns', href: '#returns', description: 'Thirty days, no questions.' },
+      ],
+    },
+  ]}
+  actions={ACTIONS}
+/>
+```
+
 ### A narrow container
 
 ```tsx

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

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

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

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

package/public/docs/components/pagination.md

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

package/public/docs/components/panel.md

@@ -0,0 +1,139 @@
+# Panel
+
+> The system's framed surface: a thin border around a fill, with the crosshair corner marks and the cut corner as options. Card is a Panel with a title, body and footer; Panel is the frame alone, for a feature tile, a demo frame or a tile that is one link.
+
+- **Best for:** Framing content that has no title, body and footer structure: a feature tile, a demo area, or a tile that is one link.
+- **Not for:** Content with a title, a body and actions: use Card. A page-width layout wrapper: use a plain div with max-w-*.
+- Atom. Source: `src/components/atoms/panel/Panel.tsx`
+- Rendered docs page: `/components/panel`
+
+## Import
+
+```tsx
+import { Panel } from 'src/components/atoms/panel/Panel'
+```
+
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Inner spacing: 0, 12px, 20px or 32px. |
+| `tone` | `'base' \| 'raised' \| 'signal'` | `'raised'` | base sits flush with the page, raised is one step up, signal is the brand wash for the one panel in a group that leads. |
+| `crosshair` | `boolean` | `false` | Draws the crosshair marks at the corners. |
+| `cut` | `boolean` | `false` | Cuts the bottom-right corner, with the border following the cut. |
+| `interactive` | `boolean` | `false` | Hover and focus states for a panel that is one link or button. Use it with asChild; it adds no behaviour of its own. |
+| `asChild` | `boolean` | `false` | Renders the single child element (an a, a router Link, a button) with the panel classes merged onto it, instead of a div. |
+| `className` | `string` |  | Merged with the component's classes. Use it for layout (a grid span, flex, gap), not for the fill or the border. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the div, or to the child with asChild. |
+| `...rest` | `HTMLAttributes<HTMLDivElement>` |  | Every native attribute, passed onto the element. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Tones
+
+```tsx
+<Panel tone="base">
+  <p className="font-display font-semibold">Base</p>
+  <p className="text-sm text-[var(--color-text-secondary)]">Flush with the page.</p>
+</Panel>
+<Panel tone="raised">
+  <p className="font-display font-semibold">Raised</p>
+  <p className="text-sm text-[var(--color-text-secondary)]">One step up.</p>
+</Panel>
+<Panel tone="signal">
+  <p className="font-display font-semibold">Signal</p>
+  <p className="text-sm text-[var(--color-text-secondary)]">The one that leads.</p>
+</Panel>
+```
+
+### Padding
+
+```tsx
+<Panel padding="none">none</Panel>
+<Panel padding="sm">sm</Panel>
+<Panel padding="md">md</Panel>
+<Panel padding="lg">lg</Panel>
+```
+
+### Crosshair and cut corner
+
+```tsx
+<Panel crosshair>Crosshair</Panel>
+<Panel cut>Cut corner</Panel>
+<Panel crosshair cut tone="signal">Both</Panel>
+```
+
+### Interactive, as a router link
+
+```tsx
+<Panel interactive cut padding="lg" asChild>
+  <RouterLink to="/components/card" className="flex flex-col gap-3">
+    <span className="font-display text-lg font-semibold">Card</span>
+    <span className="text-sm text-[var(--color-text-secondary)]">A panel with a title, a body and a footer.</span>
+    <span className="inline-flex items-center gap-2 font-semibold text-[var(--color-accent-signal-text)]">
+      Open <ArrowRight aria-hidden="true" className="size-4" />
+    </span>
+  </RouterLink>
+</Panel>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | With interactive and asChild on a link or button: moves focus to the panel and shows the focus ring. |
+| `Enter` | Follows the link, or presses the button, that the panel was rendered as. |
+
+## Do
+
+- Use signal on at most one panel in a group: the one that leads.
+- Give a clickable panel interactive and asChild, with a real link or button as the child.
+- Leave 8px around a panel with the crosshair, so a parent that clips does not cut the marks off.
+
+## Don't
+
+- Don’t put a button near the bottom-right corner of a cut panel; the cut can clip it.
+- Don’t set a fill or border colour with a class. Choose a tone.
+- Don’t put a second link or button inside an interactive panel.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<Panel className="bg-[var(--color-surface-base)] border-[var(--color-border-selection)]">
+```
+
+Right:
+
+```tsx
+<Panel tone="base">
+```
+
+The panel's fill and border come from its tone, through CSS that sits outside Tailwind's layers, so a bg- or border- class never wins. Pick the tone.
+
+Wrong:
+
+```tsx
+<Panel interactive onClick={open}>Replicas</Panel>
+```
+
+Right:
+
+```tsx
+<Panel interactive asChild><Link to="/replicas">Replicas</Link></Panel>
+```
+
+A div with a click handler cannot be reached by keyboard and is not announced as a link. interactive styles a panel that already is a link or a button; asChild makes it one.
+
+## Anatomy
+
+- **Frame**: A div (or, with asChild, your element) with the .panel class: a one-pixel border and a fill, both set by the tone.
+- **Tone**: base: surface.base fill, border.hairline border. raised: surface.raised fill, border.hairline border. signal: accent.signal.wash fill, border.selection border. All tokens, so each one is right in both themes.
+- **Crosshair**: Optional. Short marks drawn 5px outside each corner, in text.muted. The parent must not clip its overflow.
+- **Cut corner**: Optional. The bottom-right corner cut at 45 degrees (14px), with the border drawn along the cut, so the outline does not break at that corner. With the crosshair on, the bottom-right marks fall inside the cut and are not drawn.
+- **Interactive state**: Optional. On hover and on keyboard focus the border, diagonal included, turns accent.signal.indicator; keyboard focus also draws the focus ring 2px outside. Nothing moves.

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

@@ -14,7 +14,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

package/public/docs/components/progress.md

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 
@@ -23,7 +23,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | `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.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. |
+| `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.80: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,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Requires
 

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

@@ -13,13 +13,13 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `label` | `string` |  | Required. Names the field and both buttons ("Decrease Speed loader quantity"). |
+| `label` | `string` |  | Names the field and both buttons ("Decrease Speed loader quantity"). Leave it out inside a FormField, which sets it from its own label. Outside one it is required, and `division-ds check` flags a missing one. |
 | `value` | `number` |  | Controlled value (your page holds it). |
 | `defaultValue` | `number` | `min` | Starting value when the component holds the value itself (uncontrolled). |
 | `onValueChange` | `(value: number) => void` |  | Fires with the final value, pulled inside the limits: after a button click, an arrow key, Home/End, or when typing is finished by leaving the field or pressing Enter. |

package/public/docs/components/radio.md

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

package/public/docs/components/rating.md

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

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

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

package/public/docs/components/search.md

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

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

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props
 

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

@@ -13,7 +13,7 @@
 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.
+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. An install has no index barrels: import each component from its own file, never from `components/molecules`.
 
 ## Props