division-ds 0.5.0 → 0.7.0

package/AGENTS.md

@@ -51,7 +51,7 @@ installs these rules into that project's `AGENTS.md`, `GEMINI.md` and Cursor rul
 `.claude/skills/` (Claude Code).
 
 An agent that supports MCP can have the docs and the same checks as tools instead:
-`claude mcp add division-ds -- npx -y division-ds@0.4.1 mcp` (`list_components`, `get_component`,
+`claude mcp add division-ds -- npx -y division-ds@0.6.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.5.0",
+  "version": "0.7.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/badge.md

@@ -2,7 +2,7 @@
 
 > A small chip that shows a status. It comes in six tones and two emphases, and it always carries a word. A colour on its own isn't a status anyone can read.
 
-- **Best for:** You need to label a status with a word and a tone, like an order state or a sync result.
+- **Best for:** You need to label a status with a word and a tone, like an order state or a sync result. Or a label someone made, like a project tag: then pass color instead of tone.
 - **Not for:** A filter or selection someone can remove. Use Tag for that.
 - Atom. Source: `src/components/atoms/badge/Badge.tsx`
 - Rendered docs page: `/components/badge`
@@ -10,7 +10,7 @@
 ## Import
 
 ```tsx
-import { Badge, badgeVariants } from 'src/components/atoms/badge/Badge'
+import { Badge, badgeVariants, CATEGORY_COLORS } from 'src/components/atoms/badge/Badge'
 ```
 
 Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file. An install has no index barrels: import each component from its own file, never from `components/molecules`.
@@ -19,7 +19,8 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `'neutral' \| 'signal' \| 'ok' \| 'warning' \| 'hostile' \| 'info'` | `'neutral'` | The status the badge shows. |
+| `tone` | `'neutral' \| 'signal' \| 'ok' \| 'warning' \| 'hostile' \| 'info'` | `'neutral'` | The status the badge shows. Leave it out when you pass color. |
+| `color` | `'gray' \| 'brown' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'purple' \| 'pink' \| 'red'` |  | A category colour for a label people make themselves, like a project tag or a topic. It replaces tone: the types reject passing both. A category colour means 'these belong together', never good or bad. The list is exported as CATEGORY_COLORS, so an app can give each new label one at random. Works with both emphases and both sizes. |
 | `emphasis` | `'solid' \| 'subtle'` | `'subtle'` | Solid uses the invariant fill (the same in light and dark themes) with its matching ink. Subtle is the outline badge: a 1px border and text in the tone’s theme-adaptive text token, with no fill. There's no separate outline emphasis, because it would be this same look under a second name. |
 | `size` | `'sm' \| 'md'` | `'sm'` | sm (small) is the chip for everyday interface: rows, cards, tables. md (medium) takes the small control height (32px) and the 14px text step. Use it for a badge next to display-size type, like a price. |
 | `dot` | `boolean` | `false` | Adds a marker next to the text. |
@@ -36,6 +37,18 @@ Exported beside the component, from the same file. Import a type with `import ty
 export const badgeVariants = cva( …
 ```
 
+```ts
+/** Categorical colours for labels people make (a project tag, a topic), in the order a picker
+ *  shows them. Not statuses: a category colour says "same group", never good or bad. Exported so
+ *  an app can give each new label one, for example
+ *  `CATEGORY_COLORS[Math.floor(Math.random() * CATEGORY_COLORS.length)]`. */
+export const CATEGORY_COLORS = ['gray', 'brown', 'orange', 'yellow', 'green', 'teal', 'blue', 'purple', 'pink', 'red'] as const
+```
+
+```ts
+export type CategoryColor = (typeof CATEGORY_COLORS)[number]
+```
+
 ## Examples
 
 Each is compiled and rendered on the docs page. Imports are omitted; see above.
@@ -64,6 +77,26 @@ const TONES = ['neutral', 'signal', 'ok', 'warning', 'hostile', 'info'] as const
 ))}
 ```
 
+### Category colours, subtle: labels people make, not statuses
+
+```tsx
+{CATEGORY_COLORS.map(color => (
+  <Badge key={color} color={color}>
+    {color}
+  </Badge>
+))}
+```
+
+### Category colours, solid
+
+```tsx
+{CATEGORY_COLORS.map(color => (
+  <Badge key={color} color={color} emphasis="solid">
+    {color}
+  </Badge>
+))}
+```
+
 ### With a dot
 
 ```tsx
@@ -158,12 +191,15 @@ Not focusable. No keyboard behaviour of its own.
 - Go easy on solid. One solid badge in a row reads as the exception. Six read as noise.
 - Keep the tone mapping the same across the product. ok is never ‘in progress’ on one screen and ‘done’ on another.
 - Use size md when the badge sits next to a headline figure, so the two read as one statement.
+- Use tone for a status the system knows (paid, failed, syncing) and color for a label a person made (Design, Q3, Home). A colour on its own is not a status.
+- Store the colour with the label, so it stays the same on every screen. Pick one from CATEGORY_COLORS when the label is created.
 
 ## Don't
 
 - Don't build a badge that's colour only, even with a tooltip.
 - Don't put a badge inside a button. It muddies what the clickable target is.
 - Don't use hostile for something that's only pending.
+- Don't use a category colour to show a status. A red project label is not an error, and an error is tone="hostile", so it means the same thing on every screen.
 - Don't bevel it (give it a cut corner). At 22px a badge is chrome, the frame around content, not an object with its own footprint. Kbd follows the same rule for the same reason.
 - Don't resize a badge with height or text classes. The two sizes are the prop. A third size is a change to the system.
 - Don't use size md in a table row or on a card. It's as tall as a small button, so it starts to look like one.

package/public/docs/components/button.md

@@ -20,6 +20,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `variant` | `'primary' \| 'secondary' \| 'danger' \| 'ghost' \| 'link'` | `'primary'` | Which fill/border treatment to use. link looks like a Link (signal text, underline, no fill, no bevel, no fixed height) but it's still a button. Use it for an action inside a sentence, not for going to another page. |
+| `tone` | `'signal' \| 'neutral'` | `'signal'` | Only the link variant reads it. signal is the signal-coloured, underlined link. neutral is primary text with no underline until hover or keyboard focus: use it for a clickable title on a kanban card or a list row, where a column of signal links would be too loud. A link-variant label wraps onto more lines rather than overflowing its column. |
 | `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 24 / 32 / 40 / 48px (pixels). xs is exactly the 24px minimum target, the smallest area people can reliably click or tap. It isn't a token step (there is no xs control-height token) and it's meant for dense toolbars and table rows. Size has no effect on the link variant, which takes the size of the text around it. |
 | `fullWidth` | `boolean` | `false` | Stretches the wrapper as well as the button. |
 | `loading` | `boolean` | `false` | Sets aria-busy and aria-disabled, blocks the click and the form submit, and shows the spinner. The button stays focusable. |
@@ -100,6 +101,21 @@ Each is compiled and rendered on the docs page. Imports are omitted; see above.
 </p>
 ```
 
+### Neutral link: a kanban card title
+
+```tsx
+<div className="w-64 flex items-start gap-2 p-3 border border-[var(--color-border-hairline)] bg-[var(--color-surface-raised)]">
+  <div className="min-w-0 flex-1 text-sm">
+    <Button variant="link" tone="neutral">
+      Replace the hop-up bucking on the second-line support rifles before Saturday
+    </Button>
+  </div>
+  <Button variant="ghost" size="xs">
+    Move
+  </Button>
+</div>
+```
+
 ### Full width
 
 ```tsx
@@ -147,6 +163,7 @@ Each is compiled and rendered on the docs page. Imports are omitted; see above.
 - Use loading on a submit button. It keeps focus while the form works, so a keyboard user is never thrown back to the top of the page.
 - Pass icons through iconStart and iconEnd, not as children. That way they stay hidden from assistive tech and get sized with the button.
 - Use the link variant for an action that sits in running text or next to a heading (‘Reset filters’). Use Link for anything that goes somewhere.
+- Use variant="link" tone="neutral" for a card or row title that opens something on this page, such as the detail panel of a kanban card.
 
 ## Don't
 
@@ -200,5 +217,5 @@ A busy button stays focusable and tells people it's busy through loading. Native
 - **Focus wrapper**: A span that isn't clipped, carrying .bevel-focus-wrap. It draws the ring on :has(:focus-visible), so a mouse click doesn't show it, plus the reticle brackets (corner marks like a targeting sight) that close in on hover. It's always there and never optional.
 - **Button**: The clipped, bevelled control. It never carries its own outline.
 - **Spinner**: Decoration only, shown while loading. The hidden label is what screen readers announce.
-- **Label**: Oxanium semibold, uppercase: the display type role. The link variant switches to the body role, in the signal text colour, underlined.
+- **Label**: Oxanium semibold, uppercase: the display type role. The link variant switches to the body role, in the signal text colour, underlined (or primary text, underlined on hover and focus, with tone="neutral"), and wraps instead of staying on one line.
 - **Icons**: Optional, before and after the label. Each sits in an aria-hidden slot sized to the button (14px at xs and sm, 16px at md, 20px at lg). aria-hidden is an ARIA attribute (Accessible Rich Internet Applications, the labels that tell screen readers what things are) that hides the icon from screen readers. While loading, the spinner takes the leading slot.

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

@@ -31,6 +31,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | `getItemLabel` | `(item: T) => string` |  | Required. The card in plain words. The Move control, its menu and every screen reader announcement use it. |
 | `renderCard` | `(item: T) => ReactNode` |  | Required. The card's body. It can hold one link or button. The board draws the frame. |
 | `renderCardCorner` | `(item: T) => ReactNode` |  | A small mark in the card's bottom-right corner, under the Move control, about 2rem square, such as the owner's avatar. Wrap it in aria-hidden (so screen readers skip it) when the card already prints the same name. |
+| `renderCardMenu` | `(item: T, moveTo: (columnId: string) => void, columnId: string) => ReactNode` |  | Replaces the Move menu's default items (the card's name and a Move to item for each other column) with your own DropdownMenu parts, such as View, Edit or Delete. They go inside the board's menu. Call moveTo(columnId) to move the card the way the default menu does: to the end of that column, with onMove, the announcement and focus back on the Move control. columnId is the card's current column. |
 | `onMove` | `(itemId: string, toColumnId: string, toIndex: number) => void` |  | Required. Called once per move. toIndex is the card's position in the destination column after the move. A move from the menu puts it last. |
 | `emptyColumnMessage` | `string` | `'Nothing here'` | Shown in a column with no cards. |
 | `columnHeadingLevel` | `2 \| 3 \| 4` | `3` | The heading level of the column titles. Pick one that sits under the page's own heading outline. |
@@ -236,6 +237,115 @@ function WorkOrders() {
 <WorkOrders />
 ```
 
+### Your own card menu, with renderCardMenu
+
+```tsx
+type Order = { id: string; title: string; bay: string; status: 'open' | 'parts' | 'done' }
+
+const ORDER_COLUMNS: KanbanColumn[] = [
+  { id: 'open', title: 'Open' },
+  { id: 'parts', title: 'Waiting for parts' },
+  { id: 'done', title: 'Done' },
+]
+
+const ORDERS: Order[] = [
+  { id: 'wo-31', title: 'Replace dock door seal', bay: 'Bay 2', status: 'open' },
+  { id: 'wo-32', title: 'Recalibrate floor scale', bay: 'Bay 5', status: 'open' },
+  { id: 'wo-29', title: 'Service pallet jack', bay: 'Bay 1', status: 'done' },
+]
+
+const orderAccessors = {
+  getItemId: (order: Order) => order.id,
+  getColumnId: (order: Order) => order.status,
+  setColumnId: (order: Order, status: string) => ({ ...order, status: status as Order['status'] }),
+}
+
+const ORDER_LABELS = ['Urgent', 'Safety', 'Contractor'] as const
+
+function WorkOrdersWithMenu() {
+  const [orders, setOrders] = useState(ORDERS)
+  const [labels, setLabels] = useState<Record<string, string[]>>({ 'wo-31': ['Safety'] })
+  const [note, setNote] = useState('')
+  const toggleLabel = (id: string, label: string, on: boolean) =>
+    setLabels(current => ({
+      ...current,
+      [id]: on ? [...(current[id] ?? []), label] : (current[id] ?? []).filter(other => other !== label),
+    }))
+  return (
+    <div className="w-full min-w-0 flex flex-col gap-3">
+      <KanbanBoard
+        label="Depot work orders, with a card menu"
+        columns={ORDER_COLUMNS}
+        items={orders}
+        getItemId={orderAccessors.getItemId}
+        getColumnId={orderAccessors.getColumnId}
+        getItemLabel={order => order.title}
+        renderCard={order => (
+          <div className="flex flex-col gap-1">
+            <p className="font-semibold">{order.title}</p>
+            <p className="font-mono text-xs uppercase tracking-[0.12em] text-[var(--color-text-secondary)]">
+              {[order.bay, ...(labels[order.id] ?? [])].join(' · ')}
+            </p>
+          </div>
+        )}
+        renderCardMenu={(order, moveTo, columnId) => (
+          <>
+            <DropdownMenuItem icon={<Eye />} onSelect={() => setNote(`Opened ${order.title}.`)}>
+              View
+            </DropdownMenuItem>
+            <DropdownMenuItem icon={<Pencil />} onSelect={() => setNote(`Editing ${order.title}.`)}>
+              Edit
+            </DropdownMenuItem>
+            <DropdownMenuSub>
+              <DropdownMenuSubTrigger icon={<Tag />}>Labels</DropdownMenuSubTrigger>
+              <DropdownMenuSubContent>
+                {ORDER_LABELS.map(label => (
+                  <DropdownMenuCheckboxItem
+                    key={label}
+                    checked={(labels[order.id] ?? []).includes(label)}
+                    onCheckedChange={on => toggleLabel(order.id, label, on === true)}
+                    onSelect={event => event.preventDefault()}
+                  >
+                    {label}
+                  </DropdownMenuCheckboxItem>
+                ))}
+              </DropdownMenuSubContent>
+            </DropdownMenuSub>
+            <DropdownMenuSub>
+              <DropdownMenuSubTrigger icon={<ArrowRightLeft />}>Move to</DropdownMenuSubTrigger>
+              <DropdownMenuSubContent>
+                {ORDER_COLUMNS.filter(column => column.id !== columnId).map(column => (
+                  <DropdownMenuItem key={column.id} onSelect={() => moveTo(column.id)}>
+                    {column.title}
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuSubContent>
+            </DropdownMenuSub>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem
+              tone="hostile"
+              icon={<Trash2 />}
+              onSelect={() => {
+                setOrders(current => current.filter(other => other.id !== order.id))
+                setNote(`Deleted ${order.title}.`)
+              }}
+            >
+              Delete
+            </DropdownMenuItem>
+          </>
+        )}
+        onMove={(id, status, index) => setOrders(current => applyKanbanMove(current, id, status, index, orderAccessors))}
+        emptyColumnMessage="No orders waiting"
+        columnHeadingLevel={4}
+      />
+      <p className={docsProse}>{note}</p>
+    </div>
+  )
+}
+
+<WorkOrdersWithMenu />
+```
+
 ## Keyboard
 
 | Keys | Result |

package/public/docs/components/link.md

@@ -19,7 +19,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `'signal' \| 'quiet'` | `'signal'` | Which colour treatment to use. |
+| `tone` | `'signal' \| 'quiet' \| 'neutral'` | `'signal'` | Which colour treatment to use. neutral is primary text with no underline until hover or keyboard focus, for a clickable title in a list or on a card, where it is clear from position that the title is a link. Keep signal for links inside running text. |
 | `external` | `boolean` | `false` | Opens the link in a new tab. It adds target="_blank", the rel hardening (attributes that stop the new page reaching back into yours), a trailing icon and the hidden "(opens in a new tab)" warning. Using it together with target or rel is a type error, so it can't fail silently. external already sets those values, so those props are removed from the type instead of being quietly overwritten while the page runs. |
 | `href` | `string` |  | Where the link goes. |
 | `className` | `string` |  | Merged with the component classes. If two clash, the later Tailwind utility wins (Tailwind is the CSS framework this system styles with). |
@@ -59,6 +59,9 @@ Each is compiled and rendered on the docs page. Imports are omitted; see above.
 <Link href="/kits" tone="quiet">
   Field kits
 </Link>
+<Link href="/kits" tone="neutral">
+  Field kits
+</Link>
 ```
 
 ### External

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

@@ -30,6 +30,9 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | `onValueChange` | `(value: string[]) => void` |  | Runs with the whole new array every time an option is added or removed. |
 | `placeholder` | `string` | `'Select…'` | Shown while nothing is chosen. |
 | `emptyMessage` | `string` | `'No matches'` | Shown in the panel when the typed text matches no option. |
+| `creatable` | `boolean` | `false` | Adds one last row, `Create "<text>"`, when the typed text matches no option (ignoring case). It is never shown for empty text or for text that is already an option. It is an ordinary option in the list: the arrows reach it, Enter or a click chooses it, and screen readers read its label. |
+| `onCreate` | `(text: string) => void` |  | Runs with the typed text, trimmed, when the create row is chosen. The text field is then cleared. The component does not add anything itself: add the new option to options and its value to value here. |
+| `createLabel` | `(text: string) => string` | `(text) => `Create "${text}"`` | The create row's label, for other wording or another language. |
 | `inputSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Matches Input and Select: a minimum height of 32, 40 or 48px (pixels), with text at size xs, sm or base. It also sets the size of the typed text and of the option rows in the list (28, 32 or 40px). The tags come in one size, so sm fits a single row of them snugly, and md and lg add room around it. The field grows past the minimum as tags wrap. |
 | `invalid` | `boolean` | `false` | Sets aria-invalid (which tells screen readers the value has a problem) and the invalid border. FormField sets it from error. |
 | `disabled` | `boolean` | `false` | Turns the field off. The chosen tags stay visible, without their remove buttons. |
@@ -94,6 +97,39 @@ function ControlledExample() {
 <ControlledExample />
 ```
 
+### Creatable: pick or create labels
+
+```tsx
+const LABELS = [
+  { value: 'bug', label: 'Bug' },
+  { value: 'design', label: 'Design' },
+  { value: 'docs', label: 'Docs' },
+]
+
+function CreatableExample() {
+  const [options, setOptions] = useState(LABELS)
+  const [labels, setLabels] = useState<string[]>(['design'])
+  return (
+    <div className="w-full max-w-md">
+      <FormField label="Labels" help="Type a label that is not in the list, then press Enter to create it.">
+        <MultiSelect
+          options={options}
+          value={labels}
+          onValueChange={setLabels}
+          creatable
+          onCreate={text => {
+            setOptions(current => [...current, { value: text, label: text }])
+            setLabels(current => [...current, text])
+          }}
+        />
+      </FormField>
+    </div>
+  )
+}
+
+<CreatableExample />
+```
+
 ### Invalid
 
 ```tsx
@@ -161,6 +197,7 @@ const LOADOUT = [
 |---|---|
 | `↓` `↑` | Opens the list, then moves the highlight, skipping rows that are turned off. |
 | `Enter` | Adds or removes the highlighted option. The list stays open. |
+| `Enter` | On the create row (creatable): runs onCreate with the typed text and clears the text field. |
 | `Backspace` | When the text field is empty, removes the last tag. |
 | `Esc` | Closes the list. Press it again to clear the typed text. |
 | `Tab` | Moves through the tags’ remove buttons and the text field, and closes the list on the way out. |

package/public/docs/components/sidebar.md

@@ -20,7 +20,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `label` | `string` |  | Required. The name screen readers give the navigation region. |
-| `groups` | `SidebarGroup[]` |  | Required. Each group has title, icon, items, collapsible and defaultOpen. |
+| `groups` | `SidebarGroup[]` |  | Required. Each group has title, icon, items, collapsible and defaultOpen, and optionally action (a small icon button at the right end of the title row, beside the fold toggle, never inside it) and footer (under the items, lined up with them, hidden while the group is folded). |
 | `header` | `ReactNode` |  | Sits above the groups: a product name, a workspace switcher. |
 | `footer` | `ReactNode` |  | Pinned below the groups when the Sidebar has a height (h-full in a column layout): the signed-in account, a help link. |
 | `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. |
@@ -54,6 +54,13 @@ export type SidebarGroup = {
   collapsible?: boolean
   /** Ignored when the group holds the current item, which always starts open. @default true */
   defaultOpen?: boolean
+  /** Drawn at the far right of the title row: a small icon button, e.g. a ghost size="sm" Button
+   *  with a Plus icon and aria-label="New project". It sits beside the fold toggle, never inside it,
+   *  so pressing it does not open or close the group. The title truncates before it is pushed out. */
+  action?: ReactNode
+  /** Drawn under the items, inside the group, lined up with the items' left edge and padding: an
+   *  "Add project" button. Hidden (and unreachable by Tab) while the group is folded. */
+  footer?: ReactNode
 }
 ```
 
@@ -104,6 +111,36 @@ const FOOTER = <p className="text-xs text-[var(--color-text-secondary)]">Signed
 </div>
 ```
 
+### A Projects group with an action in its title row and a footer under its items
+
+```tsx
+const PROJECT_GROUPS: SidebarGroup[] = [
+  {
+    title: 'Projects',
+    icon: <FolderKanban />,
+    action: (
+      <IconButton label="New project" variant="ghost" size="sm">
+        <Plus aria-hidden="true" />
+      </IconButton>
+    ),
+    items: [
+      { label: 'Spring restock', href: '#spring-restock', icon: <Folder /> },
+      { label: 'Warehouse move', href: '#warehouse-move', icon: <Folder /> },
+    ],
+    footer: (
+      <Button variant="ghost" size="sm">
+        <Plus aria-hidden="true" />
+        New project
+      </Button>
+    ),
+  },
+]
+
+<div className="max-w-64">
+  <Sidebar label="Projects navigation" groups={PROJECT_GROUPS} />
+</div>
+```
+
 ### In a sheet on a narrow screen: picking a link closes the sheet, through renderLink
 
 ```tsx
@@ -189,5 +226,7 @@ const closeOnChoose = ({ onClick, ...props }: LinkRenderProps) => (
 - **nav**: The navigation region. Screen readers call it by the label prop.
 - **Group title**: A disclosure button (one that shows and hides the list) when the group can fold, plain text when it can't. It's text.secondary, so it still reads on a raised panel. Its list opens and closes by animating its height. Opening also fades and slides each item in, each one a little later than the one before (capped, so a long group never feels slow). Closing fades everything out together, all at once. If someone has asked their system for less motion (prefers-reduced-motion: reduce), both happen instantly.
 - **Item**: An icon, a label and an optional count. The current page gets the fill, plus aria-current, an ARIA attribute (Accessible Rich Internet Applications, the labels screen readers rely on) that tells screen readers this is the page you are on.
+- **Group action**: Optional. A small icon button at the right end of the title row, such as New project. It sits next to the fold toggle, not inside it, so pressing it never folds the group. A long title is cut short before it can push the action out.
+- **Group footer**: Optional. Under the group's items and lined up with them: an Add project button. It folds away with the items.
 - **Header**: Sits above the groups: a product name, a workspace switcher.
 - **Footer**: Pinned below the groups: the signed-in account, a help link.

package/public/docs/components/terminal.md

@@ -29,6 +29,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | `exitCode` | `number` |  | With status exited: shown beside the word, and a non-zero code turns it hostile. |
 | `statusMessage` | `string` |  | Detail beside the status, and announced with it: the reason for an error, the attempt while reconnecting. |
 | `readOnly` | `boolean` | `false` | Blocks input and never fires onData. Selecting and copying keep working, and Tab and Escape leave the terminal as they do anywhere else. |
+| `shiftEnter` | `'newline' \| 'default'` | `'default'` | What Shift+Enter sends. xterm sends the same carriage return as Enter, so a chat program inside submits. newline sends ESC then carriage return instead, which Claude Code and similar programs read as a new line. Not sent while readOnly or composing with an input method. |
 | `announceOutput` | `boolean` | `false` | Reads output aloud through xterm’s live region, up to 20 lines at a time. For a single session a screen reader user is working in. Leave it off when several terminals share a page. |
 | `onData` | `(data: string) => void` |  | What the person typed or pasted, plus the replies a program asks the terminal for. Send it to the process. |
 | `onResize` | `(size: { cols: number; rows: number }) => void` |  | The new grid size, debounced by 100ms and only when cols or rows changed. It fires once after mounting. |
@@ -329,6 +330,7 @@ function SampleTerminal(props: Omit<TerminalProps, 'ref'>) {
 | `Ctrl` `Shift` `L` | Moves focus out of the terminal to the next tab stop. Tab and Escape belong to the program, so this is the way out. |
 | `Ctrl` `C` | With text selected, copies it and clears the selection. With nothing selected, goes to the program as an interrupt. |
 | `Ctrl` `Shift` `C` | Copies the selection and keeps it. |
+| `Shift` `Enter` | Sends Enter to the program, unless shiftEnter is newline, when it sends ESC then Enter: a new line in chat programs such as Claude Code. |
 | `Ctrl` `V` | Pastes. Ctrl+Shift+V does the same. A program that wants a literal Ctrl+V does not get it. |
 
 ## Do
@@ -336,6 +338,7 @@ function SampleTerminal(props: Omit<TerminalProps, 'ref'>) {
 - Give each terminal a label that says which session it is, so a page of them can be told apart.
 - Set readOnly when nobody can usefully type: a finished process, a session someone else owns.
 - Say why in statusMessage when status is error.
+- Set shiftEnter="newline" when the session runs a chat program, such as Claude Code, where Shift+Enter should start a new line.
 - Use write’s callback to pause the source when output arrives faster than the page can draw it.
 
 ## Don't

package/public/manifest/components.json

@@ -266,7 +266,7 @@
       "tier": "atoms",
       "slug": "badge",
       "summary": "A small chip that shows a status. It comes in six tones and two emphases, and it always carries a word. A colour on its own isn't a status anyone can read.",
-      "useWhen": "You need to label a status with a word and a tone, like an order state or a sync result.",
+      "useWhen": "You need to label a status with a word and a tone, like an order state or a sync result. Or a label someone made, like a project tag: then pass color instead of tone.",
       "notFor": "A filter or selection someone can remove. Use Tag for that.",
       "source": "src/components/atoms/badge/Badge.tsx",
       "docs": "/docs/components/badge.md",
@@ -274,7 +274,8 @@
         {
           "names": [
             "Badge",
-            "badgeVariants"
+            "badgeVariants",
+            "CATEGORY_COLORS"
           ],
           "from": "src/components/atoms/badge/Badge"
         }
@@ -284,7 +285,12 @@
           "name": "tone",
           "type": "'neutral' | 'signal' | 'ok' | 'warning' | 'hostile' | 'info'",
           "default": "'neutral'",
-          "description": "The status the badge shows."
+          "description": "The status the badge shows. Leave it out when you pass color."
+        },
+        {
+          "name": "color",
+          "type": "'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'purple' | 'pink' | 'red'",
+          "description": "A category colour for a label people make themselves, like a project tag or a topic. It replaces tone: the types reject passing both. A category colour means 'these belong together', never good or bad. The list is exported as CATEGORY_COLORS, so an app can give each new label one at random. Works with both emphases and both sizes."
         },
         {
           "name": "emphasis",
@@ -331,6 +337,18 @@
           "kind": "const",
           "code": "export const badgeVariants = cva( …",
           "from": "src/components/atoms/badge/Badge"
+        },
+        {
+          "name": "CATEGORY_COLORS",
+          "kind": "const",
+          "code": "/** Categorical colours for labels people make (a project tag, a topic), in the order a picker\n *  shows them. Not statuses: a category colour says \"same group\", never good or bad. Exported so\n *  an app can give each new label one, for example\n *  `CATEGORY_COLORS[Math.floor(Math.random() * CATEGORY_COLORS.length)]`. */\nexport const CATEGORY_COLORS = ['gray', 'brown', 'orange', 'yellow', 'green', 'teal', 'blue', 'purple', 'pink', 'red'] as const",
+          "from": "src/components/atoms/badge/Badge"
+        },
+        {
+          "name": "CategoryColor",
+          "kind": "type",
+          "code": "export type CategoryColor = (typeof CATEGORY_COLORS)[number]",
+          "from": "src/components/atoms/badge/Badge"
         }
       ],
       "keyboard": [],
@@ -338,12 +356,15 @@
         "Give every badge a word.",
         "Go easy on solid. One solid badge in a row reads as the exception. Six read as noise.",
         "Keep the tone mapping the same across the product. ok is never ‘in progress’ on one screen and ‘done’ on another.",
-        "Use size md when the badge sits next to a headline figure, so the two read as one statement."
+        "Use size md when the badge sits next to a headline figure, so the two read as one statement.",
+        "Use tone for a status the system knows (paid, failed, syncing) and color for a label a person made (Design, Q3, Home). A colour on its own is not a status.",
+        "Store the colour with the label, so it stays the same on every screen. Pick one from CATEGORY_COLORS when the label is created."
       ],
       "donts": [
         "Don't build a badge that's colour only, even with a tooltip.",
         "Don't put a badge inside a button. It muddies what the clickable target is.",
         "Don't use hostile for something that's only pending.",
+        "Don't use a category colour to show a status. A red project label is not an error, and an error is tone=\"hostile\", so it means the same thing on every screen.",
         "Don't bevel it (give it a cut corner). At 22px a badge is chrome, the frame around content, not an object with its own footprint. Kbd follows the same rule for the same reason.",
         "Don't resize a badge with height or text classes. The two sizes are the prop. A third size is a change to the system.",
         "Don't use size md in a table row or on a card. It's as tall as a small button, so it starts to look like one.",
@@ -377,6 +398,14 @@
           "caption": "Tones, solid",
           "source": "const TONES = ['neutral', 'signal', 'ok', 'warning', 'hostile', 'info'] as const\n\n{TONES.map(tone => (\n  <Badge key={tone} tone={tone} emphasis=\"solid\">\n    {tone}\n  </Badge>\n))}"
         },
+        {
+          "caption": "Category colours, subtle: labels people make, not statuses",
+          "source": "{CATEGORY_COLORS.map(color => (\n  <Badge key={color} color={color}>\n    {color}\n  </Badge>\n))}"
+        },
+        {
+          "caption": "Category colours, solid",
+          "source": "{CATEGORY_COLORS.map(color => (\n  <Badge key={color} color={color} emphasis=\"solid\">\n    {color}\n  </Badge>\n))}"
+        },
         {
           "caption": "With a dot",
           "source": "<Badge tone=\"ok\" dot>\n  Nominal\n</Badge>\n<Badge tone=\"warning\" dot>\n  Degraded\n</Badge>\n<Badge tone=\"hostile\" dot>\n  Offline\n</Badge>"
@@ -426,6 +455,12 @@
           "default": "'primary'",
           "description": "Which fill/border treatment to use. link looks like a Link (signal text, underline, no fill, no bevel, no fixed height) but it's still a button. Use it for an action inside a sentence, not for going to another page."
         },
+        {
+          "name": "tone",
+          "type": "'signal' | 'neutral'",
+          "default": "'signal'",
+          "description": "Only the link variant reads it. signal is the signal-coloured, underlined link. neutral is primary text with no underline until hover or keyboard focus: use it for a clickable title on a kanban card or a list row, where a column of signal links would be too loud. A link-variant label wraps onto more lines rather than overflowing its column."
+        },
         {
           "name": "size",
           "type": "'xs' | 'sm' | 'md' | 'lg'",
@@ -528,7 +563,8 @@
         "Use loading instead of disabling the button and swapping the label yourself.",
         "Use loading on a submit button. It keeps focus while the form works, so a keyboard user is never thrown back to the top of the page.",
         "Pass icons through iconStart and iconEnd, not as children. That way they stay hidden from assistive tech and get sized with the button.",
-        "Use the link variant for an action that sits in running text or next to a heading (‘Reset filters’). Use Link for anything that goes somewhere."
+        "Use the link variant for an action that sits in running text or next to a heading (‘Reset filters’). Use Link for anything that goes somewhere.",
+        "Use variant=\"link\" tone=\"neutral\" for a card or row title that opens something on this page, such as the detail panel of a kanban card."
       ],
       "donts": [
         "Don't add bevel-* or an outline class yourself. You'll clip the ring off.",
@@ -567,7 +603,7 @@
         },
         {
           "part": "Label",
-          "description": "Oxanium semibold, uppercase: the display type role. The link variant switches to the body role, in the signal text colour, underlined."
+          "description": "Oxanium semibold, uppercase: the display type role. The link variant switches to the body role, in the signal text colour, underlined (or primary text, underlined on hover and focus, with tone=\"neutral\"), and wraps instead of staying on one line."
         },
         {
           "part": "Icons",
@@ -595,6 +631,10 @@
           "caption": "Link variant",
           "source": "<p className=\"text-sm text-[var(--color-text-secondary)] max-w-md\">\n  No replicas match these filters.{' '}\n  <Button variant=\"link\">\n    Reset filters\n  </Button>{' '}\n  to see the full catalogue.\n</p>"
         },
+        {
+          "caption": "Neutral link: a kanban card title",
+          "source": "<div className=\"w-64 flex items-start gap-2 p-3 border border-[var(--color-border-hairline)] bg-[var(--color-surface-raised)]\">\n  <div className=\"min-w-0 flex-1 text-sm\">\n    <Button variant=\"link\" tone=\"neutral\">\n      Replace the hop-up bucking on the second-line support rifles before Saturday\n    </Button>\n  </div>\n  <Button variant=\"ghost\" size=\"xs\">\n    Move\n  </Button>\n</div>"
+        },
         {
           "caption": "Full width",
           "source": "<div className=\"w-80\">\n  <Button fullWidth>Dispatch team</Button>\n</div>"
@@ -1327,9 +1367,9 @@
       "props": [
         {
           "name": "tone",
-          "type": "'signal' | 'quiet'",
+          "type": "'signal' | 'quiet' | 'neutral'",
           "default": "'signal'",
-          "description": "Which colour treatment to use."
+          "description": "Which colour treatment to use. neutral is primary text with no underline until hover or keyboard focus, for a clickable title in a list or on a card, where it is clear from position that the title is a link. Keep signal for links inside running text."
         },
         {
           "name": "external",
@@ -1417,7 +1457,7 @@
         },
         {
           "caption": "Tones",
-          "source": "<Link href=\"/kits\" tone=\"signal\">\n  Field kits\n</Link>\n<Link href=\"/kits\" tone=\"quiet\">\n  Field kits\n</Link>"
+          "source": "<Link href=\"/kits\" tone=\"signal\">\n  Field kits\n</Link>\n<Link href=\"/kits\" tone=\"quiet\">\n  Field kits\n</Link>\n<Link href=\"/kits\" tone=\"neutral\">\n  Field kits\n</Link>"
         },
         {
           "caption": "External",
@@ -6283,6 +6323,23 @@
           "default": "'No matches'",
           "description": "Shown in the panel when the typed text matches no option."
         },
+        {
+          "name": "creatable",
+          "type": "boolean",
+          "default": "false",
+          "description": "Adds one last row, `Create \"<text>\"`, when the typed text matches no option (ignoring case). It is never shown for empty text or for text that is already an option. It is an ordinary option in the list: the arrows reach it, Enter or a click chooses it, and screen readers read its label."
+        },
+        {
+          "name": "onCreate",
+          "type": "(text: string) => void",
+          "description": "Runs with the typed text, trimmed, when the create row is chosen. The text field is then cleared. The component does not add anything itself: add the new option to options and its value to value here."
+        },
+        {
+          "name": "createLabel",
+          "type": "(text: string) => string",
+          "default": "(text) => `Create \"${text}\"`",
+          "description": "The create row's label, for other wording or another language."
+        },
         {
           "name": "inputSize",
           "type": "'sm' | 'md' | 'lg'",
@@ -6347,6 +6404,12 @@
           ],
           "does": "Adds or removes the highlighted option. The list stays open."
         },
+        {
+          "keys": [
+            "Enter"
+          ],
+          "does": "On the create row (creatable): runs onCreate with the typed text and clears the text field."
+        },
         {
           "keys": [
             "Backspace"
@@ -6411,6 +6474,10 @@
           "caption": "Controlled: the page holds the chosen options",
           "source": "const LOADOUT = [\n  { value: 'mags', label: 'Spare magazines' },\n  { value: 'goggles', label: 'Full-seal goggles' },\n  { value: 'mesh', label: 'Mesh face guard' },\n  { value: 'radio', label: 'Team radio', disabled: true },\n  { value: 'gloves', label: 'Gloves' },\n  { value: 'loader', label: 'Speed loader' },\n  { value: 'tracer', label: 'Tracer unit' },\n  { value: 'pouch', label: 'Dump pouch' },\n]\n\nfunction ControlledExample() {\n  const [kit, setKit] = useState<string[]>(['mags', 'goggles', 'gloves'])\n  return (\n    <div className=\"flex flex-col gap-2 w-full max-w-md\">\n      <FormField label=\"Loadout\" help=\"Remove a tag and watch the others close the gap.\">\n        <MultiSelect options={LOADOUT} value={kit} onValueChange={setKit} />\n      </FormField>\n      <span className=\"font-mono text-xs text-[var(--color-text-secondary)]\">value: [{kit.join(', ')}]</span>\n    </div>\n  )\n}\n\n<ControlledExample />"
         },
+        {
+          "caption": "Creatable: pick or create labels",
+          "source": "const LABELS = [\n  { value: 'bug', label: 'Bug' },\n  { value: 'design', label: 'Design' },\n  { value: 'docs', label: 'Docs' },\n]\n\nfunction CreatableExample() {\n  const [options, setOptions] = useState(LABELS)\n  const [labels, setLabels] = useState<string[]>(['design'])\n  return (\n    <div className=\"w-full max-w-md\">\n      <FormField label=\"Labels\" help=\"Type a label that is not in the list, then press Enter to create it.\">\n        <MultiSelect\n          options={options}\n          value={labels}\n          onValueChange={setLabels}\n          creatable\n          onCreate={text => {\n            setOptions(current => [...current, { value: text, label: text }])\n            setLabels(current => [...current, text])\n          }}\n        />\n      </FormField>\n    </div>\n  )\n}\n\n<CreatableExample />"
+        },
         {
           "caption": "Invalid",
           "source": "const LOADOUT = [\n  { value: 'mags', label: 'Spare magazines' },\n  { value: 'goggles', label: 'Full-seal goggles' },\n  { value: 'mesh', label: 'Mesh face guard' },\n  { value: 'radio', label: 'Team radio', disabled: true },\n  { value: 'gloves', label: 'Gloves' },\n  { value: 'loader', label: 'Speed loader' },\n  { value: 'tracer', label: 'Tracer unit' },\n  { value: 'pouch', label: 'Dump pouch' },\n]\n\n<div className=\"w-full max-w-md\">\n  <FormField label=\"Loadout\" error=\"Pick eye protection.\">\n    <MultiSelect options={LOADOUT} defaultValue={['mags']} />\n  </FormField>\n</div>"
@@ -11091,6 +11158,11 @@
           "type": "(item: T) => ReactNode",
           "description": "A small mark in the card's bottom-right corner, under the Move control, about 2rem square, such as the owner's avatar. Wrap it in aria-hidden (so screen readers skip it) when the card already prints the same name."
         },
+        {
+          "name": "renderCardMenu",
+          "type": "(item: T, moveTo: (columnId: string) => void, columnId: string) => ReactNode",
+          "description": "Replaces the Move menu's default items (the card's name and a Move to item for each other column) with your own DropdownMenu parts, such as View, Edit or Delete. They go inside the board's menu. Call moveTo(columnId) to move the card the way the default menu does: to the end of that column, with onMove, the announcement and focus back on the Move control. columnId is the card's current column."
+        },
         {
           "name": "onMove",
           "type": "(itemId: string, toColumnId: string, toIndex: number) => void",
@@ -11271,6 +11343,10 @@
         {
           "caption": "Work orders, with an empty column",
           "source": "type Order = { id: string; title: string; bay: string; status: 'open' | 'parts' | 'done' }\n\nconst ORDER_COLUMNS: KanbanColumn[] = [\n  { id: 'open', title: 'Open' },\n  { id: 'parts', title: 'Waiting for parts' },\n  { id: 'done', title: 'Done' },\n]\n\nconst ORDERS: Order[] = [\n  { id: 'wo-31', title: 'Replace dock door seal', bay: 'Bay 2', status: 'open' },\n  { id: 'wo-32', title: 'Recalibrate floor scale', bay: 'Bay 5', status: 'open' },\n  { id: 'wo-29', title: 'Service pallet jack', bay: 'Bay 1', status: 'done' },\n]\n\nconst orderAccessors = {\n  getItemId: (order: Order) => order.id,\n  getColumnId: (order: Order) => order.status,\n  setColumnId: (order: Order, status: string) => ({ ...order, status: status as Order['status'] }),\n}\n\nfunction WorkOrders() {\n  const [orders, setOrders] = useState(ORDERS)\n  return (\n    <div className=\"w-full min-w-0\">\n      <KanbanBoard\n        label=\"Depot work orders\"\n        columns={ORDER_COLUMNS}\n        items={orders}\n        getItemId={orderAccessors.getItemId}\n        getColumnId={orderAccessors.getColumnId}\n        getItemLabel={order => order.title}\n        renderCard={order => (\n          <div className=\"flex flex-col gap-1\">\n            <p className=\"font-semibold\">{order.title}</p>\n            <p className=\"font-mono text-xs uppercase tracking-[0.12em] text-[var(--color-text-secondary)]\">{order.bay}</p>\n          </div>\n        )}\n        onMove={(id, status, index) => setOrders(current => applyKanbanMove(current, id, status, index, orderAccessors))}\n        emptyColumnMessage=\"No orders waiting\"\n        columnHeadingLevel={4}\n      />\n    </div>\n  )\n}\n\n<WorkOrders />"
+        },
+        {
+          "caption": "Your own card menu, with renderCardMenu",
+          "source": "type Order = { id: string; title: string; bay: string; status: 'open' | 'parts' | 'done' }\n\nconst ORDER_COLUMNS: KanbanColumn[] = [\n  { id: 'open', title: 'Open' },\n  { id: 'parts', title: 'Waiting for parts' },\n  { id: 'done', title: 'Done' },\n]\n\nconst ORDERS: Order[] = [\n  { id: 'wo-31', title: 'Replace dock door seal', bay: 'Bay 2', status: 'open' },\n  { id: 'wo-32', title: 'Recalibrate floor scale', bay: 'Bay 5', status: 'open' },\n  { id: 'wo-29', title: 'Service pallet jack', bay: 'Bay 1', status: 'done' },\n]\n\nconst orderAccessors = {\n  getItemId: (order: Order) => order.id,\n  getColumnId: (order: Order) => order.status,\n  setColumnId: (order: Order, status: string) => ({ ...order, status: status as Order['status'] }),\n}\n\nconst ORDER_LABELS = ['Urgent', 'Safety', 'Contractor'] as const\n\nfunction WorkOrdersWithMenu() {\n  const [orders, setOrders] = useState(ORDERS)\n  const [labels, setLabels] = useState<Record<string, string[]>>({ 'wo-31': ['Safety'] })\n  const [note, setNote] = useState('')\n  const toggleLabel = (id: string, label: string, on: boolean) =>\n    setLabels(current => ({\n      ...current,\n      [id]: on ? [...(current[id] ?? []), label] : (current[id] ?? []).filter(other => other !== label),\n    }))\n  return (\n    <div className=\"w-full min-w-0 flex flex-col gap-3\">\n      <KanbanBoard\n        label=\"Depot work orders, with a card menu\"\n        columns={ORDER_COLUMNS}\n        items={orders}\n        getItemId={orderAccessors.getItemId}\n        getColumnId={orderAccessors.getColumnId}\n        getItemLabel={order => order.title}\n        renderCard={order => (\n          <div className=\"flex flex-col gap-1\">\n            <p className=\"font-semibold\">{order.title}</p>\n            <p className=\"font-mono text-xs uppercase tracking-[0.12em] text-[var(--color-text-secondary)]\">\n              {[order.bay, ...(labels[order.id] ?? [])].join(' · ')}\n            </p>\n          </div>\n        )}\n        renderCardMenu={(order, moveTo, columnId) => (\n          <>\n            <DropdownMenuItem icon={<Eye />} onSelect={() => setNote(`Opened ${order.title}.`)}>\n              View\n            </DropdownMenuItem>\n            <DropdownMenuItem icon={<Pencil />} onSelect={() => setNote(`Editing ${order.title}.`)}>\n              Edit\n            </DropdownMenuItem>\n            <DropdownMenuSub>\n              <DropdownMenuSubTrigger icon={<Tag />}>Labels</DropdownMenuSubTrigger>\n              <DropdownMenuSubContent>\n                {ORDER_LABELS.map(label => (\n                  <DropdownMenuCheckboxItem\n                    key={label}\n                    checked={(labels[order.id] ?? []).includes(label)}\n                    onCheckedChange={on => toggleLabel(order.id, label, on === true)}\n                    onSelect={event => event.preventDefault()}\n                  >\n                    {label}\n                  </DropdownMenuCheckboxItem>\n                ))}\n              </DropdownMenuSubContent>\n            </DropdownMenuSub>\n            <DropdownMenuSub>\n              <DropdownMenuSubTrigger icon={<ArrowRightLeft />}>Move to</DropdownMenuSubTrigger>\n              <DropdownMenuSubContent>\n                {ORDER_COLUMNS.filter(column => column.id !== columnId).map(column => (\n                  <DropdownMenuItem key={column.id} onSelect={() => moveTo(column.id)}>\n                    {column.title}\n                  </DropdownMenuItem>\n                ))}\n              </DropdownMenuSubContent>\n            </DropdownMenuSub>\n            <DropdownMenuSeparator />\n            <DropdownMenuItem\n              tone=\"hostile\"\n              icon={<Trash2 />}\n              onSelect={() => {\n                setOrders(current => current.filter(other => other.id !== order.id))\n                setNote(`Deleted ${order.title}.`)\n              }}\n            >\n              Delete\n            </DropdownMenuItem>\n          </>\n        )}\n        onMove={(id, status, index) => setOrders(current => applyKanbanMove(current, id, status, index, orderAccessors))}\n        emptyColumnMessage=\"No orders waiting\"\n        columnHeadingLevel={4}\n      />\n      <p className={docsProse}>{note}</p>\n    </div>\n  )\n}\n\n<WorkOrdersWithMenu />"
         }
       ],
       "closed": true
@@ -11935,7 +12011,7 @@
         {
           "name": "groups",
           "type": "SidebarGroup[]",
-          "description": "Required. Each group has title, icon, items, collapsible and defaultOpen."
+          "description": "Required. Each group has title, icon, items, collapsible and defaultOpen, and optionally action (a small icon button at the right end of the title row, beside the fold toggle, never inside it) and footer (under the items, lined up with them, hidden while the group is folded)."
         },
         {
           "name": "header",
@@ -11974,7 +12050,7 @@
         {
           "name": "SidebarGroup",
           "kind": "type",
-          "code": "export type SidebarGroup = {\n  /** Also the React key for this group; unique within a Sidebar. */\n  title: string\n  /** Drawn before the title, aria-hidden; the title alone names the group. */\n  icon?: ReactNode\n  items: SidebarItem[]\n  /** @default true */\n  collapsible?: boolean\n  /** Ignored when the group holds the current item, which always starts open. @default true */\n  defaultOpen?: boolean\n}",
+          "code": "export type SidebarGroup = {\n  /** Also the React key for this group; unique within a Sidebar. */\n  title: string\n  /** Drawn before the title, aria-hidden; the title alone names the group. */\n  icon?: ReactNode\n  items: SidebarItem[]\n  /** @default true */\n  collapsible?: boolean\n  /** Ignored when the group holds the current item, which always starts open. @default true */\n  defaultOpen?: boolean\n  /** Drawn at the far right of the title row: a small icon button, e.g. a ghost size=\"sm\" Button\n   *  with a Plus icon and aria-label=\"New project\". It sits beside the fold toggle, never inside it,\n   *  so pressing it does not open or close the group. The title truncates before it is pushed out. */\n  action?: ReactNode\n  /** Drawn under the items, inside the group, lined up with the items' left edge and padding: an\n   *  \"Add project\" button. Hidden (and unreachable by Tab) while the group is folded. */\n  footer?: ReactNode\n}",
           "from": "src/components/organisms/sidebar/Sidebar"
         }
       ],
@@ -12021,6 +12097,14 @@
           "part": "Item",
           "description": "An icon, a label and an optional count. The current page gets the fill, plus aria-current, an ARIA attribute (Accessible Rich Internet Applications, the labels screen readers rely on) that tells screen readers this is the page you are on."
         },
+        {
+          "part": "Group action",
+          "description": "Optional. A small icon button at the right end of the title row, such as New project. It sits next to the fold toggle, not inside it, so pressing it never folds the group. A long title is cut short before it can push the action out."
+        },
+        {
+          "part": "Group footer",
+          "description": "Optional. Under the group's items and lined up with them: an Add project button. It folds away with the items."
+        },
         {
           "part": "Header",
           "description": "Sits above the groups: a product name, a workspace switcher."
@@ -12035,6 +12119,10 @@
           "caption": "Dashboard navigation",
           "source": "const GROUPS: SidebarGroup[] = [\n  {\n    title: 'Operations',\n    icon: <Warehouse />,\n    items: [\n      { label: 'Overview', href: '#overview', icon: <LayoutDashboard /> },\n      { label: 'Orders', href: '#orders', icon: <Package />, current: true, count: 12 },\n      { label: 'Shipments', href: '#shipments', icon: <Truck /> },\n      { label: 'Returns', href: '#returns', icon: <Inbox />, count: 3 },\n    ],\n  },\n  {\n    title: 'Catalogue',\n    icon: <Boxes />,\n    defaultOpen: false,\n    items: [\n      { label: 'Products', href: '#products', icon: <Box /> },\n      { label: 'Inventory', href: '#inventory', icon: <Map /> },\n    ],\n  },\n  {\n    title: 'Account',\n    icon: <UserCog />,\n    collapsible: false,\n    items: [\n      { label: 'Settings', href: '#settings', icon: <Settings /> },\n      { label: 'Team', href: '#team', icon: <Users /> },\n    ],\n  },\n]\n\nconst HEADER = <p className=\"font-display font-semibold\">Hexline ops</p>\n\nconst FOOTER = <p className=\"text-xs text-[var(--color-text-secondary)]\">Signed in as Ana Pop</p>\n\n<div className=\"max-w-64\">\n  <Sidebar label=\"Dashboard navigation\" groups={GROUPS} header={HEADER} footer={FOOTER} />\n</div>"
         },
+        {
+          "caption": "A Projects group with an action in its title row and a footer under its items",
+          "source": "const PROJECT_GROUPS: SidebarGroup[] = [\n  {\n    title: 'Projects',\n    icon: <FolderKanban />,\n    action: (\n      <IconButton label=\"New project\" variant=\"ghost\" size=\"sm\">\n        <Plus aria-hidden=\"true\" />\n      </IconButton>\n    ),\n    items: [\n      { label: 'Spring restock', href: '#spring-restock', icon: <Folder /> },\n      { label: 'Warehouse move', href: '#warehouse-move', icon: <Folder /> },\n    ],\n    footer: (\n      <Button variant=\"ghost\" size=\"sm\">\n        <Plus aria-hidden=\"true\" />\n        New project\n      </Button>\n    ),\n  },\n]\n\n<div className=\"max-w-64\">\n  <Sidebar label=\"Projects navigation\" groups={PROJECT_GROUPS} />\n</div>"
+        },
         {
           "caption": "In a sheet on a narrow screen: picking a link closes the sheet, through renderLink",
           "source": "const GROUPS: SidebarGroup[] = [\n  {\n    title: 'Operations',\n    icon: <Warehouse />,\n    items: [\n      { label: 'Overview', href: '#overview', icon: <LayoutDashboard /> },\n      { label: 'Orders', href: '#orders', icon: <Package />, current: true, count: 12 },\n      { label: 'Shipments', href: '#shipments', icon: <Truck /> },\n      { label: 'Returns', href: '#returns', icon: <Inbox />, count: 3 },\n    ],\n  },\n  {\n    title: 'Catalogue',\n    icon: <Boxes />,\n    defaultOpen: false,\n    items: [\n      { label: 'Products', href: '#products', icon: <Box /> },\n      { label: 'Inventory', href: '#inventory', icon: <Map /> },\n    ],\n  },\n  {\n    title: 'Account',\n    icon: <UserCog />,\n    collapsible: false,\n    items: [\n      { label: 'Settings', href: '#settings', icon: <Settings /> },\n      { label: 'Team', href: '#team', icon: <Users /> },\n    ],\n  },\n]\n\nconst HEADER = <p className=\"font-display font-semibold\">Hexline ops</p>\n\nconst FOOTER = <p className=\"text-xs text-[var(--color-text-secondary)]\">Signed in as Ana Pop</p>\n\nconst closeOnChoose = ({ onClick, ...props }: LinkRenderProps) => (\n  <SheetClose asChild type={undefined}>\n    <a {...props} onClick={onClick} />\n  </SheetClose>\n)\n\n<Sheet>\n  <SheetTrigger asChild>\n    <Button variant=\"secondary\">Open navigation</Button>\n  </SheetTrigger>\n  <SheetContent side=\"left\" title=\"Navigation\">\n    <Sidebar\n      label=\"Dashboard navigation, in a sheet\"\n      groups={GROUPS}\n      header={HEADER}\n      footer={FOOTER}\n      renderLink={closeOnChoose}\n    />\n  </SheetContent>\n</Sheet>"
@@ -12091,6 +12179,12 @@
           "default": "false",
           "description": "Blocks input and never fires onData. Selecting and copying keep working, and Tab and Escape leave the terminal as they do anywhere else."
         },
+        {
+          "name": "shiftEnter",
+          "type": "'newline' | 'default'",
+          "default": "'default'",
+          "description": "What Shift+Enter sends. xterm sends the same carriage return as Enter, so a chat program inside submits. newline sends ESC then carriage return instead, which Claude Code and similar programs read as a new line. Not sent while readOnly or composing with an input method."
+        },
         {
           "name": "announceOutput",
           "type": "boolean",
@@ -12188,6 +12282,13 @@
           ],
           "does": "Copies the selection and keeps it."
         },
+        {
+          "keys": [
+            "Shift",
+            "Enter"
+          ],
+          "does": "Sends Enter to the program, unless shiftEnter is newline, when it sends ESC then Enter: a new line in chat programs such as Claude Code."
+        },
         {
           "keys": [
             "Ctrl",
@@ -12200,6 +12301,7 @@
         "Give each terminal a label that says which session it is, so a page of them can be told apart.",
         "Set readOnly when nobody can usefully type: a finished process, a session someone else owns.",
         "Say why in statusMessage when status is error.",
+        "Set shiftEnter=\"newline\" when the session runs a chat program, such as Claude Code, where Shift+Enter should start a new line.",
         "Use write’s callback to pause the source when output arrives faster than the page can draw it."
       ],
       "donts": [

package/public/manifest/tokens.json

@@ -755,6 +755,216 @@
         "light": "10.76:1 on accent.warning.fill"
       }
     },
+    {
+      "name": "--color-category-gray-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#a3a9b3",
+        "light": "#5c636e"
+      },
+      "use": "Subtle Badge color=\"gray\": text and border. A label, not a status."
+    },
+    {
+      "name": "--color-category-gray-fill",
+      "layer": "semantic",
+      "value": "#9aa1ab",
+      "use": "Solid Badge color=\"gray\": the fill."
+    },
+    {
+      "name": "--color-category-gray-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on category.gray.fill."
+    },
+    {
+      "name": "--color-category-brown-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#c9a383",
+        "light": "#7a5232"
+      },
+      "use": "Subtle Badge color=\"brown\": text and border. A label, not a status."
+    },
+    {
+      "name": "--color-category-brown-fill",
+      "layer": "semantic",
+      "value": "#b98a64",
+      "use": "Solid Badge color=\"brown\": the fill."
+    },
+    {
+      "name": "--color-category-brown-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on category.brown.fill."
+    },
+    {
+      "name": "--color-category-orange-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#f0a060",
+        "light": "#a34a00"
+      },
+      "use": "Subtle Badge color=\"orange\": text and border. A label, not a status."
+    },
+    {
+      "name": "--color-category-orange-fill",
+      "layer": "semantic",
+      "value": "#f0913a",
+      "use": "Solid Badge color=\"orange\": the fill."
+    },
+    {
+      "name": "--color-category-orange-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on category.orange.fill."
+    },
+    {
+      "name": "--color-category-yellow-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#e6c65a",
+        "light": "#7a5c00"
+      },
+      "use": "Subtle Badge color=\"yellow\": text and border. A label, not a status."
+    },
+    {
+      "name": "--color-category-yellow-fill",
+      "layer": "semantic",
+      "value": "#e8c341",
+      "use": "Solid Badge color=\"yellow\": the fill."
+    },
+    {
+      "name": "--color-category-yellow-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on category.yellow.fill."
+    },
+    {
+      "name": "--color-category-green-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#6fcf8f",
+        "light": "#1e6b3a"
+      },
+      "use": "Subtle Badge color=\"green\": text and border. A label, not a status."
+    },
+    {
+      "name": "--color-category-green-fill",
+      "layer": "semantic",
+      "value": "#4fbf7a",
+      "use": "Solid Badge color=\"green\": the fill."
+    },
+    {
+      "name": "--color-category-green-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on category.green.fill."
+    },
+    {
+      "name": "--color-category-teal-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#5ccfc4",
+        "light": "#0d6662"
+      },
+      "use": "Subtle Badge color=\"teal\": text and border. A label, not a status."
+    },
+    {
+      "name": "--color-category-teal-fill",
+      "layer": "semantic",
+      "value": "#3fbfb2",
+      "use": "Solid Badge color=\"teal\": the fill."
+    },
+    {
+      "name": "--color-category-teal-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on category.teal.fill."
+    },
+    {
+      "name": "--color-category-blue-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#7fb2ff",
+        "light": "#1f5fbf"
+      },
+      "use": "Subtle Badge color=\"blue\": text and border. A label, not a status."
+    },
+    {
+      "name": "--color-category-blue-fill",
+      "layer": "semantic",
+      "value": "#6fa3f5",
+      "use": "Solid Badge color=\"blue\": the fill."
+    },
+    {
+      "name": "--color-category-blue-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on category.blue.fill."
+    },
+    {
+      "name": "--color-category-purple-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#b59cf5",
+        "light": "#6a3fbf"
+      },
+      "use": "Subtle Badge color=\"purple\": text and border. A label, not a status."
+    },
+    {
+      "name": "--color-category-purple-fill",
+      "layer": "semantic",
+      "value": "#a88af0",
+      "use": "Solid Badge color=\"purple\": the fill."
+    },
+    {
+      "name": "--color-category-purple-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on category.purple.fill."
+    },
+    {
+      "name": "--color-category-pink-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#f08fc4",
+        "light": "#a3306f"
+      },
+      "use": "Subtle Badge color=\"pink\": text and border. A label, not a status."
+    },
+    {
+      "name": "--color-category-pink-fill",
+      "layer": "semantic",
+      "value": "#ec84bb",
+      "use": "Solid Badge color=\"pink\": the fill."
+    },
+    {
+      "name": "--color-category-pink-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on category.pink.fill."
+    },
+    {
+      "name": "--color-category-red-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#f58a8a",
+        "light": "#b42828"
+      },
+      "use": "Subtle Badge color=\"red\": text and border. A label, not a status."
+    },
+    {
+      "name": "--color-category-red-fill",
+      "layer": "semantic",
+      "value": "#f07a7a",
+      "use": "Solid Badge color=\"red\": the fill."
+    },
+    {
+      "name": "--color-category-red-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on category.red.fill."
+    },
     {
       "name": "--color-numeral-pad",
       "layer": "semantic",