Figmaデザインをチーム開発で効率化するための取り組み - Claude Code × Figma MCP × Playwright MCP

はじめに

Figmaのデザインをもとにフロントエンドを実装する際、デザインとコードの間で起きるズレや手戻りに悩まされることは多いと思います。

Claude Code上でFigma MCPプラグインとPlaywright MCPと組み合わせることで 「Figmaデザイン取得 → コード生成 → E2Eテスト」 をCLI上で一気通貫で行う仕組みを導入・運用し始めました。

導入にあたり、自分が実際にコーディングする際の手順や課題感をClaudeと会話・整理しながら構成を考えていきました。

今回はセットアップから実践的なカスタムルール・スキルの作成を簡単に紹介します。

※画像は今流行りのGPT-Image-2で作成

環境

• ClaudeCode
• Figma MCP
• Playwright MCP

Figma MCPの導入

セットアップ

Figma MCPは .mcp.json に手動で記述するのではなく、Claude Codeにビルトインされているプラグインを使うのが推奨されています。

claude plugin install figma@claude-plugins-official

これだけでFigma MCPが有効になり、Claude Code to Figma（コードベースのUIからFigmaファイルを生成する機能）も利用できるようになります。

※ Figmaで開発モードを利用できる状態にしておく必要があります

参考: https://developers.figma.com/docs/figma-mcp-server/

Figma MCPでできること

Figma MCPには大きく3カテゴリのツールがあります。

読み取り系

ツール	説明
get_design_context	デザインのコード・スクリーンショット・コンテキスト情報を取得（メインツール）
get_screenshot	指定ノードのスクリーンショットを取得
get_metadata	ファイルやノードのメタデータを取得
get_figjam	FigJamボードの内容を取得
get_variable_defs	デザイントークン（変数定義）を取得

書き込み・生成系

ツール	説明
generate_figma_design	Figmaにデザインを書き込む
generate_diagram	FigJamにダイアグラムを生成
create_design_system_rules	プロジェクト用のデザインシステムルールを生成

Code Connect（コードとFigmaコンポーネントの紐付け）

ツール	説明
get_code_connect_map	既存のマッピングを取得
get_code_connect_suggestions	マッピングの提案を取得
add_code_connect_map	マッピングを追加
send_code_connect_mappings	マッピングを送信

Figma → Claude Code（デザインからコード生成）

基本的な使い方

FigmaのURLをClaude Codeに渡すだけで、MCPがデザイン情報を取得してコードを生成してくれます。

❯ https://www.figma.com/design/xxxxx/project?node-id=9775-6474 の画面を実装して

内部では以下のような流れで処理されます。

1. URLから fileKey と nodeId を抽出
2. get_design_context でデザインの構造化データを取得
3. get_screenshot でスクリーンショットを取得
4. コードベースのフレームワークやコンポーネントを参照して変換

Claude Code自身がプロジェクトのコードベースを参照するので、共通の変数（SCSS変数など）が利用されプロジェクトに合ったコードが出力されます。

生成されたコードの例

以下は、商品カードコンポーネントが生成された例です。Vue + SCSSで、プロジェクトの既存変数（$primary-900 等）が適切に利用されています。

<template>
  <section class="cards">
    <div class="cards__grid">
      <div v-for="(item, index) in items" :key="index" class="card">
        <div class="card__image-wrapper">
          <img :src="item.image_url" :alt="item.name" />
        </div>
        <div class="card__info">
          <p class="card__name">{{ item.name }}</p>
          <p class="card__name-en">{{ item.name_en }}</p>
        </div>
      </div>
    </div>
  </section>
</template>

@import 'resources/sass/vars';

.cards__grid {
  display: grid;
  grid-template-columns: repeat(2, 1fr);
  gap: 24px 16px;
}

.card__name {
  font-size: 20px;
  color: $primary-900;  // SCSS変数が使われている
}

Claude Code → Figma（コードからデザイン生成）

逆方向の変換も可能です。
generate_figma_design を使うと、Claude Codeからfigmaファイルにデザインを書き込むことができます。

❯ https://www.figma.com/design/xxxxx/project?m=dev このfigmaに、マイページ画面のUIを作成して

小さいコンポーネントであれば95%、大きくても80%ぐらいはフォントや構成が維持されます。
編集ありきで、Figmaでコンポーネントやページのたたき台を素早く作成したい時に便利です！

また、コンポーネントを選択してFigmaに送信することもできるので、コードベースで作った部品をFigma側のデザインシステムに反映する使い方もできそうです。

参考: https://dev.classmethod.jp/articles/Claude-code-to-figma-breakage-test/

デザインシステムルールの整備

課題感

長期間運用されているVue + SCSSのプロジェクトであったため例えば以下のような課題がありました。

1. 使われていない共有コンポーネント
2. margin/paddingの方向が混在
3. フォント指定がmixin / 直接指定 / CSS変数で混在

カスタムルールの作成

これらの課題を解決するため、Claude Codeのカスタムルールを定義します。

.claude/rules/figma-design-system.md として配置し、Figma MCPがコードを生成する際に自動で参照されるようにしました。

デザイントークン対応表

Figmaの出力カラーコードとプロジェクトのSCSS変数のマッピングを定義します。

| Figma出力 | SCSS変数 | 用途 |
|-----------|----------|------|
| `#252525` | `$primary-900` | テキスト |
| `#1f8d61` | `$secondary-500` | ボタン、リンク |
| `#db5331` | `$info-error` | エラー |

フォントのmixin対応表

| Figmaのフォント指定 | mixin | 備考 |
|---|---|---|
| `Hiragino Kaku Gothic Pro W3` | `@include font-ja()` | 日本語テキスト（通常） |
| `Riviera Nights` | `@include font-en()` | 英字・数字 |

レスポンシブ・余白のルール

## レスポンシブ実装
- 新規実装は**モバイルファースト**（`min-width` メディアクエリ）で書く
- FigmaにSP/PC両方のフレームがある場合は、SP版を先に実装する

## 余白（margin / padding）
| 場面 | 指定方法 |
|---|---|
| flex / gridの子要素間 | 親に `gap` を指定 |
| それ以外の要素間の縦余白 | 下の要素に `margin-top` を付ける |
| コンテナの内側余白 | 親に `padding` を指定 |

既存コンポーネントの再利用

## 既存コンポーネントの再利用
新しいスタイルを書く前に、既存の共有コンポーネントを確認すること。

- **ボタン**: `resources/sass/components/button.scss`
- **入力フィールド**: `resources/sass/components/input.scss`

カスタムルールとSkillsの関係

ここが重要なポイントです。

• カスタムルールは「何に変換するか」の知識（レシピの材料表）
• Skillsは「どの順番で作るか」の手順（レシピの調理手順）

カスタムルールだけでも変換精度は上がりますが、手順の抜け漏れ（スクリーンショット確認忘れ、アセット取得忘れなど）は防げません。
チームで共有するなら、両方セットで定義しておくと誰がやっても同じ手順・同じ品質になります。

Skillsの作成

デザインシステムルールを運用するために、3つのSkillsを作成しました。

1. /figma-implement — Figma URLからの実装Skill

.claude/skills/figma-implement/SKILL.md として配置します。

---
name: figma-implement
description: FigmaのURLからデザインを取得し、Vue + SCSSで実装する
user-invokable: true
argument-hint: <Figma URL>
---

# Figmaデザイン実装
$ARGUMENTS のFigma URLからデザインを取得し、`.claude/rules/figma-design-system.md` のルールに従ってVue 3 + SCSSで実装する。

## Figma MCP統合ルール
Figma入力をコードに変換する際のルール。Figma起点の変更すべてに適用する。

### 必須フロー（スキップ不可）
1. `get_design_context` を最初に実行 — 対象ノードの構造化データを取得
2. レスポンスが大きすぎる場合 — `get_metadata` でノードマップを取得し必要部分だけ再取得
3. `get_screenshot` で視覚リファレンスを取得
4. 両方取得してからアセットのダウンロード・実装を開始
5. デザインシステムルールに従ってコード変換
6. Playwright MCPでスクリーンショットを取得し、Figmaと比較

### 実装ルール
- Figma MCPの出力（React + Tailwind）は **デザインと振る舞いの表現** として扱い、最終コードスタイルではない
- Tailwindユーティリティクラスは、プロジェクトのSCSS変数・デザインシステムトークンに置き換える

などなど・・・

特に効いたポイントとしては、MCPのベストプラクティス（https://github.com/figma/mcp-server-guide?tab=readme-ov-file#mcp-best-practices ）に沿って手順を固定化することで、実装品質のばらつきを抑えられました。

2. /figma-testcase — テストケース生成Skill

---
name: figma-testcase
description: 実装変更に対するテストケースを1行1テスト形式で生成する
user-invokable: true
argument-hint: <対象の説明>
---

# Figma実装のテストケース生成
実装変更に対するテストケースを1行1テスト形式で生成する。

## 手順
### 1. 変更内容の把握
`git diff` と `git status` で今回の変更ファイルを特定し、以下を分類:
- **Vue**: コンポーネントのレンダリング・表示条件
- **SCSS**: レイアウト・スタイル

変更ファイルごとに、以下の観点でテストケースを生成:
**Vue（表示条件）:**
- `v-if` / `v-for` の条件ごとに表示/非表示を確認
- propsのデータ有無による表示分岐

**Vue（コンテンツ）:**
- テキスト（見出し、ラベル、ボタン）が正しく表示されること

などなど・・・

手元の変更ファイルを特定し、テストケースを自動生成するためのSkillです。
以下をClaudeのに指示するだけで動きます。

❯ 現在の実装の変更について、テストケースを作成してください

出力例:

AuthenticationController@login
- [] GET /login が200を返すこと
- [] items がビューに渡されること

ProductCards.vue
- [] itemsに2件渡した場合、商品カードが2件描画されること
- [] 商品カードが2カラムグリッドで並ぶこと（CSSレイアウト）

3. /figma-verify — Playwright MCPでのテスト実行Skill

---
name: figma-verify
description: 実装済みページをPlaywright MCPで検証し、テスト結果を報告する
user-invokable: true
argument-hint: <ローカルURL>
---

# Figma実装の検証
$ARGUMENTS のURLにPlaywright MCPでアクセスし、テスト結果を報告する。
`/figma-testcase` で生成済みのテストケースが会話内にある場合は、そのPlaywright実行可能なテストケースを優先的に検証する。

## 手順
### 1. ページアクセス・スナップショット取得
`browser_navigate` → `browser_snapshot` でアクセシビリティツリーを把握。

### 2. 自動テスト実行
`browser_evaluate` で以下を検証:

- **表示**: 見出し・ボタンラベル・リンクhref
- **画像**: img要素のsrcが有効値、alt属性
- **レイアウト**: grid/flexのカラム数
- **フォーム**: input存在、placeholder、required

・・・などなど

/figma-testcase で生成したテストケースを、Playwright MCPで自動実行します。

❯ 作成したテストケースに対して、Playwright MCPでテストを実行してください

実行結果がずらっと報告されます。

#	テストケース	結果
1	GET /login が200を返すこと	PASS
2	items がビューに渡されること	PASS
15	itemsに2件渡した場合、カードが2件描画されること	PASS
29	商品カードが2カラムグリッドで並ぶこと	PASS

Playwright MCPについて

Figma MCPと合わせて導入しておくと便利なのがPlaywright MCPです。
以下のようなことができます。

• ブラウザ操作: ページ遷移、クリック、フォーム入力
• スクリーンショット取得: ページの表示確認
• E2Eテスト的な操作: ローカル環境の動作確認

Skillsの /figma-verify と組み合わせることで、実装後の視覚確認を自動化できます。

運用フロー

最終的に、以下のフローでデザインから実装・検証までを行っています。

1. FigmaのURLをClaude Codeに渡してコード雛形を自動生成
2. 生成されたコードをベースに調整
3. テストケースを自動生成
4. Playwright MCPでE2Eテストを実施

デザインシステムルールとSkillsをセットで定義しておくことで、チームメンバーの誰が実装しても同じ手順・同じ品質になるのが大きなメリットです。
また、それそれを独立したSkillsにすることで必要な時に必要なものだけ呼び出すこともできます。

おわりに

Figma MCP × Claude Code × Playwright MCPの組み合わせにより、デザインから実装・検証までのフローを効率化できました。

実際、たたき台としてのコード生成とテスト自動化だけでも十分に開発効率が上がったと感じています。

今も運用しながら随時改善しより良い形を模索しています。

参考

• https://developers.figma.com/docs/figma-mcp-server/
• https://github.com/figma/mcp-server-guide
• https://github.com/microsoft/playwright-mcp
• https://dev.classmethod.jp/articles/Claude-code-to-figma-breakage-test/
• https://zenn.dev/canly/articles/78dcc98c3dfb46