Developer Experience5 min read

Storybook

Build and document React components in isolation with Storybook - stories, controls, accessibility testing, and visual regression testing.

StorybookComponent LibraryUIDocumentationReact

skill: Storybook category: Developer Experience tags: [Storybook, Component Library, UI, Documentation, React] readingTime: 5

Storybook is a component workshop - it lets you build, test, and document UI in isolation before integrating. Teams with a design system use Storybook as the source of truth; QA teams use it for visual review; developers use it to build components without waiting for backend APIs.

Workflow

Write stories in CSF formatComponent Story Format (CSF) defines a component's states as named exports - each export is a variation visible in Storybook's sidebar.
Add decorators for context providersComponents that need Router, Redux, or theme providers fail in Storybook without wrapping. Decorators add these at story or global level.
Mock data and API callsComponents connected to APIs fail in Storybook without mocking. MSW Storybook addon intercepts requests in the browser worker.
Test accessibility with a11y addonStorybook's a11y addon runs axe-core on every story - catching missing labels, color contrast failures, and ARIA errors in development.
Publish and visual regression test with ChromaticChromatic deploys Storybook to a URL and captures screenshots - detecting pixel-level regressions on every PR.

Output Format

Storybook: CSF stories, global decorators for providers, MSW for API mocking, a11y addon, and Chromatic for visual regression.

meta: { title, component, argTypes }
Primary: { args: { ... } }
Loading: { args: { isLoading: true } }
Error: { parameters: { msw: { handlers: [...] } } }

Examples

Input

Output

Edge Cases & Gotchas

Missing module aliases - Storybook doesn't resolve @/ aliases by default. Add them in .storybook/main.ts: webpackFinal config or viteFinal config.
Heavy global decorators - Wrapping all stories with Redux/React Query providers slows Storybook startup. Use decorators only where needed, or use mock state instead of full providers.
Dark mode stories - Components with light/dark variants need both tested. Use @storybook/addon-themes to switch themes per story.
Storybook interactions testing - The @storybook/addon-interactions addon lets you write interaction tests in stories - they also run in CI via the Storybook test runner.

When to Break These Rules

Skip Storybook for apps without a shared component library - the overhead is not justified for non-reusable components.
Use Ladle (lightweight Storybook alternative) for faster startup and simpler setup when you don't need Storybook's addon ecosystem.

Reference Files

https://storybook.js.org/docs
https://www.chromatic.com/docs/