division-ds 0.3.1 → 0.4.1

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Division DS: instructions for coding agents
 
-A React 19 + Tailwind 4 + Radix design system: 72 components, tokens in three layers, light and
+A React 19 + Tailwind 4 + Radix design system: 75 components, tokens in three layers, light and
 dark themes, WCAG 2.2 AA. This file is the entry point. It is short on purpose; everything it
 points to is generated from the code, so it is current.
 
@@ -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@0.3.1 mcp` (`list_components`, `get_component`,
+`claude mcp add division-ds -- npx -y division-ds@0.4.0 mcp` (`list_components`, `get_component`,
 `search`, `get_tokens`, `validate_code`, `check_contrast`, `get_add_command`,
 `get_review_checklist`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "division-ds",
-  "version": "0.3.1",
+  "version": "0.4.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/chart-panel.md

@@ -59,20 +59,26 @@ Each is compiled and rendered on the docs page. Imports are omitted; see above.
 type Week = { week: string; online: number; store: number }
 
 const WEEKS: Week[] = [
-  { week: 'W1', online: 120, store: 160 },
-  { week: 'W2', online: 131, store: 158 },
-  { week: 'W3', online: 142, store: 163 },
-  { week: 'W4', online: 150, store: 155 },
-  { week: 'W5', online: 171, store: 162 },
-  { week: 'W6', online: 188, store: 159 },
-  { week: 'W7', online: 197, store: 166 },
-  { week: 'W8', online: 214, store: 161 },
+  { week: 'W1', online: 118, store: 150 },
+  { week: 'W2', online: 149, store: 172 },
+  { week: 'W3', online: 168, store: 158 },
+  { week: 'W4', online: 141, store: 131 },
+  { week: 'W5', online: 126, store: 128 },
+  { week: 'W6', online: 174, store: 150 },
+  { week: 'W7', online: 231, store: 141 },
+  { week: 'W8', online: 183, store: 122 },
+  { week: 'W9', online: 139, store: 149 },
+  { week: 'W10', online: 162, store: 185 },
+  { week: 'W11', online: 196, store: 163 },
+  { week: 'W12', online: 170, store: 140 },
 ]
 
 <ChartPanel<Week>
   title="Weekly orders"
-  summary="Online orders rose from 120 to 214 over eight weeks and passed in-store orders in week 5."
+  summary="Online orders peaked three times in twelve weeks, highest at 231 in week 7; in-store orders peaked highest at 185 in week 10."
   kind="line"
+  area
+  curve="smooth"
   data={WEEKS}
   xKey="week"
   xLabel="Week"
@@ -116,17 +122,17 @@ type Day = { day: string; visits: number; orders: number }
 
 const DAYS: Day[] = [
   { day: 'Mon', visits: 1840, orders: 61 },
-  { day: 'Tue', visits: 2210, orders: 74 },
-  { day: 'Wed', visits: 1960, orders: 58 },
-  { day: 'Thu', visits: 2650, orders: 92 },
-  { day: 'Fri', visits: 3120, orders: 118 },
+  { day: 'Tue', visits: 2960, orders: 104 },
+  { day: 'Wed', visits: 2210, orders: 74 },
+  { day: 'Thu', visits: 1720, orders: 55 },
+  { day: 'Fri', visits: 2650, orders: 92 },
   { day: 'Sat', visits: 3890, orders: 141 },
-  { day: 'Sun', visits: 3370, orders: 126 },
+  { day: 'Sun', visits: 3120, orders: 118 },
 ]
 
 <ChartPanel<Day>
   title="Visits this week"
-  summary="Visits climbed from 1,840 on Monday to a Saturday peak of 3,890."
+  summary="Visits peaked on Tuesday at 2,960, fell to a Thursday low of 1,720, then peaked higher on Saturday at 3,890."
   kind="line"
   area
   curve="smooth"
@@ -134,7 +140,7 @@ const DAYS: Day[] = [
   xKey="day"
   xLabel="Day"
   series={[{ key: 'visits', label: 'Visits' }]}
-  headline="19,040"
+  headline="18,390"
   headingLevel={4}
 />
 ```
@@ -145,19 +151,23 @@ const DAYS: Day[] = [
 type Week = { week: string; online: number; store: number }
 
 const WEEKS: Week[] = [
-  { week: 'W1', online: 120, store: 160 },
-  { week: 'W2', online: 131, store: 158 },
-  { week: 'W3', online: 142, store: 163 },
-  { week: 'W4', online: 150, store: 155 },
-  { week: 'W5', online: 171, store: 162 },
-  { week: 'W6', online: 188, store: 159 },
-  { week: 'W7', online: 197, store: 166 },
-  { week: 'W8', online: 214, store: 161 },
+  { week: 'W1', online: 118, store: 150 },
+  { week: 'W2', online: 149, store: 172 },
+  { week: 'W3', online: 168, store: 158 },
+  { week: 'W4', online: 141, store: 131 },
+  { week: 'W5', online: 126, store: 128 },
+  { week: 'W6', online: 174, store: 150 },
+  { week: 'W7', online: 231, store: 141 },
+  { week: 'W8', online: 183, store: 122 },
+  { week: 'W9', online: 139, store: 149 },
+  { week: 'W10', online: 162, store: 185 },
+  { week: 'W11', online: 196, store: 163 },
+  { week: 'W12', online: 170, store: 140 },
 ]
 
 <ChartPanel<Week>
   title="Weekly orders, gridless"
-  summary="Online orders rose from 120 to 214 over eight weeks and passed in-store orders in week 5."
+  summary="Online orders peaked three times in twelve weeks, highest at 231 in week 7; in-store orders peaked highest at 185 in week 10."
   kind="line"
   area
   curve="smooth"
@@ -206,30 +216,34 @@ type Week = { week: string; online: number; store: number }
 type Day = { day: string; visits: number; orders: number }
 
 const WEEKS: Week[] = [
-  { week: 'W1', online: 120, store: 160 },
-  { week: 'W2', online: 131, store: 158 },
-  { week: 'W3', online: 142, store: 163 },
-  { week: 'W4', online: 150, store: 155 },
-  { week: 'W5', online: 171, store: 162 },
-  { week: 'W6', online: 188, store: 159 },
-  { week: 'W7', online: 197, store: 166 },
-  { week: 'W8', online: 214, store: 161 },
+  { week: 'W1', online: 118, store: 150 },
+  { week: 'W2', online: 149, store: 172 },
+  { week: 'W3', online: 168, store: 158 },
+  { week: 'W4', online: 141, store: 131 },
+  { week: 'W5', online: 126, store: 128 },
+  { week: 'W6', online: 174, store: 150 },
+  { week: 'W7', online: 231, store: 141 },
+  { week: 'W8', online: 183, store: 122 },
+  { week: 'W9', online: 139, store: 149 },
+  { week: 'W10', online: 162, store: 185 },
+  { week: 'W11', online: 196, store: 163 },
+  { week: 'W12', online: 170, store: 140 },
 ]
 
 const DAYS: Day[] = [
   { day: 'Mon', visits: 1840, orders: 61 },
-  { day: 'Tue', visits: 2210, orders: 74 },
-  { day: 'Wed', visits: 1960, orders: 58 },
-  { day: 'Thu', visits: 2650, orders: 92 },
-  { day: 'Fri', visits: 3120, orders: 118 },
+  { day: 'Tue', visits: 2960, orders: 104 },
+  { day: 'Wed', visits: 2210, orders: 74 },
+  { day: 'Thu', visits: 1720, orders: 55 },
+  { day: 'Fri', visits: 2650, orders: 92 },
   { day: 'Sat', visits: 3890, orders: 141 },
-  { day: 'Sun', visits: 3370, orders: 126 },
+  { day: 'Sun', visits: 3120, orders: 118 },
 ]
 
 <ChartPanel<Day>
   title="Visits"
-  headline="19,040"
-  summary="Up every day but Wednesday and Sunday."
+  headline="18,390"
+  summary="Two peaks: Tuesday, then a higher Saturday."
   kind="line"
   area
   curve="smooth"
@@ -254,9 +268,10 @@ const DAYS: Day[] = [
 />
 <ChartPanel<Week>
   title="Online orders"
-  headline="214"
-  summary="Eight weeks of growth, from 120 a week."
+  headline="170"
+  summary="Three peaks in twelve weeks; the highest, 231, in week 7."
   kind="line"
+  area
   curve="smooth"
   size="sm"
   data={WEEKS}

package/public/docs/components/code-block.md

@@ -0,0 +1,106 @@
+# CodeBlock
+
+> Code or a command in a panel, with a title bar that names the file or language and a button that copies the text. Long lines scroll sideways inside it, and code longer than one line gets line numbers.
+
+- **Best for:** Showing code or a command someone will read or copy: an install step, a config file, an example.
+- **Not for:** A word of code inside a sentence: use a code element. A key to press: use Kbd.
+- Molecule. Source: `src/components/molecules/code-block/CodeBlock.tsx`
+- Rendered docs page: `/components/code-block`
+
+## Import
+
+```tsx
+import { CodeBlock } from 'src/components/molecules/code-block/CodeBlock'
+```
+
+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
+
+- The app’s one Toaster at the root: the copy is confirmed with a toast.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `code` | `string` |  | The text shown and copied, exactly. |
+| `label` | `string` |  | What the code is, in a few words ("the theme CSS"). Names the region and the copy button ("Copy the theme CSS"). |
+| `title` | `string` |  | Shown in the title bar: a file name ("index.css") or a language ("bash"). |
+| `language` | `'css' \| 'text'` | `'text'` | css colours comments, at-rules, selectors and property names; text is plain. |
+| `lineNumbers` | `boolean` |  | Line numbers in a gutter. Unset, they show when the code has more than one line. |
+| `copyable` | `boolean` | `true` | The copy button. Turn it off for code nobody should paste, such as a wrong example. |
+| `wrap` | `boolean` | `false` | Wraps long lines instead of scrolling them sideways. For prose, such as a prompt; leave code unwrapped. |
+| `className` | `string` |  | Merged onto the frame. Use it for width (max-w-3xl) and spacing. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the frame. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A command
+
+```tsx
+<CodeBlock title="bash" label="the check command" code="npx division-ds check src" className="max-w-3xl" />
+```
+
+### A file, with CSS colours and line numbers
+
+```tsx
+<CodeBlock
+  title="index.css"
+  language="css"
+  label="the theme CSS"
+  className="max-w-3xl"
+  code={'@import "./division-ds/styles/division-ds.css";\n\n/* Square corners */\n:root {\n  --shape-bevel: 0;\n  --shape-radius: 4px;\n}\n'}
+/>
+```
+
+### Not copyable, for code nobody should paste
+
+```tsx
+<CodeBlock title="Wrong" label="a bare pre" copyable={false} code={'<pre>{command}</pre>'} className="max-w-3xl" />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the copy button, then to the code region. |
+| `←` `→` | In the focused code region: scrolls a long line sideways. |
+| `Enter` | On the copy button: copies the code. |
+
+## Do
+
+- Write a label that says what the code is, so the copy button reads "Copy the install command".
+- Give it a title: the file name it belongs in, or the language.
+- Set a max width with className; long lines scroll inside it, so it never widens the page.
+
+## Don't
+
+- Don’t put several unrelated commands in one block. One block per thing to copy.
+- Don’t set copyable on an example of what not to write.
+- Don’t wrap it in another bordered panel; it brings its own frame.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<pre className="font-mono text-sm">{command}</pre>
+```
+
+Right:
+
+```tsx
+<CodeBlock code={command} label="the install command" title="bash" />
+```
+
+A bare pre has no copy button, no name, and cannot be scrolled with a keyboard when a line runs past the edge.
+
+## Anatomy
+
+- **Frame**: A thin border around a surface.base fill. The syntax colours are measured for contrast on surface.base.
+- **Title bar**: The title on the left, in 12px uppercase mono, and the copy button on the right, above a thin line.
+- **Code region**: A pre with role region, named by the title and the label, focusable so a keyboard can scroll it. Up to 32rem tall, then it scrolls.
+- **Line numbers**: A gutter in text.muted, hidden from screen readers and from text selection.
+- **Copy button**: An IconButton named "Copy" plus the label. After copying, its icon turns into a tick for a moment and a toast confirms it.

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

@@ -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/kbd.md

@@ -20,6 +20,8 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | 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/navbar.md

@@ -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/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/progress.md

@@ -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. |