division-ds 0.3.1 → 0.4.0

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: 74 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "division-ds",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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. |

package/public/manifest/components.json

@@ -1231,6 +1231,18 @@
           "type": "ReactNode",
           "description": "The key's name, for example \"Esc\" or \"⌘\"."
         },
+        {
+          "name": "size",
+          "type": "'md' | 'sm'",
+          "default": "'md'",
+          "description": "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."
+        },
+        {
+          "name": "cut",
+          "type": "boolean",
+          "default": "false",
+          "description": "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."
+        },
         {
           "name": "className",
           "type": "string",
@@ -1251,10 +1263,11 @@
       "dos": [
         "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."
+        "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."
       ],
       "donts": [
-        "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."
       ],
@@ -1265,11 +1278,11 @@
         },
         {
           "part": "Hairline border",
-          "description": "A one-pixel border in border.hairline-strong, with no bevel (cut corners)."
+          "description": "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."
         },
         {
           "part": "Mono legend",
-          "description": "JetBrains Mono, uppercase, 11px (pixels): the tertiary type role."
+          "description": "JetBrains Mono, uppercase, 11px (pixels): the tertiary type role, at both sizes."
         }
       ],
       "examples": [
@@ -1280,6 +1293,14 @@
         {
           "caption": "A chord: one cap per key",
           "source": "<span className=\"flex items-center gap-1\">\n  <Kbd>Ctrl</Kbd>\n  <span className=\"text-[var(--color-text-muted)] text-sm\">+</span>\n  <Kbd>K</Kbd>\n</span>\n<span className=\"text-sm text-[var(--color-text-secondary)]\">Open the command palette</span>"
+        },
+        {
+          "caption": "Sizes",
+          "source": "<Kbd>Esc</Kbd>\n<Kbd size=\"sm\">Esc</Kbd>"
+        },
+        {
+          "caption": "Small and cut, inside a small button",
+          "source": "<Button variant=\"secondary\" size=\"sm\" iconStart={<Search />} aria-keyshortcuts=\"Control+K\">\n  Search\n  <Kbd aria-hidden=\"true\" size=\"sm\" cut className=\"-mr-1.5 ml-2 -translate-y-[var(--cap-shift,0px)]\">\n    Ctrl K\n  </Kbd>\n</Button>"
         }
       ],
       "closed": false
@@ -1503,6 +1524,155 @@
       ],
       "closed": false
     },
+    {
+      "name": "Panel",
+      "title": "Panel",
+      "tier": "atoms",
+      "slug": "panel",
+      "summary": "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.",
+      "useWhen": "Framing content that has no title, body and footer structure: a feature tile, a demo area, or a tile that is one link.",
+      "notFor": "Content with a title, a body and actions: use Card. A page-width layout wrapper: use a plain div with max-w-*.",
+      "source": "src/components/atoms/panel/Panel.tsx",
+      "docs": "/docs/components/panel.md",
+      "imports": [
+        {
+          "names": [
+            "Panel"
+          ],
+          "from": "src/components/atoms/panel/Panel"
+        }
+      ],
+      "props": [
+        {
+          "name": "padding",
+          "type": "'none' | 'sm' | 'md' | 'lg'",
+          "default": "'md'",
+          "description": "Inner spacing: 0, 12px, 20px or 32px."
+        },
+        {
+          "name": "tone",
+          "type": "'base' | 'raised' | 'signal'",
+          "default": "'raised'",
+          "description": "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."
+        },
+        {
+          "name": "crosshair",
+          "type": "boolean",
+          "default": "false",
+          "description": "Draws the crosshair marks at the corners."
+        },
+        {
+          "name": "cut",
+          "type": "boolean",
+          "default": "false",
+          "description": "Cuts the bottom-right corner, with the border following the cut."
+        },
+        {
+          "name": "interactive",
+          "type": "boolean",
+          "default": "false",
+          "description": "Hover and focus states for a panel that is one link or button. Use it with asChild; it adds no behaviour of its own."
+        },
+        {
+          "name": "asChild",
+          "type": "boolean",
+          "default": "false",
+          "description": "Renders the single child element (an a, a router Link, a button) with the panel classes merged onto it, instead of a div."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Merged with the component's classes. Use it for layout (a grid span, flex, gap), not for the fill or the border."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "description": "Passed through to the div, or to the child with asChild."
+        },
+        {
+          "name": "...rest",
+          "type": "HTMLAttributes<HTMLDivElement>",
+          "description": "Every native attribute, passed onto the element."
+        }
+      ],
+      "keyboard": [
+        {
+          "keys": [
+            "Tab"
+          ],
+          "does": "With interactive and asChild on a link or button: moves focus to the panel and shows the focus ring."
+        },
+        {
+          "keys": [
+            "Enter"
+          ],
+          "does": "Follows the link, or presses the button, that the panel was rendered as."
+        }
+      ],
+      "dos": [
+        "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."
+      ],
+      "donts": [
+        "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."
+      ],
+      "pitfalls": [
+        {
+          "wrong": "<Panel className=\"bg-[var(--color-surface-base)] border-[var(--color-border-selection)]\">",
+          "right": "<Panel tone=\"base\">",
+          "why": "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": "<Panel interactive onClick={open}>Replicas</Panel>",
+          "right": "<Panel interactive asChild><Link to=\"/replicas\">Replicas</Link></Panel>",
+          "why": "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": [
+        {
+          "part": "Frame",
+          "description": "A div (or, with asChild, your element) with the .panel class: a one-pixel border and a fill, both set by the tone."
+        },
+        {
+          "part": "Tone",
+          "description": "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."
+        },
+        {
+          "part": "Crosshair",
+          "description": "Optional. Short marks drawn 5px outside each corner, in text.muted. The parent must not clip its overflow."
+        },
+        {
+          "part": "Cut corner",
+          "description": "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."
+        },
+        {
+          "part": "Interactive state",
+          "description": "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."
+        }
+      ],
+      "examples": [
+        {
+          "caption": "Tones",
+          "source": "<Panel tone=\"base\">\n  <p className=\"font-display font-semibold\">Base</p>\n  <p className=\"text-sm text-[var(--color-text-secondary)]\">Flush with the page.</p>\n</Panel>\n<Panel tone=\"raised\">\n  <p className=\"font-display font-semibold\">Raised</p>\n  <p className=\"text-sm text-[var(--color-text-secondary)]\">One step up.</p>\n</Panel>\n<Panel tone=\"signal\">\n  <p className=\"font-display font-semibold\">Signal</p>\n  <p className=\"text-sm text-[var(--color-text-secondary)]\">The one that leads.</p>\n</Panel>"
+        },
+        {
+          "caption": "Padding",
+          "source": "<Panel padding=\"none\">none</Panel>\n<Panel padding=\"sm\">sm</Panel>\n<Panel padding=\"md\">md</Panel>\n<Panel padding=\"lg\">lg</Panel>"
+        },
+        {
+          "caption": "Crosshair and cut corner",
+          "source": "<Panel crosshair>Crosshair</Panel>\n<Panel cut>Cut corner</Panel>\n<Panel crosshair cut tone=\"signal\">Both</Panel>"
+        },
+        {
+          "caption": "Interactive, as a router link",
+          "source": "<Panel interactive cut padding=\"lg\" asChild>\n  <RouterLink to=\"/components/card\" className=\"flex flex-col gap-3\">\n    <span className=\"font-display text-lg font-semibold\">Card</span>\n    <span className=\"text-sm text-[var(--color-text-secondary)]\">A panel with a title, a body and a footer.</span>\n    <span className=\"inline-flex items-center gap-2 font-semibold text-[var(--color-accent-signal-text)]\">\n      Open <ArrowRight aria-hidden=\"true\" className=\"size-4\" />\n    </span>\n  </RouterLink>\n</Panel>"
+        }
+      ],
+      "closed": false
+    },
     {
       "name": "Progress",
       "title": "Progress",
@@ -1548,7 +1718,7 @@
           "name": "tone",
           "type": "'signal' | 'ok' | 'warning' | 'hostile'",
           "default": "'signal'",
-          "description": "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."
+          "description": "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."
         },
         {
           "name": "className",
@@ -4373,6 +4543,153 @@
       ],
       "closed": true
     },
+    {
+      "name": "CodeBlock",
+      "title": "Code block",
+      "tier": "molecules",
+      "slug": "code-block",
+      "summary": "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.",
+      "useWhen": "Showing code or a command someone will read or copy: an install step, a config file, an example.",
+      "notFor": "A word of code inside a sentence: use a code element. A key to press: use Kbd.",
+      "source": "src/components/molecules/code-block/CodeBlock.tsx",
+      "docs": "/docs/components/code-block.md",
+      "imports": [
+        {
+          "names": [
+            "CodeBlock"
+          ],
+          "from": "src/components/molecules/code-block/CodeBlock"
+        }
+      ],
+      "requires": [
+        "The app’s one Toaster at the root: the copy is confirmed with a toast."
+      ],
+      "props": [
+        {
+          "name": "code",
+          "type": "string",
+          "description": "The text shown and copied, exactly."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "description": "What the code is, in a few words (\"the theme CSS\"). Names the region and the copy button (\"Copy the theme CSS\")."
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "description": "Shown in the title bar: a file name (\"index.css\") or a language (\"bash\")."
+        },
+        {
+          "name": "language",
+          "type": "'css' | 'text'",
+          "default": "'text'",
+          "description": "css colours comments, at-rules, selectors and property names; text is plain."
+        },
+        {
+          "name": "lineNumbers",
+          "type": "boolean",
+          "description": "Line numbers in a gutter. Unset, they show when the code has more than one line."
+        },
+        {
+          "name": "copyable",
+          "type": "boolean",
+          "default": "true",
+          "description": "The copy button. Turn it off for code nobody should paste, such as a wrong example."
+        },
+        {
+          "name": "wrap",
+          "type": "boolean",
+          "default": "false",
+          "description": "Wraps long lines instead of scrolling them sideways. For prose, such as a prompt; leave code unwrapped."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Merged onto the frame. Use it for width (max-w-3xl) and spacing."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "description": "Passed through to the frame."
+        }
+      ],
+      "keyboard": [
+        {
+          "keys": [
+            "Tab"
+          ],
+          "does": "Moves to the copy button, then to the code region."
+        },
+        {
+          "keys": [
+            "←",
+            "→"
+          ],
+          "does": "In the focused code region: scrolls a long line sideways."
+        },
+        {
+          "keys": [
+            "Enter"
+          ],
+          "does": "On the copy button: copies the code."
+        }
+      ],
+      "dos": [
+        "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."
+      ],
+      "donts": [
+        "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."
+      ],
+      "pitfalls": [
+        {
+          "wrong": "<pre className=\"font-mono text-sm\">{command}</pre>",
+          "right": "<CodeBlock code={command} label=\"the install command\" title=\"bash\" />",
+          "why": "A bare pre has no copy button, no name, and cannot be scrolled with a keyboard when a line runs past the edge."
+        }
+      ],
+      "anatomy": [
+        {
+          "part": "Frame",
+          "description": "A thin border around a surface.base fill. The syntax colours are measured for contrast on surface.base."
+        },
+        {
+          "part": "Title bar",
+          "description": "The title on the left, in 12px uppercase mono, and the copy button on the right, above a thin line."
+        },
+        {
+          "part": "Code region",
+          "description": "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."
+        },
+        {
+          "part": "Line numbers",
+          "description": "A gutter in text.muted, hidden from screen readers and from text selection."
+        },
+        {
+          "part": "Copy button",
+          "description": "An IconButton named \"Copy\" plus the label. After copying, its icon turns into a tick for a moment and a toast confirms it."
+        }
+      ],
+      "examples": [
+        {
+          "caption": "A command",
+          "source": "<CodeBlock title=\"bash\" label=\"the check command\" code=\"npx division-ds check src\" className=\"max-w-3xl\" />"
+        },
+        {
+          "caption": "A file, with CSS colours and line numbers",
+          "source": "<CodeBlock\n  title=\"index.css\"\n  language=\"css\"\n  label=\"the theme CSS\"\n  className=\"max-w-3xl\"\n  code={'@import \"./division-ds/styles/division-ds.css\";\\n\\n/* Square corners */\\n:root {\\n  --shape-bevel: 0;\\n  --shape-radius: 4px;\\n}\\n'}\n/>"
+        },
+        {
+          "caption": "Not copyable, for code nobody should paste",
+          "source": "<CodeBlock title=\"Wrong\" label=\"a bare pre\" copyable={false} code={'<pre>{command}</pre>'} className=\"max-w-3xl\" />"
+        }
+      ],
+      "closed": true
+    },
     {
       "name": "DatePicker",
       "title": "Date picker",
@@ -5222,6 +5539,12 @@
           "default": "'default'",
           "description": "Use hostile for a destructive action: hostile-coloured text at rest, the hostile fill with ink text when highlighted."
         },
+        {
+          "name": "asChild (Item)",
+          "type": "boolean",
+          "default": "false",
+          "description": "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."
+        },
         {
           "name": "icon (Item)",
           "type": "ReactNode",
@@ -9547,7 +9870,7 @@
       "examples": [
         {
           "caption": "Line, two series",
-          "source": "type Week = { week: string; online: number; store: number }\n\nconst WEEKS: Week[] = [\n  { week: 'W1', online: 120, store: 160 },\n  { week: 'W2', online: 131, store: 158 },\n  { week: 'W3', online: 142, store: 163 },\n  { week: 'W4', online: 150, store: 155 },\n  { week: 'W5', online: 171, store: 162 },\n  { week: 'W6', online: 188, store: 159 },\n  { week: 'W7', online: 197, store: 166 },\n  { week: 'W8', online: 214, store: 161 },\n]\n\n<ChartPanel<Week>\n  title=\"Weekly orders\"\n  summary=\"Online orders rose from 120 to 214 over eight weeks and passed in-store orders in week 5.\"\n  kind=\"line\"\n  data={WEEKS}\n  xKey=\"week\"\n  xLabel=\"Week\"\n  series={[\n    { key: 'online', label: 'Online' },\n    { key: 'store', label: 'In store' },\n  ]}\n  headingLevel={4}\n/>"
+          "source": "type Week = { week: string; online: number; store: number }\n\nconst WEEKS: Week[] = [\n  { week: 'W1', online: 118, store: 150 },\n  { week: 'W2', online: 149, store: 172 },\n  { week: 'W3', online: 168, store: 158 },\n  { week: 'W4', online: 141, store: 131 },\n  { week: 'W5', online: 126, store: 128 },\n  { week: 'W6', online: 174, store: 150 },\n  { week: 'W7', online: 231, store: 141 },\n  { week: 'W8', online: 183, store: 122 },\n  { week: 'W9', online: 139, store: 149 },\n  { week: 'W10', online: 162, store: 185 },\n  { week: 'W11', online: 196, store: 163 },\n  { week: 'W12', online: 170, store: 140 },\n]\n\n<ChartPanel<Week>\n  title=\"Weekly orders\"\n  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.\"\n  kind=\"line\"\n  area\n  curve=\"smooth\"\n  data={WEEKS}\n  xKey=\"week\"\n  xLabel=\"Week\"\n  series={[\n    { key: 'online', label: 'Online' },\n    { key: 'store', label: 'In store' },\n  ]}\n  headingLevel={4}\n/>"
         },
         {
           "caption": "Bar, one series",
@@ -9555,11 +9878,11 @@
         },
         {
           "caption": "Area under a smooth line",
-          "source": "type Day = { day: string; visits: number; orders: number }\n\nconst DAYS: Day[] = [\n  { day: 'Mon', visits: 1840, orders: 61 },\n  { day: 'Tue', visits: 2210, orders: 74 },\n  { day: 'Wed', visits: 1960, orders: 58 },\n  { day: 'Thu', visits: 2650, orders: 92 },\n  { day: 'Fri', visits: 3120, orders: 118 },\n  { day: 'Sat', visits: 3890, orders: 141 },\n  { day: 'Sun', visits: 3370, orders: 126 },\n]\n\n<ChartPanel<Day>\n  title=\"Visits this week\"\n  summary=\"Visits climbed from 1,840 on Monday to a Saturday peak of 3,890.\"\n  kind=\"line\"\n  area\n  curve=\"smooth\"\n  data={DAYS}\n  xKey=\"day\"\n  xLabel=\"Day\"\n  series={[{ key: 'visits', label: 'Visits' }]}\n  headline=\"19,040\"\n  headingLevel={4}\n/>"
+          "source": "type Day = { day: string; visits: number; orders: number }\n\nconst DAYS: Day[] = [\n  { day: 'Mon', visits: 1840, orders: 61 },\n  { day: 'Tue', visits: 2960, orders: 104 },\n  { day: 'Wed', visits: 2210, orders: 74 },\n  { day: 'Thu', visits: 1720, orders: 55 },\n  { day: 'Fri', visits: 2650, orders: 92 },\n  { day: 'Sat', visits: 3890, orders: 141 },\n  { day: 'Sun', visits: 3120, orders: 118 },\n]\n\n<ChartPanel<Day>\n  title=\"Visits this week\"\n  summary=\"Visits peaked on Tuesday at 2,960, fell to a Thursday low of 1,720, then peaked higher on Saturday at 3,890.\"\n  kind=\"line\"\n  area\n  curve=\"smooth\"\n  data={DAYS}\n  xKey=\"day\"\n  xLabel=\"Day\"\n  series={[{ key: 'visits', label: 'Visits' }]}\n  headline=\"18,390\"\n  headingLevel={4}\n/>"
         },
         {
           "caption": "No grid lines: only the labels along the axes",
-          "source": "type Week = { week: string; online: number; store: number }\n\nconst WEEKS: Week[] = [\n  { week: 'W1', online: 120, store: 160 },\n  { week: 'W2', online: 131, store: 158 },\n  { week: 'W3', online: 142, store: 163 },\n  { week: 'W4', online: 150, store: 155 },\n  { week: 'W5', online: 171, store: 162 },\n  { week: 'W6', online: 188, store: 159 },\n  { week: 'W7', online: 197, store: 166 },\n  { week: 'W8', online: 214, store: 161 },\n]\n\n<ChartPanel<Week>\n  title=\"Weekly orders, gridless\"\n  summary=\"Online orders rose from 120 to 214 over eight weeks and passed in-store orders in week 5.\"\n  kind=\"line\"\n  area\n  curve=\"smooth\"\n  grid={false}\n  data={WEEKS}\n  xKey=\"week\"\n  xLabel=\"Week\"\n  series={[\n    { key: 'online', label: 'Online' },\n    { key: 'store', label: 'In store' },\n  ]}\n  headingLevel={4}\n/>"
+          "source": "type Week = { week: string; online: number; store: number }\n\nconst WEEKS: Week[] = [\n  { week: 'W1', online: 118, store: 150 },\n  { week: 'W2', online: 149, store: 172 },\n  { week: 'W3', online: 168, store: 158 },\n  { week: 'W4', online: 141, store: 131 },\n  { week: 'W5', online: 126, store: 128 },\n  { week: 'W6', online: 174, store: 150 },\n  { week: 'W7', online: 231, store: 141 },\n  { week: 'W8', online: 183, store: 122 },\n  { week: 'W9', online: 139, store: 149 },\n  { week: 'W10', online: 162, store: 185 },\n  { week: 'W11', online: 196, store: 163 },\n  { week: 'W12', online: 170, store: 140 },\n]\n\n<ChartPanel<Week>\n  title=\"Weekly orders, gridless\"\n  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.\"\n  kind=\"line\"\n  area\n  curve=\"smooth\"\n  grid={false}\n  data={WEEKS}\n  xKey=\"week\"\n  xLabel=\"Week\"\n  series={[\n    { key: 'online', label: 'Online' },\n    { key: 'store', label: 'In store' },\n  ]}\n  headingLevel={4}\n/>"
         },
         {
           "caption": "A shaded band: night hours on a 24-hour series (the band wraps past midnight)",
@@ -9567,7 +9890,7 @@
         },
         {
           "caption": "Small: stat cards, each with a sparkline (a tiny line chart with no axes)",
-          "source": "type Week = { week: string; online: number; store: number }\n\ntype Day = { day: string; visits: number; orders: number }\n\nconst WEEKS: Week[] = [\n  { week: 'W1', online: 120, store: 160 },\n  { week: 'W2', online: 131, store: 158 },\n  { week: 'W3', online: 142, store: 163 },\n  { week: 'W4', online: 150, store: 155 },\n  { week: 'W5', online: 171, store: 162 },\n  { week: 'W6', online: 188, store: 159 },\n  { week: 'W7', online: 197, store: 166 },\n  { week: 'W8', online: 214, store: 161 },\n]\n\nconst DAYS: Day[] = [\n  { day: 'Mon', visits: 1840, orders: 61 },\n  { day: 'Tue', visits: 2210, orders: 74 },\n  { day: 'Wed', visits: 1960, orders: 58 },\n  { day: 'Thu', visits: 2650, orders: 92 },\n  { day: 'Fri', visits: 3120, orders: 118 },\n  { day: 'Sat', visits: 3890, orders: 141 },\n  { day: 'Sun', visits: 3370, orders: 126 },\n]\n\n<ChartPanel<Day>\n  title=\"Visits\"\n  headline=\"19,040\"\n  summary=\"Up every day but Wednesday and Sunday.\"\n  kind=\"line\"\n  area\n  curve=\"smooth\"\n  size=\"sm\"\n  data={DAYS}\n  xKey=\"day\"\n  xLabel=\"Day\"\n  series={[{ key: 'visits', label: 'Visits' }]}\n  headingLevel={4}\n/>\n<ChartPanel<Day>\n  title=\"Orders\"\n  headline=\"670\"\n  summary=\"Saturday took 141, the most of the week.\"\n  kind=\"bar\"\n  size=\"sm\"\n  data={DAYS}\n  xKey=\"day\"\n  xLabel=\"Day\"\n  series={[{ key: 'orders', label: 'Orders' }]}\n  headingLevel={4}\n/>\n<ChartPanel<Week>\n  title=\"Online orders\"\n  headline=\"214\"\n  summary=\"Eight weeks of growth, from 120 a week.\"\n  kind=\"line\"\n  curve=\"smooth\"\n  size=\"sm\"\n  data={WEEKS}\n  xKey=\"week\"\n  xLabel=\"Week\"\n  series={[{ key: 'online', label: 'Online' }]}\n  headingLevel={4}\n/>"
+          "source": "type Week = { week: string; online: number; store: number }\n\ntype Day = { day: string; visits: number; orders: number }\n\nconst WEEKS: Week[] = [\n  { week: 'W1', online: 118, store: 150 },\n  { week: 'W2', online: 149, store: 172 },\n  { week: 'W3', online: 168, store: 158 },\n  { week: 'W4', online: 141, store: 131 },\n  { week: 'W5', online: 126, store: 128 },\n  { week: 'W6', online: 174, store: 150 },\n  { week: 'W7', online: 231, store: 141 },\n  { week: 'W8', online: 183, store: 122 },\n  { week: 'W9', online: 139, store: 149 },\n  { week: 'W10', online: 162, store: 185 },\n  { week: 'W11', online: 196, store: 163 },\n  { week: 'W12', online: 170, store: 140 },\n]\n\nconst DAYS: Day[] = [\n  { day: 'Mon', visits: 1840, orders: 61 },\n  { day: 'Tue', visits: 2960, orders: 104 },\n  { day: 'Wed', visits: 2210, orders: 74 },\n  { day: 'Thu', visits: 1720, orders: 55 },\n  { day: 'Fri', visits: 2650, orders: 92 },\n  { day: 'Sat', visits: 3890, orders: 141 },\n  { day: 'Sun', visits: 3120, orders: 118 },\n]\n\n<ChartPanel<Day>\n  title=\"Visits\"\n  headline=\"18,390\"\n  summary=\"Two peaks: Tuesday, then a higher Saturday.\"\n  kind=\"line\"\n  area\n  curve=\"smooth\"\n  size=\"sm\"\n  data={DAYS}\n  xKey=\"day\"\n  xLabel=\"Day\"\n  series={[{ key: 'visits', label: 'Visits' }]}\n  headingLevel={4}\n/>\n<ChartPanel<Day>\n  title=\"Orders\"\n  headline=\"670\"\n  summary=\"Saturday took 141, the most of the week.\"\n  kind=\"bar\"\n  size=\"sm\"\n  data={DAYS}\n  xKey=\"day\"\n  xLabel=\"Day\"\n  series={[{ key: 'orders', label: 'Orders' }]}\n  headingLevel={4}\n/>\n<ChartPanel<Week>\n  title=\"Online orders\"\n  headline=\"170\"\n  summary=\"Three peaks in twelve weeks; the highest, 231, in week 7.\"\n  kind=\"line\"\n  area\n  curve=\"smooth\"\n  size=\"sm\"\n  data={WEEKS}\n  xKey=\"week\"\n  xLabel=\"Week\"\n  series={[{ key: 'online', label: 'Online' }]}\n  headingLevel={4}\n/>"
         },
         {
           "caption": "Donut with a centre total",
@@ -10984,7 +11307,7 @@
         {
           "name": "items",
           "type": "NavbarItem[]",
-          "description": "Required. Each item has label, href and current."
+          "description": "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."
         },
         {
           "name": "actions",
@@ -11006,7 +11329,13 @@
         {
           "name": "menuFooter",
           "type": "ReactNode",
-          "description": "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."
+          "description": "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')."
+        },
+        {
+          "name": "collapseBelow",
+          "type": "'2xl' | '4xl'",
+          "default": "'2xl'",
+          "description": "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."
         },
         {
           "name": "className",
@@ -11023,7 +11352,7 @@
         {
           "name": "NavbarItem",
           "kind": "type",
-          "code": "export type NavbarItem = { label: string; href: string; current?: boolean }",
+          "code": "export type NavbarItem = NavbarLink | NavbarMenu",
           "from": "src/components/organisms/navbar/Navbar"
         }
       ],
@@ -11084,6 +11413,10 @@
           "caption": "Store navigation",
           "source": "const ITEMS = [\n  { label: 'Replicas', href: '#replicas' },\n  { label: 'Optics', href: '#optics', current: true },\n  { label: 'Parts', href: '#parts' },\n  { label: 'Care', href: '#care' },\n  { label: 'Field notes', href: '#field-notes' },\n]\n\nconst BRAND = (\n  <a\n    href=\"#home\"\n    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)]\"\n  >\n    Hexline\n  </a>\n)\n\nconst ACTIONS = (\n  <>\n    <IconButton label=\"Search\" variant=\"ghost\">\n      <Search aria-hidden=\"true\" className=\"w-5 h-5\" />\n    </IconButton>\n    <IconButton label=\"Cart, 2 items\" variant=\"ghost\" asChild>\n      <a href=\"#cart\">\n        <ShoppingBag aria-hidden=\"true\" className=\"w-5 h-5\" />\n      </a>\n    </IconButton>\n  </>\n)\n\n<Navbar label=\"Store navigation\" brand={BRAND} items={ITEMS} actions={ACTIONS} />"
         },
+        {
+          "caption": "A menu among the links",
+          "source": "const ITEMS = [\n  { label: 'Replicas', href: '#replicas' },\n  { label: 'Optics', href: '#optics', current: true },\n  { label: 'Parts', href: '#parts' },\n  { label: 'Care', href: '#care' },\n  { label: 'Field notes', href: '#field-notes' },\n]\n\nconst BRAND = (\n  <a\n    href=\"#home\"\n    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)]\"\n  >\n    Hexline\n  </a>\n)\n\nconst ACTIONS = (\n  <>\n    <IconButton label=\"Search\" variant=\"ghost\">\n      <Search aria-hidden=\"true\" className=\"w-5 h-5\" />\n    </IconButton>\n    <IconButton label=\"Cart, 2 items\" variant=\"ghost\" asChild>\n      <a href=\"#cart\">\n        <ShoppingBag aria-hidden=\"true\" className=\"w-5 h-5\" />\n      </a>\n    </IconButton>\n  </>\n)\n\n<Navbar\n  label=\"Store navigation with a menu\"\n  brand={BRAND}\n  items={[\n    ...ITEMS.slice(0, 3),\n    {\n      label: 'Guides',\n      menu: [\n        { label: 'Sizing', href: '#sizing', description: 'Fit charts for every replica.' },\n        { label: 'Returns', href: '#returns', description: 'Thirty days, no questions.' },\n      ],\n    },\n  ]}\n  actions={ACTIONS}\n/>"
+        },
         {
           "caption": "A narrow container",
           "source": "const ITEMS = [\n  { label: 'Replicas', href: '#replicas' },\n  { label: 'Optics', href: '#optics', current: true },\n  { label: 'Parts', href: '#parts' },\n  { label: 'Care', href: '#care' },\n  { label: 'Field notes', href: '#field-notes' },\n]\n\nconst BRAND = (\n  <a\n    href=\"#home\"\n    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)]\"\n  >\n    Hexline\n  </a>\n)\n\nconst ACTIONS = (\n  <>\n    <IconButton label=\"Search\" variant=\"ghost\">\n      <Search aria-hidden=\"true\" className=\"w-5 h-5\" />\n    </IconButton>\n    <IconButton label=\"Cart, 2 items\" variant=\"ghost\" asChild>\n      <a href=\"#cart\">\n        <ShoppingBag aria-hidden=\"true\" className=\"w-5 h-5\" />\n      </a>\n    </IconButton>\n  </>\n)\n\n<div className=\"max-w-sm\">\n  <Navbar label=\"Store navigation, narrow\" brand={BRAND} items={ITEMS} actions={ACTIONS} />\n</div>"

package/public/manifest/tokens.json

@@ -430,9 +430,12 @@
       "layer": "semantic",
       "value": {
         "dark": "#0d1016",
-        "light": "#c2cddc"
+        "light": "#e3e8ef"
       },
-      "use": "The opaque fill of a control you type or pick in (Input, Textarea, Select), and of small opaque surfaces: Kbd, Tag, Tooltip, menus, toasts. Not a card."
+      "use": "The opaque fill of a control you type or pick in (Input, Textarea, Select), and of small opaque surfaces: Kbd, Tag, Tooltip, menus, toasts. Not a card.",
+      "measured": {
+        "light": "neutral.50 mixed 31% of the way to neutral.100 in OKLab (#e3e8ef with the default preset), so the base-to-sunken step is OKLCH ΔL 0.038, the same step as the dark theme (#07080b to #0d1016, ΔL 0.038). neutral.100 alone sat ΔL 0.122 below base and made every field a heavy grey slab; the ramp has no stop in between. A mix of two ramp stops, not a literal, so a Theme Builder preset re-tints it."
+      }
     },
     {
       "name": "--color-surface-raised",
@@ -488,7 +491,7 @@
       "use": "The boundary of an interactive control at rest (Input, Select, secondary Button). The one border that has to be seen to find the control.",
       "measured": {
         "dark": "3.53:1 on surface.sunken (the control fill it is painted on) and 3.71:1 on surface.base — the INFORMATIONAL hairline, the one SC 1.4.11 governs. Opaque rather than alpha so the boundary holds whatever surface it lands on.",
-        "light": "3.49:1 on surface.sunken (the control fill it is painted on) and 5.10:1 on surface.base — the INFORMATIONAL hairline, the one SC 1.4.11 governs. Opaque rather than alpha so the boundary holds whatever surface it lands on."
+        "light": "4.56:1 on surface.sunken (the control fill it is painted on) and 5.10:1 on surface.base — the INFORMATIONAL hairline, the one SC 1.4.11 governs. Opaque rather than alpha so the boundary holds whatever surface it lands on."
       }
     },
     {
@@ -501,7 +504,7 @@
       "use": "The boundary of the small selection controls at rest: Checkbox, Radio, Switch track.",
       "measured": {
         "dark": "The boundary of the small selection controls (Checkbox, Radio, Switch track) at rest. 6.12:1 on surface.sunken. Brighter than border.control (3.53:1) on purpose: a 20px box drawn with the same hairline as a 320px input carries a fraction of the edge length, and at 3.53:1 an unchecked checkbox all but vanished on the dark page. border.control stays the hairline for the large fields.",
-        "light": "The boundary of the small selection controls (Checkbox, Radio, Switch track) at rest. Same value as border.control in this theme (3.49:1 on surface.sunken), which reads clearly on a light page; the token exists in both themes because dark needed its own brighter step."
+        "light": "The boundary of the small selection controls (Checkbox, Radio, Switch track) at rest. Same value as border.control in this theme (4.56:1 on surface.sunken), which reads clearly on a light page; the token exists in both themes because dark needed its own brighter step."
       }
     },
     {
@@ -544,7 +547,7 @@
       "use": "Placeholder text inside a control, on surface.sunken. Only there.",
       "measured": {
         "dark": "4.68:1 on surface.sunken, which is the control fill placeholder text is actually painted on. text.muted is gated against surface.base and passes there at 4.59:1, but reaches only 4.37:1 on the sunken fill — so placeholder needs its own step.",
-        "light": "7.83:1 on surface.sunken, the control fill it is painted on. Light theme needs no separate step from text.muted — unlike dark, where muted reaches only 4.37:1 there — but the name exists in both themes so the component layer has one alias to point at."
+        "light": "10.23:1 on surface.sunken, the control fill it is painted on. Light theme needs no separate step from text.muted — unlike dark, where muted reaches only 4.37:1 there — but the name exists in both themes so the component layer has one alias to point at."
       }
     },
     {
@@ -775,7 +778,7 @@
       "use": "Text or an icon that marks something as made by AI: the AiLabel mark, the AI glyph in a field an AI filled. Always beside a word, never colour alone.",
       "measured": {
         "dark": "Measured by the gate: 9.55:1 on surface.base, 9.08:1 on surface.sunken, 8.32:1 on surface.raised. One step lighter than accent.info.text (info.500) so AI marks and status text do not read as the same thing.",
-        "light": "Measured by the gate: 8.39:1 on surface.base, 5.75:1 on surface.sunken, 8.92:1 on surface.raised. info.700 reached only 3.49:1 on surface.sunken, so the light theme takes info.800."
+        "light": "Measured by the gate: 8.39:1 on surface.base, 7.50:1 on surface.sunken, 8.92:1 on surface.raised. info.700 reached only 3.49:1 on the earlier, darker surface.sunken (neutral.100), so the light theme takes info.800."
       }
     },
     {
@@ -788,7 +791,7 @@
       "use": "The boundary of a form field whose value an AI filled and the person has not changed. Input and Textarea paint it from aiValue; do not paint it by hand.",
       "measured": {
         "dark": "The edge of a field an AI filled. 7.91:1 on the AI-filled field (ai.wash over the control fill), far above the 3:1 SC 1.4.11 floor. Same stop as ai.text; a separate token because a boundary and text carry different floors.",
-        "light": "The edge of a field an AI filled. 5.24:1 on the AI-filled field (ai.wash over surface.sunken). Same stop as ai.text; a separate token because a boundary and text carry different floors."
+        "light": "The edge of a field an AI filled. 6.72:1 on the AI-filled field (ai.wash over surface.sunken). Same stop as ai.text; a separate token because a boundary and text carry different floors."
       }
     },
     {

package/skills/division-ds/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: division-ds
-description: Use when building or changing UI with Division DS (React 19, Tailwind 4, Radix; 72 components). Covers which component and token to use, the composition rules prop types cannot express (providers, FormField, button gaps, card borders), planning a screen's states, and how to check the result. Load it before writing any screen or component in a project that has Division DS components.
+description: Use when building or changing UI with Division DS (React 19, Tailwind 4, Radix; 74 components). Covers which component and token to use, the composition rules prop types cannot express (providers, FormField, button gaps, card borders), planning a screen's states, and how to check the result. Load it before writing any screen or component in a project that has Division DS components.
 ---
 
 # Division DS