figma-design-review

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

1. Figma MCP: mcp__figma-desktop__* ツールが利用可能であること
2. FIGMA_TOKEN: 環境変数にFigma Personal Access Tokenが設定されていること
3. Figmaデスクトップアプリ: 対象ファイルがFigmaデスクトップアプリで開かれていること（重要）

Workflow

Step 0: 前提条件チェック（必須）

このステップを最初に実行し、失敗した場合はレビューを中止すること。

1. Figma URLの確認

引数で figma_url が渡されているか確認する。

• URLがない場合: 以下のメッセージを表示してレビューを中止:

  ❌ Figma URLが指定されていません。
  
  使い方: /figma-design-review <figma_url>
  例: /figma-design-review https://figma.com/design/ABC123/MyDesign?node-id=1-2
  

2. FIGMA_TOKEN環境変数の確認

以下のコマンドで環境変数が設定されているか確認する:

test -n "$FIGMA_TOKEN" && echo "FIGMA_TOKEN is set" || echo "FIGMA_TOKEN is NOT set"

• 「FIGMA_TOKEN is NOT set」と表示された場合: 以下のメッセージを表示してレビューを中止:

  ❌ FIGMA_TOKEN環境変数が設定されていません。
  
  設定方法:
  
  1. Figma Personal Access Tokenを取得:
     - Figmaにログイン → 右上プロフィール → Settings
     - Personal access tokens → Generate new token
     - トークンをコピー
  
  2. 環境変数を設定:
  
     【一時的に設定（現在のセッションのみ）】
     export FIGMA_TOKEN="your-token-here"
  
     【永続的に設定（推奨）】
     # ~/.zshrc または ~/.bashrc に追加
     echo 'export FIGMA_TOKEN="your-token-here"' >> ~/.zshrc
     source ~/.zshrc
  
     【Claude Code設定ファイルで設定】
     # ~/.claude/settings.json に追加
     {
       "env": {
         "FIGMA_TOKEN": "your-token-here"
       }
     }
  

3. Figmaデスクトップアプリの確認

重要: Figma MCPが正常に動作するには、対象ファイルがFigmaデスクトップアプリで開かれている必要があります。

以下のメッセージを表示:

📋 Figmaデスクトップアプリの準備

レビューを開始する前に、以下を確認してください:

1. Figmaデスクトップアプリを起動
2. レビュー対象のファイルを開く: {figma_url}
3. レビュー対象のノード/フレームを選択（推奨）

準備ができたら続行します。

4. Figma MCP接続の確認

mcp__figma-desktop__get_screenshot(nodeId="{NODE_ID}") を実行してMCP接続を確認する。

• エラーの場合: 以下のメッセージを表示してレビューを中止:

  ❌ Figma MCPに接続できません。
  
  以下を確認してください:
  1. Figmaデスクトップアプリが起動しているか
  2. 対象ファイルがFigmaデスクトップアプリで開かれているか
  3. Claude Code MCP設定でfigma-desktopが有効か
  
  MCP設定方法: https://github.com/anthropics/claude-code/blob/main/docs/mcp.md
  

すべてのチェックがパスした場合のみ、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を分析:

1. スペーシング - padding/marginの一貫性、グリッド整合性（4px/8px）
2. 色 - 色の種類が多すぎないか、コントラスト比は十分か
3. サイズ - 同じ役割の要素でサイズが統一されているか
4. 構造 - Auto Layoutの適切な使用、ネストの深さ

Phase B: 実装者目線レビュー（スクリーンショット + ノード情報）

1. データ構造・状態管理 - 階層の深さ、状態の複雑さ
2. テーブル・リスト - スクロール、固定、パフォーマンス
3. フォーム・入力 - バリデーション、エラー表示
4. UI一貫性 - 色の意味、フォーマット統一
5. 権限・セキュリティ - 編集権限、監査ログ
6. 仕様確認事項 - 曖昧な点、エッジケース

Step 3: コメント投稿

各問題箇所に対して、該当する位置に個別にコメントを投稿する。

コメント投稿スクリプト:

python3 .claude/skills/figma-design-review/scripts/post_comment.py <file_key> <node_id> <x> <y> "<comment>"

引数:

• file_key: Step 1で抽出したFILE_KEY
• node_id: Step 1で抽出したNODE_ID（例: 1:197）
• x: ノード内のX座標オフセット（ピクセル）
• y: ノード内のY座標オフセット（ピクセル）
• comment: コメント本文

座標の決め方（重要）:

必ずStep 1で取得したREST APIの座標情報を使用すること。スクリーンショットからの目視推測は禁止。

get_node_info.pyの出力座標はすでにルートノードからの相対座標に変換済みなので、そのまま使用できる。

<!-- 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)

1. 問題箇所に対応する要素を特定: レビューで見つけた問題が、どの要素に関連するか特定
2. 要素の中央座標を計算: x="300" y="850" width="108" height="40" の場合
   • 中央X = 300 + (108 / 2) = 354
   • 中央Y = 850 + (40 / 2) = 870
   • → コメント座標は (354, 870)
3. 要素が見つからない場合: 最も近い親要素の中央座標を使用

例:

• テーブルヘッダー 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: 出力サイズが大きすぎる（最も多い原因）

• 症状: テーブルやリストなど、ノード数が多い画面でエラーになる
• 解決策:
  1. Figmaでより小さい子要素（ヘッダー、1行分、ボタン領域など）を選択
  2. 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サーバーのログを見ます:

# Claude Codeのログディレクトリを確認
ls -la ~/.claude/logs/

# 最新のMCPログを確認
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. 実装者目線レビュー（スクリーンショット＋ノード情報）