Storybook: A Living Style Guide for Your UI
PDF style guides go stale the week they export. Storybook is a local website that renders your actual React components in isolation — every button state, every form error, every token swatch — always in sync with code.
Designers review pixels. Developers test edge cases. QA clicks flows without running the full app.
Vocabulary
| Term | Meaning |
|---|---|
| Story | One rendered state of a component (Primary, Disabled, Loading) |
| Meta | Storybook config block — title, component, default args |
| play() | Function that simulates user clicks inside a story — becomes an automated test |
| Autodocs | Auto-generated docs page from component props |
Steps
Step 1 — Install
Detects your framework, adds a .storybook/ config folder, example stories, and npm scripts.
Step 2 — Run locally
Sidebar lists all stories. Edit a component — preview hot-reloads.
Step 3 — Write a story file
Create Button.stories.tsx next to your component:
Each export is a visual state you can review in the sidebar.
Step 4 — Add an interaction test
This runs headlessly in CI via yarn test:storybook.
Step 5 — Document design tokens
Token pages parse CSS variables at runtime so swatches never drift from production:
When --primary changes in CSS, the Storybook color page updates automatically.
Step 6 — Build a static site
Share with stakeholders who do not run Node locally.
Common pitfalls
- Hardcoding hex swatches in docs — they drift from CSS variables.
- Skipping
play()tests — broken click handlers ship silently. - Not running
test:storybookin CI — stories break without anyone noticing.
Verify it works
Open Storybook. Click through variants. Run yarn test:storybook — all play tests should pass.
Takeaway
Install with npx storybook init. Develop with yarn storybook. Test with play(). Ship docs with yarn build-storybook. If it is not in Storybook, it is harder to review and easier to break.