Initialize the React project and install Storybook, use npx storybook@latest init to configure the environment, run npm run storybook to start local services, and it is recommended to enable TypeScript to ensure type consistency; 2. Organize the component directory structure according to the functions, separate components, design tokens (colors, spacing, typography), themes and tool functions to improve maintainability; 3. Use Storybook's Args and argTypes to write interactive stories for components, supporting dynamic adjustment of attributes in the UI, which facilitates testing and review; 4. Use MDX files to combine Markdown and JSX, embed interactive stories through Canvas to build a rich documented visual guide; 5. Integrate plug-ins such as Controls, Actions, Docs, Accessibility and Designs to enhance the consistency of development experience and design; 6. Use Jest or React Testing Library for unit testing, combine Chromatic to implement visual regression testing, and package and publish the design system to npm or private warehouse for sharing by multiple teams. Through modular components, unified design of tokens, complete documentation and automated testing, the combination of React and Storybook provides a complete solution for building scalable, highly consistent UI systems.

Building a design system with Storybook and React has become a go-to approach for teams aiming to create consistent, maintainable, and scalable UIs. Storybook provides a sandbox environment to develop and test components in isolation, while React's component-based architecture fits naturally into a modular design system. Here's how to set it up effectively.

1. Set Up Storybook in a React Project

Start by initializing a React project (eg, using Vite or Create React App), then install Storybook:

 npx storybook@latest init

This command configures Storybook, adds necessary dependencies, and creates sample stories. Once installed, run:

 npm run storybook

This launches the local Storybook server, where you can view and interact with your components.

Pro tip: Use TypeScript and enforce strict typing from the start—this helps maintain consistency across your design system.

2. Structure Your Design System Components

Organize components in a logical folder structure. A common pattern:

 /src
  /components
    /Button
      Button.tsx
      Button.stories.tsx
      Button.test.tsx
      index.ts
    /Input
    /Card
  /tokens
    colors.ts
    spacing.ts
    typography.ts
  /themes
    defaultTheme.ts
  /utils
    styled-system.ts

• Tokens define design constants (colors, spacing, font sizes).
• Themes allow for theme switching and consistency.
• Utils can include helper functions for styling (eg, getColor , getSpacing ).

This separation makes it easier to scale and reuse styles.

3. Write Stories with Controls and Args

Storybook's "Args" system lets you dynamically change component props in the UI. Use args and argTypes to make stories interactivity:

 // Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: &#39;Components/Button&#39;,
  component: Button,
  tags: [&#39;autodocs&#39;],
  argTypes: {
    variant: {
      control: &#39;select&#39;,
      options: [&#39;primary&#39;, &#39;secondary&#39;, &#39;outline&#39;],
    },
    size: {
      control: &#39;radio&#39;,
      options: [&#39;sm&#39;, &#39;md&#39;, &#39;lg&#39;],
    },
  },
};

export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    label: &#39;Click me&#39;,
    variant: &#39;primary&#39;,
    size: &#39;md&#39;,
  },
};

Now, in the Storybook UI, you can toggle props using controls—great for QA and design reviews.

4. Document with MDX and Canvas

Enhance documentation using MDX to mix Markdown with JSX. Create Button.stories.mdx :

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

<Meta of={ButtonStories} />

# Button

The Button component is used for actions. Supports multiple variants and sizes.

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

Use the Canvas block to embed interactive stories. This turns Storybook into a living style guide.

5. Enforce Consistency with Addons

Leverage Storybook adds to improve quality:

• Controls : Edit props live.
• Actions : See events fired (eg, onClick ).
• Docs : Auto-generate docs.
• Accessibility : Check A11Y compliance.
• Designs : Embed Figma or Zeplin designs side-by-side.

Install them via main.ts config:

 // .storybook/main.ts
export default {
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    'storybook-addon-designs',
  ],
};

6. Test and Automate

• Write unit tests using Jest or React Testing Library.
• Use Chromatic for visual regression testing—automatically catches unintended UI changes during CI/CD.
• Publish your design system as a package (eg, with npm or a private registry) so other teams can consume it.

Final Thoughts

A React Storybook setup gives you a powerful foundation for a design system. Focus on:

• Component modularity
• Reusable design tokens
• Rich, interactive documentation
• Automated testing and review

With this workflow, your team can build UIs faster, with fewer inconsistencies.

Basically, start small, document thoroughly, and scale intentionally.

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