Claude Code × Storybook UIカタログ駆動開発ガイド｜MCP連携・Story自動生成・Play Function・Chromatic VRT

# 公式アドオンをインストール
npx storybook add @storybook/addon-mcp

# Claude CodeにMCPサーバーを登録
claude mcp add storybook-mcp --transport http http://localhost:6006/mcp --scope project

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

const config: StorybookConfig = {
  stories: ["../src/**/*.stories.@(ts|tsx)"],
  addons: [
    "@storybook/addon-essentials",
    "@storybook/addon-mcp",
  ],
  features: {
    // Storybook 9ではデフォルトtrue。Storybook 8.xでは明示的に有効化が必要
    componentsManifest: true,
  },
  framework: {
    name: "@storybook/react-vite",
    options: {},
  },
};

export default config;

{
  "mcpServers": {
    "storybook": {
      "type": "http",
      "url": "http://localhost:6006/mcp"
    }
  }
}

src/components/Button.tsx のStorybookストーリーを作成してください。

手順:
1. get-storybook-story-instructions でこのプロジェクトのStory作成ルールを確認
2. list-all-documentation で既存コンポーネント一覧を確認（重複防止）
3. get-documentation で Button のProps情報を取得
4. CSF3形式でストーリーを生成（autodocs、全バリアント、play関数付き）
5. preview-stories でプレビュー確認
6. run-story-tests でテスト実行・検証

import type { Meta, StoryObj } from "@storybook/react";
import { expect, fn } from "storybook/test";
import { Button } from "./Button";

const meta = {
  component: Button,
  tags: ["autodocs"],
  args: {
    onClick: fn(),
  },
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "danger"],
    },
    size: {
      control: "select",
      options: ["sm", "md", "lg"],
    },
    disabled: { control: "boolean" },
    loading: { control: "boolean" },
  },
} satisfies Meta<typeof Button>;

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

// 各バリアント
export const Primary: Story = {
  args: { variant: "primary", children: "送信" },
};

export const Secondary: Story = {
  args: { variant: "secondary", children: "キャンセル" },
};

export const Danger: Story = {
  args: { variant: "danger", children: "削除" },
};

// 状態別
export const Disabled: Story = {
  args: { variant: "primary", children: "送信", disabled: true },
};

export const Loading: Story = {
  args: { variant: "primary", children: "送信", loading: true },
};

// インタラクションテスト
export const ClickTest: Story = {
  args: { variant: "primary", children: "クリック" },
  play: async ({ args, canvas, step, userEvent }) => {
    await step("ボタンをクリック", async () => {
      await userEvent.click(
        canvas.getByRole("button", { name: "クリック" })
      );
    });
    await expect(args.onClick).toHaveBeenCalledOnce();
  },
};

src/components/LoginForm.tsx のストーリーを作成してください。
Play Functionで以下のインタラクションテストを含めること:
- メールとパスワードを入力してフォーム送信
- バリデーションエラー（空入力時のエラーメッセージ表示）
- step() でテストを論理的にグループ化

import type { Meta, StoryObj } from "@storybook/react";
import { expect, fn } from "storybook/test";
import { LoginForm } from "./LoginForm";

const meta = {
  component: LoginForm,
  tags: ["autodocs"],
  args: {
    onSubmit: fn(),
  },
} satisfies Meta<typeof LoginForm>;

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

export const SuccessfulLogin: Story = {
  play: async ({ args, canvas, step, userEvent }) => {
    await step("認証情報を入力", async () => {
      await userEvent.type(
        canvas.getByLabelText("メールアドレス"),
        "user@example.com"
      );
      await userEvent.type(
        canvas.getByLabelText("パスワード"),
        "password123"
      );
    });

    await step("フォームを送信", async () => {
      await userEvent.click(
        canvas.getByRole("button", { name: "ログイン" })
      );
    });

    await expect(args.onSubmit).toHaveBeenCalledWith({
      email: "user@example.com",
      password: "password123",
    });
  },
};

export const ValidationError: Story = {
  play: async ({ canvas, step, userEvent }) => {
    await step("空のまま送信", async () => {
      await userEvent.click(
        canvas.getByRole("button", { name: "ログイン" })
      );
    });

    await step("エラーメッセージを確認", async () => {
      await expect(
        canvas.getByText("メールアドレスを入力してください")
      ).toBeInTheDocument();
    });
  },
};

name: Chromatic

on: push

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 全コミット履歴が必要

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci

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

{
  "mcpServers": {
    "storybook": {
      "type": "http",
      "url": "http://localhost:6006/mcp"
    },
    "figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

Figmaの以下のフレームを参照して、
Reactコンポーネント + Storybook Storiesを作成してください。
[Figma URL をペースト]

手順:
1. Figma MCPでデザイントークン・レイアウト情報を取得
2. Storybook MCPの get-storybook-story-instructions でStory作成ルールを確認
3. get-documentation で既存の類似コンポーネントを確認（重複防止）
4. コンポーネント実装（Tailwind CSS v4）
5. CSF3 Stories生成（autodocs + 全バリアント + play関数）
6. run-story-tests で検証

## Storybook開発ルール

### MCPツール利用（必須）
- UI開発前に必ずStorybook MCPツールを呼ぶ
- list-all-documentation → get-documentation の順で既存を確認
- コンポーネントのPropsを推測しない（必ずMCPから取得）
- 作業完了後は run-story-tests で検証

### Story作成規約
- CSF3 + TypeScript（satisfies Meta<typeof Component> 構文）
- tags: ["autodocs"] を必ず付与
- argTypes はProps型から自動マッピング
- fn() でコールバック関数をスパイ化

### 必須バリエーション
1. Default（デフォルト状態）
2. 各variant（Primary, Secondary, Danger等）
3. 各size（sm, md, lg）
4. 状態別（Disabled, Loading, Error, Empty）
5. インタラクション（play関数によるユーザー操作テスト）

### Play Function規約
- step() でテストを論理的にグループ化する
- フォーム送信・クリック・入力の主要操作をカバー
- expect() でアサーション必須
- アクセシビリティ（role, label）でDOM要素を取得する（testIDは最終手段）