Building a Design System with Storybook and React

First, use npx storybook init to install and configure Storybook in React project, run npm run storybook to start the local development server; 2. Organize component file structure by function or type, and create corresponding .stories.js files to define different states in each component directory; 3. Use Storybook's Args and Controls systems to achieve dynamic attribute adjustments to facilitate testing of various interactive states; 4. Use MDX files to write rich text documents containing design specifications, accessibility instructions, etc., and support MDX loading through configuration; 5. Define design tokens through themes and use ThemeProvider to globally inject theme styles in preview.js; 6. Integrate Jest and React Testing Library performs unit testing, visual regression testing with Chromatic, and checks for accessibility issues via @storybook/addon-a11y. Finally, a scalable design system that supports independent development, visual documents, automated testing, and promotes design and development collaboration. This system can achieve efficient reuse across teams by gradually iterating components, becoming a necessary tool for improving UI consistency and development efficiency.

Building a design system with Storybook and React is a powerful way to create consistent, reusable UI components that scale across teams and products. Storybook provides an isolated development environment for UI components, making it easier to build, test, and document them in isolation—without relying on the full app. When paired with React, this combo becomes a go-to setup for modern design systems.

Here's how to approach it effectively.

1. Set Up Storybook with React

Start by adding Storybook to your React project. If you're using Create React App or a standard React setup, the easiest way is using the automated CLI:

 npx storybook init

This command installs Storybook, adds the necessary configuration files, and sets up example stories. Once done, run:

 npm run storybook

This starts the Storybook development server, usually at http://localhost:6006 , where you can view your components in real time.

Tip: The init command works well with most React settings, including Vite and Next.js. If you're using a custom webpack config, you might need to adjust .storybook/main.js accordingly.

2. Structure Your Components and Stories

A well-organized file structure is key to maintainability. Group components logically—typically by feature or type (eg, atoms , molecules , organisms ), or by category like Button , Form , Navigation .

Example structure:

 src/
├── components/
│ ├── Button/
│ │ ├── Button.jsx
│ │ ├── Button.stories.js
│ └── Button.module.css
│ ├── Input/
│ │ ├── Input.jsx
│ └── Input.stories.js
├── styles/
│ └── theme.js

In each .stories.js file, define how the component should be rendered in different states:

 // Button.stories.js
import { Button } from './Button';

export default {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary'] },
  },
};

export const Primary = {
  args: {
    label: 'Click me',
    variant: 'primary',
  },
};

export const Disabled = {
  args: {
    label: 'Disabled',
    disabled: true,
  },
};

This creates interactive controls (like dropdowns for props) and lets designers and developers explore variations visually.

3. Use Args and Controls for Dynamic Testing

Storybook's Args system allows you to change component inputs on the fly. Combined with Controls , users can tweak props directly in the UI—great for testing edge cases and showcasing flexibility.

Example:

 argTypes: {
  size: { control: 'radio', options: ['small', 'medium', 'large'] },
  onClick: { action: 'clicked' }, // logs clicks
}

This means QA, PMs, or designers can interact with the button and see how it behaves when clicked or resized—without touching code.

Pro tip: Use controls: { exclude: ['id', 'className'] } to hide internal or non-visual props from the controls panel.

4. Document with MDX and Add Design Guidelines

Go beyond code examples. Use MDX (Markdown JSX) to write rich documentation that includes design tokens, usage guidelines, accessibility notes, and even Figma links.

Create a Button.stories.mdx file:

 import { Meta, Story, Canvas } from '@storybook/blocks';
import * as ButtonStories from './Button.stories.js';

<Meta title="Components/Button" component={Button} />

# Button

Use buttons to trigger actions. Prefer primary buttons for main actions, secondary for alternatives.

<Canvas>
  <Story of={ButtonStories.Primary} />
</Canvas>

## Accessibility

Always include descriptive labels. Avoid icon-only buttons unless properly labeled with `aria-label`.

Then configure Storybook to load MDX files by updating .storybook/main.js :

 module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  // ...
};

Now your design system becomes a living style guide.

5. Integrate Design Tokens and Theming

Share visual styles (colors, typography, spacing) via a theme object, often using styled-components , emotion , or CSS-in-JS.

Example theme:

 // theme.js
export const theme = {
  colors: {
    primary: '#007bff',
    secondary: '#6c757d',
  },
  spacing: (factor) => `${0.5 * factor}rem`,
  typography: {
    heading: 'bold 1.5rem system-ui',
  },
};

Wrap your stories with a decorator to apply the theme globally in .storybook/preview.js :

 import { ThemeProvider } from 'styled-components';
import { theme } from '../src/styles/theme';

export const decorators = [
  (Story) => (
    <ThemeProvider theme={theme}>
      <Story />
    </ThemeProvider>
  ),
];

Now all components render with consistent styling.

6. Add Testing and Automation

A robust design system needs tests. Combine:

• Jest React Testing Library for unit and behavior tests.
• Chromatic (a Storybook add-on) for visual regression testing.

Install Chromatic:

 npx chromatic --project-token=<your-token>

It runs in CI and compares every story against previous versions, catching unintended visual changes.

Also consider adding a11y addon to catch accessibility issues:

 npm install @storybook/addon-a11y

Then enable it in .storybook/main.js :

 addons: ['@storybook/addon-a11y'];

Now you'll see an Accessibility tab in the UI with automated checks.

Final Thoughts

Building a design system with Storybook and React isn't just about components—it's about creating a shared language between design and development. With the right setup, you get:

• Isolated component development
• Interactive documentation
• Visual testing and consistency
• Collaboration-friendly interfaces

Start small (buttons, inputs), enforce consistency early, and grow iteratively. Over time, your design system becomes a force multipleer for product teams.

Basically, if you're using React and care about UI quality, Storybook isn't optional—it's essential.

The above is the detailed content of Building a Design System with Storybook and React. For more information, please follow other related articles on the PHP Chinese website!