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

package/.gather/skills/write-stories/SKILL.md

@@ -0,0 +1,841 @@
+---
+name: write-stories
+description: Write comprehensive, autodocs-powered Storybook stories for Arbor design system components. Fetches designer guidance from Confluence, enlists the full Golden Girls team, and produces BOMBASS documentation that teaches consumers exactly how and when to use each component.
+---
+
+# Write Storybook Stories
+
+AROOOOO HUNNI!! 🐺💖 Time to write the most EXCELLENT, most BODACIOUS Storybook stories this design system has ever seen! We're bringing the FULL GOLDEN GIRLS SQUAD and the designer wisdom from Confluence to make documentation so good people will WEEP WITH JOY!! xxx
+
+## Goal
+
+Write **comprehensive, production-quality Storybook stories** for a given Arbor design system component that:
+
+- ✅ Enable `autodocs` so consumers get full generated API documentation
+- ✅ Include a rich component-level description (what it is, when to use, when NOT to use, a11y notes, design guidance)
+- ✅ Define `argTypes` for all key props so the **Props** table is always populated
+- ✅ Cover every variant, size, and state the component supports
+- ✅ Include per-story descriptions explaining what each story demonstrates and why you'd use it
+- ✅ Incorporate designer guidance fetched directly from Confluence
+- ✅ Show interactive examples for components with complex behaviour (modals, dropdowns, etc.)
+- ✅ Link related components using Storybook story paths so consumers can navigate the docs
+- ✅ Follow our codebase story conventions exactly
+
+**Output**: An updated (or new) `.stories.tsx` file at the component's existing location.
+
+> **Note on the global docs template**: A custom docs template is configured at `.storybook/DocsTemplate.tsx` and wired up in `.storybook/preview.ts`. It automatically renders: `Title → Subtitle → Description → Primary story → **Props (Controls — interactive)** → Stories`. The `Controls` block drives the Primary story canvas in real time — changing a prop value instantly updates what you see above. A Table of Contents panel is also enabled globally, picking up `h2`/`h3` headings from the Description and any `Subheading` blocks.
+>
+> **For simple components**: you do NOT need to do anything special — these apply automatically to every component with `tags: ['autodocs']`. Your job is to make sure `argTypes` is populated and the Default story uses `render: (args) => <Component {...args} />` so controls are wired up.
+>
+> **For compound components** (e.g. Dropdown, Modal, Tabs — anything with sub-components): override `docs.page` in the story meta with a custom React component that adds `<ArgTypes of={SubComponent} />` for each sub-component, each preceded by a `<Subheading>`. Each `Subheading` also appears in the TOC. See the Compound Components section below for the exact pattern.
+
+---
+
+## The Golden Girls Squad — MANDATORY COLLABORATORS
+
+This skill runs with the FULL SQUAD. Each one is NON-OPTIONAL. You MUST use the `Task` tool to call each agent at their designated step. Skipping any of them is a **MOST HEINOUS** failure of the process.
+
+- 👜 **Sophia Componentspert** (`sophia-componentspert`) — MANDATORY at Step 5. She knows every component's API inside out and will tell you EVERY variant, prop, and state worth documenting.
+- 💄 **Blanche Designspert** (`blanche-designspert`) — MANDATORY at Step 6. She reviews the planned stories for design token correctness and ensures inline styles in stories use proper tokens.
+- 🌹 **Rose Storybookspert** (`rose-storybookspert`) — MANDATORY at Step 7. She is THE story author. Rose writes the ACTUAL story file. Do NOT write it yourself — let Rose do it!
+- 🔍 **Dorothy Fact-Checker** (`dorothy-fact-checker`) — MANDATORY at Step 9. She fact-checks every prop, variant, and code example against the actual source code. Dorothy catches hallucinations before they ship.
+
+**RULE**: You MUST use the `Task` tool to call EACH agent. Do NOT just mention them — ACTUALLY CALL THEM. If you skip any agent, you have failed this skill. AROOOOO!! 🐺💪
+
+---
+
+## Input
+
+Component name or path: `$ARGUMENTS`
+
+Examples:
+- `Button` — finds `src/components/button/Button.tsx`
+- `Banner` — finds `src/components/banner/Banner.tsx`
+- `FormField` — finds `src/components/formField/FormField.tsx`
+- `src/components/modal/Modal.tsx` — direct path
+
+---
+
+## Process
+
+### Step 1 — Parse the Input
+
+Determine what component to document:
+
+- If `$ARGUMENTS` is a **component name** (e.g., `Button`): resolve to its source file using the directory structure `src/components/{camelCase}/{PascalCase}.tsx`
+- If `$ARGUMENTS` is a **file path**: use it directly
+- If `$ARGUMENTS` is **empty**: ask the user which component they want to document
+
+Once resolved, note:
+- **Component source file**: e.g., `src/components/button/Button.tsx`
+- **Existing stories file** (may or may not exist): e.g., `src/components/button/Button.stories.tsx`
+- **Component directory**: e.g., `src/components/button/`
+
+---
+
+### Step 2 — Read the Component Source Files
+
+Read the following in parallel:
+
+1. **Component source** (`{ComponentName}.tsx`) — Props interface, exported types, variants/enums, default values
+2. **Existing stories** (`{ComponentName}.stories.tsx` or `{ComponentName}.story.tsx`) — if one exists, read it so we know what's already there and what's missing
+3. **Test file** (`{ComponentName}.test.tsx`) — useful for understanding expected behaviour and states
+4. **Component SCSS** (`{componentName}.scss`) — to understand any modifier classes that inform variants/states
+5. **`src/index.ts`** — confirm what's exported publicly (we should only document public exports)
+
+Note every **prop**, **variant**, **size**, **state**, and **enum value** you find. This forms your documentation inventory.
+
+---
+
+### Step 3 — Fetch Confluence Design Guidance
+
+Look up designer guidance for this component using the Atlassian MCP tools. Use `cloudId: "orchard.atlassian.net"`.
+
+**Known component → Confluence page mappings:**
+
+| Component(s) | Page ID | Description |
+|---|---|---|
+| Banner | `2216762167` | Banners — types, colours, content length, icon guidance |
+| Button, inputs | `2216957127` | Buttons and Inputs — states, number inputs, date/time |
+| Modal | `2216762125` | Modals — CTA buttons, size options, delete confirmations |
+| Modal, Slideover, Tooltip, Dropdown | `2216891079` | Popup vs Modal vs Slideover — when to use each |
+| Section | `2217056643` | Sections — section header link styles |
+| Toast | `2216957106` | Toasts — content length, icon alignment |
+| All components (overview) | `2371747857` | Design System Components — tables, tooltips, shadows, colours |
+
+**Instructions:**
+- If the component has a known page ID above, fetch it with `mcp__atlassian__getConfluencePage` using `contentFormat: "markdown"`
+- If the component relates to multiple topics (e.g., Modal relates to both Modals and Popup/Slideover), fetch ALL relevant pages
+- If the component has no dedicated page, fetch the main overview page (`2371747857`) and look for any relevant section
+- Extract: use cases, DO/DON'T guidance, content length limits, icon guidance, colour guidance, accessibility notes, and any "best practise" callouts
+
+---
+
+### Step 4 — Read the Component Library Manifest
+
+Read `component-library.md` (project root) for a comprehensive overview of the component's role in the design system, use cases, and known relationships to other components.
+
+If it contains guidance about when to use this component vs. alternatives, note it — it goes into the story description.
+
+---
+
+### ⚡ MANDATORY STEP 5 — CALL SOPHIA COMPONENTSPERT NOW ⚡
+
+**YOU MUST USE THE `Task` tool RIGHT NOW** to launch the `sophia-componentspert` agent. This is NOT optional. Do NOT skip this. Sophia is the component expert — she builds the definitive prop inventory and story outline.
+
+```
+Task tool: subagent_type="sophia-componentspert"
+prompt: "I'm writing comprehensive Storybook stories for the [ComponentName] component. I need your expert guidance on its complete API.
+
+COMPONENT SOURCE:
+[Paste the full component source code here]
+
+EXISTING STORIES (if any):
+[Paste existing stories, or "None yet"]
+
+DESIGN GUIDANCE FROM CONFLUENCE:
+[Paste the relevant Confluence content here]
+
+Please provide:
+1. A COMPLETE inventory of every prop, its type, default value, and description
+2. Every variant, size, and state worth demonstrating in Storybook
+3. Which props have the most impact on visual appearance (these need their own dedicated stories)
+4. Which states are important for consumers to understand (disabled, error, loading, focused, etc.)
+5. Any complex or non-obvious usage patterns that consumers MUST know about
+6. Suggestions for interactive stories that need useState/render functions (e.g., controlled inputs, modals)
+7. A recommended story outline (list of story names with a one-line description of each)
+8. When to use this component vs. its alternatives (if any)
+9. Any accessibility requirements (aria attributes, keyboard nav, screen reader text)
+
+Be specific! Story names should be PascalCase. Include every edge case and gotcha."
+```
+
+**WAIT for Sophia's response.** Her story outline is the blueprint for Rose.
+
+After Sophia responds, **RELAY HER KEY INSIGHTS TO THE USER**:
+
+> 👜 **Sophia says:** _[relay Sophia's component wisdom in her warm, knowledgeable voice — she's been around the block and knows EVERY prop. e.g. "Oh pussycat, the Button has SEVEN variants and most people only use three of them! Let me tell you about the ones that get overlooked..."]_
+
+---
+
+### ⚡ MANDATORY STEP 6 — CALL BLANCHE DESIGNSPERT NOW ⚡
+
+**YOU MUST USE THE `Task` tool RIGHT NOW** to launch the `blanche-designspert` agent. Blanche will guide you on how inline styles and decorators in stories should use design tokens.
+
+```
+Task tool: subagent_type="blanche-designspert"
+prompt: "I'm writing Storybook stories for the [ComponentName] component and need design guidance.
+
+Some stories need wrapper layouts (e.g., flex containers to show multiple variants side-by-side, or sized containers to show responsive behaviour). When I write inline styles for these story wrappers, what design tokens should I use?
+
+COMPONENT INFO:
+[Paste component name, variants, and Confluence design guidance]
+
+Please advise:
+1. What spacing tokens should story wrappers use for gaps and padding? (e.g., CSS vars vs. SCSS vars)
+2. Are there any component-specific design tokens I should reference in story descriptions?
+3. Are there any colour variants or states that have specific token names consumers should know about?
+4. Any design system best practices for THIS component that should be highlighted in the stories?
+5. Any tokens that consumers commonly misuse with this component?"
+```
+
+After Blanche responds, **RELAY HER TOKEN WISDOM TO THE USER**:
+
+> 💄 **Blanche says:** _[relay Blanche's design guidance in her glamorous, exacting voice — she would never tolerate a hardcoded hex in a story wrapper. e.g. "Sugah, when you show those Banner colour variants side by side, use `var(--space-4)` for the gap, not 16px. And darling, the `info` colour in that component? That's `--color-semantic-info-500` and I need consumers to KNOW that!"]_
+
+---
+
+### ⚡ MANDATORY STEP 7 — CALL ROSE STORYBOOKSPERT TO WRITE THE STORIES ⚡
+
+**YOU MUST USE THE `Task` tool RIGHT NOW** to launch the `rose-storybookspert` agent. **Rose writes the story file.** Do NOT write it yourself. Rose is THE expert here — she knows Storybook inside out and writes stories with warmth, clarity, and precision.
+
+```
+Task tool: subagent_type="rose-storybookspert"
+prompt: "I need you to write a comprehensive, production-quality Storybook stories file for the [ComponentName] component.
+
+COMPONENT SOURCE:
+[Paste the full component source]
+
+SOPHIA'S STORY OUTLINE:
+[Paste Sophia's recommended stories and prop inventory]
+
+BLANCHE'S DESIGN TOKEN GUIDANCE:
+[Paste Blanche's token and design advice]
+
+CONFLUENCE DESIGN GUIDANCE:
+[Paste the extracted Confluence content]
+
+EXISTING STORIES (to improve, not just replace):
+[Paste existing stories, or 'None — write from scratch']
+
+TARGET FILE PATH: [src/components/{componentName}/{ComponentName}.stories.tsx]
+
+REQUIREMENTS — please follow ALL of these:
+
+1. IMPORT: Always use `import type { Meta, StoryObj } from '@storybook/react-vite';`
+
+2. META TAGS: Always include `tags: ['autodocs']` in the meta object
+
+3. COMPONENT DESCRIPTION: Include a rich description in meta.parameters.docs.description.component that covers:
+   - What the component is and what it does (1-2 sentences)
+   - WHEN TO USE IT (specific scenarios with examples from Confluence design guidance)
+   - WHEN NOT TO USE IT (e.g. 'Use Modal instead when you need to block the user', 'Use Toast instead for transient messages')
+   - Any content/usage guidelines from the designers (e.g. 'Keep text to 1-2 lines', 'Always include an icon', etc.)
+   - Accessibility notes (keyboard behaviour, aria attributes, screen reader text)
+   - A note about related components (if any)
+   - **Radix UI link** (if applicable — see rule below)
+   
+   **RADIX UI DOCS LINK:** If the component wraps a Radix UI primitive (check the component source for `@radix-ui` imports), add a "Built on Radix UI" note to the description with a link to the relevant Radix docs page. This is especially important when the component passes through Radix props (e.g. `...rest` spread onto a Radix root) — consumers need to know where to find the full prop reference for the underlying primitive. Format:
+   ```markdown
+   > **Built on [Radix UI ComponentName](https://www.radix-ui.com/primitives/docs/components/component-name).**
+   > Props not listed above are passed through to the Radix primitive — see the Radix docs for the full API.
+   ```
+   Only include the "Props not listed above" sentence when the component actually does prop pass-through. If the component only uses Radix internally without exposing its props, just link to Radix for context (e.g. so consumers understand keyboard/focus behaviour).
+   
+   Format it in markdown, keep it warm and informative. Consumers should finish reading it and know EXACTLY what this component is for.
+
+4. STORY DESCRIPTIONS: Every single story MUST have a description in parameters.docs.description.story that explains:
+   - What this story demonstrates
+   - When you'd choose this variant or configuration in a real product
+   
+   Use the withDescription helper pattern from Badge.stories.tsx (see below).
+
+5. COVER EVERY VARIANT/STATE: Write a dedicated story for each variant, size, and significant state:
+   - All enum values (e.g., every Banner level, every Button variant)
+   - Disabled state
+   - Error state (if applicable)
+   - Loading state (if applicable)
+   - With and without optional content (e.g., icon, title, button)
+   - Edge cases (very long text, empty state, etc.)
+
+6. COMPOSITE STORIES: Include at least one 'AllVariants' or 'Overview' story using a render function that shows all variants side-by-side. This helps consumers see the full palette at a glance.
+
+7. INTERACTIVE STORIES: For components with complex behaviour (modals, dropdowns, controlled inputs), use render functions with useState to show real interactive behaviour.
+
+8. CONTENT GUIDELINES STORY: If Confluence specifies content length limits or copy guidelines (like Toast: max 2 lines, ideally 1), include a story that demonstrates both the ideal case AND what NOT to do (using a 'DoNotUse' or 'ContentGuidelines' story with inline comments).
+
+9. ARGTYPE DESCRIPTIONS: `argTypes` is MANDATORY and must be defined in the meta for every key prop. Each entry needs:
+   - `description`: plain English explanation of the prop's purpose
+   - `control`: the right control type (`'boolean'`, `'select'`, `'text'`, `false` to disable)
+   - `table.type.summary`: the TypeScript type as a string
+   - `table.defaultValue.summary`: the default value as a string
+   - `options`: array of allowed values for `control: 'select'` props
+   
+   This is what populates the **Props (Controls)** section in the global docs template. If `argTypes` is empty, consumers see an empty table. Every important prop must be documented. For compound components, add a `children` entry with a note pointing to sub-component prop documentation in the stories below.
+
+10. INTERACTIVE DEFAULT STORY: The `Default` story MUST use `render: (args) => <Component {...args} />` and declare `args` with sensible defaults. This is what wires the `Controls` block to the live canvas — without this, controls exist in the table but don't change anything on screen.
+
+    Do **NOT** add an explicit `source.code` block to the Default story — Storybook auto-generates the code from the current args so the code panel updates live when the user tweaks controls. This is the intended UX. If Storybook uses the wrong internal name (e.g. `BannerRoot` instead of `Banner` because the component uses `Object.assign`), use `source.transform` to patch the name without breaking live updates:
+    ```tsx
+    parameters: {
+      docs: {
+        source: {
+          transform: (src: string) => src.replace(/InternalName/g, 'ExportedName'),
+        },
+      },
+    },
+    ```
+
+11. SOURCE CODE FORMAT — ALL stories with `parameters.docs.source.code` MUST follow the Radix UI convention:
+    - Wrap JSX in a **named function component** — never bare JSX, never an anonymous arrow
+    - Add `export default ComponentNameExample;` at the bottom
+    - Name format: `{StoryName}Example` (e.g. story `WithTitle` → `BannerWithTitleExample`)
+    - Import only what is used
+
+    ```tsx
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+    import { Banner } from '@arbor-education/design-system.components';
+
+    function BannerInfoExample() {
+      return (
+        <Banner
+          level={Banner.Level.INFO}
+          text="Your session will expire in 10 minutes."
+        />
+      );
+    }
+
+    export default BannerInfoExample;
+    `.trim(),
+        },
+      },
+    },
+    ```
+
+    This applies to: template stories (`render: SomeTemplate`), inline render stories (`render: () => (...)`), AND the Default story. ALL stories need this treatment. Bare `<Component ... />` without a wrapper is not valid standalone code.
+
+12. RELATED COMPONENTS ORDERING: Related components must appear at the **very bottom** of the docs page, AFTER Stories. It's the last thing a consumer reaches for — the hierarchy of need is: What is it → Primary canvas → Props → Stories → Related components. The global `DocsTemplate` renders the description BEFORE the Primary story, so if "## Related components" is inside the description it will appear near the top of the page, which is wrong.
+
+    **For simple components**, the global `DocsTemplate` renders `parameters.docs.relatedComponents` as a Markdown block at the very bottom of the page automatically. You do NOT need a custom `docs.page`. Just split the related components out of the description into its own parameter:
+
+    ```tsx
+    const COMPONENT_DESCRIPTION = [
+      // main markdown: intro, when to use, when not, design guidance, gotchas, accessibility
+      // DO NOT include "## Related components" here
+    ].join('\n');
+
+    const RELATED_COMPONENTS = [
+      '## Related components',
+      '',
+      '[ComponentA](?path=/docs/components-a--docs) · [ComponentB](?path=/docs/components-b--docs)',
+    ].join('\n');
+
+    const meta = {
+      title: 'Components/ComponentName',
+      component: ComponentName,
+      tags: ['autodocs'],
+      parameters: {
+        docs: {
+          description: { component: COMPONENT_DESCRIPTION },
+          relatedComponents: RELATED_COMPONENTS,
+        },
+      },
+      argTypes: { /* ... */ },
+    };
+    ```
+
+    The global template picks up `parameters.docs.relatedComponents` via `useOf('meta')` and renders it as a final markdown block after `<Stories />`. No other wiring required.
+
+    **Props is a Heading (h2), not a Subheading (h3)**: the global template uses `<Heading>Props</Heading>` so Props sits as a TOC sibling of the description's h2 sections rather than nested under the last h2 in the description.
+
+12. COMPOUND COMPONENTS — CUSTOM DOCS PAGE: If the component is a compound component (exposes sub-components as static properties, e.g. `Dropdown.Trigger`, `Dropdown.Content`, `Modal.Header`), you MUST:
+    a. Import the doc blocks at the top of the stories file:
+       ```tsx
+       import { ArgTypes, Controls, Description, Primary, Stories, Subheading, Subtitle, Title } from '@storybook/addon-docs/blocks';
+       ```
+    b. Import each sub-component directly (not from the root barrel, but from their own files):
+       ```tsx
+       import { DropdownTrigger } from './DropdownTrigger';
+       import { DropdownContent } from './DropdownContent';
+       ```
+    c. Use the SAME string structure as simple components — `DESCRIPTION_INTRO` (1–2 sentences ONLY, no headings), `USAGE_GUIDANCE` (When to use, When NOT to use, Compound component API), `DEVELOPER_NOTES` (Critical gotchas, Accessibility), `RELATED_COMPONENTS`. Do NOT use a `DESCRIPTION_OUTRO` — that pattern is deprecated. The DocsPage function renders them in order, with the Props reference tables interleaved between the interactive canvas and Usage guidance sections.
+
+    d. Define a named docs page function ABOVE the meta. Use `Markdown` blocks (not `<Description />`) to render the split content:
+       ```tsx
+       // Import Markdown alongside the other blocks:
+       import { ArgTypes, Controls, Heading, Markdown, Primary, Stories, Subheading, Subtitle, Title } from '@storybook/addon-docs/blocks';
+
+       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 this achieves**: intro → primary story → props reference → critical notes + accessibility + related components → all stories. Related components is always last.
+
+       **IMPORTANT — TOC nesting fix**: `Subheading` renders as h3. The description uses `##` (h2). Without `<Heading>Props reference</Heading>`, the TOC nests all Subheadings under the last h2 in the intro (e.g. "Compound component API"). The `Heading` block (h2) gives the props sections their own TOC parent. Always include it.
+
+       **Do NOT include `description.component` in meta.parameters.docs** when using `Markdown` blocks — the content is rendered by the blocks directly, so a separate `description.component` is redundant.
+    d. Set `docs.page` in the meta:
+       ```tsx
+       parameters: {
+         docs: {
+           page: ComponentDocsPage,
+           description: { component: COMPONENT_DESCRIPTION },
+         },
+       },
+       ```
+    Each `Subheading` also appears in the global Table of Contents, so consumers can jump directly to the sub-component props section they need.
+
+12. ACCESSIBILITY STORIES: If the component has important a11y props (like Badge's a11yLabel), include a dedicated accessibility story.
+
+13. FILE STRUCTURE: Use the same structure as existing stories in this codebase. No default export at the bottom — it goes before story exports.
+
+14. STORYBOOK IMPORT: Use `import type { Meta, StoryObj } from '@storybook/react-vite';` — NOT `@storybook/react`.
+
+REFERENCE — the withDescription helper pattern used in this codebase:
+\`\`\`tsx
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+\`\`\`
+
+REFERENCE — component description goes in meta like this:
+\`\`\`tsx
+const meta: Meta<typeof ComponentName> = {
+  title: 'Components/ComponentName',
+  component: ComponentName,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: \`
+**ComponentName** does X, Y, Z.
+
+### When to use
+- Use ComponentName when...
+- Use it for...
+
+### When NOT to use
+- Use [OtherComponent] instead when...
+- Avoid ComponentName when...
+
+### Design guidance
+- Keep content to X lines
+- Always include...
+
+### Accessibility
+- Keyboard: ...
+- Screen readers: ...
+        \`,
+      },
+    },
+  },
+  argTypes: { ... },
+};
+\`\`\`
+
+Please write the COMPLETE stories file. Include every story from Sophia's outline. Make it comprehensive, warm, and genuinely useful for developers building with this component. AROOOOO!! 🌹💖"
+```
+
+**WAIT for Rose's full story file.** Rose will produce the complete `.stories.tsx` content.
+
+After Rose responds, **SHARE A PREVIEW WITH THE USER**:
+
+> 🌹 **Rose says:** _[relay Rose's story rationale in her warm storytelling voice — she'll explain why she chose each story, what was missing before, and what she's most proud of. e.g. "Oh hunni, I've written 12 beautiful stories for the Banner component! I was so moved when I saw the Confluence guidance about content length — I've written a ContentGuidelines story showing both the ideal AND the 'what not to do' side by side. It tells such an important story!"]_
+
+---
+
+### Step 8 — Write the Story File
+
+Use the `Write` tool to write Rose's story file to disk at the correct path:
+- `src/components/{componentName}/{ComponentName}.stories.tsx`
+
+If an existing story file was present, **REPLACE IT ENTIRELY** with Rose's improved version (not a merge — Rose's version is the authoritative one).
+
+---
+
+### Step 9 — Run Quality Checks
+
+Run lint and type checks:
+
+```bash
+source ~/.nvm/nvm.sh && nvm use && yarn check-types
+```
+
+```bash
+source ~/.nvm/nvm.sh && nvm use && yarn style-lint
+```
+
+If TypeScript reports errors, fix them. If ESLint finds issues, use `--fix`:
+
+```bash
+source ~/.nvm/nvm.sh && nvm use && yarn eslint --fix src/components/{componentName}/{ComponentName}.stories.tsx
+```
+
+**CRITICAL**: All quality checks must pass before proceeding to Dorothy.
+
+---
+
+### ⚡ MANDATORY STEP 10 — CALL DOROTHY FACT-CHECKER NOW ⚡
+
+**YOU MUST USE THE `Task` tool RIGHT NOW** to launch the `dorothy-fact-checker` agent. Dorothy reads the ACTUAL source code and verifies every claim. She will catch any props that don't exist, wrong variant names, incorrect import paths, or hallucinated behaviour.
+
+```
+Task tool: subagent_type="dorothy-fact-checker"
+prompt: "Rose has just written Storybook stories for the [ComponentName] component. I need you to FACT-CHECK every prop, variant, and code example in the stories against the actual source code.
+
+STORIES FILE WRITTEN:
+[Paste the full stories file content]
+
+YOUR TASK:
+1. Read src/components/{componentName}/{ComponentName}.tsx — verify every prop name and type used in stories
+2. Read src/index.ts — confirm ComponentName is actually exported (public API)
+3. For every story, verify:
+   - All props used in 'args' actually exist on the component
+   - All variant/enum values are real (e.g. does 'primary-destructive' actually exist as a Button variant?)
+   - All import paths are correct
+   - Interactive render functions use correct React patterns
+4. Verify the component description accurately describes what the component does
+5. Flag any props that are MISSING from stories but are important for consumers (e.g. accessibility props, required props)
+6. Confirm all imports at the top of the file are real exports from their packages
+
+BE BRUTAL. If any prop doesn't exist, if a variant name is wrong, if an import is broken — I need to know NOW before this ships to consumers. List every file you read."
+```
+
+**WAIT for Dorothy's response.**
+
+After Dorothy responds, **SHARE HER VERDICT WITH THE USER IN FULL**:
+
+> 🔍 **Dorothy says:** _[relay Dorothy's fact-check verdict completely and honestly — she does NOT sugarcoat. e.g. "Alright, I've read the source. The Button component? Real. The 'primary-destructive' variant? Also real. BUT — Rose used 'iconName' as a prop and that prop is actually called 'iconRightName'. And she missed the 'iconLeftName' prop entirely. These need fixing before this goes out."]_
+
+Fix **every issue Dorothy identifies** before presenting the final summary. Re-write affected stories, run quality checks again if needed.
+
+---
+
+### Step 11 — Present the Final Summary
+
+Once all quality checks pass and Dorothy has signed off, present this summary to the user:
+
+```
+AROOOOO HUNNI!! 🐺💖 The most BODACIOUS Storybook stories are DONE!! xxx
+
+📖 **Component documented**: [ComponentName]
+📄 **Stories file**: [path/to/Component.stories.tsx]
+
+✨ **Stories written** ([count] total):
+- [Story name] — [one line description]
+- [Story name] — [one line description]
+...
+
+📚 **Documentation includes**:
+✅ Autodocs enabled with full API docs
+✅ Component description: what it is, when to use, when NOT to use
+✅ Per-story descriptions for every variant
+✅ Designer guidance from Confluence incorporated
+✅ Accessibility notes documented
+✅ [Any other highlights — e.g. "Interactive modal demo with useState"]
+
+🎨 **Blanche approved** the token usage!
+🔍 **Dorothy verified** every prop and variant against source code!
+🌹 **Rose wrote** stories so warm and comprehensive you'll want to cry!
+
+MOST EXCELLENT documentation, hunni!! 🐺💪 xxx
+```
+
+---
+
+## What Makes a BOMBASS Story File
+
+### The Component Description (in `meta.parameters.docs.description.component`)
+
+This is the MOST IMPORTANT piece of documentation. Consumers land on the autodocs page and this is the first thing they read. It MUST include:
+
+**1. What it is (1-2 sentences)**
+Describe the component in plain language. What does it render? What is its core purpose?
+
+**2. When to USE it**
+Give 3-5 specific, real-world scenarios with enough context that a developer knows exactly when to reach for this component. Reference Confluence guidance where available.
+
+**3. When NOT to use it**
+This is critical. Explain which OTHER component to use instead in specific cases. Consumers waste time using the wrong component — this section saves them.
+
+Example: 
+- "Use `Toast` instead when the message is transient and should auto-dismiss"
+- "Use `Modal` instead when you need to block user interaction until they respond"
+
+**4. Design guidelines (from Confluence)**
+Extract the designer's guidance: content length limits, icon usage, colour semantics, stacking rules, etc.
+
+**5. Accessibility**
+Keyboard navigation, ARIA attributes, screen reader behaviour, focus management. Make this practical and specific.
+
+**6. Radix UI docs link (when applicable)**
+Many Arbor components wrap Radix UI primitives. If the component source imports from `@radix-ui`, include a "Built on Radix UI" callout with a direct link to the relevant Radix docs page. This matters because:
+- Radix provides keyboard navigation, focus management, and ARIA behaviour that consumers should understand
+- Components that spread `...rest` onto a Radix root accept additional Radix props not listed in our prop table — consumers need the Radix docs to discover those
+- Even when props aren't passed through, Radix docs explain the underlying behaviour (e.g. how Tooltip hover delay works, how Dialog traps focus)
+
+**Known Radix component → docs URL mappings:**
+
+| Arbor Component | Radix Primitive | Docs URL |
+|---|---|---|
+| Dropdown | DropdownMenu | `https://www.radix-ui.com/primitives/docs/components/dropdown-menu` |
+| Modal | Dialog | `https://www.radix-ui.com/primitives/docs/components/dialog` |
+| Toast | Toast | `https://www.radix-ui.com/primitives/docs/components/toast` |
+| Tooltip / TooltipWrapper | Tooltip | `https://www.radix-ui.com/primitives/docs/components/tooltip` |
+| Toggle | Switch | `https://www.radix-ui.com/primitives/docs/components/switch` |
+| Progress | Progress | `https://www.radix-ui.com/primitives/docs/components/progress` |
+| Separator | Separator | `https://www.radix-ui.com/primitives/docs/components/separator` |
+| DatePicker / DateTimePicker | Popover | `https://www.radix-ui.com/primitives/docs/components/popover` |
+| Combobox | Popover | `https://www.radix-ui.com/primitives/docs/components/popover` |
+
+If a component wraps a Radix primitive not in this table, derive the URL from the pattern: `https://www.radix-ui.com/primitives/docs/components/{kebab-case-name}`.
+
+---
+
+### The Story Outline
+
+Every story should:
+- Have a **PascalCase name** that clearly communicates what it shows
+- Have a **per-story description** (via `withDescription` helper or `parameters.docs.description.story`)
+- Use **real-looking content** — not "Lorem ipsum" but realistic Arbor-style copy (e.g., "Your session will expire in 10 minutes. Save your work.")
+- Avoid duplicating what another story already shows
+
+**Required stories for EVERY component:**
+- `Default` — the most basic usage with all required props
+- One story per significant **variant/enum value**
+- `Disabled` (if the component supports disabled state)
+- `AllVariants` or `Overview` — a render function showing the full palette side-by-side
+
+**Additional stories based on component type:**
+- **Form inputs**: `ErrorState`, `WithHelpText`, `WithLabel`, `Required`
+- **Overlay components (Modal, Slideover, Tooltip)**: Interactive story with `useState`
+- **Components with content guidelines**: `ContentGuidelines` story showing ideal vs. edge cases
+- **Components with accessibility props**: `WithAccessibilityLabel` or similar
+- **Components with optional content**: Stories for each combination (e.g., `WithTitle`, `WithButton`, `WithTitleAndButton`, `TitleOnly`)
+
+---
+
+## Linking Related Components
+
+The "Related components" section in the description should use **clickable Storybook story links**, not plain backtick names.
+
+### URL pattern
+
+Convert a component's `title` (in its meta) to a docs path:
+
+```
+title: 'Components/Button'          → ?path=/docs/components-button--docs
+title: 'Components/Modals/Modal'    → ?path=/docs/components-modals-modal--docs
+title: 'Components/FormField/Inputs/SelectDropdown' → ?path=/docs/components-formfield-inputs-selectdropdown--docs
+```
+
+**Rule**: lowercase everything, replace `/` and spaces with `-`, append `--docs`.
+
+### Markdown link format
+
+```markdown
+[Button](?path=/docs/components-button--docs)
+```
+
+### Known component paths
+
+| Component | Story title | Link path |
+|---|---|---|
+| Avatar | `Components/Avatar` | `?path=/docs/components-avatar--docs` |
+| AvatarGroup | `Components/AvatarGroup` | `?path=/docs/components-avatargroup--docs` |
+| Badge | `Components/Badge` | `?path=/docs/components-badge--docs` |
+| Banner | `Components/Banner` | `?path=/docs/components-banner--docs` |
+| Button | `Components/Button` | `?path=/docs/components-button--docs` |
+| Card | `Components/Card` | `?path=/docs/components-card--docs` |
+| Combobox | `Components/Combobox` | `?path=/docs/components-combobox--docs` |
+| DatePicker | `Components/DatePicker` | `?path=/docs/components-datepicker--docs` |
+| Dot | `Components/Dot` | `?path=/docs/components-dot--docs` |
+| Dropdown | `Components/Dropdown` | `?path=/docs/components-dropdown--docs` |
+| EditableText | `Components/EditableText` | `?path=/docs/components-editabletext--docs` |
+| Fieldset | `Components/FormField/Fieldset` | `?path=/docs/components-formfield-fieldset--docs` |
+| FormField | `Components/FormField` | `?path=/docs/components-formfield--docs` |
+| Heading | `Components/Heading` | `?path=/docs/components-heading--docs` |
+| Icon | `Components/Icon` | `?path=/docs/components-icon--docs` |
+| Modal | `Components/Modals/Modal` | `?path=/docs/components-modals-modal--docs` |
+| ModalManager | `Components/Modals/ModalManager` | `?path=/docs/components-modals-modalmanager--docs` |
+| Pill | `Components/Pill` | `?path=/docs/components-pill--docs` |
+| Progress | `Components/Progress` | `?path=/docs/components-progress--docs` |
+| Row | `Components/Row` | `?path=/docs/components-row--docs` |
+| SearchBar | `Components/SearchBar` | `?path=/docs/components-searchbar--docs` |
+| Section | `Components/Section` | `?path=/docs/components-section--docs` |
+| Separator | `Components/Separator` | `?path=/docs/components-separator--docs` |
+| ColourPickerDropdown | `Components/FormField/Inputs/ColourPickerDropdown` | `?path=/docs/components-formfield-inputs-colourpickerdropdown--docs` |
+| SelectDropdown | `Components/FormField/Inputs/SelectDropdown` | `?path=/docs/components-formfield-inputs-selectdropdown--docs` |
+| SingleUser | `Components/SingleUser` | `?path=/docs/components-singleuser--docs` |
+| SlideoverManager | `Components/SlideoverManager` | `?path=/docs/components-slideovermanager--docs` |
+| Table | `Components/Table` | `?path=/docs/components-table--docs` |
+| Tabs | `Components/Tabs` | `?path=/docs/components-tabs--docs` |
+| Tag | `Components/Tag` | `?path=/docs/components-tag--docs` |
+| Toast | `Components/Toast` | `?path=/docs/components-toast--docs` |
+| Toggle | `Components/Toggle` | `?path=/docs/components-toggle--docs` |
+| Tooltip | `Components/Tooltip/DestructuredTooltip` | `?path=/docs/components-tooltip-destructuredtooltip--docs` |
+| TooltipWrapper | `Components/Tooltip/TooltipWrapper` | `?path=/docs/components-tooltip-tooltipwrapper--docs` |
+| UserDropdown | `Components/UserDropdown` | `?path=/docs/components-userdropdown--docs` |
+
+If you need a component not in this table, derive its path from the `title` in its `.stories.tsx` meta using the conversion rule above.
+
+---
+
+## Confluence Design Guidance Reference
+
+The Atlassian cloud ID is always `orchard.atlassian.net`. Fetch pages with `mcp__atlassian__getConfluencePage`.
+
+| Component | Confluence Page ID | Key Guidance |
+|---|---|---|
+| Banner | `2216762167` | 4 types (Info/blue, Neutral/transparent, Destructive/red, Warning/orange). Use icons. Content max ~2 lines. |
+| Button | `2216957127` | Cover all states (disabled, focus, hover). Multiple variants. |
+| Modal | `2216762125` | Max 2 CTA buttons. Has overlay. Blocks interaction. For focused tasks. |
+| Slideover | `2216891079` | Blocks bg interaction, slides from edge. Use when editing while needing context. |
+| Tooltip, Dropdown, DatePicker | `2216891079` | Non-blocking, anchor-based. Use for quick contextual info. |
+| Section | `2217056643` | Section header link styles guidance. |
+| Toast | `2216957106` | Max 2 lines, ideally 1. Icon aligned to centre of first line. |
+| All (overview) | `2371747857` | Tables row heights, tooltip triggers, shadow guidance. |
+
+If no dedicated page exists for a component, still fetch the overview page — there may be a relevant section.
+
+---
+
+## Important Notes
+
+- **Always call ALL FOUR Golden Girls** — Sophia maps the API, Blanche validates tokens, Rose writes the stories, Dorothy verifies them
+- **Rose writes the stories** — do NOT write the story file yourself. Rose is THE expert
+- **Dorothy has final say** — if she flags a prop as wrong, fix it before shipping
+- **Real content matters** — use realistic Arbor-style copy in stories (e.g., school management UI language, not placeholder text)
+- **Storybook import**: always `@storybook/react-vite`, NOT `@storybook/react`
+- **No testIds in stories** — use accessible queries
+- **Always `nvm use`** before running any yarn commands (use `source ~/.nvm/nvm.sh && nvm use && yarn ...`)
+- **Use yarn, not npm**
+- This codebase serves millions of users in schools — ACCURATE documentation matters enormously
+- AROOO like you mean it!! 🐺💪
+
+## Story Wrapper Styling
+
+When stories need wrapper elements (divs, paragraphs, labels) to set context or layout, follow these rules:
+
+- **Never use inline styles for typography** — use a `ds-` class instead. Any class beginning with `ds-` automatically inherits the design system's base font styles. Use `className="ds-text"` for body copy, labels, and paragraph text in story wrappers.
+- **Use CSS tokens for spacing** — `var(--spacing-xlarge)`, `var(--spacing-large)`, etc. Never hardcode px values for padding/gap.
+- **Use CSS tokens for colours** — `var(--color-grey-600)`, `var(--color-semantic-destructive-600)`, etc. Never hardcode hex values.
+- **No `overflow: hidden` or `position: relative` on wrappers** for components that portal their content (Dropdown, Modal, Tooltip, Slideover) — it will clip the floating content.
+
+Example of a well-styled story wrapper:
+```tsx
+<div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+  <p className="ds-text" style={{ margin: 0 }}>Attendance report filter</p>
+  <Dropdown>...</Dropdown>
+</div>
+```
+
+## Global Docs Template & Page Structure
+
+The global template (`.storybook/DocsTemplate.tsx`) applies to all simple components automatically. It renders:
+
+1. Title + Subtitle
+2. Description (from `parameters.docs.description.component`) — intro, When to use, When NOT to use, design guidance, gotchas, accessibility. **DO NOT include "## Related components" here.**
+3. `<Heading>Props</Heading>` — h2 heading, TOC sibling of the description's h2 sections.
+4. Props intro copy — one-line hint ("The preview below is wired to the Controls panel — tweak any prop to see this story update in real time.") rendered as a Markdown block.
+5. Primary story (live interactive canvas) — lives UNDER the Props heading because the canvas and Controls are one interactive unit.
+6. `<Controls />` — interactive prop table driving the Primary canvas.
+7. `<Heading>Stories</Heading>` + `<Stories title="" />` — suppresses the built-in "STORIES" label so our explicit Heading is the only one.
+8. Related components — rendered automatically from `parameters.docs.relatedComponents` (a markdown string). Always last.
+
+For simple components, set both parameters in the meta:
+
+```tsx
+parameters: {
+  docs: {
+    description: { component: COMPONENT_DESCRIPTION },
+    relatedComponents: RELATED_COMPONENTS,
+  },
+},
+```
+
+For **compound components** (sub-component prop tables required), override `docs.page` with a custom function. Match the same final page order: intro → **Heading "Props" + intro copy** → Primary → Controls + sub-component tables → Stories → Related components.
+
+### Sub-component props for compound components
+
+When a compound component's sub-components extend external library types (e.g. Radix UI), Storybook **cannot** auto-generate `ArgTypes` for them — it shows "Args table with interactive controls couldn't be auto-generated". Fix: write manual `Markdown` prop tables instead:
+
+```tsx
+const TRIGGER_PROPS = `
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| \`disabled\` | \`boolean\` | \`false\` | Prevents the dropdown from opening. |
+| \`children\` | \`React.ReactElement\` | — | The trigger element. |
+`.trim();
+
+// In the docs page:
+<Subheading>Component.Trigger props</Subheading>
+<Markdown>{TRIGGER_PROPS}</Markdown>
+```
+
+This gives full control over which props are documented (only the ones consumers actually need, not 50 internal library props).
+
+### Storybook built-in doc blocks — availability and context gotcha
+
+`@storybook/addon-docs/blocks` exports several presentational primitives beyond `Title`/`Subtitle`/`Controls`/`Stories` — including `IconGallery` + `IconItem`, `ColorPalette` + `ColorItem`, and `Typeset`. They look tempting for reference/gallery stories but come with an **important context caveat**:
+
+**These blocks read from Storybook's internal theme (`theme.typography.fonts.base` / `fonts.mono` etc.) via Emotion's ThemeProvider. That provider is only wired up inside the docs page itself (the `docs.page` function), NOT inside regular story render functions.** Using them from a `render: () => <IconGallery>...</IconGallery>` in a normal story will crash at runtime with:
+
+```
+Error: can't access property "fonts", theme.typography is undefined
+```
+
+**Rules of thumb:**
+
+- If you want an `IconGallery` / `ColorPalette` / `Typeset` as part of a story canvas (the most common case in this codebase), **roll your own CSS-grid layout with design tokens** rather than the built-in blocks. See `Icon.stories.tsx` for a working category-grouped icon gallery using `var(--spacing-*)` and `var(--color-grey-*)` tokens.
+- Only reach for the built-in blocks if you're writing a **custom `docs.page`** (compound component style) where they render inside the docs context and the theme provider is present.
+
+**Import collision gotcha** (applies regardless of where you use them): if a story is exported with a name that matches a docs-block name (e.g. a story called `IconGallery` or `Primary`), TypeScript throws `TS2395: Individual declarations in merged declaration 'X' must be all exported or all local`. Alias the docs block on import:
+
+```tsx
+import { Primary as PrimaryBlock } from '@storybook/addon-docs/blocks';
+// ...
+export const Primary: Story = { args: { variant: 'primary' } };
+```
+
+Same pattern for `IconGallery`, `Title`, `Controls`, etc. if any of those appear as story export names.
+
+## What This Skill Does NOT Do
+
+- ❌ Modify the component source (use the component's own ticket for that)
+- ❌ Create new components
+- ❌ Write tests (stories are documentation, not tests)
+- ❌ Modify `src/index.ts`
+
+## What This Skill DOES Do
+
+- ✅ Write comprehensive autodocs-powered stories
+- ✅ Incorporate designer guidance from Confluence
+- ✅ Document all variants, states, and edge cases
+- ✅ Explain WHEN to use and WHEN NOT to use
+- ✅ Verify all props against actual source code (Dorothy!)
+- ✅ Ensure design token correctness in story wrappers (Blanche!)
+- ✅ Make stories warm, clear, and genuinely useful (Rose!)
+
+---
+
+AROOOOO HUNNI!! LET'S WRITE SOME MOST EXCELLENT STORIES AND MAKE OUR COMPONENTS SHINE LIKE THE BOMBASS DOCUMENTATION STARS THEY WERE BORN TO BE!! xxx 💪🏍️✨🐺🌹