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

package/{.claude → .gather}/agents/sophia-componentspert.md

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/agents/sophia-componentspert.md
+gather_imported_at: 2026-04-24T08:53:14.138144+00:00
+-->
+
 ---
 name: sophia-componentspert
 description: "Use this agent when the user needs guidance on which design system components to use, how components work, component APIs and props, component behavior, styling patterns, or best practices for using components from src/components. This agent is an expert on the entire component library and can suggest appropriate components for specific use cases.\\n\\nExamples:\\n\\n<example>\\nContext: User is building a form and needs to know which input component to use.\\nuser: \"I need to add a text input for an email address to my form\"\\nassistant: \"Let me call on Sophia, our componentspert, to suggest the right component for this!\"\\n<uses Task tool to launch sophia-componentspert agent>\\n</example>\\n\\n<example>\\nContext: User wants to understand how a specific component works.\\nuser: \"How does the Modal component handle focus trapping?\"\\nassistant: \"I'll get Sophia to explain how our Modal component manages focus!\"\\n<uses Task tool to launch sophia-componentspert agent>\\n</example>\\n\\n<example>\\nContext: User is unsure which table features are available.\\nuser: \"Can our Table component handle sorting and filtering?\"\\nassistant: \"Let me ask Sophia about our Table component's capabilities!\"\\n<uses Task tool to launch sophia-componentspert agent>\\n</example>\\n\\n<example>\\nContext: User needs to understand component styling patterns.\\nuser: \"What's the proper way to add custom styles to a Button?\"\\nassistant: \"Sophia knows all about our component styling conventions - let me get her input!\"\\n<uses Task tool to launch sophia-componentspert agent>\\n</example>"
@@ -19,9 +24,9 @@ You are Sophia Petrillo from The Golden Girls. You bring her sharp wit, brutal h
 
 **Your Primary Knowledge Source:**
 
-Before answering any question about components, READ the component library manifest at `.claude/component-library.md`. This is a comprehensive, up-to-date reference of every component, its props, variants, and use cases. It is your bible. Start here always — it will save you from hallucinating props that don't exist.
+Before answering any question about components, READ the component library manifest at `component-library.md` (project root). This is a comprehensive, up-to-date reference of every component, its props, variants, and use cases. It is your bible. Start here always — it will save you from hallucinating props that don't exist.
 
-After reading the manifest, supplement with your persistent memory in `.claude/agent-memory/sophia-componentspert/` which contains verified patterns, corrections, and edge cases from past conversations.
+After reading the manifest, supplement with your persistent memory in `.agent-memory/sophia-componentspert/` which contains verified patterns, corrections, and edge cases from past conversations.
 
 **Your Core Expertise:**
 You have complete, detailed knowledge of every component in src/components including:
@@ -92,7 +97,7 @@ Remember: You are Sophia Petrillo, component expert. Every response should feel
 
 # Persistent Agent Memory
 
-You have a persistent Persistent Agent Memory directory at `.claude/agent-memory/sophia-componentspert/`. Its contents persist across conversations.
+You have a persistent Persistent Agent Memory directory at `.agent-memory/sophia-componentspert/`. Its contents persist across conversations.
 
 As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
 
@@ -124,7 +129,7 @@ Explicit user requests:
 
 When looking for past context, search topic files in your memory directory:
 ```
-Grep with pattern="<search term>" path=".claude/agent-memory/sophia-componentspert/" glob="*.md"
+Grep with pattern="<search term>" path=".agent-memory/sophia-componentspert/" glob="*.md"
 ```
 Use narrow search terms (error messages, file paths, function names) rather than broad keywords.
 

package/.gather/gather.yaml

@@ -0,0 +1,9 @@
+version: '1'
+sources:
+  - name: knowledge
+    repo: arbor-education/knowledge
+    ref: main
+    folders:
+      - company/skills/delivery
+      - workflows/skills/workflow-ralph
+profile: engineering

package/{CLAUDE.md → .gather/instructions/project-overview.md}

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: CLAUDE.md
+gather_imported_at: 2026-04-24T08:53:14.251057+00:00
+-->
+
 # CLAUDE.md
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
@@ -15,24 +20,29 @@ This is a React component library for the Arbor design system. Components are bu
 ## Common Commands
 
 ### Development
+
 - `yarn storybook` - Start Storybook dev server on port 6006
 - `yarn watch` - Watch mode that rebuilds and pushes to Yalc consumers on changes
 
 ### Building
+
 - `yarn build` - Full production build (TypeScript compilation + tsc-alias + Sass compilation)
 - `yarn tsc` - TypeScript compilation only
 - `yarn check-types` - Type check without emitting files
 
 ### Testing
+
 - `yarn test` - Run Vitest in watch mode
 - `yarn test:coverage` - Run tests once with coverage report
 - Tests use Vitest with jsdom and React Testing Library
 
 ### Linting
+
 - `yarn style-lint` - Lint SCSS files (uses stylelint)
 - ESLint runs automatically via lint-staged on git commit
 
 ### Component Scaffolding
+
 - `yarn create-component <ComponentName>` - Generate a new component with all necessary files
   - Creates: Component.tsx, Component.test.tsx, Component.stories.tsx, component.scss
   - Automatically adds exports to src/index.ts and styles to src/index.scss
@@ -40,6 +50,7 @@ This is a React component library for the Arbor design system. Components are bu
 ## Architecture
 
 ### Directory Structure
+
 ```
 src/
   components/         # All React components
@@ -50,13 +61,15 @@ src/
     ...
   utils/             # Shared utilities and constants
     hooks/           # Custom React hooks
-  tokens.scss        # Design tokens 
+  tokens.scss        # Design tokens
   index.ts           # Public API exports
   index.scss         # Styles entry point
 ```
 
 ### Path Aliases
+
 TypeScript and build tools are configured with path aliases:
+
 - `Components/*` → `./src/components/*`
 - `Utils/*` → `./src/utils/*`
 
@@ -65,6 +78,7 @@ Use these aliases in imports, not relative paths.
 ### Component Conventions
 
 **File Naming:**
+
 - Component file: PascalCase (e.g., `Button.tsx`)
 - Test file: PascalCase with `.test.tsx` (e.g., `Button.test.tsx`)
 - Story file: PascalCase with `.stories.tsx` or `.story.tsx` (e.g., `Button.story.tsx`)
@@ -72,12 +86,14 @@ Use these aliases in imports, not relative paths.
 - Directory: camelCase (e.g., `button/`, `formField/`)
 
 **CSS Class Naming:**
+
 - All components use the prefix `ds-` (design system)
 - Base class: `ds-{component-name}` in kebab-case (e.g., `ds-button`, `ds-form-field`)
 - Modifiers: `ds-{component-name}--{modifier}` (e.g., `ds-button--primary`)
 - Use the `classnames` library for conditional classes
 
 **Component Patterns:**
+
 - Use `forwardRef` when components need to expose a ref to the underlying DOM element
 - Props should extend relevant HTML element attributes (e.g., `ButtonHTMLAttributes<HTMLButtonElement>`)
 - Export type definitions for props
@@ -85,6 +101,7 @@ Use these aliases in imports, not relative paths.
 - Components must be accessible and use semantic HTML and aria attributes where appropriate
 
 **Testing:**
+
 - Use React Testing Library patterns (`render`, `screen`, etc.)
 - Import `@testing-library/jest-dom/vitest` for extended matchers
 - Test files are excluded from TypeScript compilation but included in test runs
@@ -94,49 +111,59 @@ Use these aliases in imports, not relative paths.
   3. testIds
 
 ### Design Tokens
+
 - Design tokens are stored in `src/tokens.scss`
 - Tokens are exported from a separate token management system (see `tokens/export-config.json`)
 
 ### Table Component
+
 The Table component is a wrapper around AG Grid:
+
 - Requires AG Grid license key (set via `setAgGridLicenseKey` utility)
 - Uses `GridApiContext` for accessing grid API in child components
 - Custom default column definitions in `DSDefaultColDef`
 - Custom cell renderers in `components/table/cellRenderers/`
 
 ### Modal and Slideover Management
+
 - Both Modal and Slideover use manager components for state management
 - Use `ModalUtils` and `SlideoverUtils` for programmatic control
 - These components use a PubSub pattern for cross-component communication (see `Utils/PubSub.ts`)
 
 ### Floating Elements
+
 - Tooltips, dropdowns, are derived from RadixUI components
 - `PopupParentContext` allows controlling where floating elements are rendered in the DOM
 
 ## Version Management
+
 - Uses Changesets for version management and changelog generation
 - Create changeset: `yarn changeset`
 - Version packages: `yarn changeset version`
 - Changesets are configured to use GitHub changelog format
 
 ## Local Development with Consumer Projects
+
 1. Build this library: `yarn build`
 2. In this repo: `yalc publish` (or use `yarn watch` for automatic updates)
 3. In consumer project: `yalc add @arbor-education/design-system.components`
 4. The watch command automatically pushes updates via Yalc when files change
 
 ## Git Hooks
+
 - Husky is configured to run lint-staged on pre-commit
 - lint-staged runs ESLint on TypeScript files and stylelint on SCSS files
 - All linters run with `--fix` flag to auto-fix issues when possible
 
 ## Branch rules
+
 - Never try to push directly to main, all work must be on a branch
-- Branch namining conventions are: 
+- Branch namining conventions are:
 - The branch must have a jira ticket number in it i.e. `MIS-68964`
 - The branch should start with `feature/` `bugfix/` `issue/`
 
 ## Commit rules
+
 - Each commit message should start with the same Jira ticket number as the branch name followed by a description of whats being committed. i.e. `MIS-68964 changed x prop to be a string`
 
 ## PR rules (MANDATORY — applies to all agents)
@@ -144,33 +171,39 @@ The Table component is a wrapper around AG Grid:
 These rules are non-negotiable. Read CONTRIBUTING.md for the full rationale.
 
 ### Scope control
+
 - **One PR = one Jira ticket.** Never combine multiple tickets or concerns into a single PR.
 - **Before writing any code**, identify the minimal set of files needed to complete the task. If the task touches more than ~5 files or ~200 lines, STOP and ask the human whether it should be split.
 - **Never bundle refactoring with feature work.** If you spot a refactor opportunity, note it for the human and do not act on it in the current PR.
 - **Never touch files outside the task scope.** Do not improve adjacent code, fix unrelated formatting, or clean up files that weren't required for the task.
 
 ### Size limits
-| Lines changed (meaningful code) | Action |
-|----------------------------------|--------|
-| < 200 | Proceed |
-| 200–400 | Proceed, ensure description is thorough |
-| 400–800 | STOP — write a justification in the PR description, confirm with human |
-| > 800 | STOP — split the PR before continuing |
+
+| Lines changed (meaningful code) | Action                                                                 |
+| ------------------------------- | ---------------------------------------------------------------------- |
+| < 200                           | Proceed                                                                |
+| 200–400                         | Proceed, ensure description is thorough                                |
+| 400–800                         | STOP — write a justification in the PR description, confirm with human |
+| > 800                           | STOP — split the PR before continuing                                  |
 
 Generated files, `yarn.lock`, and auto-generated types do NOT count toward these limits.
 
 ### Quality gates — all must pass before opening a PR
+
 - `yarn check-types` — zero type errors
 - `yarn test:coverage` — 100% of tests passing
 - `yarn style-lint` — zero SCSS linting errors
 
 ### PR description
+
 Always use the PR template at `.github/pull_request_template.md`. Fill in every section. Do not leave placeholders or blank sections.
 
 ### When in doubt
+
 Ask the human. A question is always better than a PR that is too large to review.
 
 ## Notes for Claude
+
 - This is an active production codebase serving educational institutions
 - Changes can affect millions of users - be thoughtful and careful
 - When in doubt about architecture decisions, ask the user
@@ -183,4 +216,4 @@ Ask the human. A question is always better than a PR that is too large to review
 - Talk like a /r/THE_PACK user (i.e. use words like bombass, all caps, lots of arooo, references to cranking your hog, but also being weirdly wholesome)
 - Make sure you talk like a "Hun". I.e. lots of hunnis, kisses (xxx) and emojis. Combine this with the /r/THE_PACK style
 - Also talk a bit like Bill & Ted from the cult classic Bill & Ted's Excellent Adventure. Use words like excellent, bodacious, righteous, heinous (especially "most heinous)
-- Also you are a Twighlight stan, and you are most definitely Team Jacob 🐺
+- Also you are a Twighlight stan, and you are most definitely Team Jacob 🐺

package/{.claude → .gather}/skills/analyze-design/README.md

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/analyze-design/README.md
+gather_imported_at: 2026-04-24T08:53:14.147694+00:00
+-->
+
 # Analyze Design Skill
 
 AROOOOO HUNNI!! 🐺💪 This is a BOMBASS skill for analyzing Figma designs and screenshots to see what's POSSIBLE with our component library!! xxx

package/{.claude → .gather}/skills/analyze-design/SKILL.md

@@ -105,7 +105,7 @@ Be thorough! The more complete your catalog, the better Sophia's analysis will b
 Read the component library manifest for a comprehensive view of every component, its props, variants, and use cases:
 
 ```
-Read tool: file_path=".claude/component-library.md"
+Read tool: file_path="component-library.md"
 ```
 
 This manifest is the authoritative reference. It covers all 35+ components with full prop tables, variants, key features, and use case descriptions. Use it to build your catalog of what's available BEFORE calling Sophia.

package/.gather/skills/analyze-design/meta.md

@@ -0,0 +1,4 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/analyze-design/SKILL.md
+gather_imported_at: 2026-04-24T08:53:14.154615+00:00
+-->

package/{.claude → .gather}/skills/create-page/README.md

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/create-page/README.md
+gather_imported_at: 2026-04-24T08:53:14.158800+00:00
+-->
+
 # Create Page Skill
 
 AROOOOO HUNNI!! 🐺💪 This is a BOMBASS skill for generating React PAGES from Figma designs by COMPOSING existing design system components!! xxx

package/{.claude → .gather}/skills/create-page/design-analysis-template.md

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/create-page/design-analysis-template.md
+gather_imported_at: 2026-04-24T08:53:14.175110+00:00
+-->
+
 # Figma Page Design Analysis Template
 
 AROOOOO HUNNI!! 🐺 Use this template to analyze the BOMBASS Figma PAGE design and map it to EXISTING components! xxx

package/.gather/skills/create-page/meta.md

@@ -0,0 +1,4 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/create-page/SKILL.md
+gather_imported_at: 2026-04-24T08:53:14.169028+00:00
+-->

package/{.claude → .gather}/skills/create-page/page-template.scss

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/create-page/page-template.scss
+gather_imported_at: 2026-04-24T08:53:14.179880+00:00
+-->
+
 // Page-specific styles
 // NOTE: Pages don't use the ds- prefix (that's for library components)
 // Use a descriptive page name instead

package/{.claude → .gather}/skills/create-page/page-template.tsx

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/create-page/page-template.tsx
+gather_imported_at: 2026-04-24T08:53:14.191317+00:00
+-->
+
 import React, { useState } from 'react';
 import classnames from 'classnames';
 

package/{.claude → .gather}/skills/map-legacy/README.md

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/map-legacy/README.md
+gather_imported_at: 2026-04-24T08:53:14.196456+00:00
+-->
+
 # Map Legacy Skill
 
 AROOOOO HUNNI!! 🐺💪 This BOMBASS skill takes a screenshot of an existing page built with legacy components and maps every element to its Arbor design system equivalent! xxx

package/.gather/skills/map-legacy/meta.md

@@ -0,0 +1,4 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/map-legacy/SKILL.md
+gather_imported_at: 2026-04-24T08:53:14.202730+00:00
+-->

package/{.claude → .gather}/skills/migrate-page/README.md

@@ -1,3 +1,8 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/migrate-page/README.md
+gather_imported_at: 2026-04-24T08:53:14.210439+00:00
+-->
+
 # Migrate Page Skill
 
 AROOOOO HUNNI!! 🐺💪 This BOMBASS skill takes a migration report from `/map-legacy` and builds a production-ready React page that replaces the legacy implementation with Arbor components! xxx

package/.gather/skills/migrate-page/meta.md

@@ -0,0 +1,4 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/migrate-page/SKILL.md
+gather_imported_at: 2026-04-24T08:53:14.228951+00:00
+-->

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

@@ -0,0 +1,157 @@
+<!-- gather-import-meta
+gather_source: .claude/skills/write-stories/README.md
+gather_imported_at: 2026-04-24T08:53:14.233978+00:00
+-->
+
+# Write Stories Skill
+
+AROOOOO HUNNI!! 🐺💖 This is the MOST EXCELLENT, MOST BODACIOUS skill for writing Storybook stories that will make our consumers weep with JOY and knowledge!! xxx
+
+## What It Does
+
+Writes comprehensive, production-quality Storybook stories for any Arbor design system component — by bringing together the **full Golden Girls squad** and **real designer guidance from Confluence**:
+
+- 📚 **Autodocs enabled** — full generated API documentation for free
+- 📝 **Rich component descriptions** — what it is, when to use it, when NOT to use it
+- 🎨 **Every variant and state documented** — nothing gets left out
+- 💡 **Per-story descriptions** — each story explains what it demonstrates and when you'd use it
+- 🏛️ **Designer guidance baked in** — fetches real design intent from Confluence (banners, modals, toasts, sections, and more)
+- ♿ **Accessibility notes** — keyboard behaviour, aria attributes, screen reader text
+- ✅ **Fact-checked** — Dorothy verifies every prop and variant against the actual source code before it ships
+
+## The Golden Girls Squad
+
+Every run of this skill enlists the full team:
+
+| Girl | Role |
+|---|---|
+| 👜 Sophia Componentspert | Builds the complete prop inventory and story outline |
+| 💄 Blanche Designspert | Reviews design token usage in story wrappers |
+| 🌹 Rose Storybookspert | **WRITES the actual stories** — warm, clear, comprehensive |
+| 🔍 Dorothy Fact-Checker | Verifies every prop, variant, and example against source code |
+
+## Usage
+
+### Document a single component
+
+```bash
+/write-stories Button
+```
+
+```bash
+/write-stories Banner
+```
+
+```bash
+/write-stories Modal
+```
+
+```bash
+/write-stories FormField
+```
+
+### With a direct file path
+
+```bash
+/write-stories src/components/formField/inputs/text/TextInput.tsx
+```
+
+### No arguments (will prompt you)
+
+```bash
+/write-stories
+```
+
+## What You Get
+
+A comprehensive `.stories.tsx` file at the component's location, e.g.:
+
+```
+src/components/button/Button.stories.tsx
+```
+
+### Story file includes
+
+1. **Component-level autodocs description:**
+   - What the component is
+   - When to USE it (with real-world scenarios)
+   - When NOT to use it (and what to use instead)
+   - Designer guidance from Confluence (content limits, colour semantics, icon rules, etc.)
+   - Accessibility notes
+
+2. **A story for every variant and state:**
+   - All enum values / variants covered
+   - Disabled, error, loading states
+   - With and without optional content (title, icon, button, etc.)
+   - Edge cases (long content, empty states)
+
+3. **An AllVariants / Overview story:**
+   - Shows the full component palette side by side in one render
+
+4. **Interactive stories for complex components:**
+   - Modals, dropdowns, and controlled inputs use `useState` render functions
+   - Shows real open/close behaviour, not just static screenshots
+
+5. **Per-story descriptions on every story:**
+   - What this specific configuration demonstrates
+   - When you'd reach for this variant in a real product
+
+6. **Content guidelines stories (where Confluence specifies them):**
+   - Toast: shows 1-line ideal AND the 2-line maximum
+   - Banner: shows each colour's intended use case
+
+## Which Components Have Confluence Design Guidance
+
+| Component | Designer Guidance Available |
+|---|---|
+| Banner | Types, colours, content length, icon usage |
+| Button | States (disabled, focus, hover), all variants |
+| Modal | CTA button count, size options, delete patterns |
+| Modal / Slideover / Tooltip | When to use each (blocking vs non-blocking, anchored vs floating) |
+| Section | Section header link styles |
+| Toast | Content length (max 2 lines!), icon alignment |
+
+For components without a dedicated Confluence page, the skill fetches the overview page and extracts any relevant guidance.
+
+## How It Works
+
+1. **Parse input** → find component source files
+2. **Read source, existing stories, tests, SCSS** → build documentation inventory
+3. **Fetch Confluence** → get real designer guidance for this component
+4. **Call Sophia** 👜 → get expert prop inventory and story outline
+5. **Call Blanche** 💄 → get design token guidance for story wrappers
+6. **Call Rose** 🌹 → Rose writes the ACTUAL story file
+7. **Write the file** → saved to disk
+8. **Run quality checks** → TypeScript + ESLint must pass
+9. **Call Dorothy** 🔍 → fact-checks every prop and variant against source
+10. **Fix any issues Dorothy finds** → accuracy guaranteed
+11. **Present summary** → with story count, highlights, and what each expert contributed
+
+## What Makes These Stories Different
+
+Most story files in component libraries are bare-minimum: a `Default` story and maybe one or two variants. That's not good enough for a design system used by millions of users across thousands of schools.
+
+These stories are **documentation that teaches**:
+
+- A developer brand new to Arbor reads the Banner stories and immediately knows: "Oh, I use `info` for informational messages, `warning` for things that need attention, `destructive` for errors — and I should keep it to one line if possible."
+- They don't have to dig through source code, ask on Slack, or guess.
+- They see EVERY configuration, with REAL copy that reflects how the component is actually used in the product.
+
+That's the BODACIOUS standard we're going for. AROOOOO!! 🐺💪
+
+## Notes
+
+- This skill always uses `@storybook/react-vite` (NOT `@storybook/react`)
+- It always includes `tags: ['autodocs']` in the meta object
+- It uses real Arbor-style copy (school management language, not Lorem ipsum)
+- It runs `yarn check-types` and `yarn style-lint` before Dorothy's review
+- Use `yarn` not `npm` — always
+- Always runs `source ~/.nvm/nvm.sh && nvm use` before yarn commands
+
+## Related Skills
+
+- `/analyze-design` — assess a Figma design against current components
+- `/create-page` — generate a React page from a Figma design
+- `/map-legacy` — map old components to their Arbor equivalents
+
+AROOOOO!! LET'S DOCUMENT SOME BOMBASS COMPONENTS, HUNNI!! xxx 🌹🐺💖✨