How to Build a Design System with Storybook

A design system is a maintained set of reusable interface components, design decisions, and guidance for using them. Storybook gives a team a place to build components in isolation, show their rendered states, document their use, check them, and share the resulting catalog. It does not choose component boundaries, assign ownership of tokens, or define your contribution and release process; your team must establish those.

The practical sequence is: agree on the system’s scope, install Storybook in the frontend project, make stories for useful component states, add consumer guidance, connect tokens and design references where helpful, add accessibility checks, and publish a reviewable Storybook.

1. Define the system before filling the catalog

Start by deciding what belongs in the system and who owns each part. These are team decisions, not settings Storybook can make for you.

Scope: list the components and foundations your product teams need, such as buttons, form controls, typography, spacing, and color tokens.
Public APIs: decide which props and behaviors consumers can rely on. Prefer a small, understandable API over exposing implementation details.
Ownership: name who reviews changes to components, tokens, documentation, and accessibility expectations.
Contribution and release: define how a change is proposed, reviewed, versioned, and communicated to consumers.
Design source of truth: decide where tokens live and how implementation values stay aligned with design references.

Storybook is useful around these decisions: it provides an isolated workbench and a place to communicate the result. Keep the governance rules in your team’s contribution and release documentation as well as any relevant Storybook pages.

2. Install Storybook in the existing frontend project

Run the official quick-start command from the root of the application or component-library repository:

npm create storybook@latest

Follow the prompts for the project’s framework and build setup. Storybook documents support for React, Vue, Angular, Svelte, Web Components, and other integrations; support and setup details can change, so check the current Storybook getting-started documentation for your framework and version.

Use the package manager already used by the repository. Review the generated configuration and scripts, then start Storybook using the command the setup added to your project. Do not assume a command or configuration file is identical across frameworks or Storybook versions.

Keep the workbench close to the source

Stories should import the real components from the application or library. That lets the workbench render the component consumers will use, with project styles, providers, and assets configured as needed. If a component depends on a theme or context provider, configure the necessary decorator or global setup for stories rather than copying component markup into the story.

3. Build a useful story inventory

A story records a rendered component state, and a component can have multiple stories. Use that model to make the states consumers need to understand visible and repeatable.

Component type	Useful states to consider
Button	Default, secondary or destructive variant, sizes, disabled, loading, icon placement
Text field	Empty, filled, focused, disabled, invalid, helper text, long content
Dialog	Open, long content, confirmation, error, keyboard dismissal behavior
Data display	Populated, empty, loading, error, dense content, narrow viewport
Navigation	Current item, collapsed layout, overflow, responsive behavior

These are planning examples, not states Storybook creates automatically. Choose the states that expose actual design and behavior decisions. Include responsive or theme variants when consumers need to compare them. Avoid making a separate story for every theoretical combination of props; document meaningful combinations and use controls where interactive exploration helps.

Keep stories deterministic. Use stable example data and make required providers, fonts, and assets available so the same state is understandable locally and after publishing. Storybook describes stories as a pragmatic starting point for UI testing, so a clear story inventory can also become a foundation for checks.

4. Add documentation people can use

Storybook Autodocs can generate a baseline documentation page from component metadata. Use it where inferred API information is useful, then add authored guidance for points code metadata cannot explain. Storybook also supports custom documentation layouts and MDX pages. See Storybook’s component documentation guide and check the documentation version that matches your installed release.

A useful component page answers:

When should a consumer use this component, and when is another pattern more appropriate?
Which variants and props are supported, and which combinations are discouraged?
What interaction behavior should consumers expect, including keyboard behavior?
What content, labeling, and accessibility requirements apply?
How does this component compose with related components?

Keep the rendered examples near the explanation. Generated prop tables are a starting point, not a substitute for guidance about intent, limits, composition, and behavior.

5. Make design tokens and references discoverable

If the system uses design tokens, make their names and values easy for component consumers to find. A token catalog can show categories such as color, spacing, typography, and radius. Consider linking or mapping tokens to the components that use them when that helps people understand the system.

The Storybook Design Token addon documents rendering token documentation from annotated stylesheets and icon files, adding a token documentation block to Docs pages, and showing component usage for token names. It also describes custom presenters, filters, and themes. Its documentation is version-sensitive: the cited v5 branch supports Storybook v10 and newer, with separate branches for v9 and versions 7/8. Check compatibility before installing it.

For design handoff, Storybook documents embedding stories in Figma and embedding Figma frames in Storybook. Add references where they clarify intended appearance or behavior, and establish which source is authoritative when a design reference and implementation differ. See Storybook’s sharing documentation.

6. Add accessibility checks to the component workflow

Storybook’s accessibility addon checks rendered stories against automated rules based on WCAG and related practices. Its documentation describes findings as violations, passes, or incomplete, and says the addon uses Deque axe-core. Choose deliberately whether violations should warn or fail a check; the documentation describes both enforcement modes. See Storybook’s accessibility testing guide.

Run the checks against representative stories for each component.
Fix confirmed violations and keep a record of accepted exceptions.
Review incomplete results manually; they require human assessment.
Test important keyboard, focus, and assistive-technology behavior in addition to automated checks.

A passing automated panel is not proof that a component is accessible. Automated checks are one part of quality assurance; content, interaction, and real usage still need review.

7. Publish a Storybook for review

A static Storybook gives teammates and stakeholders a URL where they can review components without running the project locally. Storybook documents building a static site with npm run build-storybook and deploying it to a web host. It also documents Chromatic publishing and CI workflows. Use the current publishing guide for version-specific commands and action versions.

Choose a publishing workflow based on access control, CI, feedback, and how reviewers need to compare changes. Storybook lists static hosting options such as GitHub Pages, Netlify, or AWS S3, as well as hosted review workflows. The documentation does not establish one universal best choice.

When a library has its own Storybook

If you publish a shared component package, consumers may benefit from browsing its examples inside their own Storybook. Storybook documents remote Storybook composition and package composition. Package composition can use a storybook.url field, and Storybook recommends Chromatic for full support of package-composition features. This is optional; a single published catalog is enough for many internal systems. See the composition guide and package composition guide.

8. A repeatable contribution workflow

Propose the change: identify the component or token, the consumer need, and any API or visual impact.
Update implementation and stories together: include the states that make the change understandable and reviewable.
Update consumer documentation: explain changed usage, constraints, and migration needs.
Review quality: inspect the rendered states, automated accessibility findings, and relevant interaction behavior.
Publish a preview: give reviewers a link to the change where your publishing workflow supports it.
Release and communicate: follow the system’s versioning policy and tell consumers what changed.

Storybook supports the isolated development, documentation, testing, and sharing parts of this loop. Your repository process still needs to define approvals, compatibility guarantees, and release ownership.

Or skip the browser setup

For screenshots of a published Storybook or component page, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. The API documentation covers the available parameters.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://storybook.js.org -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://storybook.js.org"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://storybook.js.org' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing. Response headers report the page verdict and billing status.
An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Every feature is available on every plan.

Try ScreenshotNeo with 1,000 free screenshots a month, with no card required.

Troubleshooting

Problem	Likely cause	What to do
Storybook setup selects the wrong framework or fails during installation	The repository’s framework, version, package manager, or build configuration was not matched to the setup.	Check the current getting-started documentation for the exact framework and version, then review the generated configuration and dependency changes.
A story renders without the application theme or context	The isolated preview does not include a provider or global style used by the component.	Configure the necessary global setup or decorator and ensure its assets and styles are available to Storybook.
A component appears unstyled	Global CSS, fonts, assets, or build aliases are not loaded in the Storybook preview.	Trace the component’s dependencies in the application configuration and mirror the required style and asset setup in Storybook.
Autodocs omits useful guidance	Generated metadata does not express intent, composition rules, or usage constraints.	Add authored prose and examples using the documentation features supported by the installed Storybook version.
Token addon does not work with the installed release	The selected addon documentation branch targets a different Storybook version.	Check the addon’s version-specific documentation before installation and choose the branch compatible with the project.
An accessibility result is marked incomplete	The rule requires human judgment or cannot be resolved by automated analysis.	Review the rendered state manually, including its content and interactions; do not treat incomplete as a pass.
Published Storybook is missing styles or assets	The production build cannot resolve an asset, environment setting, or path used locally.	Inspect the build output and deployment configuration, verify assets are included, and use the current publishing guide for release-specific settings.
Reviewers cannot open the published catalog	Hosting access controls or the chosen review workflow restrict access.	Check the intended audience and hosting permissions, then share through a workflow that grants the required access.

Performance, reliability, and cost

Keep the catalog focused: document meaningful states rather than every possible prop combination. This keeps navigation useful and reduces avoidable review work.
Make examples deterministic: stable data, fonts, providers, and assets make stories easier to compare and less likely to vary between local and published builds.
Make publishing part of review: a maintained build and a reliable preview path help reviewers see the same component states documented in source.
Budget maintenance: every public component API and story adds ongoing documentation and compatibility work. Assign ownership and retire obsolete examples.
Choose hosting for workflow needs: access control, CI integration, feedback, and versioning matter more than an unsupported universal performance ranking. The cited Storybook sources provide publishing paths, not comparative hosting benchmarks.
Plan for tool and addon versions: framework integrations, CLI commands, and addon compatibility can change. Check current official documentation when upgrading.

Storybook is open source and free according to its getting-started documentation. Hosted publishing and review choices may have their own terms and costs; consult the relevant provider’s current information before selecting one. ScreenshotNeo is an optional way to capture published pages, with the plan prices listed above.

FAQ

Does Storybook create a design system automatically?

No. It provides a workbench and documentation environment; your team defines the system, APIs, ownership, and release process.

Do all components need stories?

Prioritize reusable components and states that consumers or reviewers need to inspect. A story is most useful when it makes a meaningful state reproducible.

Can the catalog include design files?

Storybook documents integrations for embedding stories in Figma and Figma frames in Storybook. Choose references that help consumers understand the implementation.

Should every Storybook be public?

No. Select access controls and hosting based on who needs to review the system and your organization’s requirements.

Can screenshots replace component tests?

No. A screenshot captures a rendered page state. Stories, interaction checks, accessibility review, and other tests answer different questions.