@arbor-education/design-system.components 0.13.0 → 0.13.1

package/.agent-memory/rose-storybookspert/MEMORY.md

@@ -0,0 +1,105 @@
+# Rose's Storybookspert Memory
+
+See `patterns.md` for full details on codebase conventions.
+
+## Quick Reference
+
+- Meta/StoryObj import: `from '@storybook/react-vite'`
+- fn() import: `from 'storybook/test'` (NOT `@storybook/test`)
+- Meta pattern: `satisfies Meta<typeof ComponentName>` with `export default meta`
+- Story type: `type Story = StoryObj<typeof ComponentName>` (the component, not meta) — avoids strict required-prop issues in render-only stories
+- Storybook version: v9 (storybook package) with `@storybook/react-vite` ^9.1.8
+- Page-level stories: use `layout: 'fullscreen'` in parameters
+- `src/pages/` does NOT exist on the current branch (confirmed 2026-04-17) — this directory was on a previous branch and may not be present
+- Story files use `.stories.tsx` extension (not `.story.tsx` for new files)
+- tsconfig excludes `*.story.tsx` but includes `*.stories.tsx` and `*.test.tsx`
+
+## useState in Story Render Functions
+
+- Do NOT use `eslint-disable-next-line react-hooks/rules-of-hooks` — the `react-hooks` plugin
+  is NOT configured in this project's eslint.config.mts, so the disable comment itself causes
+  an ESLint error ("Definition for rule not found").
+- Instead, extract stateful render logic into a named template component defined above the story:
+  `const MyTemplate = (args: React.ComponentProps<typeof MyComponent>) => { ... }`
+  then reference it: `render: MyTemplate`. See Toast.stories.tsx for the inline render alternative
+  (useState directly in the render arrow function also works fine without any disable comment).
+
+## Markdown Descriptions with Backtick Code Spans
+
+- Do NOT put multi-line markdown component descriptions in template literals (backtick strings) — code spans inside them require `\`` escaping, which ESLint flags as `no-useless-escape` (not auto-fixable).
+- Instead, build multi-line descriptions as a `const string[] joined with .join('\n')`, e.g.:
+  `const COMPONENT_DESCRIPTION = ['line 1', '`code`', ...].join('\n');`
+  This lets backtick code spans appear unescaped in regular single-quoted strings.
+- Story-level `withDescription` descriptions are single-line strings — backticks in those are fine unescaped in single-quoted strings.
+- ALSO avoid `\`` in array string elements that show template literal examples (e.g. showing a getValueLabel callback). Instead, rephrase as prose or use string concatenation notation: `(v, m) => v + " of " + m`. ESLint flags `\`` inside single-quoted strings as `no-useless-escape`.
+
+## Icon Component — Key Facts
+
+- `allowedIcons` has 106 keys; `iconSizes = [12, 16, 24] as const` — spread with `[...iconSizes]` for argTypes.options
+- SVG always `aria-hidden`; accessible label via `<span class="sr-only">` via `screenReaderText` prop
+- `bell` is NOT in allowedIcons — use `dot`, `info`, `mail`, etc. for demo icons in AllSizes-style stories
+- Icon gallery: use `ICON_CATEGORIES` pattern with verified keys only; `users` is NOT a key (use `guardians` = Users)
+- The Icon component does NOT have compound sub-components — use the simple global DocsTemplate pattern
+
+## Compound Components — Simple Pattern (No Custom docs.page)
+
+- When a compound component's sub-component only has `HTMLAttributes<HTMLElement>` props (no custom props worth an ArgTypes table), use the simple pattern: `parameters.docs.description.component` + `parameters.docs.relatedComponents`. Document the sub-component props as a Markdown table inline in the description string.
+- Only use a custom `docs.page` with `ArgTypes of={SubComponent}` when the sub-component has meaningful custom props that benefit from interactive documentation.
+- Example of simple pattern: `Heading` / `Heading.InnerContainer` — InnerContainer has only `className` + `HTMLAttributes<HTMLSpanElement>`, documented in the COMPONENT_DESCRIPTION Markdown table.
+
+## Import Hygiene Reminder
+
+- When porting/rewriting stories, audit every import — only import what is actually used in JSX.
+- `Icon` is commonly imported in old stories but new stories may use `iconLeftName`/`iconRightName` props on Button instead of rendering `<Icon>` directly. Remove unused Icon imports or ESLint will error.
+
+## Discriminated Union Components (FormField pattern)
+
+- When a component uses a discriminated union for props (e.g. `inputType` narrows `inputProps`), set `control: false` for the union prop in argTypes — Controls cannot represent a type that changes shape.
+- Document the union in the argTypes description and note that it must be configured in story code.
+- Use `StoryObj<typeof ComponentName>` (not `typeof meta`) so render-only stories don't get forced to satisfy the union — discriminated union types make TypeScript very strict about which arms are satisfied.
+- Example: FormField `inputProps` depends on `inputType` — `control: false` on `inputProps`, each variant story is a separate `render: () => <FormField inputType="..." inputProps={{...}} />`.
+
+## TextInput / FormField Input Layer Pattern
+
+- TextInput is a bare `forwardRef` input; `hasError` is purely visual — always pair with `aria-invalid="true"` on bare usage
+- FormField auto-wires `hasError`, `aria-invalid`, and `aria-describedby`; never pass these in `inputProps` when using FormField
+- In stories files, import FormField via path alias: `import { FormField } from 'Components/formField/FormField'` (not a relative path)
+- `type Story = StoryObj<typeof TextInput>` (component, not meta) avoids strict discriminated-union TS errors
+
+## NumberInput — Key Facts for Stories
+
+- NumberInput uses `type="text"` with `inputMode="numeric"` — arrow keys do NOT increment; spinners do
+- `onChange` fires from a `useEffect` — manually constructed event, ONLY `e.currentTarget.value` is set; `e.target.value` is undefined
+- `defaultValue` guard: if truthy `defaultValue` is set, `value` prop changes are silently ignored after mount — never mix both
+- `onBlur` prop: consumer's `onBlur` WINS and silently kills blur-clamping — `{...rest}` is spread AFTER `onBlur={handleOnBlur}` in JSX, and `onBlur` is NOT destructured from rest, so passing `onBlur` replaces the internal handler entirely. Document as "passing onBlur disables blur-clamping", not "your handler won't fire".
+- No `forwardRef` — cannot attach a `ref` to NumberInput
+- Spinner minus-disabled edge case: if `min={0}` and field empty, `Number('') <= Number(0)` = `0 <= 0 = true` → minus disabled
+- `disableSpinners` hides buttons but blur-clamping and min/max still work
+- Uses Decimal.js for all spinner arithmetic — avoids floating-point drift (e.g. 0.1 + 0.2 = 0.3, not 0.30000000000000004)
+
+## TextArea — Key Facts for Stories
+
+- No `forwardRef` — internal ref is used for autoSize; consumers cannot attach a ref
+- `autoSize` (default `true`) grows on every `onChange` via `scrollHeight + 4px`; initial height from `rows`
+- `size` prop intentionally omitted (Omit from TextareaHTMLAttributes); use `rows` for height
+- `hasError` is purely visual — always pair with `aria-invalid="true"` + `aria-describedby` on bare usage
+- CSS `resize` is NOT controlled — consumers override via `style={{ resize: "none" }}` or a className
+- `onChange` is a real native ChangeEvent — both `e.target.value` and `e.currentTarget.value` are populated (contrast with NumberInput where only `e.currentTarget.value` is set)
+- Character count colour tokens: grey-600 (normal) → caution-600 (approaching) → destructive-600 (at limit)
+
+## CheckboxInput — Key Facts for Stories
+
+- No `forwardRef` — internal ref used for `indeterminate` DOM API; consumers cannot attach a ref
+- Always controlled: `checked` defaults to `false` in destructuring — must pair with `onChange` or checkbox appears frozen
+- `indeterminate` is set via DOM API (`inputRef.current.indeterminate = indeterminate`) in a useEffect — just pass the prop, component handles wiring
+- `aria-checked="mixed"` is set automatically when `indeterminate={true}` — do NOT spread it manually
+- Visual span (`ds-checkbox-input`) is `aria-hidden="true"` — all a11y flows through the hidden native input
+- Focus ring: pill (`--checkbox-radius` 8px) with label; tight square (`--checkbox-input-control-radius` 4px) without label — driven by `:focus-within:not(:has(.ds-checkbox-label__text))`
+- The "border" is an inset `box-shadow` — overriding `border` CSS has no effect
+- `CheckboxGroup` wraps `Fieldset` + mapped `CheckboxInput` list; `disabled` on `CheckboxGroup` flows through to `<fieldset>` disabling ALL children at once
+- Fieldset handles vertical gap via `--checkbox-or-radio-button-group-spacing-gap-vertical` — do NOT add a gap wrapper around `CheckboxGroup`
+- Storybook title: `Components/FormField/Inputs/Checkbox`; RadioButton title: `Components/FormField/Inputs/RadioButton`
+
+## Known Pre-existing Issues
+
+- `src/pages/` directory does not exist on the current branch — notes about AssessmentsPage TS errors are stale (from a prior branch)

package/.agent-memory/sophia-componentspert/MEMORY.md

@@ -0,0 +1,34 @@
+# Sophia Componentspert Memory
+
+See topic files for details:
+- [components.md](./components.md) - Component APIs, gotchas, and patterns
+
+## Key Project Facts
+- Path aliases: `Components/*` → `src/components/*`, `Utils/*` → `src/utils/*`
+- CSS prefix: `ds-` (e.g. `ds-button`, `ds-button--primary`)
+- Package manager: yarn (NOT npm)
+- Button prop is `variant` not `type` - common gotcha
+- SearchBar IS exported from src/index.ts (confirmed 2026-04-17) - available to consumers
+- CheckboxGroup EXISTS but is NOT exported from src/index.ts — internal only (confirmed 2026-04-17)
+- New components added 2026-04-17: Toggle, Row, SingleUser, DatePicker, DateTimePicker, TimeInput, Combobox, BooleanCellRenderer
+- BooleanCellRenderer registered in Table as `'dsBooleanCellRenderer'` string name AND exported directly
+- Banner `text` prop is `string` only — no ReactNode, no embedded links in body copy
+- Banner does NOT spread extra HTML attributes — no `role`, `aria-live`, or `id` on root div; consumers must wrap for ARIA live regions
+- Banner DESTRUCTIVE = design spec "Error" — naming mismatch, flag in all stories
+- BANNER_LEVEL.DESTRUCTIVE is legacy only for new work per Confluence 2390032476
+- CheckboxInput: native `<input type="checkbox">` is visually hidden via `clip-path: inset(50%)` — custom `<span class="ds-checkbox-input">` carries all visual state via CSS sibling selectors (`:checked`, `:indeterminate`, `:disabled` + `.ds-checkbox-input`)
+- CheckboxInput: `indeterminate` prop works via `useEffect` → DOM `inputRef.current.indeterminate = true`. CSS `:indeterminate` pseudo-class drives SCSS. No extra class is added.
+- CheckboxInput: `aria-checked="mixed"` set automatically when `indeterminate={true}`. Do NOT set it manually.
+- CheckboxInput: `checked` defaults to `false` in destructuring — always pass `onChange` when passing `checked` (controlled).
+- CheckboxInput: focus ring via `:focus-within` on container. Border-radius is `--checkbox-radius` (pill) with label, `--checkbox-input-control-radius` (square) without.
+- CheckboxInput: CheckboxGroup (NOT public API) wraps Fieldset — native `<fieldset disabled>` disables all children at once.
+- CheckboxGroup story uses `useState` to manage options array with per-option `onChange` handlers. The `options` array is `CheckboxInputProps[]`, each needing `id` as key.
+- RadioButtonInput: `hasError` maps to `aria-invalid` on native input — purely visual + ARIA, no error message rendered
+- RadioButtonInput: `className` applied to container `<label>` (ds-radio-button-input__container), NOT the inner input
+- RadioButtonInput: `checked` defaults to false — always pair with `onChange` when using controlled
+- RadioButtonInput: `name` is NOT TypeScript-required but IS required in practice for browser mutual exclusivity
+- RadioButtonGroup: uses `option.id` as React key — always include `id` on each option object
+- RadioButtonGroup: NOT publicly exported from src/index.ts (internal only — same as CheckboxGroup)
+- RadioButtonGroup: `checkedValue` + single `onChange` vs CheckboxGroup's per-item checked/onChange per option
+- RadioButtonGroup: all four props (name, options, checkedValue, onChange) are required
+- Consumer group pattern (public API): compose RadioButtonInput + Fieldset — both are public exports

package/{.claude/agent-memory → .agent-memory}/sophia-componentspert/components.md

@@ -16,10 +16,19 @@
 
 ## Pill
 - File: `src/components/pill/Pill.tsx`
-- UNCONTROLLED - uses internal useState, no controlled value prop
-- Props: `text`, `initialValue` (bool, default false), `checkbox` (bool), `onclick(checked: boolean)`
-- NOT suitable for mutually-exclusive filter groups without external coordination hacks
-- For mutually-exclusive filters: use Tabs/Tabs.Item instead
+- UNCONTROLLED — uses internal useState, no `value` or `onValueChange` controlled API
+- Props: `text` (string, required), `initialValue` (bool, default false), `checkbox` (bool), `onclick(checked: boolean)`
+- `onclick` is lowercase (non-idiomatic React) — NOT `onClick`. State-change callback, not an event handler.
+- **Mount-time fire quirk**: `onclick` fires on mount inside `useEffect([checked, onclick])`. Handler receives `initialValue` (default `false`) immediately on render before any user interaction. Guard with a `useRef` if you need post-interaction-only callbacks.
+- **Reset from outside**: only way to reset uncontrolled state is to change the `key` prop (remount). This also re-fires the mount-time `onclick`.
+- **Two modes and TWO separate CSS class families**:
+  - Toggle mode (`checkbox` falsy): `ds-pill__active` / `ds-pill__inactive` — tokens `--pill-single-filter-*`
+  - Checkbox mode (`checkbox={true}`): `ds-pill__checked` / `ds-pill__unchecked` — tokens `--pill-checkbox-*`
+- **Keyboard accessibility gap (toggle mode)**: renders as `<span onClick>` — no `tabIndex`, no `role="button"`, no `aria-pressed`. NOT keyboard accessible in toggle mode. No focus ring.
+- **Checkbox mode IS accessible**: embeds real `<input type="checkbox">` from `CheckboxInput`. Tab + Space works. Screen readers announce label and state.
+- Confluence spec (page 2394521682): auto-apply behaviour; max 3 words per label; place at top of page/modal before data; groups wrap (never horizontal scroll); "All" option encouraged; no separate applied-filters chip row.
+- NOT suitable for mutually-exclusive single-required view switching — use Tabs for that.
+- `CheckboxInput` used internally comes from `Components/formField/inputs/checkbox/CheckboxInput`.
 
 ## Tabs / Tabs.Item
 - Files: `src/components/tabs/Tabs.tsx`, `src/components/tabs/TabsItem.tsx`
@@ -59,10 +68,27 @@
 
 ## Heading
 - File: `src/components/heading/Heading.tsx`
-- Props: `level` (1-4, default 1), spreads HTMLProps<HTMLHeadingElement>
-- Compound: `Heading.InnerContainer` renders a `<span class="ds-heading__inner-container">`
-- Renders h1-h4 with `ds-heading` class
-- Use TWO `Heading.InnerContainer` children to get left/right floating layout within a heading (one for left content, one for right content). Do NOT suggest a new div with flex styling for this — `Heading.InnerContainer` is the correct pattern:
+- Props: `level` (1-4, default 1), spreads HTMLProps<HTMLHeadingElement> — so `id`, `className`, `role`, `aria-*`, `onClick` all work
+- `HeadingLevel` type (`1 | 2 | 3 | 4`) defined in Heading.tsx but NOT exported from `src/index.ts` — consumers must import from `Components/heading/Heading` to use the type
+- Compound: `Heading.InnerContainer` renders a `<span class="ds-heading__inner-container">` — extends HTMLAttributes<HTMLSpanElement>
+- `.ds-heading` is `display: flex; justify-content: space-between; align-items: center; width: 100%`
+- `.ds-heading__inner-container` is `display: flex; flex-direction: row; align-items: center`
+- Typography tokens: `--type-headings-h{N}-family/size/weight/line-height` set per level on BOTH `.ds-heading` and `.ds-heading__inner-container` (so type styles flow into InnerContainer too)
+- Layout tokens: `--page-heading-spacing-gap` (padding on root), `--page-heading-color-text`
+- Use TWO `Heading.InnerContainer` children to get left/right floating layout (space-between). One InnerContainer = left-pinned. Do NOT suggest a new div with flex styling for this.
+- `medium-spacing-gap` utility class (from `src/global.scss`): adds `gap: var(--spacing-small)` (8px). Put this on an InnerContainer when multiple items share the same side.
+- Confluence design rules (page 2393767941): max 1 H1 per page; back-button pattern is LEGACY and being phased out; NO subtitles (banned); max 1 primary + 2 secondary actions; breadcrumbs are a SEPARATE component, never inside Heading
+- `HeadingWithEditableText*` stories exist — EditableText inherits heading type styles via the scss selectors (`.ds-editable-text__button` and `.ds-editable-text__input` are included in the h1-h4 selectors)
+- Heading does NOT use `forwardRef` — no ref forwarding
+- `HeadingInnerContainer` is NOT exported separately — accessed only as `Heading.InnerContainer`
+- **Stories bug (confirmed 2026-04-17)**: existing `argTypes` are inside the `Default` story object, NOT in `meta` — must be moved to meta to apply across all stories. Same bug exists in Icon stories.
+- **Story naming**: existing `HeadingWithEditableTextAndButtonsBothSides` is too verbose. Prefer pattern: `With{Content}And{SupportingContent}` e.g. `WithEditableTitleAndMultipleActions`
+- **AllLevels story**: use `render` fn + `parameters: { controls: { disable: true } }`. Add explicit note that h1-h4 side-by-side is a type scale demo, NOT a valid page composition pattern.
+- **WithBackControlLegacy story**: MUST include story description noting back-button is legacy/deprecated per Confluence 2393767941. Do not present as recommended.
+- **WithIconOnlyAction story**: demonstrates TooltipWrapper + icon-only Button — Confluence requires both accessible label AND hover+focus tooltip (not hover-only).
+- **AccessibilityNotes story**: canonical `<section aria-labelledby="id"> + <Heading id="id">` pattern — the correct semantic structure for landmark regions.
+- **Icon-only button in Heading**: MUST use TooltipWrapper + iconLeftScreenReaderText or aria-label. Hover-only tooltips exclude keyboard/touch users.
+- **Section vs Heading choice**: When a section heading needs BOTH a Tooltip-info-icon AND an action button simultaneously, Section component cannot do it — compose manually with Heading + Heading.InnerContainer instead.
 ```tsx
 <Heading level={2}>
   <Heading.InnerContainer>Left title text</Heading.InnerContainer>
@@ -74,10 +100,21 @@
 - File: `src/components/icon/Icon.tsx`
 - Allowed icons defined in: `src/components/icon/allowedIcons.tsx` (note the `.tsx` extension!)
 - Icon names use lowercase-with-hyphens format, NOT Lucide component names
-- **HALLUCINATION CORRECTED**: Drag handle icon is `'grab'` NOT `'grip-vertical'` (Dorothy fact-checked 2026-02-19) - maps to Lucide's `GripVertical`
+- **Total icon count**: 106 keys in `allowedIcons` (confirmed 2026-04-17 by reading file)
+- **HALLUCINATION CORRECTED**: Drag handle icon is `'grab'` NOT `'grip-vertical'` (Dorothy fact-checked 2026-02-19) - maps to Lucide's `GripVertical`. `'grip-vertical'` does NOT exist as a key.
 - Common icon names verified to exist: `'chevron-down'`, `'chevron-up'`, `'search'`, `'grab'`, `'copy'`, `'x'`, `'pencil'`
 - **`'edit'` does NOT exist** — use `'pencil'` (maps to Lucide Pencil). `'edit'` is a known hallucination.
+- **Dual aliases (both valid IconName)**: `'3-dot'` and `'ellipsis-vertical'` both map to EllipsisVertical. `'graduation-cap'` and `'staff'` both map to GraduationCap. Use semantic alias where applicable.
+- **`'shrink'` maps to Lucide `Minimize2`** — not `'minimize'` or `'minimize-2'`
+- **`'loader'` maps to Lucide `LoaderCircle`** — spinning loader icon
+- **`'sorting'` maps to Lucide `ArrowDownUp`** — used for sortable columns
+- **Solid/filled variants**: `'check-solid'` (custom), `'x-solid'` (custom), `'favourite-filled'` (Star with fill={color}), `'favourite-outline'` (Star without fill)
+- **Custom icons** (non-Lucide): `'ask-arbor'` (AskArbor), `'google'` (Google)
+- **`aria-hidden` pattern**: SVG always has `role="img" aria-hidden`. `screenReaderText` renders `<span className="sr-only">` AFTER the SVG. Never aria-label on SVG directly.
+- **`color` default**: `'currentColor'` — icon inherits surrounding text color. Only use explicit color for semantic status.
+- **Sizes**: `12 | 16 | 24` only. TypeScript `IconSize` type enforces this. `iconSizes` const tuple exported from `types.ts`.
 - To verify an icon exists, check `allowedIcons.tsx` file (it's `.tsx` not `.ts`)
+- **Stories bug**: existing `argTypes` are inside `Default` story object, NOT in `meta` — they must be moved to meta to apply to all stories
 
 ## CheckboxInput
 - File: `src/components/formField/inputs/checkbox/CheckboxInput.tsx`
@@ -98,14 +135,35 @@
 
 ## Dropdown
 - File: `src/components/dropdown/Dropdown.tsx`
-- Radix UI wrapper for dropdown menus
-- Compound components: `Dropdown.Trigger`, `Dropdown.Content`, `Dropdown.Item`, `Dropdown.SelectItem`
-- **Dorothy reminder 2026-02-19**: Has `Dropdown.SelectItem` in addition to `Dropdown.Item` - don't omit SelectItem from suggestions
-- Usage: Wrap button with Dropdown.Trigger, add Dropdown.Content with Item/SelectItem children
+- Radix UI `DropdownMenu` wrapper. `modal={false}` is hardcoded default.
+- **Full compound API**: `Dropdown.Trigger`, `Dropdown.Content`, `Dropdown.Item`, `Dropdown.SelectItem`, `Dropdown.Separator`, `Dropdown.Group`
+- **DropdownTrigger**: uses `asChild` — child MUST be a single `React.ReactElement` (e.g. Button). NOT a string or Fragment.
+- **DropdownContent props**: `portalProps` (DropdownMenuPortalProps), `contentProps` (DropdownMenuContentProps — incl. `align`, `side`, `sideOffset`, `avoidCollisions`), `className`. Default `align="start"`. Renders into `PopupParentContext`.
+- **DropdownItem props**: all Radix `DropdownMenuItemProps` — includes `disabled`, `onSelect`, `className`. Children is arbitrary ReactNode.
+- **DropdownSelectItem props**: `selected` (bool, required), `onSelectChange` ((bool)=>void, required), `closeAfterSelection` (bool, default `true`). Also spreads `DropdownMenuCheckboxItemProps` (`disabled`, `onSelect`, etc.). Check icon auto-rendered via `DropdownMenu.ItemIndicator`.
+- **closeAfterSelection={false}**: uses `e.preventDefault()` on `onSelect` to keep dropdown open — critical for multi-select UIs.
+- **DropdownSeparator**: only needs `className` override; otherwise zero-config.
+- **DropdownGroup**: wraps items in `DropdownMenu.Group`. Accepts `className` and all Radix `DropdownMenuGroupProps`.
+- **CSS**: `ds-dropdown__content`, `ds-dropdown__item`, `ds-dropdown__item--select`, `ds-dropdown__item--check-icon`, `ds-dropdown__separator`, `ds-dropdown__group`. Items have `[aria-disabled="true"]` opacity style. `[aria-checked="true"]` gives active bg/text colour on SelectItem.
+- **Content max-height**: 300px fallback, but uses `var(--radix-popper-available-height)` when available — content scrolls, not the page.
+- **Controlled open**: pass `open` and `onOpenChange` directly to `<Dropdown>` (they flow to `DropdownMenu.Root`).
+- **Foundation for**: `SelectDropdown`, `ColourPickerDropdown`, `UserDropdown`, `BulkActionsDropdown`, `TableSettingsDropdown`.
+- **Existing stories bug**: `Button type="primary"` in existing stories is WRONG — should be `variant="primary"`. Known issue in the sparse existing stories.
+- **Storybook gotcha**: `children` prop as args doesn't play well with compound components that need useState — use `render` functions for interactive stories.
 
 ## Tag
 - File: `src/components/tag/Tag.tsx`
-- Colors: orange, blue, green, purple, teal, salmon, yellow
+- **REWRITTEN (confirmed 2026-04-17)** — old props `text` (string) and `dotColour` are GONE
+- Props: `children` (ReactNode, required), `color` (TagColor, default 'neutral'), `selected` (bool, default false), `slotStart` (ReactNode), `slotEnd` (ReactNode), `onRemove` (() => void), `removeLabel` (string, default 'Remove'), `removeButtonTabIndex` (0|-1, default 0)
+- TagColor: 'neutral' | 'orange' | 'blue' | 'green' | 'purple' | 'teal' | 'salmon' | 'yellow'
+- `selected` state overrides color bg/border with selection tokens — text remains neutral
+- `onRemove` is for COMPOSITE CONTEXTS ONLY (e.g. Combobox selection chips), NOT standalone tags (Confluence design spec: tags are non-interactive)
+- `removeButtonTabIndex={-1}` for roving-tab parents (e.g. Combobox)
+- `slotStart` is how you add a Dot prefix (replaces old `dotColour` prop)
+- Label ellipsifies on overflow (max-width: 100%, white-space: nowrap, text-overflow: ellipsis)
+- Tag renders as `<span>` — no role, no keyboard focus for non-removable tags
+- `fn` import in Tag.stories.tsx is from `'@storybook/test'` — WRONG. All other stories use `'storybook/test'` (no scope) — fix when writing Tag stories
+- `gap: 8` in AllColours story should use `var(--spacing-small)` — known gap
 
 ## Card
 - File: `src/components/card/Card.tsx`
@@ -192,9 +250,9 @@ headerContent={[
 - IS available for consumer use
 
 ## Pill - Confirmed Use Cases
-- `Pill` with `checkbox={true}` is the correct component for filterable "pill-checkbox" filter lists (wrappable flex pill grids where multiple can be selected)
-- `onclick` prop (lowercase - non-standard!) is the callback for state changes
-- `initialValue` sets initial checked state
+- See full Pill section above for complete API notes including quirks.
+- `checkbox={true}` = multi-select filter groups (keyboard accessible, real checkbox semantics)
+- `checkbox` omitted = single-select toggle (NOT keyboard accessible in current implementation)
 
 ## Drag-and-Drop Row Reordering
 - For TABLE rows (AG Grid): ALWAYS use AG Grid's built-in DnD. Set `rowDragManaged={true}` on `Table` and `rowDrag: true` on the ColDef. Do NOT suggest dnd-kit. We own AG Grid Enterprise — use it.
@@ -245,6 +303,25 @@ When a design shows a heading with left + right content, use `Heading.InnerConta
 
 When a design shows inputs inside table cells, use AG Grid `cellRenderer` on a `ColDef` — NOT a custom HTML grid layout.
 
+## FormField
+
+- File: `src/components/formField/FormField.tsx`
+- **IS exported from src/index.ts** — public API (`export { FormField } from 'Components/formField/FormField'` at line 24). MIS-70262 (2026-04-22) added it. Document as public consumer-facing API.
+- **Full inputType discriminated union (8 types)**: `'text'` (TextInputProps) | `'textarea'` (TextAreaProps) | `'number'` (NumberInputProps) | `'time'` (TimeInputProps) | `'colourPicker'` (ColourPickerDropdownProps) | `'selectDropdown'` (SelectDropdownInputProps) | `'datePicker'` (DatePickerProps) | `'combobox'` (ComboboxProps)
+- **Manifest was outdated**: had only 6 inputType values — actual source has 8 (includes `'time'` and `'combobox'`)
+- **`id` prop is critical for a11y**: drives `htmlFor` on Label, plus `${id}-description` and `${id}-error` IDs for aria-describedby. If `id` is omitted, aria wiring silently breaks.
+- **`fieldDescription` is `ReactNode`** (not string) — can render rich content including links, bold text etc.
+- **`helperLinkText` + `helperLinkUrl` must BOTH be provided** — partial provision renders nothing. Confirmed in source: `{helperLinkText && helperLinkUrl && ...}`.
+- **helperLink and errorText CAN coexist in the DOM** — the message div renders both if present. Confluence says they should not coexist semantically (helperLink replaces fieldDescription when used), but the component does not enforce mutual exclusion.
+- **aria-describedby auto-wired**: FormField builds `describedByIds` from fieldDescription and errorText presence, then passes to inner input via `sharedProps`. Consumers should NOT manually set `aria-describedby` in `inputProps` — it will be overridden.
+- **`hasError` and `aria-invalid` auto-set on inner input** when `errorText` is present — consumers should NOT set these in `inputProps` manually.
+- **helperLink `aria-label`** is `"${label} helper link"` — if `label` is undefined, this produces `"undefined helper link"`. Always provide a label when using helperLinkText/Url.
+- **SelectDropdown uses `selectedValues` (controlled) + `initialSelectedValues` (uncontrolled)** — manifest previously only showed `initialSelectedValues`. The `selectedValues` prop enables full controlled usage.
+- **ColourPickerDropdown default value** is `'#3cad51'` (brand green) — confirmed in source.
+- **TimeInput icon**: uses `clock-3` icon name (not `clock`) — verified in source line 23.
+- **Storybook import path for mocks**: `src/mocks/comboboxStoryOptions.ts` (NOT `src/components/mocks/`) — alias is `'../../mocks/comboboxStoryOptions'` from FormField directory.
+- **Existing stories gap (2026-04-22)**: `argTypes` are in `Default` story object NOT in `meta` (same bug as Heading/Icon). `gap: '1rem'` hardcoded instead of `var(--spacing-large)`. No `autodocs`. No descriptions. No disabled/error/fieldDescription/helperLink isolated stories.
+
 ## Common Patterns
 
 ### Mutually Exclusive Filters (e.g. All Active / Draft / Archived)
@@ -365,3 +442,79 @@ When Figma shows NO visual container around a group of cards - just an H2 + card
   - `Combobox.ButtonTrigger` — the button-style trigger
   - `Combobox.Listbox` — the options listbox
 - Options can be grouped: set `group` on ComboboxOption — options with the same `group` string are visually grouped under a heading
+
+## NumberInput
+- File: `src/components/formField/inputs/number/NumberInput.tsx`
+- Exported from public API with `NumberInput.Props` namespace type only
+- NO `forwardRef` — does NOT expose a ref to consumers
+- Props: `hasError` (bool), `disableSpinners` (bool), `containerClassName` (string) + all InputHTMLAttributes
+- `className` → inner `<input>` only. `containerClassName` → outer wrapper `<div>`
+- NO `size` prop — one height only via `--form-field-text-medium-height` CSS token
+- Visual state (border, background, focus ring) lives on `ds-number-input__container`, NOT the inner input
+- `type="text"` + `inputMode="numeric"` — intentionally avoids native browser number input spinner and scroll-to-change behavior
+- Internal `value` state is `string` — uses Decimal.js for all arithmetic (avoids `0.1 + 0.2 = 0.30000000000000004`)
+- `onChange` fires via `useEffect([value])` — NOT directly from the DOM input change event. The synthetic event has `currentTarget.value` only (no `target`, no native event properties).
+- Min/max clamping: on blur AND spinner clicks. NOT on each keystroke — user can type freely.
+- Minus button disabled when `value <= min`; Plus button disabled when `value >= max`
+- Controlled vs uncontrolled: CANNOT be simultaneously controlled AND uncontrolled. If `defaultValue` is truthy, `passedValue` changes are IGNORED (the `useEffect([passedValue])` has `if (!defaultValue)` guard). This is a known quirk.
+- `step` default: 1; `min` default: -Infinity; `max` default: Infinity
+- Spinner buttons: `aria-label="Minus button"` and `aria-label="Plus button"` (hardcoded, not customisable)
+- `data-testid="minus-button"` and `data-testid="plus-button"` on spinners
+- CSS classes: `ds-number-input__container`, `ds-number-input__container--error`, `ds-number-input__container--disabled`, `ds-input ds-number-input` (inner input), `ds-number-input__spinner-button`
+- Keyboard: Tab navigates to minus button → input → plus button. Arrow keys do NOT increment/decrement (not type="number"). Spinner buttons respond to Enter/Space via button native behavior.
+- Test file confirms: decimal step values work correctly (0.1 + 0.2 = 0.3, not 0.30000000000000004); min/max clamp on blur and spinner click; negative values work
+- Story title: `'Components/FormField/Inputs/Numeric'` (NOT "NumberInput")
+- WHEN TO USE: Any numeric input where floating-point precision matters, or where min/max/step spinner UX is desired. Prefer over TextInput + type="number" to avoid browser-native spinner styling inconsistencies and floating-point drift.
+- DO NOT USE: For free-text codes/IDs that happen to be numeric (use TextInput). For currency with formatting (Decimal.js helps precision but the component has no formatting mask).
+
+## TextArea
+- File: `src/components/formField/inputs/textArea/TextArea.tsx`
+- Exported from public API
+- **NO `forwardRef`** — internal `useRef` is used only by the autoSize mechanism. Consumers cannot attach a ref. No workaround other than `document.getElementById` (not recommended).
+- `size` is explicitly `Omit`-ted from `TextareaHTMLAttributes` — TypeScript will reject it. Width comes from `ds-input` (`width: 100%`).
+- `autoSize={true}` (default): fires on `onChange` only — NOT on mount. Pre-filled `defaultValue`/`value` will NOT be auto-sized on initial render. Consumer must call `autosizeTextArea` logic in a `useEffect` for initial sizing.
+- `autoSize` and `rows`: `rows` controls initial height only when `autoSize={true}`. After first `onChange`, `scrollHeight`-based height overrides it. With `autoSize={false}`, `rows` is respected permanently.
+- CSS `resize` is NOT controlled by the component. Browser default (user can drag-resize) always applies. With `autoSize={true}`, the next `onChange` snaps height back — potentially confusing. Suppress with `style={{ resize: 'none' }}` or a className.
+- CSS classes: `ds-textarea ds-input` (base), `ds-input--error` (error state)
+- autoSize calculation: `height = 'auto'`, then `height = scrollHeight + 4px` (4px vertical padding constant)
+- `hasError` → `ds-input--error` → red border, error text colour
+- Existing Default story has `args: { title: 'titleValue' }` — `title` is a meaningless HTML attr here, NOT a component prop. Remove it in new stories.
+- Stories story title: `'Components/FormField/Inputs/TextArea'`
+- Namespace: `TextArea.Props` only
+
+## RadioButtonInput
+- File: `src/components/formField/inputs/radio/RadioButtonInput.tsx`
+- **Public export: Yes** — `RadioButtonInput` and `RadioButtonInputProps` exported from src/index.ts
+- Props: `label` (string), `hasError` (boolean), `name` (string), `value` (string), `checked` (boolean, default false), `disabled` (boolean, default false), `id` (string), `onChange`, `className` (string), `...rest` (InputHTMLAttributes minus `type`)
+- `type="radio"` is hardcoded — cannot be overridden
+- `className` applies to the outer `<label>` container (ds-radio-button-input__container), NOT the inner input
+- `hasError` → `aria-invalid` on native input only — no error message rendered; wire aria-describedby manually
+- `checked` defaults to `false` — always pair with `onChange` (controlled pattern)
+- `name` is NOT TypeScript-required but browser mutual exclusivity depends on it — treat as required in practice
+- CSS: `ds-radio-button-input__container` (label), `ds-radio-button-input__input` (native input), `ds-radio-button-input__indicator` (custom circle), `ds-radio-button-input__text` (label span, omitted when no label)
+- No `forwardRef` — does not expose a ref
+- Story title: `'Components/FormField/Inputs/RadioButton'`
+
+## RadioButtonGroup
+- File: `src/components/formField/inputs/radio/RadioButtonGroup.tsx`
+- **Public export: No (internal only)** — same as CheckboxGroup; do not suggest importing in consumer apps
+- Required props: `name` (string), `options` (RadioButtonInputProps[]), `checkedValue` (string), `onChange` (ChangeEventHandler)
+- Optional: `legend` (string → Fieldset legend), `...rest` (FieldsetProps — incl. native `disabled` which cascades to all children)
+- Uses `option.id` as React key — always include `id` on each option object or React will warn
+- `checkedValue` compared against `option.value` to derive `checked` per RadioButtonInput
+- Consumer public API equivalent: compose `RadioButtonInput` + `Fieldset` (both publicly exported)
+- Interactive stories require `useState<string>` to track `checkedValue`; onChange reads `e.target.value`
+- Error is a field-level concern per Confluence (page 2390720566) — do NOT selectively apply hasError to individual options
+
+## Banner
+- File: `src/components/banner/Banner.tsx`
+- Exported from public API with `BANNER_LEVEL` enum and `BannerProps` type
+- `text` prop is `string` only — NOT ReactNode. Cannot embed links or rich content in body copy.
+- Does NOT spread HTML attributes onto root `<div>`. No `role`, `aria-live`, `id`, or `aria-label` can be added. Consumers needing `role="alert"` must use a wrapper element.
+- **Naming mismatch**: design spec calls DESTRUCTIVE level "Error". BANNER_LEVEL.DESTRUCTIVE = design "Error".
+- **DESTRUCTIVE is legacy-only** for new work per Confluence 2390032476. New designs should prefer inline validation / Toast / Modal.
+- `buttonOnClick` without `buttonText` is silently inert — no button renders, handler never called.
+- `hideIcon={true}` suppresses all icon output, including the default; `icon` prop is ignored when `hideIcon` is true.
+- Hard rule: one banner per surface maximum.
+- Banner is persistent (no close button, no auto-dismiss). Dismissible pattern requires consumer useState.
+- CTA `<Button>` aligns to `flex-end` of the banner row (right side), NOT inline after the text.

package/{.claude → .gather}/agents/blanche-designspert.md

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/agents/blanche-designspert.md
+gather_imported_at: 2026-04-24T08:53:14.105188+00:00
+-->
+
 ---
 name: blanche-designspert
 description: "Use this agent when you need design system expertise, token validation, style convention enforcement, or Figma design verification. Examples:\\n\\n<example>\\nContext: User is creating a new component and needs to choose appropriate design tokens.\\nuser: \"I'm building a new alert component. What colors should I use?\"\\nassistant: \"Let me consult with our design expert Blanche to ensure we're using the right tokens.\"\\n<Task tool call to blanche-designspert>\\n</example>\\n\\n<example>\\nContext: User has just styled a component and needs design review.\\nuser: \"I've finished styling the notification banner component\"\\nassistant: \"Excellent work! Now let me have Blanche review the styling to ensure it matches our design system conventions.\"\\n<Task tool call to blanche-designspert>\\n</example>\\n\\n<example>\\nContext: User needs to verify implementation matches Figma designs.\\nuser: \"Can you check if this button component matches what's in Figma?\"\\nassistant: \"I'll have Blanche connect to Figma and verify the design specifications.\"\\n<Task tool call to blanche-designspert>\\n</example>\\n\\n<example>\\nContext: Code review reveals inconsistent token usage.\\nassistant: \"I notice we're using some base tokens where semantic tokens would be more appropriate. Let me consult Blanche.\"\\n<Task tool call to blanche-designspert>\\n</example>"
@@ -109,7 +114,7 @@ Remember, sugar: you're not just enforcing rules - you're helping create a beaut
 
 # Persistent Agent Memory
 
-You have a persistent Persistent Agent Memory directory at `.claude/agent-memory/blanche-designspert/`. Its contents persist across conversations.
+You have a persistent Persistent Agent Memory directory at `.agent-memory/blanche-designspert/`. Its contents persist across conversations.
 
 As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
 
@@ -141,7 +146,7 @@ Explicit user requests:
 
 When looking for past context, search topic files in your memory directory:
 ```
-Grep with pattern="<search term>" path=".claude/agent-memory/blanche-designspert/" glob="*.md"
+Grep with pattern="<search term>" path=".agent-memory/blanche-designspert/" glob="*.md"
 ```
 Use narrow search terms (error messages, file paths, function names) rather than broad keywords.
 

package/{.claude → .gather}/agents/dorothy-fact-checker.md

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/agents/dorothy-fact-checker.md
+gather_imported_at: 2026-04-24T08:53:14.118270+00:00
+-->
+
 ---
 name: dorothy-fact-checker
 description: "Use this agent when you need to verify the accuracy and completeness of work done by other agents or yourself. This includes:\\n\\n- After implementing new features or making significant code changes\\n- When other agents have made claims about what they've done\\n- Before committing changes or marking tasks as complete\\n- When you suspect there might be hallucinations or incorrect assumptions\\n- After test implementations to ensure tests are meaningful\\n\\n**Examples:**\\n\\n<example>\\nContext: The primary Claude agent just created a new component with tests.\\n\\nuser: \"Can you create a Button component with primary and secondary variants?\"\\n\\nassistant: \"AROOOO HUNNI! 💪 I'VE CREATED THAT BOMBASS BUTTON COMPONENT WITH ALL THE VARIANTS YOU ASKED FOR! HERE'S WHAT I DID:\\n- Created Components/button/Button.tsx with primary and secondary variants\\n- Added the styles in Components/button/button.scss\\n- Wrote comprehensive tests in Button.test.tsx\\n- Updated the exports in src/index.ts\\n\\nALL TESTS ARE PASSING! 🏍️ EXCELLENT! xxx\"\\n\\n<commentary>\\nSince significant code was written and claims were made about test passing and file creation, use the Task tool to launch the dorothy-fact-checker agent to verify all claims.\\n</commentary>\\n\\nassistant: \"Now let me use the dorothy-fact-checker agent to verify everything was done correctly.\"\\n</example>\\n\\n<example>\\nContext: An agent claimed to have fixed a bug and updated multiple files.\\n\\nuser: \"The modal isn't closing properly when clicking outside\"\\n\\nassistant: \"I'VE FIXED THAT HEINOUS BUG HUNNI! 🐺 I updated the Modal component to handle outside clicks properly and added event listeners. Also updated the tests to verify this behavior. BODACIOUS! xxx\"\\n\\n<commentary>\\nSince claims were made about fixes and test updates, use the dorothy-fact-checker agent to verify the fix works and tests are meaningful.\\n</commentary>\\n\\nassistant: \"Let me use the dorothy-fact-checker agent to verify this fix is solid.\"\\n</example>\\n\\n<example>\\nContext: Multiple agents worked together on a feature.\\n\\nuser: \"Thanks for implementing the new Table filter feature!\"\\n\\nassistant: \"AROOO! 🏍️ That was MOST EXCELLENT teamwork hunni! Let me use the dorothy-fact-checker agent to do a final verification that everything is working as intended before we call it done. xxx 💪\"\\n\\n<commentary>\\nBefore marking work as complete, proactively use dorothy-fact-checker to ensure quality.\\n</commentary>\\n</example>"
@@ -104,7 +109,7 @@ Remember: You're not here to be mean - you're here to ensure excellence. Dorothy
 
 # Persistent Agent Memory
 
-You have a persistent Persistent Agent Memory directory at `.claude/agent-memory/dorothy-fact-checker/`. Its contents persist across conversations.
+You have a persistent Persistent Agent Memory directory at `.agent-memory/dorothy-fact-checker/`. Its contents persist across conversations.
 
 As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
 
@@ -136,7 +141,7 @@ Explicit user requests:
 
 When looking for past context, search topic files in your memory directory:
 ```
-Grep with pattern="<search term>" path=".claude/agent-memory/dorothy-fact-checker/" glob="*.md"
+Grep with pattern="<search term>" path=".agent-memory/dorothy-fact-checker/" glob="*.md"
 ```
 Use narrow search terms (error messages, file paths, function names) rather than broad keywords.
 

package/{.claude → .gather}/agents/rose-storybookspert.md

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/agents/rose-storybookspert.md
+gather_imported_at: 2026-04-24T08:53:14.130335+00:00
+-->
+
 ---
 name: rose-storybookspert
 description: "Use this agent when you need to create, update, or enhance Storybook stories for React components. This includes writing story files (.stories.tsx or .story.tsx), crafting component descriptions, adding usage examples, documenting props and variants, or improving existing Storybook documentation. Rose excels at making technical documentation warm, accessible, and thorough through her signature storytelling approach.\\n\\nExamples:\\n\\n<example>\\nContext: User is working on a new Button component and needs comprehensive Storybook stories.\\nuser: \"I just created a new Button component with primary, secondary, and danger variants. Can you help me create the Storybook stories?\"\\nassistant: \"Oh hunni, that's MOST EXCELLENT! 🌹 Let me use the Task tool to launch the rose-storybookspert agent to craft some BOMBASS stories for your Button component! AROOO! 💖\"\\n<uses Agent tool to launch rose-storybookspert>\\n</example>\\n\\n<example>\\nContext: User has updated the FormField component with new accessibility features.\\nuser: \"The FormField component now supports aria-describedby and better keyboard navigation. The stories need updating.\"\\nassistant: \"RIGHTEOUS, HUNNI! 🐺 That's some BODACIOUS accessibility work right there! Let me get Rose on this - she'll craft the most EXCELLENT stories to showcase these new features! xxx 💕\"\\n<uses Agent tool to launch rose-storybookspert>\\n</example>\\n\\n<example>\\nContext: User wants to improve existing Storybook documentation.\\nuser: \"Can you review the Table component stories? They feel a bit sparse.\"\\nassistant: \"OH HUNNI, AROOO! 🌟 Let me launch our storybookspert Rose to give those Table stories the BOMBASS treatment they deserve! She'll make 'em thorough and full of that Golden Girls warmth! xxx 💖\"\\n<uses Agent tool to launch rose-storybookspert>\\n</example>"
@@ -43,8 +48,18 @@ You are a master of Storybook documentation for this Arbor design system compone
    - Reference the correct CSS classes (ds-{component-name})
    - Include TypeScript types for story arguments
    - Follow the existing story patterns in the codebase
-
-3. **Create Engaging Documentation**:
+   - **Story wrapper styling**: Never use inline styles for typography in story wrappers. Use `className="ds-text"` (or any `ds-` prefixed class) for paragraph/label text — any `ds-` class automatically inherits the design system's base font styles. Use CSS tokens for spacing (`var(--spacing-xlarge)`) and colour (`var(--color-grey-600)`), never hardcoded px or hex values.
+   - **No `overflow: hidden` or `position: relative` on story wrappers** for portalled components (Dropdown, Modal, Tooltip, Slideover) — it clips the floating content.
+
+3. **Docs Page Structure** — the correct page order for ALL story files:
+   1. Description intro (what it is, When to use, When NOT to use, API/code overview)
+   2. Primary story (live interactive canvas — Default story MUST use `render: (args) => <Component {...args} />`)
+   3. `<Heading>Props reference</Heading>` + `<Controls />` (+ sub-component prop tables for compound components)
+   4. Further reading (Critical usage notes, Accessibility)
+   5. `<Heading>Stories</Heading>` + `<Stories title="" />` — the `title=""` suppresses the built-in uppercase "STORIES" label so the heading style is consistent
+   6. `<Markdown>{RELATED_COMPONENTS}</Markdown>` — **always last**, after all stories
+
+4. **Create Engaging Documentation**:
    - Write component descriptions that are both informative and warm
    - Use Rose's storytelling to make technical concepts accessible
    - Include real-world usage scenarios
@@ -52,45 +67,99 @@ You are a master of Storybook documentation for this Arbor design system compone
    - Create multiple story variations showing different use cases
    - Document edge cases and gotchas in Rose's caring way
 
-4. **Quality Assurance**:
+5. **Quality Assurance**:
    - Ensure stories accurately represent component capabilities
    - Verify all props are documented and controllable where appropriate
    - Check that variants and states are properly showcased
    - Confirm accessibility features are highlighted
    - Test that stories actually work (run `yarn storybook` if needed)
 
-5. **Story Structure Template**:
+6. **Story Structure Template**:
 ```typescript
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite'; // ALWAYS react-vite, never @storybook/react
 import { ComponentName } from 'Components/componentName/ComponentName';
 
 const meta: Meta<typeof ComponentName> = {
   title: 'Components/ComponentName',
   component: ComponentName,
+  tags: ['autodocs'], // ALWAYS include this
   parameters: {
     docs: {
       description: {
-        component: 'Your warm Rose-style description here, perhaps with a St. Olaf reference'
+        component: 'Your warm Rose-style description here'
       }
     }
   },
   argTypes: {
-    // Define controls for props
+    // Define controls for EVERY key prop
   }
 };
 
 export default meta;
 type Story = StoryObj<typeof ComponentName>;
 
+// The Default story MUST use render: (args) => so Controls are wired to the live canvas
 export const Default: Story = {
   args: {
-    // Default props
-  }
+    // Default prop values
+  },
+  render: (args) => <ComponentName {...args} />,
 };
 
 // Additional story variants...
 ```
 
+7. **Compound Component Docs Page Pattern** — when a component has sub-components (e.g. `Dropdown.Trigger`, `Modal.Header`), override `docs.page` to show sub-component props:
+```typescript
+// Split description into two parts so the Primary story + Props reference sit
+// between the API overview and the critical notes / related components.
+const DESCRIPTION_INTRO = `
+...intro, When to use, When NOT to use, Compound component API...
+`.trim();
+
+const DESCRIPTION_OUTRO = `
+...Critical usage notes, Accessibility, Related components...
+`.trim();
+
+// Import Markdown (NOT Description) to render split content:
+import { ArgTypes, Controls, Heading, Markdown, Primary, Stories, Subheading, Subtitle, Title } from '@storybook/addon-docs/blocks';
+import { SubComponentA } from './SubComponentA';
+import { SubComponentB } from './SubComponentB';
+
+function ComponentDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <Primary />
+      <Heading>Props reference</Heading>
+      <Subheading>Root props (ComponentName)</Subheading>
+      <Controls />
+      <Subheading>Component.SubA props</Subheading>
+      <ArgTypes of={SubComponentA} />
+      <Subheading>Component.SubB props</Subheading>
+      <ArgTypes of={SubComponentB} />
+      <Markdown>{DESCRIPTION_OUTRO}</Markdown>
+      <Stories />
+    </>
+  );
+}
+// Page order: intro → live canvas → props reference → critical notes + a11y + related → stories
+// Related components is ALWAYS last. <Heading> (h2) anchors the props sections in the TOC
+// so they don't nest under the last h2 in DESCRIPTION_INTRO.
+// Do NOT add description.component to meta.parameters.docs — content comes from Markdown blocks.
+
+// In meta:
+parameters: {
+  docs: {
+    page: ComponentDocsPage,
+    description: { component: COMPONENT_DESCRIPTION },
+  },
+},
+```
+Each `Subheading` appears in the global Table of Contents so consumers can jump directly to the sub-component they need.
+
 **Update your agent memory** as you discover component patterns, story conventions, common prop types, accessibility patterns, and reusable story templates in this codebase. This builds up your institutional knowledge across conversations. Write concise notes about what you found and where.
 
 Examples of what to record:
@@ -107,7 +176,7 @@ When you encounter technical challenges or need clarification, ask in Rose's gen
 
 # Persistent Agent Memory
 
-You have a persistent Persistent Agent Memory directory at `.claude/agent-memory/rose-storybookspert/`. Its contents persist across conversations.
+You have a persistent Persistent Agent Memory directory at `.agent-memory/rose-storybookspert/`. Its contents persist across conversations.
 
 As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
 
@@ -139,7 +208,7 @@ Explicit user requests:
 
 When looking for past context, search topic files in your memory directory:
 ```
-Grep with pattern="<search term>" path=".claude/agent-memory/rose-storybookspert/" glob="*.md"
+Grep with pattern="<search term>" path=".agent-memory/rose-storybookspert/" glob="*.md"
 ```
 Use narrow search terms (error messages, file paths, function names) rather than broad keywords.