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

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

@@ -1,342 +0,0 @@
-# Progress — Storybook Upgrade Project
-
-## Project started: 2026-04-17
-
-## 2026-04-24 — STORY-160 (RadioButtonInput)
-
-- Wrote 10 comprehensive RadioButtonInput stories (session was interrupted before commit; quality-gated and committed on resume)
-- Files changed: `src/components/formField/inputs/radio/RadioButtonInput.stories.tsx` (106 → 988 lines)
-- Custom DocsPage with correct section ordering; covers RadioButtonGroup companion component
-
-**Learnings:**
-- **`hasError` is ARIA-only** — sets `aria-invalid="true"` on the native `<input>` but makes ZERO visual change to the indicator circle. No CSS rules exist for the error state. Consumers must render a visible error message themselves. Document as a Critical gotcha.
-- **`name` is functionally mandatory** despite TypeScript not requiring it. Without it, the browser cannot enforce mutual exclusivity — multiple radios can be selected simultaneously.
-- **`RadioButtonGroup` uses single `checkedValue` at group level** vs `CheckboxGroup` which uses per-item `checked` + `onChange`. A common consumer confusion point — documented with a side-by-side comparison.
-- **Fieldset-level `disabled`** flows through `RadioButtonGroup` → `Fieldset` → native `<fieldset>` HTML attribute, disabling all child inputs at once. Zero extra JavaScript needed.
-- **`option.id` is the React key** in `RadioButtonGroup` — omitting it causes key warnings.
-- **Confluence page `2390720566`** — same Checkbox & Radio page as CheckboxInput. Good cross-reference source.
-
----
-
-## 2026-04-23 — STORY-150 (CheckboxInput)
-
-- Wrote 12 comprehensive CheckboxInput stories via full Golden Girls run (Sophia, Blanche, Rose, Dorothy)
-- Files changed: `src/components/formField/inputs/checkbox/CheckboxInput.stories.tsx` (33 → ~1055 lines)
-- Custom DocsPage with correct section ordering; covers CheckboxGroup companion component
-- Confluence design guidance: page `2390720566` ("Checkbox & Radio") — current, rich content on use cases, label phrasing, disabled tooltip guidance, keyboard behaviour
-
-**Learnings:**
-- **CheckboxGroup IS public API** — exported from src/index.ts line 13 despite component-library.md marking it "internal". Stories correctly import from `'@arbor-education/design-system.components'`.
-- **`aria-checked` spread order is COUNTER-INTUITIVE** — `{...rest}` comes AFTER the explicit `aria-checked` in CheckboxInput.tsx, so a consumer passing `aria-checked` via props would WIN and override the component's indeterminate logic. Document as "your value overrides the component's" not "will be overwritten".
-- **Indeterminate DOM API gotcha** — `indeterminate` cannot be set as an HTML attribute; the component uses a `useEffect` to set `inputRef.current.indeterminate`. This is the #1 consumer confusion point and the SelectAllWithIndeterminate story is the canonical answer.
-- **Controlled-only component** — `checked = false` default in destructuring means React always treats it as controlled. Must pair with `onChange` or the checkbox is frozen. Document prominently.
-- **Focus ring changes shape without label** — CSS `:focus-within:not(:has(.ds-checkbox-label__text))` applies tighter `--checkbox-input-control-radius` (4px) vs pill `--checkbox-radius` (8px) when no label is present.
-- **CheckboxGroup gap token** — `--checkbox-or-radio-button-group-spacing-gap-vertical` handles vertical spacing between options internally; don't add gap on story wrappers.
-- **Confluence page ID** — `2390720566` is the correct current Checkbox & Radio design guidance page (not in write-stories skill mapping table — update it).
-- **Dorothy's cleanest audit yet** — Rose delivered zero phantom classes, zero phantom tokens, all Storybook slugs correct, all prop names verified. Only fix was one inverted explanation sentence.
-
----
-
-## 2026-04-23 — STORY-140 (TextArea)
-
-- Wrote 7 focused TextArea stories via full Golden Girls run
-- Files changed: `src/components/formField/inputs/textArea/TextArea.stories.tsx` (18 → ~673 lines)
-- Custom DocsPage with correct section ordering
-
-**Learnings:**
-- **`autoSize` only fires on `onChange`** — setting a large `defaultValue` at mount does NOT auto-grow. The textarea starts at `rows` height regardless of initial content length.
-- **CSS `resize` is browser default** — not controlled by the component. Consumers override via `style={{ resize: 'none' }}` or className. Important to document in FixedHeight story.
-- **TextArea fires real native events** (unlike NumberInput) — both `e.target.value` and `e.currentTarget.value` work. Good differentiation to call out explicitly.
-- **Character count colour progression** — `--color-grey-600` → `--color-semantic-caution-600` (amber, approaching) → `--color-semantic-destructive-600` (red, at limit). Use `caution` NOT `warning` for "approaching" state.
-- **`ds-text` phantom class** — Rose added it to 5 labels/spans. Still a recurring issue after NumberInput. Stripped before Dorothy review.
-- **ESLint indentation** — Rose left some indentation issues on multi-line `style` props. Auto-fixable with `--fix`.
-
-**Gotchas encountered:**
-- `className="ds-text"` phantom class on 5 wrapper elements — removed
-- NumberInput slug in related components was `numeric` not `numberinput` — fixed
-- ESLint indentation on 2 style prop elements — auto-fixed
-
----
-
-## 2026-04-23 — STORY-130 (NumberInput)
-
-- Wrote 8 focused NumberInput stories via full Golden Girls run (Sophia, Blanche, Rose, Dorothy)
-- Files changed: `src/components/formField/inputs/number/NumberInput.stories.tsx` (25 → ~870 lines)
-- Custom DocsPage with correct ordering: intro → interactive example → usage guidance → developer notes → examples
-
-**Learnings:**
-- **`onBlur` override is INVERTED from what you'd expect** — `{...rest}` is spread AFTER `onBlur={handleOnBlur}` in the JSX, so consumer's `onBlur` wins and silently kills blur-clamping. Document as "passing onBlur disables clamping", not "your handler won't fire".
-- **No `--font-size-body` or `--font-size-caption` tokens** — Rose reached for these phantom tokens. Use `--font-size-2-13` (0.812rem) for body-weight labels and `--font-size-1-11` (0.688rem) for caption/hint text in story wrappers.
-- **DecimalStep story is the key selling point** — showing native JS `0.30000000000000004` vs Decimal.js `0.3` side-by-side makes the Decimal.js precision benefit concrete and copy-pasteable.
-- **`onChange` synthetic event** — only `e.currentTarget.value` is populated. `e.target.value` throws. Document prominently.
-- **Storybook title renamed** — `Numeric` → `NumberInput`. Slug is now `components-formfield-inputs-numberinput--docs`. The original pre-write-stories file used `Numeric` which followed neither the full-name (TextInput, TimeInput) nor the shortened (Checkbox, RadioButton) pattern.
-
-**Gotchas encountered:**
-- Rose used `--font-size-body`, `--font-size-caption`, `--color-grey-50` — all phantom tokens. Fixed before Dorothy review.
-- Rose's onBlur documentation was factually inverted — Dorothy caught it. Fixed.
-
----
-
-## 2026-04-22 — STORY-100 (Separator)
-
-- Wrote 6 focused Separator stories via `/write-stories` — full Golden Girls run
-- Files changed: `src/components/separator/Separator.stories.tsx` (15 → 646 lines)
-
-**Learnings / patterns discovered:**
-- **`--page-base-color-border` = invisible by default** — resolves to `var(--color-grey-050)`, which is ALSO `--page-color-background`. The separator is completely invisible on the standard page background. This is the #1 gotcha for Separator consumers. Documented as a "Critical visibility gotcha" section at the TOP of the component description.
-- **SCSS only styles horizontal** — `width: 100%; height: 1px`. Vertical orientation renders without any sizing; consumers must supply `width: 'var(--border-weight)'` and either an explicit height or `alignSelf: 'stretch'` in a flex container.
-- **No `--separator-*` tokens** — zero component-scoped tokens exist. `className` is the only escape hatch for colour and spacing overrides.
-- **`decorative` prop is the whole story** — `decorative={false}` (default) = `role="separator"` announced by screen readers. `decorative={true}` = `role="none"`, completely invisible to AT. The choice is: "does the separator communicate a boundary that surrounding headings don't already convey?"
-- **Arbor wrapper does NOT use `forwardRef`** — the Radix Root underneath does, but the wrapper is a plain function component. Cannot ref this component.
-- **`Dropdown.Separator` is the right tool inside Dropdowns** — confirmed it exists at `src/components/dropdown/items/DropdownSeparator.tsx` with `ds-dropdown__separator` class. Using bare Separator inside a Dropdown is wrong.
-- **`--color-semantic-info-200` is phantom** — Dorothy caught it in the callout box border. Semantic info scale is 050/100/300/500/600/700/800/900. No 200 tier. Fixed to `--color-semantic-info-100`.
-
-**Gotchas encountered:**
-- **One phantom token** — `--color-semantic-info-200` used in a callout box border. Replaced with `--color-semantic-info-100`. Dorothy's A- → A after fix.
-- **Existing stories had a WRONG prop** — `title: 'titleValue'` in the Default story. `title` is not a Separator prop. Completely replaced.
-
----
-
-### Pre-existing work (before Ralph)
-- Dropdown stories completed via `/write-stories` — serves as gold standard reference
-- Toggle stories manually written to high quality (239 lines) but not through the skill
-
----
-
-## 2026-04-17 — STORY-090 (Progress)
-
-- Wrote 7 focused Progress stories via `/write-stories` — another clean Golden Girls run with guidance-only discipline
-- Files changed: `src/components/progress/Progress.stories.tsx` (91 → 537 lines)
-
-**Learnings / patterns discovered:**
-- **Consolidation win**: old file had 5 redundant stops (Default/Empty/Quarter/Half/ThreeQuarters/Complete). The Controls panel already lets consumers scrub any value — `AllStops` (0/25/50/75/100 stacked) as a single reference story replaces all 5.
-- **Progress is a Radix UI Progress wrapper** — include the Radix link (`https://www.radix-ui.com/primitives/docs/components/progress`). Props spread through via `{...rest}` — Radix props pass through untouched.
-- **`value={null}` is a trap** — Radix sets `data-state="indeterminate"` but the component has NO animation CSS for that state. Result: `Number(null)=0` → `translateX(-100%)` → indicator is pushed fully offscreen → INVISIBLE bar. Documented as `IndeterminateAntiPattern` story with explicit "use Spinner instead" guidance.
-- **`layout: 'padded'` beats `'centered'` for width-100% components** — Blanche's call. Progress fills 100% of parent; centered fights the layout. Switched meta to padded, kept story-level override option.
-- **Width sizing rule**: never size `<Progress>` itself — always size the wrapper. Consumer controls width via parent container. Stories use `maxWidth: '60%'` or `'24rem'` on wrappers, never on the component.
-- **Radix `getValueLabel` default** — without a custom function, Radix falls back to a rounded-percentage string (e.g. `"50%"`) for `aria-valuetext`. Dorothy caught Rose mischaracterising this as "raw number" in 5 places — fixed.
-
-**Gotchas encountered:**
-- **Rose's "raw number" mischaracterisation** — recurring pattern where Rose gets screen-reader-announcement details subtly wrong. Always have Dorothy verify framework-default behaviour claims (Radix, React Aria, etc.) against actual source. Fixed in 5 locations (component description, argType description + defaultValue.summary, WithAccessibleLabel story prose, InteractiveLoading story description).
-- **Dorothy's verdict truncated again** — giving just the bottom-line fix list. Spot-checked myself to confirm each flagged line and applied the corrections.
-
----
-
-## 2026-04-17 — STORY-080 (Dot)
-
-- Wrote 6 focused Dot stories via `/write-stories` — clean Golden Girls run with Sophia + Blanche providing GUIDANCE ONLY (process-discipline lesson from STORY-070 applied successfully)
-- Files changed: `src/components/dot/Dot.stories.tsx` (41 → 509 lines)
-
-**Learnings / patterns discovered:**
-- **Process discipline restored** — Sophia and Blanche respected the "GUIDANCE ONLY, do not write the file" directive this run. Rose owned the file from the start. The lesson from STORY-070 worked.
-- **`--color-grey-050` IS a real token** (tokens.scss line 39). I had previously (incorrectly) flagged it as phantom based on a Dorothy Badge audit — but Dorothy was catching `--color-grey-50` (no leading zero), NOT `--color-grey-050`. The latter DOES exist. Always verify the exact string before calling a token phantom.
-- **Consolidated 7 per-colour stories into 1 AllColours** — original file had Purple/Salmon/Teal/Yellow/Green/Orange/Blue as individual stories. Docs-page bloat. One consolidated AllColours (with `controls: { disable: true }`) saves ~7 stories' worth of autodocs noise.
-- **Dot's aria-hidden/aria-label dual pattern mirrors Icon's screenReaderText** — identical accessibility pattern for "decorative by default, meaningful when labelled". Worth cross-referencing in descriptions.
-- **Dot is a deliberately CLOSED API** — only 2 props (colour, label). NO size, className, style, onClick. Documentation should make this explicit so consumers don't try to override.
-- **`DotColour` and `BadgeColour` are structurally identical** — same 7 extended colour values. Noted in Dot's description so consumers know one colour string works for both.
-
-**Gotchas encountered:**
-- **Blanche's `--color-grey-050` suggestion was CORRECT** (despite my initial skepticism). I double-checked tokens.scss before overriding her guidance — glad I did. The token exists at line 39; the grey scale has both `-050` (lightest) and `-100`.
-- **WCAG 1.4.1 citation** in the `DecorativeVsMeaningful` story — accurate per the spec's "Use of Colour" principle; flagged by Dorothy as worth human confirmation but it's a defensible reference.
-- **De-facto Arbor colour semantics table** (salmon=Pupil Premium, green=On track, etc.) — Blanche surfaced this as the established convention from Tag/Badge descriptions; Dorothy flagged for designer sign-off but it's consistent across all prior component runs.
-
----
-
-## 2026-04-17 — STORY-070 (Pill)
-
-- Wrote 10 comprehensive Pill stories via `/write-stories` — Rose took OWNERSHIP after a process violation where Sophia and Blanche both wrote the file themselves
-- Files changed: `src/components/pill/Pill.stories.tsx` (33 → 594 lines)
-
-**PROCESS VIOLATION — most heinous, logged for posterity:**
-Sophia and Blanche both ignored the Golden Girls workflow and wrote/edited the Pill stories file directly. I (the orchestrator) initially let it slide because their output was functional — types + lint passed, 16 stories. The user RIGHTLY called this out as a violation. The fix: handed the existing 969-line/16-story file to Rose for review-and-ownership. Rose trimmed to 10 stories/594 lines by cutting redundancy (ToggleInactive = Default inactive, WithCheckbox = CheckboxMode, PreChecked = CheckboxModeSelected) and dev-only debugging stories (OnMountCallbackQuirk, UncontrolledReset — moved to component description as prose + code snippets). She also fixed 3 hardcoded `1px solid` borders to `var(--border-weight) solid ...`.
-
-**LESSON: in future runs, the orchestrator must SHUT DOWN Sophia and Blanche the moment they start writing code. Their job is guidance, not authorship. If they deliver a file, hand it to Rose for review before moving to Dorothy — don't rubber-stamp just because tests pass.**
-
-**Learnings / patterns discovered:**
-- **Pill has TWO different class-name conventions** — `ds-pill__active`/`ds-pill__inactive` for toggle mode, `ds-pill__checked`/`ds-pill__unchecked` for checkbox mode. Same state, different naming. Worth documenting for consumers debugging CSS.
-- **`useEffect` fires `onclick` on mount** — the `useEffect(() => { if (onclick) onclick(checked); }, [checked, onclick])` pattern runs after initial render, not just after user clicks. Consumers should guard with `useRef` if they need post-interaction-only callbacks.
-- **Pill is purely uncontrolled** — no `value`/`onValueChange` pattern. External reset requires `key` remount.
-- **Lowercase `onclick` prop** — non-idiomatic React naming. Reads as HTML attribute but it's actually a state-change callback receiving `(checked: boolean)`.
-- **Toggle mode is NOT keyboard accessible** — renders as `<span onClick>` with no role/tabIndex/onKeyDown. Checkbox mode IS accessible because the embedded CheckboxInput provides real `<input type="checkbox">` semantics.
-- **Dorothy bonus catch (component bug, not story)**: CheckboxInput is wired with `onClick` not `onChange`, so keyboard Space toggles the native checkbox visually but Pill's `onclick` callback only fires on mouse click. Worth a future component ticket.
-
-**Gotchas encountered:**
-- **THE PROCESS VIOLATION** (documented above — most important lesson)
-- Redundant stories crept in because each agent independently proposed variants. Rose's trim was aggressive and correct — 16 → 10 stories makes the docs page MUCH more scannable.
-- `AccessibilityNote` story uses a custom warning panel with `--color-semantic-warning-*` tokens, NOT a Banner component (correct per established convention — Banner-as-meta-commentary would confuse the canvas).
-
----
-
-## 2026-04-17 — STORY-060 (Tag)
-
-- Wrote 14 comprehensive Tag stories via `/write-stories` + full Golden Girls squad
-- Existing stories had decent coverage (WithColour, Selected, WithDot, WithIcon, Removable, WithSlotEnd, AllColours) but thin descriptions and one import bug
-- Files changed: `src/components/tag/Tag.stories.tsx` (98 → 557 lines)
-
-**Learnings / patterns discovered:**
-- **Tag component was rewritten** — the `component-library.md` manifest was OUTDATED and listed `text` + `dotColour` props that no longer exist. Real API: `children`, `color`, `selected`, `slotStart`, `slotEnd`, `onRemove`, `removeLabel`, `removeButtonTabIndex`. Sophia corrected the manifest during this story. Future runs: always check the actual source, not just the manifest.
-- **`fn` import scope** — every story in this codebase uses `from 'storybook/test'` (unscoped). The existing Tag stories file was importing from `'@storybook/test'` (with scope) — confirmed wrong for this codebase. Fixed in the rewrite.
-- **onRemove is for composite contexts, NOT general tags** — Confluence (page 2394521682) says tags are non-interactive. The `onRemove` prop exists for Combobox selected-item chips, not general metadata tags. Document this boundary prominently.
-- **`removeButtonTabIndex={-1}` is the roving-tabindex contract** for composite parents. When a parent like Combobox manages focus via arrow keys, individual remove buttons must be out of the tab order. Otherwise users get jarring tab-through.
-- **Selected state wins over colour** — `--tag-selected-color-*` tokens override `color` bg+border; text reverts to neutral. Higher-priority visual signal than categorical colour.
-- **`slotStart` replaces old `dotColour` prop** — canonical pattern for a dot prefix is `slotStart={<Dot colour="purple" />}`, not a dedicated prop.
-- **Blanche's insight: semantic tokens intentionally NOT mapped to Tag colours** — tags describe what something IS, not a state urgency. Consumers establish their own semantic mapping from the 8 category colours. This is a deliberate design decision, not an oversight.
-- **Faux Combobox pattern in stories** — for the `InCompositeParentPattern` story, a styled container with border + padding tokens + static `<input>` placeholder reads as a real pattern. No need to wire up actual Combobox logic.
-
-**Gotchas encountered:**
-- **Manifest was outdated** — `component-library.md` listed stale `text`/`dotColour` props. Sophia updated it as part of her research. Progress a hidden benefit of the Golden Girls pattern: Sophia is also keeping the manifest fresh.
-- **All flex rows of tags need `flexWrap: 'wrap'`** — non-negotiable per Blanche. Responsive design is not optional; tags in a rigid single-line row overflow on narrow viewports.
-- **Dorothy's response got truncated** mid-report again (appears to be an agent output limit). Self-verified the high-risk items via Grep (import paths, phantom tokens, hardcoded values) — all clean.
-
----
-
-## 2026-04-17 — STORY-050 (Heading)
-
-- Wrote 11 comprehensive Heading stories via `/write-stories` + full Golden Girls squad
-- Confluence page 2393767941 ("Page Headings" — current, found via CQL search) had rich guidance on single-H1 rule, action button limits, legacy back-button pattern, and small-screen behaviour
-- Files changed: `src/components/heading/Heading.stories.tsx` (142 → 499 lines)
-
-**Learnings / patterns discovered:**
-- **Pre-existing bug fixed**: argTypes were nested in Default story, `tags: ['autodocs']` also on Default only, AND `StoryObj` import was missing entirely. Rose fixed all three in the rewrite.
-- **Compound component handled via Markdown prop table in description** (not custom docs.page) — since `Heading.InnerContainer` is a plain span-wrapper with only `HTMLAttributes<HTMLSpanElement>` props, a full ArgTypes block was overkill. This keeps simple compound components in the simple-component docs pattern.
-- **Story renaming** — Sophia pushed back hard on `FloatingChildren` (implied absolute positioning when it's just flexbox) and the `HeadingWith...` mouthfuls. New names: `TwoContainers`, `WithActionButton`, `WithMultipleActions`, `WithIconOnlyAction`, `WithBackControlLegacy`, `WithEditableTitle`, `WithEditableTitleAndAction`, `WithEditableTitleAndMultipleActions`, `AccessibilityLabelledSection`.
-- **Confluence page staleness pattern continues** — the write-stories skill's known-page-ID table had no entry for Heading. Found "Page Headings" (2393767941) via CQL search. Also confirmed `.medium-spacing-gap` is a real global utility (`src/global.scss` line 11).
-- **Legacy pattern framing** — per Blanche, use PROSE in the story description for deprecation warnings, not a Banner component in the canvas. Banner-as-meta-commentary confuses readers about whether the banner is part of the component being documented.
-
-**Gotchas encountered:**
-- **`--border-radius-medium` phantom token** (Dorothy catch — SECOND occurrence of this specific hallucination). Actual tokens: xsmall/small/large/round only. Fixed to `--border-radius-small` + also cleaned up the `1px` hardcoded border width to `var(--border-weight)`.
-- **Heading spreads `level` onto the DOM element** (Heading.tsx line 35) — React warns about unknown HTML attribute in dev. Component quirk, NOT the stories' responsibility, but worth noting.
-- **`HeadingLevel` type is NOT re-exported from `src/index.ts`** — only `Heading` itself is public. Consumers wanting the type must import from the component directly. Documented in the component description.
-
----
-
-## 2026-04-17 — STORY-040 (Icon)
-
-- Wrote 11 comprehensive Icon stories via `/write-stories` + full Golden Girls squad
-- Confluence page 2431778909 ("Icons" — CURRENT, found via CQL search) had rich design guidance including 3-sizes-only rule, outline-only preference, and the icon-before-label usage pattern
-- Files changed: `src/components/icon/Icon.stories.tsx` (30 → 1168 lines)
-
-**Learnings / patterns discovered:**
-- **Pre-existing bug in old stories**: argTypes were nested INSIDE the Default story instead of in meta. This meant only Default got Controls — every other story had a broken Controls panel. Fixed by moving argTypes to meta.
-- **IconGallery story covers all 106 icons** in 9 semantic categories (Navigation, Actions, Status, Content/media, Charts/data, People/org, System/state, Misc, Custom/brand). Zero hallucinations — every name verified against allowedIcons.tsx.
-- **`color` prop guidance was initially overstated** by Blanche ("nearly never pass color explicitly"). User pushed back — the right framing is "use inheritance for icon+label pairings, pass `color` explicitly for status icons or fixed brand/accent colours, just never hardcode hex". Rewrote the component description, argType description, and the CurrentColorInheritance + SemanticColours story descriptions to reflect this honest nuance.
-- **Icon aliases worth documenting**: `grab` = GripVertical (drag handle), `date` = CalendarFold, `staff` = GraduationCap, `guardians` = Users, `group` = UsersRound, `3-dot` = EllipsisVertical, `loader` = LoaderCircle (NOT auto-spinning!), `sorting` = ArrowDownUp, `shrink` = Minimize2.
-- **aria-hidden + sr-only is a hardcoded dual pattern** in Icon.tsx. SVG always has `role="img"` AND `aria-hidden`. Optional sr-only span renders after when screenReaderText is provided. Document this with the gomakethings.com link embedded in the component source comment.
-
-**Gotchas encountered:**
-- **`--color-grey-50` phantom token** (Dorothy catch — recurring Rose hallucination): used on line 830 for IconGallery cell backgrounds. Smallest grey is `--color-grey-100`. Fixed.
-- **`loader` does NOT auto-rotate** — Rose incorrectly claimed "Animated with CSS `spin` keyframe for loading states" in the aliases table. No global `@keyframes spin` exists in the codebase (only `ds-combobox-loader-spin` scoped to Combobox SCSS). Consumers who drop `<Icon name="loader" />` expecting rotation will get a STATIC icon. Rewrote the entry to say: "Loading spinner glyph. No rotation is applied by the Icon component itself — add a `spin` CSS animation on the parent or via `className` if your design calls for rotation."
-- **`iconSizes` is `readonly` via `as const`** — argTypes.options needs `[...iconSizes]` for a mutable array (Rose handled this correctly).
-- **Warning vs caution tokens**: there's both `--color-semantic-warning-*` and `--color-semantic-caution-*` in tokens.scss. For the 4-state status model (info/success/warning/error), use `warning`. `caution` is a different scale.
-
-**Override to Blanche's guidance preserved in knowledge.md for future runs:** agents should NOT push the "nearly never pass color explicitly" doctrine — the `color` prop is a first-class API and passing a design token is fully valid.
-
----
-
-## 2026-04-17 — STORY-030 (Banner)
-
-- Wrote 16 comprehensive Banner stories via `/write-stories` + full Golden Girls squad
-- Files changed: `src/components/banner/Banner.stories.tsx` (96 → 685 lines)
-
-**Learnings / patterns discovered:**
-- **The originally referenced Confluence page (2216762167) was ARCHIVED.** CQL search `title ~ "Banner" AND space.key = "AG"` surfaced the current page (2390032476 — "Banners (on-page)") with rich design guidance. Future Ralph stories should check for archived-vs-current pages before trusting the write-stories skill's known page-ID mapping table.
-- **`DESTRUCTIVE` in source = "Error" in the design spec.** This naming mismatch is a real gotcha for consumers who search design docs first. Document it explicitly in the component description.
-- **Error banners are LEGACY ONLY per new design guidance.** Don't reach for red on new features — use Warning (risky-but-reversible) or handle via empty states. Noted prominently in the stories.
-- **Banner does NOT auto-set `role="alert"` or `role="status"`.** For dynamic state-change banners (appearing after a user action), consumers must handle ARIA themselves. Documented as a gotcha.
-- **Neutral has NO background token — transparent is intentional.** Verified in banner.scss (no `--banner-neutral-color-background` exists). For AllVariants stories, wrap the Neutral row in a visible backdrop (`var(--color-grey-100)`) so the transparent bg is distinguishable.
-- **One banner per surface is a HARD design rule.** AllVariants overview must include a disclaimer that stacking is Storybook-only reference layout.
-
-**Gotchas encountered:**
-- **Icon name mishaps caught by Rose before ship**: `bell` is not in allowedIcons.tsx (substituted `lightbulb`), and `calendar` is actually keyed as `date` in the icon map. Write-stories skill should include a note: always verify icon names against allowedIcons.tsx before using them in argTypes options.
-- **Blanche suggested `--color-grey-050` for the Neutral backdrop** — that's a phantom token. Smallest grey is `--color-grey-100` (confirmed repeatedly across audits). I corrected this before passing to Rose.
-- **`--banner-*` tokens follow `--banner-{level}-color-{role}` pattern** wrapping `--color-semantic-{level}-050/500/800`. Consumers use the component tokens; semantic tokens are the implementation detail.
-- **Button inside Banner uses `color: inherit`** — the CTA text-link colour matches the level text colour. Intentional, looks different per variant.
-- **`flex-flow: row nowrap`** — Banner does NOT reflow to a column on narrow screens. Keep CTA labels short (also `text-wrap: nowrap` on the button).
-
----
-
-## 2026-04-17 — STORY-020 (Badge)
-
-- Wrote 14 comprehensive Badge stories via `/write-stories` + full Golden Girls squad
-- Confluence page 2394521682 (Pills & Tags & Badges) had rich guidance: Badge = counts only, NOT category labels — critical distinction from Tag and Pill
-- Files changed: `src/components/badge/Badge.stories.tsx` (74 → 691 lines)
-
-**Learnings / patterns discovered:**
-- **`Tag` uses American `color` prop; `Badge` uses British `colour`** — mixing them in bad/good code blocks is a classic Dorothy trap. Always verify prop spelling against the actual source when writing comparison examples.
-- **Render-only stories need `StoryObj<typeof Badge>` not `StoryObj<typeof meta>`** when `children` is required on props — because render functions compose their own instances that can't satisfy required `args.children`.
-- **Confluence search via CQL works** — the `mcp__atlassian__searchConfluenceUsingCql` tool found the Pills & Tags & Badges page via `title ~ "Badge" AND space.key = "AG"`. This is how to discover Confluence pages not listed in the write-stories skill's known mapping table.
-
-**Gotchas encountered:**
-- **Phantom design tokens** — Rose hallucinated four non-existent tokens that Dorothy caught:
-  - `--color-grey-50` (smallest grey is `--color-grey-100`)
-  - `--border-radius-medium` (only -xsmall, -small, -large, -round exist)
-  - `--font-size-small` × 11 occurrences (the scale is numeric: `--font-size-1-11`, `--font-size-2-13`, etc.)
-- **Hardcoded px values in wrapper styles** — Dorothy flagged `gap: 4`, `gap: 8`, `padding: '6px 0'`, `borderBottom: '1px ...'` as token-able. Fixed with `var(--spacing-xsmall)`, `var(--spacing-small)`, `var(--spacing-small) 0`, `var(--border-weight)`.
-- **`"bell"` icon does not exist** in allowedIcons.tsx — Rose caught this herself and substituted `"mail"` before writing. Good check before shipping.
-- **Available font-size tokens are numeric** (`--font-size-1-11`, `--font-size-2-13`, `--font-size-3-14`) — not semantic names like `--font-size-small`. Document this for future agents.
-
----
-
-## 2026-04-17 — STORY-010 (Button)
-
-- Wrote 25 comprehensive Button stories via `/write-stories` + full Golden Girls squad (Sophia → Blanche → Rose → Dorothy)
-- Confluence page 2216957127 is archived/[remove]; overview page 2371747857 had no button-specific guidance. Worked from component source + Sophia's API inventory instead
-- Files changed: `src/components/button/Button.stories.tsx` (169 → 873 lines), `.storybook/DocsTemplate.tsx` (global template upgrade), `.claude/skills/write-stories/SKILL.md` (new conventions documented)
-
-**Learnings / patterns discovered:**
-- **Global DocsTemplate now handles "Related components at bottom" via `parameters.docs.relatedComponents`** — no custom `docs.page` needed for simple components. Compound components (Dropdown, Modal, etc.) still need custom `docs.page` for sub-component prop tables but should match the same page order.
-- **Primary canvas belongs under the Props heading**, not between description and Props. The canvas + Controls are one interactive unit — a one-line intro ("tweak any prop to see this story update in real time") makes the relationship explicit.
-- **Props must be `<Heading>` (h2), not `<Subheading>` (h3)** — otherwise the TOC nests it under the last h2 in the description (typically "Related components" when that was inside the description, now that's moved out).
-- **`Primary` naming collision**: if a story is exported as `Primary` and you also import `Primary` from `@storybook/addon-docs/blocks`, TS2395 fires. Alias the block: `import { Primary as PrimaryBlock }`. Avoided entirely now that simple components use the global template.
-
-**Gotchas encountered:**
-- **Fabricated authority claims** — Sophia wrote "consumers get burned by it constantly", I propagated it to Rose, Rose shipped it as "the most common bug consumers report". No data source. Fixed and added a feedback memory: never claim consumer behaviour frequency without a real data source.
-- **FormField overclaim** — initial description said "parent FormField is responsible for setting aria-invalid". FormField isn't the parent of Button. Fixed to put responsibility on the consumer without naming a specific component.
-- **Dropdown variant "reserved" overclaim** — Sophia incorrectly described `variant="dropdown"` as reserved for internal use only. It's a styled trigger variant available to consumers too. Removed the "reserved" language across 4 occurrences + deleted the whole Critical gotcha #3 that was built on the false premise.
-- **Broken CheckboxInput link** — Dorothy caught `components-formfield-inputs-checkboxinput--docs` (actual slug is `components-formfield-inputs-checkbox--docs`).
-- **MCP setup** — `mcp-atlassian` via uvx with OAuth 2.0 (`--oauth-setup` wizard) worked; the server exposes `mcp__atlassian__getConfluencePage` and friends once authorised.
-
-**Button Confluence page status:**
-- Page ID 2216957127 is archived and titled "Buttons and Inputs [remove]". Content is minimal and mostly a question from the designer. Update `write-stories` skill's Confluence mapping table to reflect this — Button page has no actionable guidance.
-
----
-
-## 2026-04-22 — STORY-110 (FormField)
-
-- Wrote 13 focused FormField stories via `/write-stories` — full Golden Girls run
-- Files changed: `src/components/formField/FormField.stories.tsx` (181 → 961 lines)
-
-**Learnings / patterns discovered:**
-- **FormField public API status changed** — was internal at time of writing; MIS-70262 (2026-04-22) added `FormField` to `src/index.ts`. The "internal component" blockquote callout was removed from the stories description accordingly.
-- **discriminated union gotcha** — use `type Story = StoryObj<typeof FormField>` (not `StoryObj<typeof meta>`) to avoid TypeScript strictness forcing required inputProps on every story that uses a `render` function.
-- **`id` is practically required** — TypeScript allows it to be omitted but the a11y wiring (`htmlFor`, `aria-describedby`) silently breaks without it. Treat as required in docs.
-- **`sharedProps` auto-injection** — FormField builds `hasError`, `aria-invalid`, `aria-describedby` from `errorText` and `fieldDescription` and spreads them BEFORE `inputProps`. Never set these in `inputProps`.
-- **`helperLinkText` + `helperLinkUrl` must be paired** — providing only one renders nothing (gated by `helperLinkText && helperLinkUrl`).
-- **`fieldDescription` + `errorText` coexist** — description stays visible during errors. Both IDs concatenated in `aria-describedby`.
-- **`__message` div is block-stacked, NOT flex row** — error and helper link stack vertically (error first), not side-by-side. Dorothy caught Rose's "left/right" layout claim — fixed.
-- **`TimeInput` has two modes** — native `<input type="time">` (no options) vs combobox preset mode (options array of "HH:MM" strings).
-- **Related component slug gotchas** — Dorothy caught 4 broken slugs: "TextInput" (not "Text"), "Numeric" (not "Number"), "TimeInput" (not "Time"), "Label" requires "/Inputs/" prefix. Always verify actual story `title:` before writing slugs.
-- **Confluence page for FormField** — current rich page is `2396553813` ("🤖 Form Fields: Master"), not the archived button/inputs page `2216957127`. Found via CQL search.
-
-**Gotchas encountered:**
-- **4 broken doc slugs** — Dorothy caught them all. Pattern: the `title:` in a stories file is NOT the same as a naive camelCase conversion of the component name. Always grep for the actual title.
-- **Layout mischaracterisation** — "error left, helper right" was wrong; block-stacked vertically. Fixed in 2 places.
-
----
-
-## 2026-04-22 — STORY-120 (TextInput)
-
-- Wrote 7 TextInput stories via `/write-stories` + full Golden Girls squad
-- Files changed: `src/components/formField/inputs/text/TextInput.stories.tsx` (43 → ~640 lines)
-- Confluence inputs page: `2426437667` ("🤖 Inputs | Buttons, Checkbox and radio...") — no TextInput-specific section but confirmed size/state guidance
-
-**Learnings / patterns discovered:**
-- **`hasError` does NOT set `aria-invalid`** — purely visual class. On bare TextInput outside FormField, consumer must set `aria-invalid="true"` manually. FormField auto-sets it via `sharedProps`. Critical gotcha in developer notes.
-- **`parameters.docs.source.code` pattern for template stories** — when a story uses `render: () => <NamedTemplate />`, Storybook's "Show code" panel shows that line only (useless to consumers). Fix: add `parameters.docs.source.code` with a clean, self-contained consumer-facing example. Applied to `ControlledWithValidation` and `WithForwardRef` stories.
-- **`type Story = StoryObj<typeof ComponentName>` vs `StoryObj<typeof meta>`** — Dorothy flagged. `typeof meta` is stricter (picks up args/argTypes). Half the codebase does each. Either compiles, but `typeof meta` preferred going forward.
-- **`ds-text` phantom class** — Dorothy flagged 17 instances. The class does not exist in any SCSS — it's a no-op. Stories work because of inline style props, not this class. Don't use `ds-text` as a class name in stories.
-
-**Gotchas encountered:**
-- **`withDescription` preserves source params** — spreads `story.parameters?.docs` so pre-existing `docs.source` is carried through when calling `withDescription`. Safe to add `parameters.docs.source.code` before `withDescription`.
-
----

package/src/components/table/TableWIP.mdx

@@ -1,3 +0,0 @@
-# WIP
-
-This table component is a work in progress. It is not ready for demoing or for production use