| name | figma-design-review |
| description | Figmaデザインをノード情報を活用してレビューし、該当箇所に個別コメントを投稿する。Use when (1) ユーザーがFigmaデザインのレビューを依頼した時 (2) 実装者目線、エンジニア視点でのフィードバックが必要な時 (3) デザインに対してFigma上にコメントを残したい時。padding/margin、色のコントラスト、グリッド整合性などベーシックなデザインチェックも実施。Requires Figma MCP connection and FIGMA_TOKEN environment variable. |
Figma Design Review
Figmaのノード情報（padding、色、サイズ等）を活用したベーシックデザインレビューと、スクリーンショットによる実装者目線レビューを実施し、各問題箇所に個別コメントを投稿する。
引数
figma_url (必須): レビュー対象のFigma URL
- 形式:
https://figma.com/design/{FILE_KEY}/{file_name}?node-id={NODE_ID}
- 例:
https://figma.com/design/ABC123/MyDesign?node-id=1-2
Prerequisites
- Figma MCP:
mcp__figma-desktop__* ツールが利用可能であること
- FIGMA_TOKEN: 環境変数にFigma Personal Access Tokenが設定されていること
- Figmaデスクトップアプリ: 対象ファイルがFigmaデスクトップアプリで開かれていること（重要）
Workflow
Step 0: 前提条件チェック（必須）
このステップを最初に実行し、失敗した場合はレビューを中止すること。
1. Figma URLの確認
引数で figma_url が渡されているか確認する。
2. FIGMA_TOKEN環境変数の確認
以下のコマンドで環境変数が設定されているか確認する:
test -n "$FIGMA_TOKEN" && echo "FIGMA_TOKEN is set" || echo "FIGMA_TOKEN is NOT set"
3. Figmaデスクトップアプリの確認
重要: Figma MCPが正常に動作するには、対象ファイルがFigmaデスクトップアプリで開かれている必要があります。
以下のメッセージを表示:
📋 Figmaデスクトップアプリの準備
レビューを開始する前に、以下を確認してください:
1. Figmaデスクトップアプリを起動
2. レビュー対象のファイルを開く: {figma_url}
3. レビュー対象のノード/フレームを選択（推奨）
準備ができたら続行します。
4. Figma MCP接続の確認
mcp__figma-desktop__get_screenshot(nodeId="{NODE_ID}") を実行してMCP接続を確認する。
すべてのチェックがパスした場合のみ、Step 1に進む。
Step 1: URLを解析してデザイン情報を取得
1. URLからFILE_KEYとNODE_IDを抽出
URL形式: https://figma.com/design/{FILE_KEY}/{file_name}?node-id={NODE_ID}
例: https://figma.com/design/ABC123/MyDesign?node-id=1-2
→ FILE_KEY: ABC123
→ NODE_ID: 1:2 (URLの「1-2」を「1:2」に変換)
ブランチURLの場合:
https://figma.com/design/{FILE_KEY}/branch/{BRANCH_KEY}/{file_name}?node-id={NODE_ID}
→ FILE_KEY: {BRANCH_KEY}を使用
2. Figma MCPでデザイン情報を取得
以下を実行:
1. mcp__figma-desktop__get_screenshot(nodeId="{NODE_ID}")
→ 必須。これが失敗したらStep 0の確認を再度行う
2. mcp__figma-desktop__get_design_context(nodeId="{NODE_ID}")
→ デザイン詳細情報。エラー時はスキップ可
3. REST APIでノード詳細情報を取得（必須）
コメント位置とデザイン分析のため、必ずREST APIで詳細情報を取得する:
python3 .claude/skills/figma-design-review/scripts/get_node_info.py <file_key> <node_id> --detail
--detailオプションで、座標に加えてpadding、色、スペーシング情報も取得する。
出力例:
<FRAME name="月報作成" x="0" y="0" width="1440" height="968" fill="#ffffff" padding="24,24,24,24" gap="16">
<FRAME name="Header" x="0" y="0" width="1440" height="64" fill="#f5f5f5" padding="16,24,16,24">
</FRAME>
<FRAME name="保存ボタン" x="300" y="850" width="108" height="40" fill="#0066ff" radius="8">
</FRAME>
</FRAME>
=== Design Analysis ===
1. [SPACING] パディング値が5種類使用されている。統一を検討
2. [COLOR] 背景色が12種類使用されている。デザインシステムの色に統一を検討
この出力をStep 2-3で使用するため、必ず保存しておくこと。
REST APIが失敗した場合:
以下のメッセージを表示してレビューを中止:
❌ 座標情報の取得に失敗しました。
考えられる原因:
1. FIGMA_TOKENが無効または期限切れ
2. ファイルへのアクセス権限がない
3. ネットワークエラー
座標情報なしではコメント位置を正確に指定できないため、レビューを中止します。
Step 2: レビュー実施
references/review-checklist.md を参照し、2段階でレビューを実施する。
Phase A: ベーシックデザインレビュー（ノード情報から検出）
get_node_info.py --detailの出力とDesign Analysisを分析:
- スペーシング - padding/marginの一貫性、グリッド整合性（4px/8px）
- 色 - 色の種類が多すぎないか、コントラスト比は十分か
- サイズ - 同じ役割の要素でサイズが統一されているか
- 構造 - Auto Layoutの適切な使用、ネストの深さ
Phase B: 実装者目線レビュー（スクリーンショット + ノード情報）
- データ構造・状態管理 - 階層の深さ、状態の複雑さ
- テーブル・リスト - スクロール、固定、パフォーマンス
- フォーム・入力 - バリデーション、エラー表示
- UI一貫性 - 色の意味、フォーマット統一
- 権限・セキュリティ - 編集権限、監査ログ
- 仕様確認事項 - 曖昧な点、エッジケース
Step 3: コメント投稿
各問題箇所に対して、該当する位置に個別にコメントを投稿する。
コメント投稿スクリプト:
python3 .claude/skills/figma-design-review/scripts/post_comment.py <file_key> <node_id> <x> <y> "<comment>"
引数:
file_key: Step 1で抽出したFILE_KEYnode_id: Step 1で抽出したNODE_ID（例: 1:197）x: ノード内のX座標オフセット（ピクセル）y: ノード内のY座標オフセット（ピクセル）comment: コメント本文
座標の決め方（重要）:
必ずStep 1で取得したREST APIの座標情報を使用すること。スクリーンショットからの目視推測は禁止。
get_node_info.pyの出力座標はすでにルートノードからの相対座標に変換済みなので、そのまま使用できる。
<FRAME name="月報作成" x="0" y="0" width="1440" height="968">
<FRAME name="テーブルヘッダー" x="208" y="115" width="1260" height="37">
</FRAME>
<FRAME name="Footer" x="188" y="834" width="1252" height="72">
<FRAME name="保存ボタン" x="300" y="850" width="108" height="40">
</FRAME>
</FRAME>
</FRAME>
座標の使い方（要素の中央に配置）:
コメントは対象要素の中央に配置する。座標は以下の計算で求める:
中央X = x + (width / 2)
中央Y = y + (height / 2)
- 問題箇所に対応する要素を特定: レビューで見つけた問題が、どの要素に関連するか特定
- 要素の中央座標を計算:
x="300" y="850" width="108" height="40" の場合
- 中央X = 300 + (108 / 2) = 354
- 中央Y = 850 + (40 / 2) = 870
- → コメント座標は
(354, 870)
- 要素が見つからない場合: 最も近い親要素の中央座標を使用
例:
- テーブルヘッダー
x="208" y="115" width="1260" height="37" に問題
→ 中央座標 (208 + 630, 115 + 18.5) = (838, 133) を使用
- 保存ボタン
x="300" y="850" width="108" height="40" に問題
→ 中央座標 (300 + 54, 850 + 20) = (354, 870) を使用
- ナビゲーション全体
x="0" y="0" width="1440" height="60" に問題
→ 中央座標 (720, 30) を使用
注意:
- スクリーンショットを見て「このあたり」と推測するのは禁止
- 必ずREST APIの出力から正確な座標を取得すること
- 出力座標はすでに相対座標なので、変換は不要
- 適切な要素が見つからない場合は、親要素または最も近い要素の座標を使用
コメントフォーマット:
基本は一行で意味が伝わる形式を使う。複雑な問題は複数段落可。
【{カテゴリ}】{一行で伝わる問題点と提案}
シンプルな指摘（推奨）:
python3 .../post_comment.py ABC123 1:197 354 870 "【余白】padding 24/16/20px混在 → 16pxに統一推奨"
python3 .../post_comment.py ABC123 1:197 200 100 "【色】背景#f0f0f0とテキスト#888のコントラスト比2.5:1 → 4.5:1以上に"
python3 .../post_comment.py ABC123 1:197 500 300 "【サイズ】ボタン高さ36/40/44px混在 → 40pxに統一推奨"
複雑な指摘（詳細が必要な場合）:
python3 .../post_comment.py ABC123 1:197 354 870 "【データ構造】4階層ネストは実装が複雑になる
工事 > 請負/常用 > 作業内容 > 日付 の構造。
状態管理・API設計で問題になりやすい。
→ 2階層にフラット化できないか検討"
Step 4: サマリー報告
投稿したコメントの一覧をユーザーに報告する。
## レビュー完了
### ベーシックデザイン
| # | カテゴリ | 内容 |
|---|---------|------|
| 1 | 余白 | padding 24/16/20px混在 → 16pxに統一推奨 |
| 2 | 色 | 背景色が12種類 → デザインシステムの色に統一 |
| 3 | サイズ | ボタン高さ36/40/44px混在 → 40pxに統一 |
### 実装者目線
| # | カテゴリ | 内容 |
|---|---------|------|
| 4 | データ構造 | 4階層ネストは実装が複雑 |
| 5 | パフォーマンス | 大規模テーブルに仮想スクロール必要 |
| 6 | フォーム | 保存タイミングの仕様確認必要 |
報告に含める情報:
- カテゴリ: 余白、色、サイズ、グリッド（ベーシック）/ データ構造、パフォーマンス、フォーム等（実装者目線）
- 内容: 問題点と提案を一行で
Troubleshooting
get_metadata / get_design_context がエラーになる
原因1: Figmaデスクトップアプリでファイルが開かれていない
- 解決: Figmaデスクトップアプリを起動し、対象ファイルを開く
原因2: 対象ノードが選択されていない
- 解決: Figmaで対象のフレーム/ノードをクリックして選択する
原因3: 出力サイズが大きすぎる（最も多い原因）
- 症状: テーブルやリストなど、ノード数が多い画面でエラーになる
- 解決策:
- Figmaでより小さい子要素（ヘッダー、1行分、ボタン領域など）を選択
- URLのnode-idを子要素のIDに変更して再実行
- 注意: MCPがエラーでもREST API（get_node_info.py）は動作することが多い
原因4: Figma MCPの接続問題
- 解決: Figmaデスクトップアプリを再起動し、MCPプラグインが有効か確認する
get_screenshot は成功するが MCP get_metadata/get_design_context が失敗する
これは一般的なケースです。get_screenshotは画像キャプチャのみのため軽量ですが、get_metadataやget_design_contextはノード構造を解析するため、複雑なノードでエラーになることがあります。
対策: REST APIを使用する
MCPがエラーでも、REST API（get_node_info.py）で座標情報を取得できます:
python3 .claude/skills/figma-design-review/scripts/get_node_info.py <file_key> <node_id>
REST APIはMCPとは独立して動作するため、MCPがエラーでも座標情報を取得できることが多いです。
get_node_info.py の出力が不十分な場合
get_node_info.py はデフォルトで深さ3階層、各階層10要素までに制限されています。
より詳細な座標情報が必要な場合は、スクリプトの制限を緩和するか、特定の子ノードIDを指定して再実行してください。
MCPサーバーのログを確認する
エラーの詳細を確認するには、MCPサーバーのログを見ます:
ls -la ~/.claude/logs/
cat ~/.claude/logs/mcp*.log | tail -100
または、Figmaデスクトップアプリの開発者ツール（メニュー > Plugins > Development > Open Console）でエラーを確認できる場合があります。
Resources
scripts/
post_comment.py: Figma APIでコメントを投稿するスクリプトget_node_info.py: Figma REST APIでノード情報を取得するスクリプト
--detailオプション: padding、色、スペーシング情報も出力- Design Analysis: パディング不一致、色の多用、グリッド逸脱を自動検出
references/
review-checklist.md: レビューチェックリスト
- A. ベーシックデザイン（ノード情報から検出）
- B. 実装者目線レビュー（スクリーンショット＋ノード情報）
