Storybook

UI コンポーネントを独立に開発・表示・テストできるカタログツール。各コンポーネントの使い方を「ストーリー」として記述し、視覚的に確認できる。React・Vue・Angular・Svelte・Web Components など主要フレームワークに対応。

概要

Storybook は アプリ本体から切り離して UI コンポーネント単体を表示・操作するサンドボックス 。各コンポーネントに対して複数の状態（通常 / エラー / ローディング / 空など）を「ストーリー」として書き、ブラウザでカタログ的に閲覧できる。

観点	Storybook の役割
開発	コンポーネント単体を独立に作る・確認する
ドキュメント	使い方を「動く例」として記録
テスト	視覚回帰・インタラクション・アクセシビリティ
デザイナーとの連携	デザインシステムの実装版カタログ

ストーリー（Story）とは

「ストーリー」は コンポーネントの 1 つの使い方を表すコード例 。*.stories.ts ファイルに記述する。

// Button.stories.ts
export default { component: Button }

export const Primary = {
  args: { label: '注文確定', variant: 'primary' }
}

export const Disabled = {
  args: { label: '注文確定', variant: 'primary', disabled: true }
}

export const Loading = {
  args: { label: '送信中...', variant: 'primary', loading: true }
}

ブラウザの Storybook UI で、これらのバリエーションをサイドバーから切り替えて閲覧できる。

主な用途

1. コンポーネント開発のサンドボックス

アプリ全体を起動せず、 対象コンポーネントだけを表示 して開発できる。表示確認のために毎回ログイン・遷移しなくて済む。

2. デザインシステムのカタログ

アトミックデザインと組み合わせて、Atoms / Molecules / Organisms をカテゴリ別に並べる。デザイナーが「実装済みのコンポーネント一覧」を見られる。

3. 視覚回帰テスト

スクリーンショットを自動取得し、変更前後で差分を比較。 意図しない見た目の変化を自動検知 。

ツール	役割
Chromatic	Storybook 製作元が提供する SaaS。差分レビュー UI が強力
Percy	BrowserStack 製。Storybook 連携あり
Playwright + Storybook	自前で組む場合の選択肢

4. インタラクションテスト

play 関数でユーザー操作を記述し、Storybook 内で実行できる。E2E より軽く、単体より実環境に近い。

5. ドキュメント自動生成

MDX で各コンポーネントの説明を書くと、 使い方ドキュメントが Storybook に自動生成 される。

アトミックデザインとの相性

Storybook はアトミックデザインの運用基盤として ほぼ必須 。Atoms / Molecules / Organisms をフォルダ単位で分類し、各コンポーネントに .stories.ts をペアで配置する。

libs/ui/
  ├── atoms/
  │   ├── Button.tsx
  │   └── Button.stories.ts
  ├── molecules/
  │   ├── SearchBox.tsx
  │   └── SearchBox.stories.ts
  └── organisms/
      ├── Header.tsx
      └── Header.stories.ts

ストーリーの整備が進むほど、新規開発者・デザイナー・AI が 「このコンポーネントはどう使うのか」 を学習できる。

AI 駆動開発との関係

Storybook は AI 駆動開発で 3 つの効用を発揮する。

1. AI に「使い方」を学習させる

AI に「PriceDisplay の使い方を教えて」と聞かれたとき、コードではなく *.stories.ts を参照させる方が正確。 ストーリーがコンポーネントの仕様書 として機能する。

2. AI 生成コードの暴走を視覚回帰で検知

AI が UI を勝手に変更しても、 Chromatic / Percy で 見た目の差分を CI で自動検知 できる。意図しない変更が即わかる。

3. AI に新ストーリーを書かせる

AI への指示例:
  atoms/Button に「ghost バリアント」を追加したい。
  button.stories.ts の既存パターンに倣って、
  ghost バリアントのストーリーを追加してください。

既存ストーリーが整っていると、AI が 同じパターンでストーリーを書ける 。1 コンポーネント 1 ストーリーが規約化されているプロジェクトほど、AI に任せやすい。

アンチパターン

失敗	是正
ストーリーを書かないコンポーネントが増える	1 コンポーネント 1 ストーリー以上を規約化
ストーリーが古い	CI でストーリービルドを必須化、壊れたら通さない
Storybook を立てっぱなしにせず存在を忘れる	デザイナー・PdM もブックマーク、定期的に見る
視覚回帰テストを入れない	Chromatic / Percy を早期導入

開発手法ガイド：アトミックデザイン編 — Storybook がカタログ基盤
開発手法ガイド：テスト技法編 — 視覚回帰テストの位置づけ
開発手法ガイド：モノレポ編 — libs/ui/ パッケージとして配置

概要