design-compare

デザイン比較

Figma のデザインスクリーンショットとローカルプレビューのスクリーンショットを比較し、構造化されたビジュアルレビューとインタラクティブな HTML 比較ページを作成します。1 つのレポートで複数の画面に対応しています。

セットアップ

$SKILL_DIR は、この SKILL.md ファイルが格納されているディレクトリを指します。スキルのインストール先（例：.claude/skills/design-compare、.agents/skills/design-compare など）に基づいて解決してください。

前提条件

エクスポートスクリプトには FIGMA_ACCESS_TOKEN 環境変数が必要です。リポジトリのルートにある .env に保存してください：

FIGMA_ACCESS_TOKEN=figd_...

スクリプトはリポジトリのルートにある .env を自動的に読み込みます。トークンは https://www.figma.com/developers/api#access-tokens から取得してください。

重要： トークンをコミットしないよう、.env が .gitignore に記載されていることを確認してください。

ワークフロー

ステップ 1：各画面の画像を取得する

比較する画面ごとに繰り返します。ファイル名にはスラッグ（例：empty-state、list-view）を使用してください。

プロジェクト名またはコンテキスト名からレポートフォルダー名を決めます。例：design-compare-reports/LayoutCheckExample/。このフォルダー内に、ソースファイル名（拡張子なし）をフォルダー名にした画面ごとのサブフォルダーを作成し、画像を保存してください。例：ContentView/、SliderView/。レポートフォルダーには、共通の config.js と report.html を保存します。

Figma デザイン画像：

• Figma URL から fileKey と nodeId を抽出します。
• 抽出したパラメーターを指定して mcp__figma__get_screenshot を呼び出します。スクリーンショットはステップ 2 での目視比較用にインラインで返されます。
• HTML ページ用のファイルとして保存するには、エクスポートスクリプトを実行します：

  mkdir -p "design-compare-reports/<ReportName>/<ViewName>"
  bash "$SKILL_DIR/scripts/export-figma-node.sh" "<fileKey>" "<nodeId>" "design-compare-reports/<ReportName>/<ViewName>/<slug>_figma.png"
  

  スクリプトは fileKey が英数字（ハイフン／アンダースコアを含む）であること、nodeId が数字とコロン／ハイフンのパターンに一致することを検証します。無効な入力は拒否されます。 スクリプトは、デバイスのピクセル密度に合わせ、フレームの境界に正確に切り抜くため、use_absolute_bounds=true を指定して 3 倍のスケールでエクスポートします。
• スクリプトが失敗した場合（トークンがない場合）、Figma のスクリーンショットファイルをユーザーに提供してもらいます。

プレビュー画像：

• Xcode MCP を使用する場合は、mcp__xcode__RenderPreview を呼び出して新しいプレビューをレンダリングし、返された previewSnapshotPath を使用します。
• それ以外の場合は、ユーザーからプレビュー画像のパスを受け取ります。
• レポートフォルダーにコピーします：

  cp "<preview_path>" "design-compare-reports/<ReportName>/<ViewName>/<slug>_preview.png"
  

ステップ 2：ビジュアル比較

両方の画像（Figma のインラインスクリーンショットとプレビューファイル）を読み込んで表示し、分析します。次の項目を評価してください。

1. レイアウト - 要素の配置、整列、要素間の余白
2. タイポグラフィ - フォントサイズ、太さ、行の高さ、テキスト内容
3. 色 - 背景色、テキスト色、ティントカラー、不透明度
4. コンポーネント - ボタン、ツールバー、アイコン、ナビゲーション要素
5. サイズ - 要素の寸法、パディング、マージン

ステップ 3：比較の概要を出力する

視覚的な重要度の高い順に並べた Markdown テーブルを 1 つ作成します：

状態	項目	詳細
✅	レイアウトの整列	デザインと一致
❌	背景色	#1A1A1A の想定に対し、#FFFFFF

一致には ✅、不一致には ❌ を使用します。各行は簡潔に記述してください（1 行）。不一致については、違いと修正方法を記載してください。

ステップ 4：HTML 比較ページを生成する

共通の成果物（config.js、report.html）はすべて design-compare-reports/<ReportName>/ に保存します。画像は画面ごとのサブフォルダー（<ViewName>/）に保存します。

1. 画面のメタデータを含む config.js を生成します。画像パスには <ViewName>/ のプレフィックスを使用します。次の JavaScript を design-compare-reports/<ReportName>/config.js に書き込みます：

   // config.js — generated by design-compare skill
   const reportConfig = {
     generatedAt: "TIMESTAMP",       // replace with current date/time
     screens: [
       {
         name: "SCREEN_NAME",        // replace with human-readable name
         figma: "VIEW_NAME/SLUG_figma.png",
         preview: "VIEW_NAME/SLUG_preview.png",
         figmaUrl: "FIGMA_URL"       // replace with full Figma URL for the node
       }
     ]
   };
   

   プレースホルダーを置き換えます：TIMESTAMP → 現在の日時、SCREEN_NAME → 人が読める画面名、VIEW_NAME → ソースファイル名（拡張子なし）、SLUG → ファイルのスラッグ、FIGMA_URL → Figma の完全な URL。

   複数の画面がある場合は、screens 配列に項目を追加します。

2. HTML テンプレートをコピーします：

   cp "$SKILL_DIR/assets/compare.html" "design-compare-reports/<ReportName>/report.html"
   

3. open design-compare-reports/<ReportName>/report.html を実行してファイルを開きます。

HTML ページでは、スワイプ（デフォルト）と並列表示の比較モード、複数画面のレポート用画面タブ、Figma への直接リンクを利用できます。