Storybook Development for UI Component Documentation

Storybook Development for UI Component Documentation

Storybook is development environment and documentation for UI components in isolation from application. Component opens without router context, store, authentication — only with props it needs. This speeds development, simplifies testing, and creates living documentation always up-to-date.

When Storybook is Needed

Storybook justified if at least one condition met:

• Component library used in multiple projects
• More than 2–3 frontend developers on team
• Designers need to verify implementation
• Components complex (DatePicker, DataTable, RichTextEditor)

For small projects with one team Storybook is overhead. Visual testing in app itself sufficient.

Storybook 8 Setup

Storybook 8 (2024) — current version. Supports React, Vue, Angular, Svelte, Web Components.

Initialization in existing project:

npx storybook@latest init

Auto-detects framework, adds .storybook/main.ts and .storybook/preview.ts, creates example stories.

Configuration .storybook/main.ts for React + Vite:

import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@chromatic-com/storybook',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
};
export default config;

Writing Stories: CSF3 Format

Component Story Format 3 (CSF3) — current standard. Each story is named object with args:

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

const meta: Meta<typeof Button> = {
  component: Button,
  tags: ['autodocs'],           // auto-generate docs page
  args: {
    children: 'Click',
    variant: 'primary',
    size: 'md',
  },
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost', 'danger'],
    },
  },
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {};

export const Secondary: Story = {
  args: { variant: 'secondary' },
};

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

export const Loading: Story = {
  args: { isLoading: true },
};

Key CSF3 features:

• args — component props, controlled via Controls panel in real-time
• argTypes — control configuration: select, text, boolean, color, number
• tags: ['autodocs'] — Storybook auto-generates documentation page with prop table and all stories

Autodocs: Automatic Documentation

With autodocs tag Storybook generates page for each component:

• All stories with previews
• Props table with types (from TypeScript) and descriptions (from JSDoc/TSDoc)
• Interactive Canvas with Controls

For JSDoc prop descriptions:

type ButtonProps = {
  /** Visual button variant */
  variant?: 'primary' | 'secondary' | 'ghost';
  /** Button size */
  size?: 'sm' | 'md' | 'lg';
  /** Shows spinner instead of content */
  isLoading?: boolean;
};

These descriptions automatically appear in props table in Autodocs.

Addon A11y: Accessibility Check

@storybook/addon-a11y adds Accessibility tab to each story. Runs axe-core on component render and shows violations right in Storybook:

npm install -D @storybook/addon-a11y

Add to addons: ['@storybook/addon-a11y'] in main.ts. After that each story checked automatically: violations, incomplete, passes visible.

Theming and Global Decorators

If app supports dark mode — set up theme toggle in Storybook via global decorators in preview.ts:

// .storybook/preview.ts
import type { Preview } from '@storybook/react';
import '../src/styles/globals.css';

const preview: Preview = {
  globalTypes: {
    theme: {
      name: 'Theme',
      defaultValue: 'light',
      toolbar: {
        icon: 'circlehollow',
        items: ['light', 'dark'],
        showName: true,
      },
    },
  },
  decorators: [
    (Story, context) => {
      const theme = context.globals.theme;
      return (
        <div data-theme={theme} className={theme}>
          <Story />
        </div>
      );
    },
  ],
};

export default preview;

Visual Regression with Chromatic

Chromatic (developed by Storybook team, commercial) — cloud service for visual regression testing:

1. Takes screenshots of all stories on each PR
2. Compares against baseline (approved snapshots)
3. Shows diff in PR review
4. Reviewer approves or rejects changes

GitHub Actions integration:

- name: Publish to Chromatic
  uses: chromaui/action@latest
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

Free tier: 5000 snapshots/month. For 3–5 developer team with 30–50 component library — sufficient.

Deploy Storybook

Storybook deploys as static site:

npm run build-storybook    # builds to /storybook-static

Hosting: Chromatic (built-in), Vercel, Netlify, GitHub Pages. For CI/CD add step in pipeline, deploy on every main merge.

Timeline

For 20–30 component library: 2–3 weeks for complete Storybook with autodocs, a11y addon and Chromatic. Further maintenance — stories added alongside new component development.