Antigravity × Storybook でコンポーネント駆動開発を加速する — AIが支援するUI設計・テスト・ドキュメント自動化

取り組みの背景 — なぜ今、コンポーネント駆動開発なのか

フロントエンド開発の規模が大きくなるほど、UIの一貫性を保つことが難しくなります。ボタン1つとっても、ページごとに微妙にスタイルが異なっていたり、状態管理が統一されていなかったりすることは珍しくありません。

コンポーネント駆動開発（Component-Driven Development / CDD） は、UIを独立した小さなコンポーネント単位で設計・開発・テストするアプローチです。そして、そのCDDを実現する最も強力なツールが Storybook です。

Antigravity IDEのAIエージェント機能とStorybookを組み合わせることで、Storyファイルの自動生成、ビジュアルリグレッションテスト、ドキュメント自動化といった作業を大幅に効率化できます。その具体的な手順とベストプラクティスを順を追って整理していきます。

Storybook とは — 基本概念の整理

Storybookは、UIコンポーネントをアプリケーションから切り離して個別に開発・テスト・ドキュメント化できるツールです。React、Vue、Angular、Svelteなど主要なフレームワークに対応しています。

Storybookの主な利点は以下の通りです。コンポーネントをブラウザ上で単体表示し、さまざまなpropsや状態を即座に確認できること。チーム内でUIカタログとして共有できること。そしてビジュアルテストやアクセシビリティテストを自動化できることです。

Antigravity で Storybook 環境をセットアップする

Antigravityのターミナルまたはエージェントに、以下のコマンドでStorybookを導入できます。

# Storybook を既存の React/Next.js プロジェクトに追加
npx storybook@latest init
 
# Storybook を起動して動作確認
npm run storybook
# → http://localhost:6006 でUIカタログが開く

Antigravityのエージェントに「このプロジェクトにStorybookをセットアップして」と指示するだけで、フレームワークの検出からインストール、設定ファイルの生成まで自動で行ってくれます。

AIエージェントによる Story ファイルの自動生成

Storybook導入後の最初のハードルは、既存コンポーネントのStoryファイルを書く作業です。手動で一つずつ作成するのは非常に時間がかかりますが、Antigravityのエージェントを使えばこのプロセスを自動化できます。

既存コンポーネントから Story を一括生成する

Antigravityのチャットパネルで以下のように指示します。

src/components/ 配下の全コンポーネントに対して
Storybook の Story ファイルを生成してください。
各コンポーネントの props を分析して、
代表的なバリエーション（default, disabled, loading 等）を
含めてください。

エージェントはコンポーネントのTypeScript型定義を解析し、適切なStoryを生成します。以下は生成されるStoryファイルの例です。

// src/components/Button/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 Default: Story = {
  args: {
    children: 'Click me',
    variant: 'primary',
    size: 'md',
  },
};
 
// 無効化状態
export const Disabled: Story = {
  args: {
    ...Default.args,
    disabled: true,
  },
};
 
// ローディング状態
export const Loading: Story = {
  args: {
    ...Default.args,
    isLoading: true,
  },
};

生成されたStoryファイルは、npm run storybook でブラウザ上にUIカタログとして確認できます。

インタラクションテストの自動追加

Storybookの play 関数を使えば、ユーザー操作のシミュレーションも記述できます。Antigravityのエージェントに「各Storyにインタラクションテストも追加して」と追加指示するだけで対応可能です。

// インタラクションテスト付きのStory
import { within, userEvent, expect } from '@storybook/test';
 
export const ClickTest: Story = {
  args: { ...Default.args },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');
 
    // ボタンをクリック
    await userEvent.click(button);
 
    // クリック後の状態を検証
    await expect(button).toHaveAttribute('aria-pressed', 'true');
  },
};

デザインシステムとの連携 — Figma → Storybook → コード

Antigravityは Figma MCPサーバー との連携が可能です。この機能とStorybookを組み合わせることで、デザインとコードの一貫性を保つワークフローを構築できます。

ワークフローの全体像

デザイナーがFigmaでコンポーネントを更新すると、Antigravityのエージェントが変更を検知し、対応するReactコンポーネントとStoryファイルの両方を更新提案します。開発者はStorybook上で変更を確認し、問題なければマージするという流れです。

# Figma の変更を検知して Storybook に反映するスクリプト例
antigravity agent run --prompt "
  Figma ファイル ${FIGMA_FILE_ID} の最新デザイントークンを取得し、
  src/components/ のコンポーネントと対応する .stories.tsx を
  更新してください。変更がある場合は diff を表示してください。
"

この統合により、デザインの変更がコードに反映されるまでのリードタイムを大幅に短縮できます。

ビジュアルリグレッションテストの自動化

コンポーネントの見た目が意図せず変わってしまう「ビジュアルリグレッション」は、フロントエンド開発でよく起きる問題です。Storybookと Chromatic（または Percy）を組み合わせることで、この問題を自動検出できます。

Chromatic によるビジュアルテストの設定

# Chromatic のインストールと初期設定
npm install --save-dev chromatic
 
# ビジュアルテストの実行
npx chromatic --project-token=<your-token>

Antigravityのエージェントを使えば、GitHub Actionsとの連携も自動で設定できます。

# .github/workflows/visual-test.yml
name: Visual Regression Test
on: [push, pull_request]
 
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Run Chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

PRを作成するたびにビジュアルテストが自動実行され、UIの変更をスクリーンショットで比較確認できるようになります。

ドキュメント自動生成 — autodocs の活用

Storybook 7以降では、autodocs 機能により、コンポーネントのpropsテーブルや使用例を含むドキュメントページが自動生成されます。Antigravityのエージェントと組み合わせることで、JSDocコメントの追加も自動化し、ドキュメントの質をさらに高められます。

// Antigravity エージェントが追加する JSDoc コメント例
/**
 * プライマリUIボタン。フォーム送信やアクション実行に使用します。
 *
 * @example
 * <Button variant="primary" size="md">送信</Button>
 */
export interface ButtonProps {
  /** ボタンの見た目を制御するバリアント */
  variant: 'primary' | 'secondary' | 'danger';
  /** ボタンのサイズ */
  size: 'sm' | 'md' | 'lg';
  /** 無効化状態 */
  disabled?: boolean;
  /** ローディング中かどうか */
  isLoading?: boolean;
  /** ボタン内のコンテンツ */
  children: React.ReactNode;
}

エージェントに「全コンポーネントのpropsにJSDocを追加して」と指示すれば、型定義を解析して適切なコメントを一括生成してくれます。Storybook上では、これらのコメントがそのままドキュメントとして表示されます。

実践的なプロジェクト構成

Storybookを導入したプロジェクトの推奨ディレクトリ構成を紹介します。各コンポーネントのStoryファイルは、コンポーネントと同じディレクトリに配置するコロケーションパターンが管理しやすくおすすめです。

src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx           # コンポーネント本体
│   │   ├── Button.stories.tsx   # Storyファイル
│   │   ├── Button.test.tsx      # ユニットテスト
│   │   └── index.ts             # エクスポート
│   ├── Card/
│   │   ├── Card.tsx
│   │   ├── Card.stories.tsx
│   │   └── index.ts
│   └── ...
├── .storybook/
│   ├── main.ts                  # Storybook設定
│   └── preview.ts               # グローバルデコレータ
└── ...

Antigravityのエージェントに新しいコンポーネントの作成を依頼する際、「Storyファイルも一緒に作成して」と付け加えるだけで、この構成に従ったファイルが自動生成されます。

まとめ — AIとStorybookで開発ワークフローを次のレベルへ

Antigravity × Storybookの組み合わせにより、以下のことが実現できます。AIエージェントによるStoryファイルの自動生成でセットアップ時間を削減できること。ビジュアルリグレッションテストの自動化でUIの品質を維持できること。autodocsとJSDoc自動追加でドキュメントの鮮度を保てること。そしてFigma連携でデザインとコードの乖離を防げることです。

コンポーネント駆動開発は、プロジェクトの規模が大きくなるほど効果を発揮します。まずは主要なUIコンポーネント10個程度からStorybookを導入し、AIの支援を受けながら段階的にカバレッジを広げていくことをおすすめします。

UIの設計から実装、テストまでを効率化したい方は、Tailwind CSS v4 による UI 開発ガイドも併せてご覧ください。