Storybook — DS showcase and sandbox

Design system documentation lives next to the code. Storybook gives isolated component rendering, a matrix of variants, prop controls, and a statically built site for the team.

Why Storybook in a DS

A catalog of every state without hunting through the product.
A shared language for designers, developers, and QA.
A base for visual regression (Chromatic and similar) and the a11y addon.
Onboarding: a new engineer sees the API through examples.

Installation (Storybook 8+ orientation)

In the root of the component library:

npx storybook@latest init

The initializer will pick up React/Vite/Webpack. Confirm the scripts appeared:

{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  }
}

Core concepts

Concept	Meaning
Story	One example of a component in a specific state
CSF	Component Story Format — stories as ES modules
Args	Story props wired to Controls
Addon	Extension (a11y, links, viewport, docs)
Autodocs	Auto-generated docs page from meta/stories

Config

.storybook/main.js (simplified):

const config = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-themes',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  docs: {
    autodocs: 'tag',
  },
};
export default config;

.storybook/preview.js — global decorators, CSS tokens, theme:

import '../src/styles/tokens.css';

const preview = {
  parameters: {
    controls: { matchers: { color: /(background|color)$/i } },
    layout: 'centered',
  },
};
export default preview;

Wire in the same fonts and CSS variables as the product — otherwise stories lie.

Useful addons for a DS

Essentials — controls, actions, viewport, backgrounds, docs.
A11y — highlights axe violations directly in the UI.
Themes — switch light/dark or brand themes.
Links — navigate between related components.

File structure

Keep stories next to the component:

src/components/ui/button/
  Button.jsx
  Button.stories.jsx
  Button.test.jsx

That way documentation does not lag behind folder refactors.

Practice

Initialize Storybook in the UI package.
Import tokens.css in preview.
Enable addon-a11y.
Run npm run storybook and open an empty Button story as a smoke test.