Comparing Screenshots

FigmaデザインとHTML生成物のスクリーンショットを比較し、ピクセルレベルで差異を検出するスキル。

Overview

このスキルは以下を提供します：

1. HTMLスクリーンショット取得 - Puppeteerを使用したHTML画面キャプチャ
2. Figmaスクリーンショット取得 - MCP経由でFigma画像を取得
3. 画像比較 - pixelmatchによるピクセル単位の差異検出
4. 差分レポート - 視覚的な差異の定量化

Quick Start

# 1. セットアップ（初回のみ）
cd ~/.agents/scripts/html-screenshot && npm install

# 2. HTMLスクリーンショット取得
node ~/.agents/scripts/html-screenshot/screenshot.js ./index.html

# 3. 画像比較
node ~/.agents/scripts/html-screenshot/compare.js html_screenshot.png figma_screenshot.png diff.png

Workflow

Copy this checklist:

Screenshot Comparison Progress:
- [ ] Step 1: Figmaスクリーンショット取得
- [ ] Step 2: HTMLスクリーンショット取得
- [ ] Step 3: 画像比較実行
- [ ] Step 4: 結果解釈と報告

Step 1: Figmaスクリーンショット取得

MCP経由で取得:

mcp__figma__get_screenshot(fileKey, nodeId)

APIから取得（代替）:

curl -s "https://api.figma.com/v1/images/{fileKey}?ids={nodeId}&format=png&scale=2" \
  -H "X-Figma-Token: {token}" | jq -r '.images["{nodeId}"]'

取得したURLからダウンロード:

curl -L -o figma-screenshot.png "{image_url}"

Step 2: HTMLスクリーンショット取得

基本コマンド:

node ~/.agents/scripts/html-screenshot/screenshot.js <html-file> [output-path] [options]

オプション:

例:

# モバイルビュー（iPhone X サイズ）
node ~/.agents/scripts/html-screenshot/screenshot.js ./index.html ./html-screenshot.png

# タブレットビュー
node ~/.agents/scripts/html-screenshot/screenshot.js ./index.html ./tablet.png --width=768 --height=1024

# デスクトップビュー
node ~/.agents/scripts/html-screenshot/screenshot.js ./index.html ./desktop.png --width=1440 --height=900

デフォルト動作:

• Retinaクオリティ（deviceScaleFactor: 2）
• フルページキャプチャ
• マッピングオーバーレイ非表示
• networkidle0 待機

Step 3: 画像比較実行

基本コマンド:

node ~/.agents/scripts/html-screenshot/compare.js <image1> <image2> [diff-output]

例:

# 比較のみ
node ~/.agents/scripts/html-screenshot/compare.js html-screenshot.png figma-screenshot.png

# 差分画像も出力
node ~/.agents/scripts/html-screenshot/compare.js html-screenshot.png figma-screenshot.png diff.png

差分画像の解釈:

• 🔴 赤いピクセル: 差異がある箇所
• 🟢 緑のピクセル: 代替差分色（アンチエイリアス）

Step 4: 結果解釈と報告

出力結果の解釈:

レポート形式:

## スクリーンショット比較結果

| 項目 | 値 |
|------|-----|
| HTML | [ファイルパス] |
| Figma | [nodeId] |
| 差異率 | X.XX% |
| 判定 | ✅/🟡/🟠/🔴 |

### 差分画像
![diff](diff.png)

サイズ不一致の処理

画像サイズが異なる場合、ツールは自動的に:

1. 両画像の最大サイズを計算
2. 小さい方を白背景でパディング
3. 同じサイズで比較

警告メッセージ例:

Warning: Image dimensions differ
  Image 1: 750x1624
  Image 2: 750x1500
  Comparing at: 750x1624 (padding smaller image)

トラブルシューティング

スクリプトの場所

~/.agents/scripts/html-screenshot/
├── screenshot.js    # HTMLスクリーンショット取得
├── compare.js       # 画像比較
├── package.json     # 依存関係定義
└── README.md        # 使用方法

統合例: Figma-HTML比較フロー

# 1. 出力ディレクトリに移動
cd .outputs/screen-name/

# 2. Figmaスクリーンショット取得（MCPまたはAPI）
# mcp__figma__get_screenshot または curl で取得
curl -L -o figma-screenshot.png "{figma_image_url}"

# 3. HTMLスクリーンショット取得
node ~/.agents/scripts/html-screenshot/screenshot.js ./index.html ./html-screenshot.png

# 4. 比較実行
node ~/.agents/scripts/html-screenshot/compare.js \
  html-screenshot.png \
  figma-screenshot.png \
  diff.png

# 5. 結果確認
# 差異率が5%未満ならOK、それ以上なら修正が必要

成果物フォルダ構造

比較完了後、以下の構造で成果物を格納すること：

.outputs/{screen-id}/
├── index.html              # 生成HTML
├── mapping-overlay.js      # マッピング可視化
├── spec.md                 # 画面仕様書
├── assets/                 # アセットファイル
│   ├── *.svg
│   └── *.png
└── comparison/             # ★ 比較成果物フォルダ
    ├── figma.png           # Figmaスクリーンショット
    ├── html.png            # HTMLスクリーンショット
    ├── diff.png            # 差分画像
    └── README.md           # 比較レポート

comparison/ フォルダの作成

# 1. フォルダ作成
mkdir -p .outputs/{screen-id}/comparison

# 2. ファイルコピー
cp figma-screenshot.png comparison/figma.png
cp html-screenshot.png comparison/html.png
cp diff.png comparison/diff.png

# 3. READMEテンプレート
cat > comparison/README.md << 'EOF'
# Figma-HTML 比較レポート

| 項目 | 値 |
|------|-----|
| 画面ID | {screen-id} |
| 比較日時 | {date} |
| 差異率 | {percentage}% |
| 判定 | {status} |
EOF

成果物チェックリスト

比較完了時に以下を確認すること：

# 成果物チェックスクリプト
check_comparison_outputs() {
  local dir="$1"
  local missing=0
  
  echo "=== 成果物チェック: $dir ==="
  
  # 必須ファイル
  for f in comparison/figma.png comparison/html.png comparison/diff.png comparison/README.md; do
    if [ -f "$dir/$f" ]; then
      echo "✅ $f"
    else
      echo "❌ $f (MISSING)"
      missing=$((missing + 1))
    fi
  done
  
  if [ $missing -eq 0 ]; then
    echo ""
    echo "✅ すべての成果物が揃っています"
  else
    echo ""
    echo "❌ $missing 個のファイルが不足しています"
  fi
}

# 使用例
check_comparison_outputs .outputs/screen-name

チェックリスト（手動確認用）

Comparison Deliverables:
- [ ] comparison/figma.png が存在する
- [ ] comparison/html.png が存在する
- [ ] comparison/diff.png が存在する
- [ ] comparison/README.md が存在する
- [ ] 画像サイズが一致している（両方同じピクセル数）
- [ ] 差異率が記録されている

参照

• [comparing-figma-html](../../agents/comparing-figma-html.md): 視覚比較エージェント（このスキルを使用）
• [converting-figma-to-html](../converting-figma-to-html/SKILL.md): HTML変換スキル