実践的な活用

主要なアドオン

Storybookの機能はアドオンで拡張できます。@storybook/addon-essentialsには よく使うアドオンがバンドルされていますが、個別に追加できるものも多くあります。

// .storybook/main.ts でアドオンを追加
const config: StorybookConfig = {
  stories: ["../src/**/*.stories.@(ts|tsx)"],
  addons: [
    "@storybook/addon-essentials",  // 基本セット
    "@storybook/addon-a11y",        // アクセシビリティ
  ],
  framework: {
    name: "@storybook/nextjs",
    options: {},
  },
};

// インストール
// npm install -D @storybook/addon-a11y

ビジュアルリグレッションテスト

ビジュアルリグレッションテストは、UIのスクリーンショットを前回と比較して意図しない見た目の変更を検出する手法です。 Storybookとの連携により、各ストーリーを自動でスクリーンショット比較できます。

# Chromaticのセットアップ
npm install -D chromatic

# ビジュアルテストを実行
npx chromatic --project-token=<your-token>

# CI（GitHub Actions）での自動実行例
# .github/workflows/chromatic.yml
name: Chromatic
on: push
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
      - run: npm ci
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

PRごとにビジュアル差分が自動検出されるため、CSSの変更やコンポーネントの修正が 他のUIに影響していないかを確認できます。

ドキュメント自動生成

Storybookのautodocs機能を使うと、 コンポーネントのprops、ストーリー、ソースコードから自動的にドキュメントページが生成されます。

// metaにtags: ["autodocs"]を追加するだけ
const meta: Meta<typeof Button> = {
  title: "Components/Button",
  component: Button,
  tags: ["autodocs"],   // ← これだけでDocsページが生成される
  argTypes: {
    variant: {
      description: "ボタンのスタイルバリエーション",
      table: {
        defaultValue: { summary: "primary" },
      },
    },
    size: {
      description: "ボタンのサイズ",
      table: {
        defaultValue: { summary: "md" },
      },
    },
  },
};

// 自動生成されるDocsページには以下が含まれる:
// - コンポーネントの説明（JSDocコメントから取得）
// - Propsテーブル（型、デフォルト値、説明）
// - 全ストーリーのプレビュー
// - ソースコードの表示

さらに、MDXファイルを使ってカスタムドキュメントを作成することも可能です。

// src/docs/GettingStarted.mdx
import { Meta, Story, Canvas } from "@storybook/blocks";
import * as ButtonStories from "../components/Button.stories";

<Meta title="Guides/Getting Started" />

# はじめに

このデザインシステムの使い方を説明します。

## Buttonコンポーネント

基本的なボタンコンポーネントです。

<Canvas of={ButtonStories.Primary} />

### バリエーション

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

CI/CDとの連携

Storybookをビルドして静的サイトとしてデプロイすることで、チーム全員がコンポーネントカタログにアクセスできます。 CIパイプラインにインタラクションテストやビジュアルテストを組み込むことも重要です。

# Storybookを静的サイトとしてビルド
npm run build-storybook
# → storybook-static/ ディレクトリに出力

# test-runnerでインタラクションテストをCIで実行
npm install -D @storybook/test-runner
npx test-storybook --url http://localhost:6006

# GitHub Actionsの例
# .github/workflows/storybook.yml
name: Storybook CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci

      # Storybookをバックグラウンドで起動
      - run: npx storybook dev -p 6006 --ci &
      - run: npx wait-on http://localhost:6006

      # インタラクションテスト実行
      - run: npx test-storybook

      # 静的ビルド（デプロイ用）
      - run: npm run build-storybook

      # デプロイ（例: GitHub Pages）
      - uses: actions/upload-pages-artifact@v3
        with:
          path: storybook-static/

デザインシステムワークフロー

Storybookはデザインシステムの構築・運用の中心的なツールです。 デザイナーと開発者の共通言語として機能し、 コンポーネントの一貫性を保ちます。

# デザインシステムの典型的なディレクトリ構造
design-system/
├── .storybook/
│   ├── main.ts
│   └── preview.ts
├── src/
│   ├── tokens/
│   │   ├── colors.ts           # カラートークン
│   │   ├── typography.ts       # タイポグラフィ
│   │   └── spacing.ts          # スペーシング
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.stories.tsx
│   │   │   └── Button.test.tsx
│   │   └── Card/
│   │       ├── Card.tsx
│   │       ├── Card.stories.tsx
│   │       └── Card.test.tsx
│   └── docs/
│       ├── Introduction.mdx     # カスタムドキュメント
│       └── ColorPalette.mdx
└── package.json