farmanlab Comparing Screenshots
FigmaデザインとHTML生成物のスクリーンショットを比較し、ピクセルレベルで差異を検出するスキル。
Overview
このスキルは以下を提供します：
- HTMLスクリーンショット取得 - Puppeteerを使用したHTML画面キャプチャ
- Figmaスクリーンショット取得 - MCP経由でFigma画像を取得
- 画像比較 - pixelmatchによるピクセル単位の差異検出
- 差分レポート - 視覚的な差異の定量化
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]
オプション:
| オプション | デフォルト | 説明 |
|---|---|---|
--width=N |
375 | ビューポート幅（モバイル） |
--height=N |
812 | ビューポート高さ |
--no-full-page |
- | ビューポートのみキャプチャ |
--with-mapping |
- | マッピングオーバーレイ表示 |
例:
# モバイルビュー（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: 結果解釈と報告
出力結果の解釈:
| パーセント | ステータス | 意味 |
|---|---|---|
| 0% | ✅ PIXEL PERFECT | 完全一致 |
| < 1% | 🟡 NEARLY PERFECT | 軽微な差異（フォントレンダリングなど） |
| < 5% | 🟠 NOTICEABLE | 目立つ差異あり |
| ≥ 5% | 🔴 SIGNIFICANT | 大きな差異あり |
レポート形式:
## スクリーンショット比較結果
| 項目 | 値 |
|------|-----|
| HTML | [ファイルパス] |
| Figma | [nodeId] |
| 差異率 | X.XX% |
| 判定 | ✅/🟡/🟠/🔴 |
### 差分画像
サイズ不一致の処理
画像サイズが異なる場合、ツールは自動的に:
- 両画像の最大サイズを計算
- 小さい方を白背景でパディング
- 同じサイズで比較
警告メッセージ例:
Warning: Image dimensions differ
Image 1: 750x1624
Image 2: 750x1500
Comparing at: 750x1624 (padding smaller image)
トラブルシューティング
| 問題 | 原因 | 対処法 |
|---|---|---|
puppeteer エラー |
依存関係未インストール | cd ~/.agents/scripts/html-screenshot && npm install |
| フォント差異 | システムフォントの違い | Webフォントを使用、または許容する |
| 画像読み込み失敗 | パスが間違っている | 絶対パスを使用 |
| 大きな差異 | レイアウト崩れ | 差分画像を確認して原因特定 |
スクリプトの場所
~/.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: 視覚比較エージェント（このスキルを使用）
- converting-figma-to-html: HTML変換スキル