comparing-screenshots

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Comparing Screenshots

截图对比

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

本技能用于对比Figma设计稿与HTML生成页面的截图，以像素级精度检测差异。

Overview

概述

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

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

本技能提供以下功能：

HTML截图获取 - 使用Puppeteer捕获HTML页面画面
Figma截图获取 - 通过MCP获取Figma图像
图像对比 - 借助pixelmatch进行像素级差异检测
差异报告 - 视觉差异的量化呈现

Quick Start

快速开始

bash

undefined

bash

undefined

1. セットアップ（初回のみ）

1. 环境搭建（仅首次执行）

cd ~/.agents/scripts/html-screenshot && npm install

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

2. 获取HTML截图

node ~/.agents/scripts/html-screenshot/screenshot.js ./index.html

3. 画像比較

3. 图像对比

node ~/.agents/scripts/html-screenshot/compare.js html_screenshot.png figma_screenshot.png diff.png

undefined

node ~/.agents/scripts/html-screenshot/compare.js html_screenshot.png figma_screenshot.png diff.png

undefined

Workflow

工作流程

Copy this checklist:

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

复制以下检查清单：

截图对比进度：
- [ ] 步骤1：获取Figma截图
- [ ] 步骤2：获取HTML截图
- [ ] 步骤3：执行图像对比
- [ ] 步骤4：结果解读与报告

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

步骤1：获取Figma截图

MCP経由で取得:

bash

mcp__figma__get_screenshot(fileKey, nodeId)

APIから取得（代替）:

bash

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からダウンロード:

bash

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

通过MCP获取:

bash

mcp__figma__get_screenshot(fileKey, nodeId)

通过API获取（替代方案）:

bash

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下载截图:

bash

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

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

步骤2：获取HTML截图

基本コマンド:

bash

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

オプション:

オプション	デフォルト	説明
`--width=N`	375	ビューポート幅（モバイル）
`--height=N`	812	ビューポート高さ
`--no-full-page`	-	ビューポートのみキャプチャ
`--with-mapping`	-	マッピングオーバーレイ表示

例:

bash

undefined

基础命令:

bash

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

可选参数:

参数	默认值	说明
`--width=N`	375	视口宽度（移动端）
`--height=N`	812	视口高度
`--no-full-page`	-	仅捕获视口范围
`--with-mapping`	-	显示映射覆盖层

示例:

bash

undefined

モバイルビュー（iPhone X サイズ）

移动端视图（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 待機

---

node ~/.agents/scripts/html-screenshot/screenshot.js ./index.html ./desktop.png --width=1440 --height=900


**默认行为:**
- Retina画质（deviceScaleFactor: 2）
- 全页面捕获
- 隐藏映射覆盖层
- 等待networkidle0状态

---

Step 3: 画像比較実行

步骤3：执行图像对比

基本コマンド:

bash

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

例:

bash

undefined

基础命令:

bash

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

示例:

bash

undefined

比較のみ

仅执行对比

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


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

---

node ~/.agents/scripts/html-screenshot/compare.js html-screenshot.png figma-screenshot.png diff.png


**差异图像解读:**
- 🔴 红色像素：存在差异的区域
- 🟢 绿色像素：替代差异色（抗锯齿效果）

---

Step 4: 結果解釈と報告

步骤4：结果解读与报告

出力結果の解釈:

パーセント	ステータス	意味
0%	✅ PIXEL PERFECT	完全一致
< 1%	🟡 NEARLY PERFECT	軽微な差異（フォントレンダリングなど）
< 5%	🟠 NOTICEABLE	目立つ差異あり
≥ 5%	🔴 SIGNIFICANT	大きな差異あり

レポート形式:

markdown

undefined

输出结果解读:

百分比	状态	含义
0%	✅ 像素级完全一致	完全匹配
< 1%	🟡 近乎完全一致	轻微差异（如字体渲染差异等）
< 5%	🟠 存在明显差异	有显著可见差异
≥ 5%	🔴 存在重大差异	差异较大

报告格式:

markdown

undefined

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

截图对比结果

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

项目	值
HTML	[文件路径]
Figma	[nodeId]
差异率	X.XX%
判定	✅/🟡/🟠/🔴

差分画像

差异图像

---

---

サイズ不一致の処理

尺寸不一致的处理

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

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

警告メッセージ例:

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

当图像尺寸不同时，工具会自动执行以下操作:

计算两张图像的最大尺寸
将尺寸较小的图像以白色背景填充至最大尺寸
以相同尺寸进行对比

警告消息示例:

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フォントを使用、または許容する
画像読み込み失敗	パスが間違っている	絶対パスを使用
大きな差異	レイアウト崩れ	差分画像を確認して原因特定

问题	原因	解决方法
`puppeteer` 错误	依赖未安装	`cd ~/.agents/scripts/html-screenshot && npm install`
字体差异	系统字体不同	使用Web字体，或接受该差异
图像加载失败	路径错误	使用绝对路径
差异较大	布局错乱	查看差异图像以定位原因

スクリプトの場所

脚本位置

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

~/.agents/scripts/html-screenshot/
├── screenshot.js    # HTML截图获取脚本
├── compare.js       # 图像对比脚本
├── package.json     # 依赖定义文件
└── README.md        # 使用说明文档

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

集成示例：Figma-HTML对比流程

bash

undefined

bash

undefined

1. 出力ディレクトリに移動

1. 进入输出目录

cd .outputs/screen-name/

2. Figmaスクリーンショット取得（MCPまたはAPI）

2. 获取Figma截图（通过MCP或API）

mcpfigmaget_screenshot または curl で取得

使用mcpfigmaget_screenshot 或 curl 获取

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

3. HTMLスクリーンショット取得

3. 获取HTML截图

node ~/.agents/scripts/html-screenshot/screenshot.js ./index.html ./html-screenshot.png

4. 比較実行

4. 执行对比

node ~/.agents/scripts/html-screenshot/compare.js
html-screenshot.png
figma-screenshot.png
diff.png

5. 結果確認

5. 确认结果

差異率が5%未満ならOK、それ以上なら修正が必要

差异率低于5%则视为合格，高于5%则需要修正

---

---

成果物フォルダ構造

成果物文件夹结构

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

.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           # 比較レポート

对比完成后，请按以下结构存储成果物：

.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/ フォルダの作成

创建comparison/文件夹

bash

undefined

bash

undefined

1. フォルダ作成

1. 创建文件夹

mkdir -p .outputs/{screen-id}/comparison

2. ファイルコピー

2. 复制文件

cp figma-screenshot.png comparison/figma.png cp html-screenshot.png comparison/html.png cp diff.png comparison/diff.png

3. READMEテンプレート

3. 生成README模板

cat > comparison/README.md << 'EOF'

Figma-HTML 比較レポート

Figma-HTML 对比报告

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

---

项目	值
页面ID	{screen-id}
对比时间	{date}
差异率	{percentage}%
判定	{status}
EOF

---

成果物チェックリスト

成果物检查清单

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

bash

undefined

对比完成后，请确认以下内容：

bash

undefined

成果物チェックスクリプト

成果物检查脚本

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() { 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 + 1)) fi done

if [ $missing -eq 0 ]; then echo "" echo "✅ 所有成果物已齐备" else echo "" echo "❌ 缺失 $missing 个文件" fi }

使用例

使用示例

check_comparison_outputs .outputs/screen-name

undefined

check_comparison_outputs .outputs/screen-name

undefined

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

手动检查用清单

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

对比成果物检查：
- [ ] comparison/figma.png 已存在
- [ ] comparison/html.png 已存在
- [ ] comparison/diff.png 已存在
- [ ] comparison/README.md 已存在
- [ ] 图像尺寸一致（两者像素数相同）
- [ ] 差异率已记录

参照

参考资料

comparing-figma-html: 視覚比較エージェント（このスキルを使用）
converting-figma-to-html: HTML変換スキル

comparing-figma-html：视觉对比Agent（使用本技能）
converting-figma-to-html：HTML转换技能

comparing-screenshots

Original

Translation

Comparing Screenshots

截图对比

Overview

概述

Quick Start

快速开始

1. セットアップ（初回のみ）

1. 环境搭建（仅首次执行）

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

2. 获取HTML截图

3. 画像比較

3. 图像对比

Workflow

工作流程

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

步骤1：获取Figma截图

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

步骤2：获取HTML截图

モバイルビュー（iPhone X サイズ）

移动端视图（iPhone X尺寸）

タブレットビュー

平板视图

デスクトップビュー

桌面端视图

Step 3: 画像比較実行

步骤3：执行图像对比

比較のみ

仅执行对比

差分画像も出力

同时输出差异图像

Step 4: 結果解釈と報告

步骤4：结果解读与报告

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

截图对比结果

差分画像

差异图像

サイズ不一致の処理

尺寸不一致的处理

トラブルシューティング

故障排除

スクリプトの場所

脚本位置

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

集成示例：Figma-HTML对比流程

1. 出力ディレクトリに移動

1. 进入输出目录

2. Figmaスクリーンショット取得（MCPまたはAPI）

2. 获取Figma截图（通过MCP或API）

mcp__figma__get_screenshot または curl で取得

使用mcp__figma__get_screenshot 或 curl 获取

3. HTMLスクリーンショット取得

3. 获取HTML截图

4. 比較実行

4. 执行对比

5. 結果確認

5. 确认结果

差異率が5%未満ならOK、それ以上なら修正が必要

差异率低于5%则视为合格，高于5%则需要修正

成果物フォルダ構造

成果物文件夹结构

comparison/ フォルダの作成

创建comparison/文件夹

1. フォルダ作成

1. 创建文件夹

2. ファイルコピー

2. 复制文件

3. READMEテンプレート

3. 生成README模板

Figma-HTML 比較レポート

Figma-HTML 对比报告

成果物チェックリスト

成果物检查清单

成果物チェックスクリプト

成果物检查脚本

必須ファイル

必需文件

使用例

mcpfigmaget_screenshot または curl で取得

使用mcpfigmaget_screenshot 或 curl 获取