Figma→コード生成の失敗を防ぐ！Claude Codeが理解しやすいデザインデータ整備のコツ

こんにちは！サービスデザイン部 技術推進チームです。

以前私たちは、さまざまなAI技術やツールを実際に試し、得られた気づきや今後の活用可能性について考察しました。

「AIで変わるデザイン業務」——デザイナーが実際に試したリアルな検証レポート | GMOメディア クリエイターブログ

この取り組みの中で、特に注目したいのが「コード生成とデザイン連携」です。

FigmaのDev Mode MCPサーバー（以下、Figma MCP）を活用し、AIエージェントによるコーディングが可能であることはすでに実証済みです。しかし今回は、より効率的に、かつ既存のサービス開発フローに組み込むための検証を行いました。

その過程で、「Figmaデータの見直し（デザインシステムの再整備）」と「AIエージェントのためのコーディングガイドライン」の整備が特に重要であるという気づきを得ました。

そこで本稿では、Figma MCPとClaude Codeを用いてコードを生成する前に、Figmaデザインで準備しておくべきポイントを、実際の検証結果に基づいてご紹介いたします。

0. はじめに: Figma MCP ServerとClaude Codeの採用理由

Figma MCP Server (Figma Dev Mode MCPサーバー)

📝 Figmaデザインファイルからコードを生成するAIエージェントに、重要なデザイン情報とコンテキストを提供することで、Figmaをワークフローに直接組み込むことができます。

https://help.figma.com/hc/ja/articles/32132100833559-Dev-Mode-MCPサーバー利用ガイド

弊社では複数のサービスやプロダクトを運用しており、それぞれが独自のデザインシステムを持っています。さらに、利用する開発フレームワークも異なるため、開発環境にも差異があり、特定のサービスやプロダクト専用にMCPを自前で用意するのは困難な状況でした。

一方でデザインシステムについては、すべてのサービスやプロダクトにおいて、Figma上に存在しています。そこで、独自のMCPを新たに構築して連携するのではなく、既存のFigmaデザインデータをそのまま活用できるよう、Figma MCPを採用することにしました。

Claude Code

📝 Claude Codeは、Anthropic社が提供するAIコーディングエージェントです。
コードベース全体を理解し、リファクタリングや新規実装を支援できるのが特長です。

https://docs.claude.com/ja/docs/claude-code/overview

「広範囲のファイル分析」や「コードベース全体を踏まえたコーディング」が可能なAIエージェントとして、特に有用だと感じた点は以下の通りです。

• 既存コンポーネントを調査し、コーディング時に参照できる。

• コードのリファクタリング、とりわけレガシーコードが残るサービスでの作業に役立つ。

加えて、「すでに社内エンジニア全員に導入済みである」という環境要因もあったため、必ずしもClaude Codeに限定する必要はないと考えています。

1. 準備①: Claude Codeのガイドラインファイルの作成

なぜガイドラインを作るのか

AIエージェントでコーディングを行う上で重要となるのは、「どのようなルールに基づいてコードを生成するか」を定義する仕組みです。

近年、その仕組みとして注目を集めているのが MCP（Model Context Protocol） です。

📝 MCP（Model Context Protocol）は、AIにルールやコンテキストを渡すための仕組みです。サーバー側で情報を管理し、コード生成などのAI出力に反映させることができます。

Claude CodeのようなAIコーディングエージェントと組み合わせることで、「Figmaデザイン → コード生成」の精度を大幅に高めることが可能です。

特にFigma MCP Serverを活用すれば、「デザイン情報やガイドラインをAIエージェントにコンテキストとして渡す」 ことができ、これによりAIエージェントがデザインシステムを理解しやすくなります。
その結果、ガイドラインに沿った安定的なコード生成が実現できます。

弊社では複数のサービスを運用しており、それぞれに特化したデザインシステムが存在します。ただし、一定のデザインやコーディングルールは全社的に共通しているため、全社共通ガイドライン と サービス特化ガイドライン を切り分けて整備しました。

全社共通ガイドライン

すべてのサービスに共通して適用する基本ルールを記載します。

• HTMLタグ：セマンティックな構造化、SEOと可読性への配慮

• CSS/SCSS：命名規則・書式の統一

• アクセシビリティ：フォーカス表示、ARIA属性、フォーム、レスポンシブ対応などを社内ガイドラインに基づいて基準化

サービス特化ガイドライン

サービスのデザインシステムや開発環境ごとに必要となる独自ルールを記載します。

• プロジェクト構成：テンプレート／SCSSの配置、ビルド環境、Figma命名規約

• SCSS設計：ディレクトリ構造、プレフィックス規則

• デザイントークン：色・タイポ・スペーシング・角丸・シャドウ

• CSS/実装ガイドライン：レスポンシブ方針やレイアウト

• UI仕様：主要コンポーネントの使い方、Figmaとclass命名の対応

• HTMLガイドライン：テンプレート構造、命名規則

• チェックリスト：以上の項目が正しく実装できているか（例：CSSがトークン参照になっているか）

工夫した点

ガイドラインをAIに理解させやすくするため、ファイルを用途ごとに分割しました。

.claude/
├── design_system/
    ├── 01_basic.md      # デザインシステムの概要
    ├── 02_token.md      # デザイントークン
    ├── 03_component.md  # コンポーネント
    ├── 04_common.md     # 全社共通ガイドライン

このように構造化することで、Claude Codeが必要な情報を適切に参照できるようになりました。

2. 準備②: Figmaデータの見直し(デザインシステム再整備)

本稿でいう「デザインシステム」とは

ここでいう「デザインシステム」とは、Figma上に配置されたUIコンポーネントだけを指すものではありません。以下の要素を含めた、より包括的な概念を指します。

• カラーパレット、余白、タイポグラフィなどのデザイン原則

• 主要なUIコンポーネント

• プロダクト開発時に利用する際の制約事項

なぜデータを見直すのか

Figmaのデザインデータは、AIにとって入力（コンテキスト）の基盤となります。

そのため、読み取りやすさやコードとの一貫性を確保する目的で、特に以下の3点を見直しました。

Variables（デザイントークン）の適用

色・タイポグラフィ・シャドウ・余白・サイズなどをVariablesで定義し、コード上のトークン名と統一することで、AIの出力とデザインデータとの齟齬を減らすことができました。

主要コンポーネントの整理とclass命名の一致

検証の結果、コンポーネントのclass名をコードと一致させると出力の安定性が高まることがわかりました。そのため、ボタンなど汎用的なコンポーネントに対象を絞り、コード上のclass名とFigmaのレイヤー名を統一する運用としました。さらに、descriptionに使用用途を記載しておくことで、デザイン意図や使い分けの精度も向上するため、併せて整備するのが望ましいです。

Auto Layoutの活用

レスポンシブ対応や構造を意識して適切に設定することで、CSSの再現度やレスポンシブ実装の精度が向上しました。

やらなくてもよさそうなこと

📝 前提：Figmaのメインコンポーネントが定義されているなど、基本的な整備はすでに実施済みであること。

コード生成の精度向上のために上記の整備を行いましたが、一方でFigmaのコンポーネント設計については、AIエージェントがある程度コンテキストを読み取り補完してくれるため、特別な調整は必ずしも必要ではありませんでした。

• マークアップ構造とFigmaフレームの対応：

  マークアップを意識した構造にしておくことは重要ですが、厳密に対応させなくてもセマンティックな構造をAIが補完してくれました。

• アノテーションでの注釈やデザイントークンの補足：

  MCP経由でアノテーション情報が渡っていることは確認できましたが、補足がなくても十分な精度でコード生成が可能でした。

⚠️ 上記は、あらかじめコンテキストを読み込ませるガイドラインが存在することが前提です。この場合、レイヤー名などは厳密に定義されていなくても問題はありません。

一方で、ガイドラインが存在しない場合には、レイヤー名やレイヤー構造を本番環境（実際に運用しているHTML／CSSの構造）に近づけておくことで、コード生成の精度を高めることができます。

3. 結果: 準備後の生成精度について

今回は、既存ページに新しいコンポーネントを追加した事例をご紹介します。

これまでは出力精度を高めるために、デザイントークンを定義したscssファイルのパスを指定するなど、詳細なプロンプトを記載する必要がありました。または、AIエージェントとの対話を通じて精度を調整していました。

しかし、あらかじめガイドラインを整備し、Figmaデータを適切に準備することで、以下のシンプルなプロンプトだけで高精度なアウトプットを得られるようになりました。

★今回実装したい新規コンポーネント（Figma上のデザイン）

★Claude Codeに送ったプロンプト

https://www.figma.com/design/[フレームのURLをここにいれます]
上記のFigmaコンポーネントを、下記要件に従ってコーディングしてください。

## 対象サービス
- [サービス名をここにいれます]

## 対象デバイス
- [デバイス名をここにいれます]

## HTML（テンプレート）
- [既存のページのファイルpath]に作成

## 注意
- .claude/design_systemに従ってコーディングすること
- 画像は[特定のpathをここにいれます]内のものを使用してください

★生成されたコード

内部で利用しているカスタム関数や変数は、特別に指定しなくても正しく反映されており、class名もコーディングルールに沿って違和感なく定義されていました。さらに、新規のscssファイルも適切な位置に配置されており、手直しを加える必要はありませんでした。

そしてもちろん、Figma上のデザインと同一のものが正しく実装されていました。

4. まとめ: デザインシステム整備のポイント

今回の取り組みを整理すると、以下の通りです。

Figma整備

• FigmaのVariablesで定義したデザイントークンと、CSSなどコード側のデザイントークンを揃え、生成時の齟齬を防ぐ

• 主要コンポーネントを整理し、コンポーネント名とclass名を一致させて出力を安定させる

• Auto Layoutを適切に活用し、レスポンシブ対応の精度を高める

ガイドライン整備

• 全社共通とサービス特化の二層構造で整理し、一貫性と柔軟性を両立する

• クラス設計ルールやアクセシビリティ基準を明示し、品質を担保する

• ディレクトリ構成や命名規則まで具体的に落とし込み、実装の再現性を高める

5. さいごに

今回の検証を通じて改めて実感したのは、AIによるコーディングは「整備されたデザインシステム」を前提として初めて真価を発揮するという点です。Figmaやガイドラインを通じて「どのような前提でコードを書くのか」を明示することで、生成結果は場当たり的なものから一貫性のあるものへと変化しました。

さらに、ガイドラインを用意することで、プロンプティングスキルに個人差があっても期待通りの生成結果を得やすくなり、個人のパフォーマンス向上だけでなくチーム全体の生産性向上にもつながりました。この点で、今回の取り組みは非常に有意義であったと感じています。

しかしながら、生成結果が「期待通りかどうか」を判断するには、依然としてコーディングスキルが必要です。また、ガイドラインに記載した内容は、私たち自身が知識として理解しておくことが欠かせません。

今後もAIの可能性を検証しながら、自分たちのスキルも磨き続けていきたいと思います。