Storybook 完全入門｜コンポーネントカタログの作り方【2026年版】

Storybook は、UIコンポーネントを独立して開発・テスト・ドキュメント化できるツールです。React、Vue、Svelte、Angular などあらゆるフレームワークに対応し、デザインシステムの構築には欠かせない存在となっています。2026年現在、世界中で 100万以上のプロジェクトで採用されています。

Storybook とは何か

Storybook は、コンポーネントをアプリケーションから切り離して表示・操作できる開発環境です。

主な用途:

• コンポーネントカタログ: チームで共有できる UI ライブラリ
• 独立した開発: ページの完成を待たずにコンポーネントを開発
• ビジュアルテスト: 見た目のリグレッションを検出
• ドキュメント: コンポーネントの使い方を自動生成
• デザイナーとの協業: 動作するコンポーネントをデザイナーに見せる

インストール

# 既存プロジェクトに追加
npx storybook@latest init

# 新規プロジェクト
npx storybook@latest init --type react

対応フレームワークを自動検出し、必要な設定を生成してくれます。

ディレクトリ構造

.storybook/
  ├── main.ts          # 設定ファイル
  ├── preview.ts       # グローバル設定
  └── manager.ts       # UI カスタマイズ

src/
  └── components/
      ├── Button.tsx
      └── Button.stories.tsx  # ストーリー

基本的なストーリーの書き方

React の例

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

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

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

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Primary Button',
  },
};

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

export const Large: Story = {
  args: {
    variant: 'primary',
    size: 'lg',
    children: 'Large Button',
  },
};

コンポーネントの起動

npm run storybook

http://localhost:6006 で Storybook が開き、左サイドバーに定義したストーリーが表示されます。

アドオン（Addons）

Storybook の強力さは、豊富なアドオンエコシステムにあります。

必須アドオン

// .storybook/main.ts
export default {
  addons: [
    '@storybook/addon-essentials',  // 基本機能
    '@storybook/addon-links',       // ストーリー間リンク
    '@storybook/addon-a11y',        // アクセシビリティチェック
    '@storybook/addon-interactions', // ユーザー操作シミュレーション
  ],
};

addon-essentials に含まれる機能

• Actions: イベント発火の確認
• Controls: プロップスを動的に変更
• Viewport: レスポンシブ確認
• Backgrounds: 背景色の切替
• Measure: 要素のサイズ計測
• Outline: 要素の境界表示
• Docs: 自動ドキュメント生成

インタラクションテスト

Storybook 7 以降、コンポーネントのインタラクションテストが可能になりました。

import { expect, within, userEvent } from '@storybook/test';

export const LoginForm: Story = {
  args: {},
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    // 入力
    await userEvent.type(canvas.getByLabelText('Email'), 'test@example.com');
    await userEvent.type(canvas.getByLabelText('Password'), 'password');

    // クリック
    await userEvent.click(canvas.getByRole('button', { name: 'Login' }));

    // アサーション
    await expect(canvas.getByText('Welcome')).toBeInTheDocument();
  },
};

アクセシビリティのチェック

@storybook/addon-a11y をインストールすると、各ストーリーのアクセシビリティ問題を自動検出します。

Storybook UI に「Accessibility」タブが追加される
  ↓
violations（違反）、passes（合格）、incomplete（不完全）が表示
  ↓
具体的な修正方法を提示

Webアクセシビリティ WCAG 2.2 完全対応ガイド と併せて活用すると効果的です。

デザイントークンの統合

CSS 変数やカラーパレットを Storybook に統合できます。

// .storybook/preview.ts
import '@/styles/tokens.css';
import '@/styles/global.css';

export default {
  parameters: {
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'dark', value: '#0f172a' },
      ],
    },
    viewport: {
      viewports: {
        mobile: { name: 'Mobile', styles: { width: '375px', height: '667px' } },
        tablet: { name: 'Tablet', styles: { width: '768px', height: '1024px' } },
        desktop: { name: 'Desktop', styles: { width: '1440px', height: '900px' } },
      },
    },
  },
};

MDX での詳細ドキュメント

より詳細なドキュメントは MDX で記述できます。

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

<Meta of={ButtonStories} />

# Button Component

汎用的なボタンコンポーネントです。プライマリアクションに使います。

## 使い方

```tsx
<Button variant="primary" onClick={handleClick}>
  クリック
</Button>

バリエーション

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

npm run build-storybook

# dist/ を GitHub Pages にデプロイ

# package.json
"scripts": {
  "build-storybook": "storybook build"
}

npm install --save-dev @storybook/test-runner

# テスト実行
npm run test-storybook

export const Primary: Story = {
  args: { /* ... */ },
  parameters: {
    design: {
      type: 'figma',
      url: 'https://www.figma.com/file/...',
    },
  },
};

// .storybook/main.ts
export default {
  features: {
    storyStoreV7: true,  // 高速化
  },
};

packages/
  ├── ui/
  │   ├── src/
  │   │   ├── Button/
  │   │   │   ├── Button.tsx
  │   │   │   └── Button.stories.tsx
  │   │   └── Input/
  │   └── package.json
  └── app/
      └── package.json

// .storybook/main.ts
export default {
  stories: [
    '../packages/ui/src/**/*.stories.@(js|jsx|ts|tsx)',
  ],
};

Components/Atoms/Button
Components/Molecules/SearchBar
Components/Organisms/Header
Pages/Home