design-compare

设计对比

将 Figma 设计截图与本地预览截图进行对比，生成结构化的视觉评审和交互式 HTML 对比页面。支持在单个报告中对比多个屏幕。

设置

$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 步：获取每个屏幕的图像

对每个要对比的屏幕重复此操作。使用 slug（例如 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 是否符合数字加冒号或连字符的格式。无效输入会被拒绝。 脚本会以 3 倍比例导出，并设置 use_absolute_bounds=true，以匹配设备像素密度并精确裁切到画框边界。
• 如果脚本失败（缺少令牌），请让用户提供 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 表格：

状态	方面	详情
✅	布局对齐	与设计一致
❌	背景颜色	应为 #1A1A1A，实际为 #FFFFFF

匹配项使用 ✅，不匹配项使用 ❌。每行保持简洁（单行）。对于不匹配项，请说明差异及修复方法。

第 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 → 文件 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 直达链接。