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

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Write comprehensive, production-quality 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
@@ -11,11 +11,11 @@ AROOOOO HUNNI!! 🐺💖 Time to write the most EXCELLENT, most BODACIOUS Storyb
 
 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
+- ✅ Use the **mandatory custom docs.page format** (see below — NOT plain autodocs)
+- ✅ Include a custom `DocsPage` component with the correct TOC structure
+- ✅ Define `argTypes` for all key props so the **Controls** panel 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
+- ✅ Include per-story descriptions via the `withDescription` helper
 - ✅ 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
@@ -23,11 +23,16 @@ Write **comprehensive, production-quality Storybook stories** for a given Arbor
 
 **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.
+> **⚠️ MANDATORY DOCS FORMAT — READ THIS BEFORE DOING ANYTHING ELSE**
 >
-> **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.
+> ALL stories in this codebase use a **custom `docs.page` component** — NOT the plain autodocs format.
+> The canonical reference file is `src/components/progress/Progress.stories.tsx`. READ IT before writing any stories.
 >
-> **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 required page structure (TOC sections the user expects to see):
+> **Interactive example → Usage guidance → Developer notes → Examples → Related components**
+>
+> Do NOT use `parameters.docs.description.component` as a single blob. Do NOT omit the `docs.page` override.
+> Every single stories file must have the `XxxDocsPage` function and `docs: { page: XxxDocsPage }` in meta.
 
 ---
 
@@ -113,7 +118,7 @@ Look up designer guidance for this component using the Atlassian MCP tools. Use
 
 ### 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.
+Read `.claude/component-library.md` 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.
 
@@ -212,247 +217,149 @@ 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.
+**⚠️ BEFORE YOU WRITE A SINGLE LINE — READ `src/components/progress/Progress.stories.tsx`.**
+That is the canonical reference. Every stories file in this codebase follows that format. No exceptions.
+
+1. STORYBOOK IMPORT:
+   ```tsx
+   import type { Meta, StoryObj } from '@storybook/react-vite';
+   import {
+     Controls,
+     Heading as DocHeading,
+     Markdown,
+     Primary as DocPrimary,
+     Stories,
+     Subtitle,
+     Title,
+   } from '@storybook/addon-docs/blocks';
    ```
-   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(),
-        },
-      },
-    },
-    ```
+2. CONTENT STRINGS — define these as separate named consts ABOVE everything else:
+   - `DESCRIPTION_INTRO` — 1-2 sentence intro + Radix UI link if applicable (blockquote format)
+   - `USAGE_GUIDANCE` — `### When to use` bullets + `---` + `### When NOT to use` table
+   - `DEVELOPER_NOTES` — `### Critical usage patterns` + `---` + `### Accessibility` + `---` + `### TypeScript types` code block
+   - `RELATED_COMPONENTS` — `## Related components` with component links
+   - `PROPS_INTRO` — one sentence: `'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.'`
+
+3. CUSTOM DOCS PAGE — define a named function component ABOVE the meta:
+   ```tsx
+   function ComponentNameDocsPage() {
+     return (
+       <>
+         <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>
+       </>
+     );
+   }
+   ```
+   This is NOT optional. This is what produces the correct TOC.
+
+4. META — use `satisfies Meta<typeof ComponentName>` and wire the docs page:
+   ```tsx
+   const meta = {
+     title: 'Components/ComponentName',
+     component: ComponentName,
+     tags: ['autodocs'],
+     parameters: {
+       layout: 'padded',
+       docs: { page: ComponentNameDocsPage },
+     },
+     argTypes: { /* all key props */ },
+   } satisfies Meta<typeof ComponentName>;
+   ```
+   Do NOT put `description.component` in parameters.docs — the content is rendered by the Markdown blocks in the DocsPage function.
+
+5. ARGTYPES — MANDATORY for every key prop:
+   - `description`: plain English (use array of strings joined with space for long descriptions)
+   - `control`: appropriate control type or `false` to disable
+   - `table.type.summary`: TypeScript type as string
+   - `table.defaultValue.summary`: default value as string
+   - For callbacks: `action: 'callbackName'`, `control: false`
+
+6. STORY TYPE — prefer `type Story = StoryObj<typeof meta>` over `StoryObj<typeof ComponentName>`. The `typeof meta` form is stricter: it picks up `args` and `argTypes` for better type inference.
+
+7. WITHDESCRPTION HELPER — include verbatim (copy from Progress.stories.tsx):
+   ```tsx
+   const withDescription = (story: Story, description: string): Story => ({
+     ...story,
+     parameters: {
+       ...story.parameters,
+       docs: { ...story.parameters?.docs, description: { story: description } },
+     },
+   });
+   ```
 
-    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: { /* ... */ },
-    };
-    ```
+8. NAMED TEMPLATE COMPONENTS — for ALL stateful or complex stories, define a named function component BEFORE the story exports. No inline `() => {}` with useState. Follow the Progress.stories.tsx pattern exactly:
+   ```tsx
+   const MyStoryTemplate = () => {
+     const [state, setState] = useState(...);
+     return <Component ... />;
+   };
+   ```
+
+9. ALL STORIES use `withDescription(storyObject, 'description')`:
+   - `Default` story: `args` + `render: args => <Component {...args} />` — this wires Controls
+   - All other stories: `render: TemplateComponent` or `render: args => <Wrapper><Component {...args} /></Wrapper>`
+   - Non-default stories include `parameters.controls: { disable: true }` and `parameters.docs.source.code` with a named function component + `export default`
+
+10. SOURCE CODE — CRITICAL DISTINCTION:
+   - **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.
+   - **All other stories** (template-based, inline renders, stateful): use explicit `source.code` with a named function + `export default`.
+
+   For `Object.assign` components (Banner, AvatarGroup) where Storybook picks up the internal function name, use `source.transform` on the Default story to rename without breaking live updates:
+   ```tsx
+   parameters: {
+     docs: {
+       source: {
+         transform: (src: string) => src.replace(/BannerRoot/g, 'Banner'),
+       },
+     },
+   },
+   ```
 
-    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 },
-         },
+   Non-default SOURCE CODE FORMAT:
+   ```tsx
+   parameters: {
+     controls: { disable: true },
+     docs: {
+       source: {
+         language: 'tsx',
+         code: `
+   import { ComponentName } from '@arbor-education/design-system.components';
+
+   function ComponentNameStoryNameExample() {
+     return (
+       <ComponentName ... />
+     );
+   }
+   export default ComponentNameStoryNameExample;
+   `.trim(),
        },
-       ```
-    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!! 🌹💖"
+     },
+   },
+   ```
+
+10. REALISTIC CONTENT — use realistic Arbor/school-management copy in options and examples, not "Option 1, Option 2" or "Lorem ipsum"
+
+11. RADIX UI LINK — if the component wraps a Radix primitive, add this to DESCRIPTION_INTRO:
+    ```markdown
+    > **Built on [Radix UI ComponentName](https://www.radix-ui.com/primitives/docs/components/component-name).**
+    > The [panel/overlay/etc] renders via a portal — do **not** place inside a container with `overflow: hidden`.
+    ```
+
+Please write the COMPLETE stories file. Read Progress.stories.tsx first — match its structure exactly. Include every story from Sophia's outline. AROOOOO!! 🌹💖"
 ```
 
 **WAIT for Rose's full story file.** Rose will produce the complete `.stories.tsx` content.
@@ -704,15 +611,20 @@ If you need a component not in this table, derive its path from the `title` in i
 
 The Atlassian cloud ID is always `orchard.atlassian.net`. Fetch pages with `mcp__atlassian__getConfluencePage`.
 
+> **⚠️ Page staleness warning**: Some older page IDs are archived. If a page returns no usable content, use CQL search to find the current page: `mcp__atlassian__searchConfluenceUsingCql` with `title ~ "ComponentName" AND space.key = "AG"`.
+
 | 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. |
+| Banner | `2390032476` | Current page: "Banners (on-page)". 4 types, icon guidance, content length. |
+| Button, inputs | `2216957127` | States, number inputs, date/time (check if archived). |
+| 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` | Max 2 lines, ideally 1. Icon aligned to centre of first line. |
+| Icon | `2431778909` | 3-sizes-only rule, icon+label patterns, accessibility. |
+| Badge / Tag / Pill | `2394521682` | "Pills & Tags (& Badges)" — current. |
+| Heading | `2393767941` | Single-H1 rule, action button limits, back-button legacy. |
+| CheckboxInput / RadioButtonInput | `2390720566` | Use cases, label phrasing, disabled tooltip guidance, keyboard/a11y. |
 | 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.
@@ -726,9 +638,13 @@ If no dedicated page exists for a component, still fetch the overview page — t
 - **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`
+- **Story type**: prefer `type Story = StoryObj<typeof meta>` over `StoryObj<typeof ComponentName>` — stricter inference
+- **`fn` imports**: come from `storybook/test` (unscoped), NOT `@storybook/test`
 - **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**
+- **No unsourced authority claims** — never write "most common bug" or "consumers frequently hit" without a source
+- **UserDropdown** — slated for demolition, do NOT write stories for it and exclude from "related components" lists
 - This codebase serves millions of users in schools — ACCURATE documentation matters enormously
 - AROOO like you mean it!! 🐺💪
 
@@ -736,44 +652,64 @@ If no dedicated page exists for a component, still fetch the overview page — t
 
 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.
+- **No unsourced authority claims** — never write "most common bug consumers report" or "consumers frequently hit this". No data source = no claim.
 
 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>
+  <p style={{ margin: 0, fontSize: 'var(--font-size-3-14)' }}>Attendance report filter</p>
   <Dropdown>...</Dropdown>
 </div>
 ```
 
-## Global Docs Template & Page Structure
+## Design Token Gotchas (Verified — always check before using)
+
+- **Font sizes are numeric, not semantic**: `--font-size-1-11` (0.688rem), `--font-size-2-13` (0.812rem), `--font-size-3-14` (0.875rem). There is NO `--font-size-small`, `--font-size-body`, or `--font-size-caption`.
+- **Grey scale**: `--color-grey-050` and `--color-grey-100` both exist. `--color-grey-50` (no leading zero) does NOT exist.
+- **Border radius**: only `--border-radius-xsmall` (4px), `--border-radius-small` (8px), `--border-radius-large` (16px), `--border-radius-round` (99px). NO `--border-radius-medium`.
+- **Spacing tokens**: `--spacing-xsmall`, `--spacing-small`, `--spacing-medium`, `--spacing-large`, `--spacing-xlarge`, `--spacing-xxlarge`, `--spacing-xxxlarge`.
+- **`--color-semantic-info-200` is phantom** — info scale is 050/100/300/500/600/700/800/900. No 200 tier.
+- **Icon names — always grep `allowedIcons.tsx`**: `calendar` is keyed as `date`. `bell` does NOT exist. Never assume an icon name.
+- **`fn` imports come from `storybook/test`** (unscoped), NOT `@storybook/test`. Flag if Rose ever uses the scoped form.
 
-The global template (`.storybook/DocsTemplate.tsx`) applies to all simple components automatically. It renders:
+## Docs Page Structure
 
-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.
+ALL stories use a custom `docs.page` function. The canonical reference is `src/components/progress/Progress.stories.tsx`.
 
-For simple components, set both parameters in the meta:
+The required page structure — produces this TOC:
+1. **Interactive example** — `<DocPrimary />` + `<Controls />`
+2. **Usage guidance** — When to use / When NOT to use
+3. **Developer notes** — Critical usage patterns / Accessibility / TypeScript types
+4. **Examples** — `<Stories title="" />`
+5. **Related components** — `<Markdown>{RELATED_COMPONENTS}</Markdown>` (always last)
 
 ```tsx
-parameters: {
-  docs: {
-    description: { component: COMPONENT_DESCRIPTION },
-    relatedComponents: RELATED_COMPONENTS,
-  },
-},
+function ComponentNameDocsPage() {
+  return (
+    <>
+      <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>
+    </>
+  );
+}
 ```
 
-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.
+For **compound components** (sub-components with their own prop tables), extend this pattern by adding `<Subheading>` + `<ArgTypes of={SubComponent} />` blocks between Controls and Usage guidance.
 
 ### Sub-component props for compound components
 

package/.storybook/preview.ts

@@ -5,6 +5,11 @@ import '../src/index.scss';
 
 const preview: Preview = {
   parameters: {
+    options: {
+      storySort: {
+        order: ['Getting Started', ['Welcome', 'Using the Components', 'Contributing'], 'Components', '*'],
+      },
+    },
     controls: {
       matchers: {
         color: /(background|color)$/i,

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.16.0
+
+### Minor Changes
+
+- [#175](https://github.com/arbor-education/design-system.components/pull/175) [`eb701a4`](https://github.com/arbor-education/design-system.components/commit/eb701a4177d358ceee29419247d7d6d898930faf) Thanks [@angusmglfraser](https://github.com/angusmglfraser)! - MIS-69977 🐛 sort out key population on checkbox and radio groups
+
+- [#168](https://github.com/arbor-education/design-system.components/pull/168) [`36de162`](https://github.com/arbor-education/design-system.components/commit/36de1620148a853b07539116b4f003585dd0a468) Thanks [@rickbairstow](https://github.com/rickbairstow)! - MIS-70192 Customisations for Table Dropdown Settings
+
+- [#171](https://github.com/arbor-education/design-system.components/pull/171) [`ba865e1`](https://github.com/arbor-education/design-system.components/commit/ba865e1b0316114120fed1264bd28996f7fead28) Thanks [@AmeeMorris](https://github.com/AmeeMorris)! - MIS-70118 New public API additions:
+
+  - `FormField` now supports `inputType: 'dateTimePicker'` with `inputProps: DateTimePickerProps`
+  - `Table.InlineTextCellRenderer` and `Table.SelectDropdownCellRenderer` are now exported from the `Table` namespace, consistent with all other cell renderers
+
+### Patch Changes
+
+- [#174](https://github.com/arbor-education/design-system.components/pull/174) [`d4ea4b7`](https://github.com/arbor-education/design-system.components/commit/d4ea4b74c0e81c2abd2c07f61a1d3d89bf282bd8) Thanks [@angusmglfraser](https://github.com/angusmglfraser)! - MIS-68567 🐛 fix AG Grid floating elements clamping to the main grid container
+
+## 0.15.0
+
+### Minor Changes
+
+- [#155](https://github.com/arbor-education/design-system.components/pull/155) [`1461039`](https://github.com/arbor-education/design-system.components/commit/146103967baa767076ec7a316944d5cb156134e6) Thanks [@Alex-DN-SP](https://github.com/Alex-DN-SP)! - MIS-69125 Number cell editor
+
+### Patch Changes
+
+- [#160](https://github.com/arbor-education/design-system.components/pull/160) [`cc9dc10`](https://github.com/arbor-education/design-system.components/commit/cc9dc10adafba77d790020afa60d7f3a22deb071) Thanks [@Alex-DN-SP](https://github.com/Alex-DN-SP)! - MIS-64984 Added option for vertical column headers
+
 ## 0.14.0
 
 ### Minor Changes

package/README.md

@@ -15,6 +15,14 @@ https://main--68c3f2a09d95b22aa55a11e8.chromatic.com/
 
 ---
 
+## Consuming the package
+
+If you're integrating this library into a consumer project, check out the guide on Confluence:
+
+[Consuming the design system NPM package](https://orchard.atlassian.net/wiki/spaces/SATD/pages/2500591662/Consuming+the+design+system+NPM+package)
+
+---
+
 ## Local setup
 
 ### Prerequisites