@arbor-education/design-system.components 0.14.0 → 0.16.0

package/.ralph/storybook-upgrade/knowledge.md

@@ -1,308 +0,0 @@
-# Knowledge — Storybook Upgrade Project
-
-## Project Overview
-
-Upgrade all component story files (except Dropdown, which is already done, and UserDropdown, which is slated for demolition) to the `/write-stories` gold standard. Each component gets the full Golden Girls squad treatment: Sophia (API inventory), Blanche (design tokens), Rose (story authoring), Dorothy (fact-checking).
-
-## Branch
-
-`feature/MIS-70118-storybook-skill` — all work happens on this branch.
-
-## Gold Standard References
-
-**Button** (`src/components/button/Button.stories.tsx`, 873 lines, completed 2026-04-17) is the reference for **simple components**. Uses the global `DocsTemplate` with `parameters.docs.description.component` + `parameters.docs.relatedComponents`. No custom `docs.page`.
-
-**Dropdown** (`src/components/dropdown/Dropdown.stories.tsx`, 714 lines) is the reference for **compound components**. It demonstrates:
-- Compound component docs page with `addon-docs/blocks` imports
-- Manual Markdown prop tables for Radix-based sub-components
-- `DESCRIPTION_INTRO` / `DESCRIPTION_OUTRO` split for optimal page flow
-- `<Heading>Props reference</Heading>` for TOC nesting
-- Rich argTypes with descriptions, controls, table.type.summary, table.defaultValue.summary
-- Per-story descriptions
-- Interactive stories with `useState`
-- Realistic Arbor-style copy (school management domain)
-- `ds-text` class on wrapper text elements
-- CSS token spacing (`var(--spacing-xlarge)`) not hardcoded px
-
-## Implementation Pattern
-
-Each story is implemented by invoking `/write-stories ComponentName`. The skill handles:
-1. Reading component source, tests, SCSS, and existing stories
-2. Fetching Confluence design guidance (see page ID mapping in skill)
-3. Calling Sophia for API inventory and story outline
-4. Calling Blanche for design token guidance
-5. Calling Rose to write the actual story file
-6. Writing the file to disk
-7. Running lint + type checks
-8. Calling Dorothy to fact-check every prop and variant
-
-## Design Token Gotchas (Verified)
-
-**Font sizes are numeric, not semantic:** The font-size scale is `--font-size-1-11` (0.688rem), `--font-size-2-13` (0.812rem), `--font-size-3-14` (0.875rem), etc. There is NO `--font-size-small` or `--font-size-medium`. When writing story wrapper caption text, use the numeric tokens.
-
-**Grey scale has `--color-grey-050` and `--color-grey-100`:** Both exist (tokens.scss lines 39 and 30). The phantom token is `--color-grey-50` (no leading zero) — that one does NOT exist. Always verify the exact string before flagging.
-
-**Border radius tokens:** Only `--border-radius-xsmall` (4px), `--border-radius-small` (8px), `--border-radius-large` (16px), `--border-radius-round` (99px). NO `--border-radius-medium`.
-
-**Border weight:** Only `--border-weight` (1px) exists. For 2px/3px visual accents there's no matching token — either use `--focus-border` (3px) where appropriate, or accept a hardcoded value with a comment.
-
-**Available spacing tokens:** `--spacing-xsmall` (0.25rem), `--spacing-small` (0.5rem), `--spacing-medium` (0.75rem), `--spacing-large` (1rem), `--spacing-xlarge` (1.5rem), `--spacing-xxlarge` (2rem), `--spacing-xxxlarge` (4rem).
-
-**Prop spelling — Tag vs Badge:** Tag uses American spelling `color`; Badge uses British `colour`. When writing bad/good code comparison blocks that cross components, VERIFY the prop name in each component's source. Mixing them will ship a TypeScript error into the docs.
-
-**Icon names — gotchas:** `bell` does NOT exist in `allowedIcons.tsx`. `calendar` is keyed as `date`. Always grep allowedIcons.tsx before using an icon name in argTypes options.
-
-**Confluence page staleness:** The write-stories skill's known-page-ID table may reference archived pages. Confluence pages for Banner (old 2216762167 = archived, new 2390032476 = current) and Button (2216957127 = archived with no usable guidance) have been replaced or superseded. Use CQL search (`mcp__atlassian__searchConfluenceUsingCql` with `title ~ "ComponentName" AND space.key = "AG"`) to find the current page before fetching.
-
-**Newly discovered current Confluence pages (not in skill's mapping table):**
-- Icon → `2431778909` ("Icons" — current, rich guidance on 3-sizes-only rule, icon+label patterns, accessibility)
-- Badge / Tag / Pill → `2394521682` ("Pills & Tags (& Badges)" — current)
-- Banner → `2390032476` ("Banners (on-page)" — current)
-- Heading → `2393767941` ("Page Headings" — current, single-H1 rule, action button limits, back-button legacy, NO subtitle support)
-- CheckboxInput / RadioButtonInput → `2390720566` ("Checkbox & Radio" — current, use cases, label phrasing, disabled tooltip guidance, keyboard/a11y)
-
-**`--color-semantic-info-200` is phantom** — the semantic info scale is 050/100/300/500/600/700/800/900. There is NO 200 tier. Rose reached for it in a callout box border; replaced with `--color-semantic-info-100`. Dorothy caught it. Watch for this in future info-coloured callout boxes.
-
-**Separator visibility gotcha** — `--page-base-color-border` resolves to `--color-grey-050`, which is ALSO `--page-color-background`. The Separator is completely invisible on the standard page background by default. Consumers must override via `className`. No `--separator-*` tokens exist. Document this prominently for any future Separator-adjacent work.
-
-**Separator vertical orientation** — the SCSS only styles horizontal. For vertical, consumer must supply `width: 'var(--border-weight)'` and either an explicit height or `alignSelf: 'stretch'` in a flex container. `decorative` should almost always be `true` for vertical separators.
-
-**Rose's recurring `--border-radius-medium` phantom** — second confirmed occurrence (also hit Badge stories). Scale is ONLY `xsmall | small | large | round`. No medium. Rose keeps reaching for it as a "common design system convention" but it doesn't exist in OUR tokens.scss. Agents should double-check before using it.
-
-**Blanche's `color` prop doctrine for Icon — REJECTED by user.** Blanche initially suggested "consumers should nearly never pass `color` explicitly to Icon — always wrap the parent and let currentColor do the work". The user overruled this. Correct framing: `color` is a first-class API. Use inheritance (the default) for icon+label pairings where the icon should track text colour through state changes. Pass `color` explicitly for status icons, fixed brand/accent colours, or anywhere a specific colour is semantically required. Always use design tokens — never hardcode hex. Applies to future Icon-adjacent stories.
-
-**NumberInput `onBlur` gotcha — consumer wins, not the component.** `{...rest}` is spread AFTER `onBlur={handleOnBlur}` in the JSX. So if a consumer passes `onBlur`, their handler fires and the internal blur-clamping silently stops working. Document as "passing `onBlur` disables min/max clamping on blur" — NOT "your handler won't fire".
-
-**NumberInput font-size phantom tokens** — Rose reached for `--font-size-body` and `--font-size-caption` which do not exist. Use `--font-size-2-13` (0.812rem) for body-weight wrapper labels and `--font-size-1-11` (0.688rem) for caption/hint text in story wrappers.
-
-**`loader` icon is STATIC.** The Icon component does not apply any rotation animation to `loader` (LoaderCircle). There is no global `@keyframes spin` in the codebase — only `ds-combobox-loader-spin` scoped to Combobox. If a consumer needs rotation, they must add a CSS animation via `className` or parent styling.
-
-**`fn` imports come from `storybook/test` (unscoped)**, not `@storybook/test`. The latter is wrong for this codebase — every existing story uses the unscoped form. Flag if Rose ever slips.
-
-**Tag component API was rewritten** — old `text` + `dotColour` props are gone. Real API uses `children` (required), `color` (British), `slotStart`/`slotEnd` for prefix/suffix content (Dot/Icon), and `onRemove`/`removeLabel`/`removeButtonTabIndex` for composite-chip contexts. Manifest updated 2026-04-17.
-
-**GOLDEN GIRLS PROCESS DISCIPLINE (important lesson from Pill run):** Sophia and Blanche are GUIDANCE agents. They provide prop inventories, token advice, and anti-pattern lists. They MUST NOT write or edit the stories file — Rose owns the file. If a subagent delivers actual code instead of guidance, the orchestrator must: (1) flag the process violation, (2) hand the file to Rose for ownership review (validate or rewrite, her call), and (3) not proceed to Dorothy until Rose has signed off. Don't rubber-stamp a non-Rose file just because types pass. The Pill stories initially shipped as a 969-line/16-story file by Sophia+Blanche; Rose trimmed to 594 lines/10 stories after review.
-
-**Pill component quirks** — lowercase `onclick` prop (non-idiomatic React), uncontrolled-only (no `value`/`onValueChange`), `useEffect` fires callback on mount, toggle-mode renders as `<span onClick>` without keyboard accessibility, CheckboxInput is wired with `onClick` not `onChange` so keyboard Space toggles visual state but not the parent's `onclick`. Worth a future component-level ticket.
-
-## Key Conventions
-
-- **Storybook import**: `import type { Meta, StoryObj } from '@storybook/react-vite'` (NOT `@storybook/react`)
-- **Story type**: prefer `type Story = StoryObj<typeof meta>` over `StoryObj<typeof ComponentName>` — `typeof meta` is stricter (picks up args/argTypes for better inference)
-- **Autodocs**: `tags: ['autodocs']` in meta
-- **Story names**: PascalCase
-- **Story descriptions**: Use `withDescription` helper or `parameters.docs.description.story`
-- **Wrapper text**: use `className="ds-text"` is a phantom class (does NOT exist in any SCSS) — it is a no-op. Stories use inline `style` props for typography, not this class. Do NOT add `ds-text` expecting it to apply styles.
-- **Wrapper spacing**: Use CSS tokens (`var(--spacing-large)`) — never hardcoded px
-- **Wrapper colours**: Use CSS tokens (`var(--color-grey-600)`) — never hardcoded hex
-- **No overflow:hidden on wrappers** for portal-based components (Dropdown, Modal, Tooltip, Slideover)
-- **Realistic content**: School management domain copy, not Lorem ipsum
-- **No unsourced authority claims**: never write "most common bug consumers report", "consumers frequently hit this" etc. — no data source = no claim
-
-## `ds-text` phantom class — Rose's recurring bad habit
-
-Rose keeps adding `className="ds-text"` to wrapper `<label>` and `<span>` elements in stories. This class does NOT exist in any SCSS file in the codebase — it is a complete no-op. Strip it before Dorothy reviews. Confirmed phantom on: NumberInput (5 occurrences), TextArea (5 occurrences). Use `style={{ ... }}` with inline styles for wrapper typography instead.
-
-## `parameters.docs.source.code` — The Full Convention
-
-Every story's code panel MUST show a complete, runnable file that a consumer can copy-paste. The convention (matching Radix UI docs) is:
-
-```tsx
-import { MyComponent } from '@arbor-education/design-system.components';
-
-function MyComponentExample() {
-  return (
-    <MyComponent prop="value" />
-  );
-}
-
-export default MyComponentExample;
-```
-
-**Rules:**
-1. **Always a named function component** — never bare JSX, never an anonymous arrow. Even one-liners need a named component.
-2. **Always `export default ComponentNameExample`** at the bottom.
-3. **Import only what's used** — do not include unused imports.
-4. **Function name convention**: `{StoryName}Example` in PascalCase (e.g. story `WithTitle` → `BannerWithTitleExample`). For stateful templates that already have good names (e.g. `YearGroupFilter`), keep the descriptive name.
-
-**When to apply `parameters.docs.source.code`**:
-- **Named template stories** (`render: SomeTemplate`) — always. Storybook shows `render: SomeTemplate` otherwise.
-- **Inline render stories** (`render: () => (...)`) — always. Storybook shows a bare arrow function without imports.
-- **Default/interactive story** — always, especially when the component uses `Object.assign` internally (see Banner gotcha below). The code panel shows a representative static example; the live Controls canvas still updates independently.
-
-**CRITICAL DISTINCTION — Default story vs all other stories:**
-- **Default/interactive story**: do NOT add `source.code`. Let Storybook auto-generate from current args so the code panel updates live when controls change. This is the intended UX of the interactive canvas.
-- **All other stories** (template-based, inline renders, stateful stories): use explicit `source.code` with a named function component + `export default`.
-
-```tsx
-// NON-DEFAULT story — explicit source.code with function wrapper
-export const MyStory: Story = withDescription(
-  {
-    render: () => <MyComponent prop="value" />,
-    parameters: {
-      docs: {
-        source: {
-          language: 'tsx',
-          code: `
-import { MyComponent } from '@arbor-education/design-system.components';
-
-function MyComponentExample() {
-  return <MyComponent prop="value" />;
-}
-
-export default MyComponentExample;
-`.trim(),
-        },
-      },
-    },
-  },
-  'Story description here.',
-);
-```
-
-**Why `withDescription` is safe**: The helper spreads `story.parameters?.docs`, so `docs.source` is preserved when `description` is added on top.
-
-## `Object.assign` Internal Name Gotcha — Banner
-
-`Banner` is defined as `Object.assign(BannerRoot, { Level, ... })`. Storybook picks up the internal function name `BannerRoot` for auto-generated code.
-
-**Fix**: Use `source.transform` on the Default story to rename the internal name without breaking live updates:
-
-```tsx
-parameters: {
-  docs: {
-    source: {
-      // Keeps code panel dynamic (updates with controls) — only renames the internal component name
-      transform: (src: string) => src.replace(/BannerRoot/g, 'Banner'),
-    },
-  },
-},
-```
-
-Only `Banner.tsx` and `AvatarGroup.tsx` use this pattern — all other components are safe.
-
-## Docs Page Structure (ALL components — updated 2026-04-22)
-
-Every component (simple and compound) now uses a custom `docs.page` function. The global `DocsTemplate` is no longer used directly. The gold standard is `src/components/button/Button.stories.tsx`.
-
-### String consts (in order)
-
-1. **`DESCRIPTION_INTRO`** — one or two sentences, no headings. The hook that appears before the interactive canvas.
-2. **`USAGE_GUIDANCE`** — "Usage guidance" section content. Sub-sections as `###` h3s, each separated by `---`. Typically: When to use, When NOT to use, Design guidance. Also include compound component API overviews here.
-3. **`DEVELOPER_NOTES`** — "Developer notes" section content. Sub-sections as `###` h3s, each separated by `---`. Typically: Critical gotchas, Accessibility, TypeScript types (always last).
-4. **`RELATED_COMPONENTS`** — unchanged, still a markdown string with `## Related components`.
-5. **`PROPS_INTRO`** — always exactly: `'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.'`
-
-### DocsPage function render order
-
-```tsx
-<Title />
-<Subtitle />
-<Markdown>{DESCRIPTION_INTRO}</Markdown>
-<DocHeading>Interactive example</DocHeading>
-<Markdown>{PROPS_INTRO}</Markdown>
-<DocPrimary />
-<Controls />
-<DocHeading>Usage guidance</DocHeading>
-<Markdown>{USAGE_GUIDANCE}</Markdown>
-<DocHeading>Developer notes</DocHeading>
-<Markdown>{DEVELOPER_NOTES}</Markdown>
-<DocHeading>Examples</DocHeading>
-<Stories title="" />
-<Markdown>{RELATED_COMPONENTS}</Markdown>
-```
-
-### Doc blocks import (always alias to avoid naming conflicts)
-
-```ts
-import {
-  Controls,
-  Heading as DocHeading,
-  Markdown,
-  Primary as DocPrimary,
-  Stories,
-  Subtitle,
-  Title,
-} from '@storybook/addon-docs/blocks';
-```
-
-### meta.parameters.docs
-
-Only `page: {ComponentName}DocsPage`. No `description.component`, no `relatedComponents` — both rendered manually in the DocsPage.
-
-### TypeScript types section
-
-Always the last `###` inside `DEVELOPER_NOTES`. Only include if the component has a namespace export. Show a usage snippet + table of all types. Enums (Object.assign pattern, e.g. `Banner.Level`) get a note that they're runtime values not just types.
-
-### Heading conflicts
-
-`Heading` component stories must alias BOTH the component-level `Heading` import AND the doc block: use `Heading as DocHeading` in the doc blocks import. Same applies to any future component whose name clashes with a Storybook doc block name (Primary, Controls, Stories, etc.).
-
-## Confluence Page IDs
-
-| Component(s) | Page ID | Key Content |
-|---|---|---|
-| Banner | `2216762167` | Types, colours, content length, icon guidance |
-| Button, inputs | `2216957127` | States, number inputs, date/time |
-| Modal | `2216762125` | CTA buttons, size options, delete confirmations |
-| Modal, Slideover, Tooltip, Dropdown | `2216891079` | Popup vs Modal vs Slideover — when to use each |
-| Section | `2217056643` | Section header link styles |
-| Toast | `2216957106` | Content length, icon alignment |
-| All (overview) | `2371747857` | Tables, tooltips, shadows, colours |
-
-## Utilities That Need Documentation Stories
-
-### PopupParentContext (`src/utils/PopupParentContext.ts`)
-- React context holding a `RefObject<HTMLElement | null>` — controls where portalled floating elements render
-- Default value comes from `getDefaultPopupParent()`
-- Exported from `src/index.ts` as a public API
-- Consumed by: Dropdown, Modal, Tooltip, DatePicker, DateTimePicker, Combobox, SlideoverManager, Table column filters (TimeFilter, BooleanFilter)
-- **Not a component** — cannot use `/write-stories`. Needs a manually authored documentation story
-- Story should go at `Utils/PopupParentContext` in Storybook
-- Key use case: when floating components are inside containers with `overflow: hidden` or custom z-index stacking contexts, consumers wrap with `<PopupParentContext.Provider value={ref}>` to re-parent portals
-
-## Components Without Dedicated Stories
-
-- `slideover/` — no story file; `SlideoverManager` handles it
-- `tableSettingsDropdown/` — empty directory
-- `testComponent/` — empty directory (test-only)
-
-## Excluded Components
-
-- **UserDropdown** — slated for demolition. Do NOT write stories for it. Removed from the Ralph backlog on 2026-04-17. Any references to UserDropdown in future stories (e.g. component relationships, "related components" lists) should be omitted.
-
-## Quality Tiers (Current State)
-
-**CheckboxGroup IS public API** — exported from `src/index.ts` line 13, despite the component-library.md marking it as "internal". Import from `'@arbor-education/design-system.components'` is correct for story documentation.
-
-**`aria-checked` spread order in CheckboxInput — COUNTER-INTUITIVE:** `{...rest}` is spread AFTER the explicit `aria-checked` in CheckboxInput.tsx. This means a consumer passing `aria-checked` via `...rest` would WIN and override the component's indeterminate logic. Document as "your value overrides the component's" not "it will be overwritten".
-
-**CheckboxGroup `--checkbox-or-radio-button-group-spacing-gap-vertical`** — handles vertical spacing between options internally via Fieldset. Do NOT add a gap wrapper around CheckboxGroup in stories or layouts — it will double-space the items.
-
-### Already done (skip)
-- Dropdown (714 lines) — full write-stories treatment ✅ (compound component reference)
-- Button (873 lines) — full write-stories treatment ✅ (simple component reference) — 2026-04-17
-- Badge (691 lines) — full write-stories treatment ✅ — 2026-04-17
-- Banner (685 lines) — full write-stories treatment ✅ — 2026-04-17
-- Icon (1168 lines) — full write-stories treatment ✅ — 2026-04-17 (includes a 106-icon gallery)
-- Heading (499 lines) — full write-stories treatment ✅ — 2026-04-17 (compound with InnerContainer)
-- Tag (557 lines) — full write-stories treatment ✅ — 2026-04-17 (non-interactive metadata, 14 stories incl. faux Combobox pattern)
-- Pill (594 lines) — full write-stories treatment ✅ — 2026-04-17 (interactive filter control, 10 stories; Rose rescued after Sophia+Blanche broke process)
-- Dot (509 lines) — full write-stories treatment ✅ — 2026-04-17 (6 focused stories; clean Golden Girls run with guidance-only discipline)
-- Progress (537 lines) — full write-stories treatment ✅ — 2026-04-17 (7 focused stories; Radix Progress wrapper; IndeterminateAntiPattern story documents the `value={null}` trap)
-- Separator (646 lines) — full write-stories treatment ✅ — 2026-04-22 (6 focused stories; visibility gotcha + decorative/semantic distinction documented; Dropdown.Separator anti-pattern called out)
-- TextInput (~640 lines) — full write-stories treatment ✅ — 2026-04-22 (7 focused stories; aria-invalid gotcha on bare TextInput; ControlledWithValidation + WithForwardRef use source.code pattern)
-- NumberInput (~870 lines) — full write-stories treatment ✅ — 2026-04-23 (8 focused stories; DecimalStep makes Decimal.js precision benefit concrete; onBlur override gotcha documented correctly)
-- CheckboxInput (~1055 lines) — full write-stories treatment ✅ — 2026-04-23 (12 stories; SelectAllWithIndeterminate canonical pattern; controlled-only + aria-checked spread gotchas; CheckboxGroup companion documented)
-
-### Minimal (< 50 lines — needs everything)
-Separator (15), Label (15), TooltipWrapper (24), ColourPickerDropdown (29), Tooltip (35), Modal (37)
-
-### Basic (50–100 lines — has some stories but no descriptions)
-TabsItem (55), SingleUser (63), Badge (74), Row (85), SearchBar (86), Fieldset (89), Section (90), Progress (90), Tabs (92), Avatar (92), Banner (96), Tag (98), Card (99)
-
-### Medium (100–250 lines — decent structure, needs enrichment)
-DatePicker (105), RadioButtonInput (106), Toast (113), EditableText (136), Heading (142), Button (169), TimeInput (170), FormField (181), SelectDropdown (200), DateTimePicker (202), AvatarGroup (218), Toggle (239)
-
-### Large (250+ lines — significant existing content)
-Combobox (358), SlideoverManager (374), ModalManager (497), Table (1412)