feat(skills): promote Storybook story generation to a documented skill

.claude/CUSTOM-AGENTS-GUIDE.md

@@ -142,7 +142,7 @@ User: "Use the accessibility-auditor agent to check this page"
 
 ## Agent + Skill Integration
 
-Agents work alongside the 23 custom skills in `.claude/skills/`:
+Agents work alongside the 24 custom skills in `.claude/skills/`:
 
 | Agent | Complementary Skill |
 |-------|-------------------|

.claude/skills/README.md

@@ -1,7 +1,7 @@
 # Skills Catalog
 
-**Last Updated:** 2026-06-11
-**Total Skills:** 23
+**Last Updated:** 2026-07-01
+**Total Skills:** 24
 **Location:** `.claude/skills/`
 
 Skills are documentation-based workflows that trigger automatically when relevant keywords appear in conversation. They provide systematic guidance, not tool integrations.
@@ -146,6 +146,14 @@ These skills provide patterns and best practices. They trigger on relevant keywo
 - **Triggers:** "InDesign to React", "IDML", "PDF to React", "indesign pipeline", "brochure to React", "aurelius pipeline indesign"
 - **Output:** A React project (`components`, `stories`, `index.ts`, `tokens/`, extracted assets, plus Markdown + JSON reports)
 
+### Storybook Skills
+
+#### 24. storybook-story-generation (Phase 4.5)
+
+- **Purpose:** Auto-generates Storybook 8 (CSF3) `.stories.tsx` and `.mdx` docs from built React components using a `ts-morph` AST. Emits prop-aware `argTypes`/controls, a `Default` story seeded with destructured defaults, one variant story per string-literal-union value, `True`/`False` stories for booleans, and action args for `on*` callbacks. Wraps `scripts/generate-stories.sh`. Non-blocking.
+- **Triggers:** Phase 4.5 of `/build-from-figma`, `/build-from-canva`, and `/build-from-screenshot` (after component build), "generate Storybook stories", "auto-generate stories", "add MDX docs"
+- **Output:** `src/components/**/*.stories.tsx` and `src/components/**/*.mdx`
+
 ---
 
 ## Pipeline Flow
@@ -181,6 +189,8 @@ Figma Design                    Canva Design
               OR canva-react-converter (Canva)
               → components pass tests (GREEN)
                     |
+        +-- [Phase 4.5] storybook-story-generation → stories + MDX (non-blocking)
+                    |
                     v
     [Phase 5] visual-qa-verification → pixel-diff loop (max 5 iterations)
                     |

.claude/skills/figma-to-react-workflow/SKILL.md

@@ -379,6 +379,32 @@ pnpm vitest run --reporter=verbose
 
 Iterate until all tests pass (Green phase of TDD).
 
+### Step 2.7: Generate Storybook Stories (Non-Blocking)
+
+Once components are built and their unit tests pass, auto-generate Storybook
+stories and MDX docs. Invoke the **storybook-story-generation** skill (or run the
+script directly). This is **Phase 4.5** of the pipeline and is **non-blocking** —
+a failure here logs a warning and the pipeline continues.
+
+```bash
+# Generate .stories.tsx + .mdx for every component (skips ones that already have stories)
+./scripts/generate-stories.sh
+
+# Preview without writing, or force-regenerate:
+./scripts/generate-stories.sh --dry-run
+./scripts/generate-stories.sh --force
+```
+
+The generator parses each component with a `ts-morph` AST and emits CSF3 stories
+with prop-aware controls, one variant story per string-literal-union value,
+`True`/`False` stories for booleans, action args for `on*` callbacks, and an MDX
+autodocs page. Behavior is configured by `.claude/pipeline.config.json` →
+`storybook`. See the storybook-story-generation skill for the full reference.
+
+When running under `parallel-orchestration`, this maps to the `storybook` phase
+(`depends: [component-build]`, `blocking: false`) and runs alongside the visual
+diff and dark-mode checks.
+
 ## Phase 3: Verification
 
 After generation completes, invoke verification checks.
@@ -650,6 +676,7 @@ This skill works with:
 - **design-token-lock skill** — Produces `design-tokens.lock.json` consumed by Phase 2
 - **tdd-from-figma skill** — Produces test files that Phase 2 MUST satisfy (hard gate)
 - **e2e-test-generator skill** — Generates Playwright E2E tests in Phase 3.3
+- **storybook-story-generation skill** — Auto-generates Storybook stories + MDX docs in Phase 4.5 (non-blocking)
 - **figma-react-converter agent** — Generates React components during Phase 2
 - **visual-qa-agent** — Performs screenshot comparison in Phase 3
 - **accessibility-auditor agent** — Validates ARIA and keyboard navigation
@@ -660,6 +687,7 @@ This skill works with:
 - **scripts/verify-tokens.sh** — Token integrity enforcement in quality gate
 - **scripts/verify-test-coverage.sh** — Test existence verification (TDD gate)
 - **scripts/cross-browser-test.sh** — Multi-browser screenshot capture
+- **scripts/generate-stories.sh** — AST-based Storybook story + MDX generation (Phase 4.5)
 - **.claude/pipeline.config.json** — Thresholds, iteration limits, app type config
 
 ---

.claude/skills/storybook-story-generation/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: storybook-story-generation
+description: Use after React components are built (Phase 4.5 of the Figma/Canva/screenshot pipeline) or whenever a project needs Storybook coverage — auto-generates .stories.tsx and .mdx docs from components via ts-morph AST parsing, with prop controls, variant stories, action args, and default args. Keywords: Storybook, generate stories, .stories.tsx, MDX docs, argTypes, controls, autodocs, CSF3, variant stories, action args, component documentation, story generation, ts-morph
+---
+
+# Storybook Story Generation — AST-Based Stories + MDX Docs
+
+## Purpose
+
+Auto-generate Storybook 8 (CSF3) stories and MDX documentation from built React
+components. The generator parses each component's TypeScript source with a
+`ts-morph` AST — not regex — so it can reliably extract prop types, string-literal
+unions, default values, callback props, and JSDoc comments, then emit:
+
+- **`Component.stories.tsx`** — `Meta` with `tags: ['autodocs']`, prop-aware
+  `argTypes`/controls, a `Default` story seeded with destructured defaults, one
+  variant story per union value, `True`/`False` stories for booleans, action args
+  for callbacks, and optional responsive-viewport stories.
+- **`Component.mdx`** — an autodocs page with `Meta`, `Canvas`, `Controls`, and
+  `ArgTypes` blocks, plus the component's JSDoc description and a `Canvas` per
+  variant.
+
+The skill wraps `scripts/generate-stories.sh` (a thin wrapper over
+`scripts/generate-stories.js`). It is a **non-blocking** step: a failure never
+fails the build.
+
+## When to Use
+
+- **Phase 4.5** of `/build-from-figma`, `/build-from-canva`, and
+  `/build-from-screenshot` — immediately after components are built and unit tests
+  pass, before/alongside visual QA (runs in parallel, non-blocking).
+- Backfilling Storybook coverage for an existing component library.
+- When the user asks to "generate Storybook stories", "add stories for these
+  components", "create autodocs", or "document components in Storybook".
+
+**Trigger phrases:**
+- "Generate Storybook stories"
+- "Auto-generate stories for my components"
+- "Add MDX docs to Storybook"
+- "Create stories with controls and variants"
+
+**Do NOT use for:** hand-authored interaction/`play()` tests (those belong to the
+`react-testing-workflows` skill), or non-React output targets.
+
+## Inputs
+
+- **Required:** Built components under `src/components/**/*.tsx` (override with
+  `--src-dir`). Components must be **exported** and named with an uppercase first
+  letter (function, arrow-const, or default export).
+- **Recommended:** A props `interface ComponentNameProps` — the generator keys off
+  this naming convention to build controls and variants.
+- **Optional:** `.claude/pipeline.config.json` → `storybook` (thresholds and
+  toggles; see [Configuration](#configuration)).
+- **Optional:** `tsconfig.json` — used by `ts-morph` when present; otherwise a
+  sensible in-memory compiler config is used.
+
+## Process
+
+### Step 1: Read configuration
+
+Load `.claude/pipeline.config.json` → `storybook` (falls back to defaults if the
+file is missing or `autoGenerate` is unset). Relevant keys: `skipPatterns`,
+`generateMdx`, `maxVariantsPerProp`, `includeResponsiveViewports`, `viewports`
+(widths resolved from `visualDiff.breakpoints`).
+
+### Step 2: Scan for components
+
+Recursively walk `src/components`, collecting `.tsx` files while excluding
+`*.test.tsx`, `*.stories.tsx`, `*.d.ts`, `index.tsx`, and the `node_modules`,
+`__tests__`, and `__mocks__` directories. Files matching a `skipPatterns` glob are
+skipped. Components that already have a `.stories.tsx` sibling are skipped unless
+`--force` is passed.
+
+### Step 3: Extract prop metadata (AST)
+
+For each component the generator:
+1. Finds the first exported uppercase component (function decl, exported
+   `const`, or default export).
+2. Locates its `ComponentNameProps` interface.
+3. For each prop, records: name, optionality, control type, union options,
+   JSDoc description, and whether it is a callback.
+4. Reads default values from the parameter destructuring pattern
+   (`({ size = 'md' })` → `size: 'md'`).
+
+**Control mapping:**
+
+| Prop type | Control | Notes |
+|-----------|---------|-------|
+| `string` | `text` | |
+| `number` | `number` | |
+| `boolean` | `boolean` | also emits `True`/`False` variant stories |
+| `'a' \| 'b' \| 'c'` (string-literal union) | `select` | `options` populated; one variant story per value |
+| `on*` function (e.g. `onClick`) | action arg | `{ action: 'clicked' }` (past-tense of the event) |
+| other / complex | `text` | falls back to `text`; adjust manually if needed |
+
+### Step 4: Generate `.stories.tsx`
+
+Emit CSF3 with `title: 'Components/<path-relative-to-src>'`, `tags: ['autodocs']`,
+`argTypes`, a `Default` story (seeded with destructured defaults), variant stories
+(capped at `maxVariantsPerProp` per prop), and viewport stories when
+`includeResponsiveViewports` is enabled.
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { Badge } from './Badge';
+
+const meta: Meta<typeof Badge> = {
+  title: 'Components/ui/Badge',
+  component: Badge,
+  tags: ['autodocs'],
+  argTypes: {
+    variant: { control: 'select', options: ['info', 'success', 'warning', 'error'] },
+    onDismiss: { action: 'dismissed' },
+  },
+};
+export default meta;
+type Story = StoryObj<typeof Badge>;
+
+export const Default: Story = { args: { variant: 'info' } };
+export const Info: Story = { args: { variant: 'info' } };
+export const Success: Story = { args: { variant: 'success' } };
+// …one per union value
+```
+
+### Step 5: Generate `.mdx` (unless `--no-mdx` or `generateMdx: false`)
+
+Emit an autodocs page importing `@storybook/blocks`, referencing the sibling
+`.stories`, and embedding the component's JSDoc description, the `Default`
+`Canvas`, `Controls`, a `Canvas` per variant, and the full `ArgTypes` table.
+
+```mdx
+import { Meta, Canvas, Controls, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Badge.stories';
+
+<Meta of={Stories} />
+
+# Badge
+
+A status badge with semantic color variants.
+
+<Canvas of={Stories.Default} />
+<Controls of={Stories.Default} />
+<Canvas of={Stories.Info} />
+<ArgTypes of={Stories} />
+```
+
+### Step 6: Run and report
+
+```bash
+./scripts/generate-stories.sh            # generate stories + MDX for all components
+./scripts/generate-stories.sh --dry-run  # report what would be written, write nothing
+./scripts/generate-stories.sh --force    # overwrite existing stories
+./scripts/generate-stories.sh --no-mdx   # stories only, skip MDX
+./scripts/generate-stories.sh --json     # machine-readable { generated, skipped, files }
+```
+
+Because this step is **non-blocking**, log the generated/skipped counts and
+continue the pipeline even if generation fails.
+
+## CLI Reference
+
+| Flag | Default | Effect |
+|------|---------|--------|
+| `--src-dir <path>` | `src/components` | Component source directory to scan |
+| `--config <path>` | `.claude/pipeline.config.json` | Pipeline config path |
+| `--force` | off | Overwrite existing `.stories.tsx` files |
+| `--dry-run` | off | Report only; write nothing |
+| `--no-mdx` | off | Skip `.mdx` generation |
+| `--json` | off | Emit JSON (suppresses human logs) |
+
+## Configuration
+
+`.claude/pipeline.config.json` → `storybook`:
+
+| Key | Default | Purpose |
+|-----|---------|---------|
+| `autoGenerate` | `true` | Enable/disable generation in the pipeline |
+| `includeResponsiveViewports` | `true` | Add a viewport story per breakpoint |
+| `viewports` | `["mobile","tablet","desktop"]` | Which breakpoints to emit (widths from `visualDiff.breakpoints`) |
+| `skipPatterns` | `["**/index.ts","**/*.test.*","**/*.stories.*"]` | Globs to exclude |
+| `generateMdx` | `true` | Emit `.mdx` docs alongside stories |
+| `maxVariantsPerProp` | `10` | Cap variant stories per prop (prevents explosion) |
+
+## Output
+
+| File | Purpose |
+|------|---------|
+| `src/components/**/Component.stories.tsx` | CSF3 stories with controls, variants, actions |
+| `src/components/**/Component.mdx` | Autodocs page (Meta/Canvas/Controls/ArgTypes) |
+
+## Common Mistakes
+
+- **No controls generated.** Props are declared as a `type` alias rather than an
+  `interface ComponentNameProps`. The generator detects the type but does not yet
+  expand its members — convert to an `interface` (or add controls manually).
+- **Component skipped.** The export is lowercase, not exported, or the file is a
+  `*.test.tsx`/`index.tsx`. Ensure the component is exported with an uppercase name.
+- **Stories not overwritten.** Existing `.stories.tsx` are preserved by design; pass
+  `--force` to regenerate.
+- **`children`/complex props show a text control.** Non-primitive props fall back to
+  a `text` control — refine `argTypes` by hand where richer controls matter.
+- **Action name looks odd.** Action args derive a past-tense label from the event
+  name (`onClick` → `clicked`, `onChange` → `changed`); rename the arg in the story
+  if a different label reads better.
+
+## Integration
+
+- **figma-to-react-workflow skill** — invokes this skill as Phase 4.5, right after
+  components are built and unit tests pass (non-blocking, in parallel with visual QA).
+- **react-testing-workflows skill** — owns hand-authored `play()`/interaction tests;
+  this skill produces the base stories those can extend.
+- **parallel-orchestration skill** — runs the `storybook` phase (depends on
+  `component-build`, `blocking: false`) alongside `visual-diff` and `dark-mode`.
+- **scripts/generate-stories.sh** — bash wrapper; forwards all flags to the Node
+  generator.
+- **scripts/generate-stories.js** — the `ts-morph` AST generator that does the work.
+- **.claude/pipeline.config.json → storybook** — thresholds and toggles.
+
+---
+
+**Skill Version:** 1.0.0
+**Last Updated:** 2026-07-01

CLAUDE.md

@@ -18,7 +18,7 @@ The framework is designed for:
 project-root/
 ├── .claude/              # Claude Code configuration
 │   ├── agents/           # 56 specialized agents
-│   ├── skills/           # 23 React-specific skills
+│   ├── skills/           # 24 React-specific skills
 │   ├── commands/         # Custom slash commands
 │   ├── hooks/            # Hook scripts (automated hooks configured in settings.json)
 │   └── pipeline.config.json  # Pipeline thresholds, iteration limits, app types
@@ -238,7 +238,7 @@ Agents are invoked automatically based on task context.
 
 ---
 
-### Skills (23 Total)
+### Skills (24 Total)
 
 | Skill | Purpose | Triggers |
 |-------|---------|----------|
@@ -247,6 +247,7 @@ Agents are invoked automatically based on task context.
 | design-token-lock | Extract + lock Figma values → lockfile | Phase 2 of /build-from-figma |
 | tdd-from-figma | Write tests FIRST, app-type-aware (Chrome ext, PWA) | Phase 3 of /build-from-figma |
 | e2e-test-generator | Generate Playwright E2E from build-spec (new) | Phase 6 of /build-from-figma |
+| storybook-story-generation | Auto-generate Storybook stories + MDX from components (AST-based, non-blocking) | Phase 4.5 of /build-from-figma, "generate stories" |
 | react-component-development | Component patterns and best practices | "create component", "custom hook" |
 | react-testing-workflows | Vitest, RTL, Playwright, Storybook | "write tests", "test coverage" |
 | react-performance-optimization | Profiling, bundle analysis, Web Vitals | "performance", "bundle size" |
@@ -617,7 +618,7 @@ node scripts/metrics-dashboard.js summary  # Quick metrics summary
 
 ---
 
-**Last Updated:** 2026-06-20
-**Architecture:** 56 agents, 23 skills, 4 plugins + gh CLI, Figma + Canva + Playwright MCP, 40 scripts, 8 hooks, 5 renderers (nextjs, vite, astro, sveltekit, expo)
+**Last Updated:** 2026-07-01
+**Architecture:** 56 agents, 24 skills, 4 plugins + gh CLI, Figma + Canva + Playwright MCP, 40 scripts, 8 hooks, 5 renderers (nextjs, vite, astro, sveltekit, expo)
 
 > **Keeping counts in sync:** When adding or removing agents, skills, scripts, or hooks, update all count references across the project. Search for the old count number in `*.md` files to find all references: `CLAUDE.md`, `README.md`, `CONTRIBUTING.md`, `docs/onboarding/`, `docs/react-development/`, and `.claude/AGENT-NAMING-GUIDE.md`. The agent and skill counts are enforced automatically by `scripts/check-doc-counts.sh` (run in CI and on pre-commit), which recounts `.claude/agents/` and `.claude/skills/` and fails on any documented count that disagrees.

CONTRIBUTING.md

@@ -137,7 +137,7 @@ Because the bump is derived from commit history, **conventional commit messages
 
 ## Claude Code Agents
 
-Aurelius includes 56 specialized Claude Code agents and 23 skills that automate significant portions of the development workflow — from design-to-code conversion to testing, accessibility, and deployment.
+Aurelius includes 56 specialized Claude Code agents and 24 skills that automate significant portions of the development workflow — from design-to-code conversion to testing, accessibility, and deployment.
 
 If you have Claude Code installed, these agents and skills are available to you automatically when working in this repository. They can assist with component development, test writing, visual QA, and much more.