--- 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-design-review https://figma.com/design/ABC123/MyDesign?node-id=1-2 ``` #### 2. FIGMA_TOKEN環境変数の確認 以下のコマンドで環境変数が設定されているか確認する: ```bash 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で詳細情報を取得する:** ```bash python3 .claude/skills/figma-design-review/scripts/get_node_info.py --detail ``` `--detail`オプションで、座標に加えてpadding、色、スペーシング情報も取得する。 **出力例:** ```xml === 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: コメント投稿 各問題箇所に対して、**該当する位置に**個別にコメントを投稿する。 **コメント投稿スクリプト:** ```bash python3 .claude/skills/figma-design-review/scripts/post_comment.py "" ``` **引数:** - `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`の出力座標は**すでにルートノードからの相対座標に変換済み**なので、そのまま使用できる。 ```xml ``` **座標の使い方（要素の中央に配置）:** コメントは対象要素の**中央**に配置する。座標は以下の計算で求める: ``` 中央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の出力から正確な座標を取得すること - 出力座標はすでに相対座標なので、変換は不要 - 適切な要素が見つからない場合は、親要素または最も近い要素の座標を使用 **コメントフォーマット:** 基本は**一行で意味が伝わる形式**を使う。複雑な問題は複数段落可。 ``` 【{カテゴリ}】{一行で伝わる問題点と提案} ``` **シンプルな指摘（推奨）:** ```bash python3 .../post_comment.py ABC123 1:197 354 870 "【余白】padding 24/16/20px混在 → 16pxに統一推奨" ``` ```bash python3 .../post_comment.py ABC123 1:197 200 100 "【色】背景#f0f0f0とテキスト#888のコントラスト比2.5:1 → 4.5:1以上に" ``` ```bash python3 .../post_comment.py ABC123 1:197 500 300 "【サイズ】ボタン高さ36/40/44px混在 → 40pxに統一推奨" ``` **複雑な指摘（詳細が必要な場合）:** ```bash python3 .../post_comment.py ABC123 1:197 354 870 "【データ構造】4階層ネストは実装が複雑になる 工事 > 請負/常用 > 作業内容 > 日付 の構造。 状態管理・API設計で問題になりやすい。 → 2階層にフラット化できないか検討" ``` ### Step 4: サマリー報告 投稿したコメントの一覧をユーザーに報告する。 ```markdown ## レビュー完了 ### ベーシックデザイン | # | カテゴリ | 内容 | |---|---------|------| | 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）で座標情報を取得できます: ```bash python3 .claude/skills/figma-design-review/scripts/get_node_info.py ``` REST APIはMCPとは独立して動作するため、MCPがエラーでも座標情報を取得できることが多いです。 ### get_node_info.py の出力が不十分な場合 get_node_info.py はデフォルトで深さ3階層、各階層10要素までに制限されています。 より詳細な座標情報が必要な場合は、スクリプトの制限を緩和するか、特定の子ノードIDを指定して再実行してください。 ### MCPサーバーのログを確認する エラーの詳細を確認するには、MCPサーバーのログを見ます: ```bash # 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. 実装者目線レビュー（スクリーンショット＋ノード情報）