Turn Storybook into the Agent's Visual Verification Loop

Tier: Core · Workflow area: Component development · Tools: Storybook, Storybook MCP addon, Claude Code

Most AI component work fails at states nobody rendered: the loading skeleton that never got looked at, the error variant with unreadable contrast, the empty state that overflows. Storybook makes states cheap to enumerate; wiring it to the agent makes them cheap to verify — closing the loop between "generated" and "seen."

When to use

• Storybook already exists (or you're willing to run npx storybook@latest init today) and components have meaningful state matrices.
• Agents write or modify componentsevery generated component should arrive with its states rendered, not imagined.
• Reviews keep catching unrendered states"did anyone look at the error variant?" is the tell.
• You want visual regression laterstory coverage (this playbook) is the substrate Chromatic/Percy-style tooling (pb-26) runs on.

When NOT to use

• Pure logic moduleshooks and utilities need tests, not stories.
• One-off internal pages with a single statea story adds ceremony without leverage.
• As a substitute for interaction testsstories verify appearance per state; behavior still needs RTL/Playwright (pb-22, pb-24).

The recipe

1. 1.

   Make story generation part of every component task. Add the rule to your instruction file (pb-02), then request the matrix explicitly:

   Copy

   For OrderStatusCard, write OrderStatusCard.stories.tsx (CSF3) covering
   every visually distinct state:
   - Default (paid), Overdue, Void, Refunded
   - Loading (skeleton), Error (fetch failed, retry visible)
   - Empty (no line items), Long content (30-char product names, 12 items)
   - Dark mode via our theme decorator; RTL via our direction decorator
   Use realistic data from src/mocks/orders.ts. One story per state, named
   so the sidebar reads as a state inventory. Add argTypes for variant
   and size with controls.
   

   Good output: 8–10 named exports, realistic (not foo/bar) data, decorators reused from .storybook/preview.tsx rather than reinvented inline.

2. 2.

   Wire the agent to Storybook so it can see what it built. Run Storybook, then register the MCP endpoint (Storybook's MCP addon exposes stories, args, and rendered snapshots to agents):

   Copy

   npm run storybook
   claude mcp add storybook --transport http http://localhost:6006/mcp
   

   No MCP available? Screenshots close the same loop:

   Copy

   npx playwright screenshot \
     "http://localhost:6006/iframe.html?id=orderstatuscard--error&viewMode=story" \
     shots/orderstatuscard-error.png
   

3. 3.

   Make self-verification the definition of done. This prompt is the heart of the loop — the agent renders, inspects, and fixes before reporting back:

   Copy

   For each story in OrderStatusCard.stories.tsx: render it, look at it,
   and report a table of story -> pass/fail against these checks:
   - matches our tokens (no off-scale spacing, no non-token colors)
   - text truncation behaves at the long-content story
   - skeleton dimensions match loaded layout (no shift)
   - error state: retry button present, message readable in dark mode
   Fix every fail, re-render, and show the final table. Do not report done
   with any fail outstanding.
   

   A good final table lists each story with pass, plus a short note on what was fixed ("Overdue badge used #d97706 — replaced with text-warning-fg").

4. 4.

   Generate the usage docs while the context is hot. The agent has the whole API in context; capture it as MDX autodocs:

   Copy

   Write OrderStatusCard.mdx: one-paragraph purpose, when to use vs.
   StatusBadge, a Canvas block per key story, a props table via ArgTypes,
   and a Do/Don't list (3 each) based on our design-system conventions.
   

5. 5.

   Gate CI on story health so the loop can't rot. Storybook's test runner executes every story and fails on render errors and accessibility violations (with the a11y addon):

   Copy

   npx storybook build --quiet
   npx concurrently -k -s first \
     "npx http-server storybook-static -p 6006 --silent" \
     "npx wait-on tcp:6006 && npx test-storybook --url http://localhost:6006"
   

   Add coverage discipline: a PR that adds a component without stories fails review by convention, and your provenance checklist (pb-28) includes "all states have stories."

Make it yours

• React + Vite/Nextas written; prefer CSF3 with typed Meta/StoryObj, and the @storybook/addon-a11y + test-runner pairing for the CI gate.
• Vue 3 / AngularStorybook supports both with the same CSF3 shape; decorators wrap with your Pinia/provider setup or Angular's moduleMetadata; the self-verification prompt is unchanged.
• React NativeStorybook for React Native (on-device) or react-native-web Storybook in CI; screenshot capture runs through the RN Storybook web build, and the state matrix gains platform-specific stories (Android ripple, iOS safe-area).
• No-MCP environmentsthe Playwright screenshot loop in step 2 works with any agent that accepts images; batch-capture all stories with test-storybook --json output driving a small script.

Quality check

• Sidebar reads as a state inventorya teammate can enumerate the component's states from story names alone.
• The agent's pass/fail table exists in the PRevidence it rendered and checked each state, with fixes noted.
• Skeleton/loading stories match loaded dimensionstoggle between them; no layout shift.
• test-storybook green in CI including a11y checks — render errors and axe violations block merge.
• Docs MDX currentprops table generated from types, Do/Don't reflects this quarter's conventions.