How to build a Storybook component library in 2026
A practical setup for Storybook 10: stories that scale, args and controls, autodocs, and interaction, accessibility, and visual tests from the same files.
Most component libraries have a Storybook. Far fewer have a Storybook that fails when a component breaks. The difference is not the tool; it is how the stories are written, tagged, and wired into CI.
A Storybook component library is a component library in which every component, variant, and state is captured as a story: a small, typed example that renders in isolation and serves as documentation and as a test at the same time. You build one by writing stories in Component Story Format, driving variants with args, generating docs with autodocs, and running interaction, accessibility, and visual tests against those same stories.
Key takeaways
- As of October 2026 the current Storybook docs cover version 10.6, which is ESM-only and requires Node 20.16+, 22.19+, or 24+.
- Write one story per meaningful state, not per prop combination, and put shared defaults in component-level args.
- Adding the
autodocstag in your preview file gives every component a generated docs page with a live Controls table. - The Vitest addon turns every story into a test, so a story that renders is already a smoke test.
- For a large system, organize the sidebar by intent (foundations, components, patterns) and use tags to hide work in progress.
What does Storybook look like in 2026?
Storybook 10 shipped in October 2025 with one breaking change: it dropped CommonJS and became ESM-only. According to the Storybook team, its install is 29% smaller than Storybook 9, which was itself 50% smaller than Storybook 8. It also added module automocking through sb.mock, the ability to exclude stories by tag in the sidebar, and a preview of CSF Factories, also called CSF Next.
The docs now describe version 10.6. The core loop is unchanged: you write stories, and addons test and document them. What changed is how much testing now runs on Vitest, in a real browser.
How do you write stories that scale?
A story file has a default export, the meta, which names the component and sets shared defaults, and named exports, which are the stories. In Component Story Format 3, a story is an object with args. CSF Next, still a preview feature in 10.6, replaces the objects with factory functions: definePreview in your preview file, then preview.meta and meta.story in each story file, which gives full type safety and autocompletion for args.
Args and controls
Args are the inputs to a story, and they cascade at three levels:
- Project args in
.storybook/previewapply to every story. - Component args on the meta apply to every story for that component.
- Story args override both for a single story.
The Controls panel edits args live, so a designer can flip variant from default to destructive without touching code. Use argTypes to choose the control (select, color, boolean) and its mapping to turn simple options into complex values, such as an icon name into an actual icon element, since JSX cannot be serialized into the URL or the panel.
One story per state
Don't write a story for every prop combination. Write one for every state a person can see: default, each variant, disabled, loading, error, empty, and long content. Spread shared args (...Default.args) so a change in defaults flows through.
How does autodocs generate documentation?
Add tags: ['autodocs'] to .storybook/preview and every component gets a docs page. The generated page includes a title and description pulled from component metadata, a primary story, a Controls table of args and argTypes, and the remaining stories. Opt a component out with '!autodocs' on its meta, or hide a single story from the page the same way.
For that, write an MDX page that combines doc blocks with your own guidance, or set a custom docs.page template so every component's docs follow the same structure.
Autodocs answers what a component accepts; your guidance has to answer when to use it.
How do you test a component library in Storybook?
Every test type below runs against stories you have already written.
| Test type | What it catches | How it runs |
|---|---|---|
| Render test | Components that throw or fail to mount | Every story, automatically, with the Vitest addon |
| Interaction test | Broken behavior: a dialog that won't close, a form that won't submit | A play function that clicks, types, and asserts |
| Accessibility test | Missing labels, low contrast, invalid ARIA | The a11y addon, built on Deque's axe-core |
| Visual test | Unintended pixel changes in any story | Chromatic, via the @chromatic-com/storybook addon |
| Coverage | Code no story exercises | The testing widget and a coverage report |
Install the Vitest addon with npx storybook add @storybook/addon-vitest. It turns stories into Vitest tests that run in browser mode, and the testing widget at the bottom of the sidebar runs them on demand or in watch mode. In CI, add a script that runs vitest --project=storybook.
For accessibility, set parameters.a11y.test to 'error' so violations fail the run, or to 'todo' while you work through a backlog. The docs say the addon catches up to 57% of WCAG issues automatically, so keep a keyboard and screen reader pass for the rest. Visual tests compare each story to an accepted baseline; changed stories are highlighted, and you accept or fix them.
How should you organize stories for a large design system?
Storybook builds the sidebar from each story's title, and slashes create groups: Components/Forms/Select sits inside Forms inside Components. By default stories appear in import order; set storySort in your preview parameters with an order array to fix the sequence, and use a '*' entry to push everything else, such as a WIP group, to the end.
For a system with hundreds of components, use the four-shelf layout:
- Foundations: tokens rendered as swatches, type scales, spacing, radius, and icons.
- Components: one file per component, titled by family, such as
Components/Overlays/Dialog. - Patterns: compositions like sign-in forms, filter bars, and empty states.
- Pages: full screens built only from the shelves above, which prove the system composes.
Then give every component the same checklist before it ships:
- A
Defaultstory plus one story per variant and per visible state. - A
playfunction for every interactive behavior, usingfnto assert callbacks. - Accessibility set to
'error', with any exception written down in the story. - Autodocs enabled, plus a short usage note on when to choose this component.
- A status tag such as
experimentalordeprecated, with experimental stories excluded from the sidebar by default.
Storybook 10 lets you exclude tagged stories in the sidebar and set default filters in config, so unfinished work stays reachable without crowding the components people should use.
Where Pegasus fits
Pegasus ships a Storybook with stories and tests for its components, alongside the React code and a Figma library of 1,540 components. Component names and variant structure match across surfaces, so the variants a story exercises are the variants a designer picks in Figma, and one token source themes both.
The components are written in TypeScript and built on shadcn/ui, Base UI primitives, recharts, and Tailwind CSS. They are built to WCAG 2.1 AA, with keyboard paths, focus states, and contrast documented per component, so the accessibility checklist above has a documented target to test against. If you extend Pegasus with your own components, the four-shelf layout and checklist give them the same structure as the rest of the library. A local MCP server also exposes the component catalog, including props, variants, and tokens, to clients such as Claude Code and Cursor.
FAQ
What is the latest version of Storybook?
As of October 2026, the Storybook documentation covers version 10.6. Storybook 10 launched in October 2025 as an ESM-only release that requires Node 20.16+, 22.19+, or 24+. It added module automocking, tag exclusion in the sidebar, and a preview of CSF Next for React.
Does Storybook replace unit tests for a component library?
For most UI behavior, yes. Interaction tests in play functions click, type, and assert against a real browser, which covers what component unit tests usually check. Keep plain unit tests for logic with no UI, such as formatters and reducers. Storybook adds what unit tests rarely have: a visible, debuggable record of each step.
Do I need Chromatic for visual testing in Storybook?
The visual testing workflow in Storybook's documentation uses Chromatic through the @chromatic-com/storybook addon, which takes snapshots in the cloud and compares them with accepted baselines, including across browsers. Interaction and accessibility tests run locally through the Vitest addon without it. Check Chromatic's site for current plans before you commit.
Sources
- Storybook 10, Storybook blog (2025)
- CSF Next, Storybook docs (2026)
- Args, Storybook docs (2026)
- Automatic documentation and Storybook, Storybook docs (2026)
- How to test UIs with Storybook, Storybook docs (2026)
- Accessibility tests, Storybook docs (2026)
- Visual tests, Storybook docs (2026)
- Naming components and hierarchy, Storybook docs (2026)
One system. In Figma and in code.
Pegasus ships 1,540 components, 470 tokens, matching React code, Storybook, and a local MCP server. $149, one-time.
Get the full system