Claude Code × Storybook で築く本番グレードのコンポーネント駆動開発 — Visual Regression とデザインシステム運用の実装パターン

claude "src/components/ 以下のすべてのコンポーネントについて、次の情報を JSON で出力してください:
- name: コンポーネント名
- path: ファイルパス
- props: Props の型定義から抽出した必須/任意/型情報
- variants_estimated: Props の組み合わせから推定されるバリアント数
- complexity: 'low' | 'medium' | 'high'（依存コンポーネント数や状態管理の有無で判断）
- has_story: すでに .stories.tsx が存在するか
 
出力先: tmp/components-catalog.json"

# Story 生成テンプレート
 
引数で渡されたコンポーネントについて、CLAUDE.md の Storybook ルールに従って .stories.tsx を生成してください。
 
## 必須要件
1. CSF 3.0 形式
2. Default Story を含む
3. Props の型から argTypes を自動生成
4. 状態を持つコンポーネントの場合は Loading / Error / Empty Story を追加
5. 子要素を取るコンポーネントは Slots Story を追加（Story 内でモック子要素を配置）
6. アクセシビリティに配慮し、aria-label を持つ要素は a11y addon が認識できる形にする
7. Tailwind カスタムクラスを使う場合は preview.tsx に import 済みであることを前提とする
 
## 出力
- ファイルパス: コンポーネントと同じディレクトリ
- 実行後、生成した Story 名のリストを箇条書きで報告

// scripts/validate-stories.ts
import { glob } from 'glob';
import { readFile } from 'fs/promises';
 
interface ValidationError {
  file: string;
  rule: string;
  message: string;
}
 
async function validateStories(): Promise<ValidationError[]> {
  const errors: ValidationError[] = [];
  const files = await glob('src/components/**/*.stories.tsx');
 
  for (const file of files) {
    const content = await readFile(file, 'utf-8');
 
    // CSF 3.0 形式チェック
    if (!content.includes('export default')) {
      errors.push({ file, rule: 'csf-meta', message: 'meta オブジェクトの default export がありません' });
    }
 
    // Default Story の存在チェック
    if (!/export const Default/.test(content)) {
      errors.push({ file, rule: 'default-story', message: 'Default Story が定義されていません' });
    }
 
    // argTypes の存在チェック（Props を持つコンポーネントの場合）
    if (content.includes('args:') && !content.includes('argTypes:')) {
      errors.push({ file, rule: 'arg-types', message: 'args を使用していますが argTypes が定義されていません' });
    }
 
    // 禁止パターンチェック
    if (/style=\{\{.*background/.test(content)) {
      errors.push({ file, rule: 'no-inline-color', message: 'インラインで background を指定しています。Tailwind トークンを使用してください' });
    }
  }
 
  return errors;
}
 
validateStories().then((errors) => {
  if (errors.length > 0) {
    console.error('Story 検証エラー:');
    errors.forEach((e) => console.error(`  ${e.file} [${e.rule}]: ${e.message}`));
    process.exit(1);
  }
  console.log('✅ すべての Story が規約に準拠しています');
});

# .github/workflows/chromatic.yml
name: Chromatic
on:
  push:
    branches: [main]
  pull_request:
 
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Chromatic は履歴が必要
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build-storybook
      - uses: chromaui/action@v11
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          onlyChanged: true  # 変更があった Story のみテスト
          exitZeroOnChanges: true  # 差分があってもジョブは成功扱い
          autoAcceptChanges: main  # main への push は自動承認
        env:
          CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

// .storybook/test-runner.ts
import type { TestRunnerConfig } from '@storybook/test-runner';
import { toMatchImageSnapshot } from 'jest-image-snapshot';
 
const config: TestRunnerConfig = {
  setup() {
    expect.extend({ toMatchImageSnapshot });
  },
  async postVisit(page, context) {
    // インタラクション後のスクリーンショットを比較
    if (context.tags?.includes('visual')) {
      const image = await page.screenshot({ fullPage: true });
      // @ts-expect-error jest-image-snapshot は型定義が拡張される
      expect(image).toMatchImageSnapshot({
        customSnapshotIdentifier: context.id,
        failureThreshold: 0.02,
        failureThresholdType: 'percent',
      });
    }
  },
};
 
export default config;

claude "src/components/Form/LoginForm/LoginForm.stories.tsx に Interaction Story を追加してください。
 
要件:
1. play 関数で次のシナリオを実装:
   - メールアドレス未入力で送信 → エラーメッセージ表示確認
   - 不正なメール形式で送信 → エラーメッセージ表示確認
   - 正しい入力で送信 → onSubmit が呼ばれることを確認
2. @storybook/test の userEvent と expect を使用
3. 各シナリオは別 Story として独立させる
4. await step() でシナリオを段階的に記述
 
参考: 既存の SignupForm.stories.tsx と同じスタイルで書いてください。"

// src/components/Form/LoginForm/LoginForm.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { expect, userEvent, within } from '@storybook/test';
import { LoginForm } from './LoginForm';
 
const meta: Meta<typeof LoginForm> = {
  title: 'Form/LoginForm',
  component: LoginForm,
  parameters: { layout: 'centered' },
  tags: ['autodocs'],
};
export default meta;
 
type Story = StoryObj<typeof LoginForm>;
 
export const Default: Story = {
  args: { onSubmit: () => {} },
};
 
export const ValidationEmpty: Story = {
  args: { onSubmit: () => {} },
  play: async ({ canvasElement, step }) => {
    const canvas = within(canvasElement);
    await step('空のまま送信', async () => {
      await userEvent.click(canvas.getByRole('button', { name: 'Sign in' }));
      await expect(canvas.getByText('メールアドレスを入力してください')).toBeInTheDocument();
    });
  },
};
 
export const ValidationInvalidEmail: Story = {
  args: { onSubmit: () => {} },
  play: async ({ canvasElement, step }) => {
    const canvas = within(canvasElement);
    await step('不正なメール形式で送信', async () => {
      await userEvent.type(canvas.getByLabelText('Email'), 'not-an-email');
      await userEvent.click(canvas.getByRole('button', { name: 'Sign in' }));
      await expect(canvas.getByText('正しい形式のメールアドレスを入力してください')).toBeInTheDocument();
    });
  },
};

// .storybook/test-runner.ts に追記
import { getStoryContext } from '@storybook/test-runner';
import { injectAxe, checkA11y } from 'axe-playwright';
 
const config: TestRunnerConfig = {
  // 既存の設定に追加
  async preVisit(page) {
    await injectAxe(page);
  },
  async postVisit(page, context) {
    const storyContext = await getStoryContext(page, context);
    if (storyContext.parameters?.a11y?.disable) return;
 
    await checkA11y(page, '#storybook-root', {
      detailedReport: true,
      detailedReportOptions: { html: true },
      axeOptions: { runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] } },
    });
  },
};

# .github/workflows/component-review.yml
name: Component Review
on:
  pull_request:
    paths:
      - 'src/components/**'
 
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Get changed files
        id: changes
        run: |
          CHANGED=$(git diff --name-only origin/main...HEAD -- 'src/components/**/*.tsx' | tr '\n' ' ')
          echo "files=$CHANGED" >> $GITHUB_OUTPUT
      - name: Run Claude Code review
        if: steps.changes.outputs.files != ''
        run: |
          npx @anthropic-ai/claude-code review \
            --files "${{ steps.changes.outputs.files }}" \
            --prompt-file .github/prompts/component-review.md \
            --output review.md
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - name: Post review comment
        if: steps.changes.outputs.files != ''
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          path: review.md

# コンポーネント変更レビュー
 
以下のコンポーネントが変更されました。CLAUDE.md の規約と照らし合わせて、次の観点でレビューしてください。
 
1. **Story の追従**: 変更された Props や状態に対応する Story が更新されているか
2. **アクセシビリティ**: 新たに追加された UI 要素に role / aria-label が適切に設定されているか
3. **デザイントークン**: 直書きの色・スペーシングが含まれていないか
4. **Breaking Change**: 既存の Props 削除や型変更がないか。あれば移行ガイドの提案
5. **パフォーマンス**: 不必要な再レンダリングを誘発する変更がないか
 
各項目について、問題があれば該当行を引用しコメント。問題なければ `✅` のみ。
出力フォーマット: Markdown チェックリスト形式。

// .claude/mcp-servers/storybook.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { glob } from 'glob';
import { readFile } from 'fs/promises';
 
const server = new McpServer({ name: 'storybook-catalog', version: '1.0.0' });
 
server.tool(
  'list_components',
  'プロジェクトの全コンポーネントとその Story 一覧を返す',
  async () => {
    const files = await glob('src/components/**/*.stories.tsx');
    const components = await Promise.all(
      files.map(async (file) => {
        const content = await readFile(file, 'utf-8');
        const titleMatch = content.match(/title:\s*['"]([^'"]+)['"]/);
        const stories = [...content.matchAll(/export const (\w+):/g)].map((m) => m[1]);
        return {
          file,
          title: titleMatch?.[1] ?? 'Unknown',
          stories: stories.filter((s) => s !== 'default'),
        };
      })
    );
    return { content: [{ type: 'text', text: JSON.stringify(components, null, 2) }] };
  }
);
 
server.tool(
  'get_component_props',
  '指定したコンポーネントの Props 型定義を返す',
  { component: { type: 'string' } },
  async ({ component }) => {
    const file = `src/components/${component}/${component}.tsx`;
    const content = await readFile(file, 'utf-8');
    const propsMatch = content.match(/(?:type|interface)\s+\w*Props\s*=?\s*\{([^}]+)\}/s);
    return {
      content: [{ type: 'text', text: propsMatch?.[1].trim() ?? 'Props 型が見つかりません' }],
    };
  }
);
 
const transport = new StdioServerTransport();
await server.connect(transport);