ui-diff

name	ui-diff
description	对比 UI 设计稿和 App 截图，检查元素间距、位置、对齐、颜色、字号等差异。 TRIGGER when: 用户提供设计稿和截图要求对比；用户说 UI 走查、UI 对比、检查还原度、看看差异；用户贴两张 App 界面图片说「对比一下」「看看有什么不同」「帮我检查 UI」；提到设计稿 vs 截图/实现；用户给出图片目录要求批量对比。 SKIP: 代码 review、架构图对比、线框图、非 UI 图片（照片、文档截图等）。

UI 对比 Skill

对比 UI 设计稿与 App 实际截图，找出视觉差异。

使用方式

方式一：批量对比（推荐）

/ui-diff <目录路径>

目录结构如下，每个子文件夹是一组对比：

pages/
├── 确认订单/
│   ├── xxx.png      ← 不需要特定命名，自动识别哪个是设计稿
│   └── yyy.png
├── 全部功能-热门/
│   ├── aaa.png
│   └── bbb.jpg

执行流程：

1. 用 Glob 扫描目录下所有子文件夹
2. 每个子文件夹读取图片（支持 png/jpg/jpeg，不区分大小写）
3. 预处理：检查图片尺寸，任一边超过 1999 像素时自动缩放（避免 API 图片尺寸限制）：

   sips -g pixelHeight -g pixelWidth <图片路径>
   # 如果超过限制，缩放到最长边 1999px，保存到同目录 _resized 文件
   sips --resampleHeightWidthMax 1999 <图片路径> --out <同目录/原文件名_resized.扩展名>
   

   后续读取使用缩放后的文件。对比完成后删除 _resized 临时文件。
4. 自动识别哪个是设计稿、哪个是实际截图（见下方识别规则）
5. 逐组对比，输出结果

如果某个子文件夹不是恰好 2 张图片，跳过并提示。

每组对比完成后，在该子文件夹中生成 diff.md 文件保存对比结果。例如：

pages/
├── 确认订单/
│   ├── 1.png
│   ├── 2.png
│   └── diff.md      ← 自动生成的对比报告
├── 全部功能-热门/
│   ├── 1.png
│   ├── 2.png
│   └── diff.md

方式二：直接指定两张图

/ui-diff <设计稿路径> <截图路径>

方式三：对话中直接贴图

用户在对话中粘贴两张图片并说明哪个是设计稿即可，自动识别也会生效。

自动识别规则

按优先级从高到低判断哪张是设计稿、哪张是实际截图：

优先级 1：文件名编号

如果文件名为纯数字（如 1.png、2.png），编号小的是设计稿，编号大的是实际截图。

优先级 2：状态栏时间

• 状态栏时间为 9:41 → 设计稿（Apple 设计模板默认时间，最可靠的视觉信号）
• 状态栏时间为真实时间（非 9:41）→ 实际截图

优先级 3：其他视觉特征

• **设计稿特征：**信号/WiFi/电量为标准满格样式，无运营商名称，画面干净
• **实际截图特征：**有 debug 悬浮按钮、真实运营商/VPN 图标、测试标注（红框等）

无法自动识别时

如果以上规则都无法判断（如都没有状态栏且文件名无规律），询问用户。

对比维度

按以下维度逐项检查，只报告有差异的项，没问题的不要列出来：

1. 布局与间距

• 元素之间的间距是否一致（上下左右）
• 内边距（padding）和外边距（margin）
• 整体布局结构是否匹配

2. 对齐

• 水平对齐：左对齐、居中、右对齐
• 垂直对齐：顶部、居中、底部
• 多个元素之间的对齐关系

3. 尺寸

• 元素宽高是否匹配
• 图片/图标尺寸
• 按钮、输入框等控件尺寸

4. 文字

• 字号大小
• 字重（粗细）
• 行高 / 行间距
• 文字颜色
• 文字内容是否一致

5. 颜色与样式

• 背景色
• 边框颜色和粗细
• 圆角大小
• 阴影效果
• 透明度

6. 其他

• 缺失的元素（设计稿有但截图没有）
• 多余的元素（截图有但设计稿没有）

输出格式

写作要求（严格遵守）

每个字段严格控制在一句话内（不超过 30 字），超过就是写多了。

规则：

• 只陈述事实，不解释、不分析、不给理由
• 「建议修改」只说动作（改什么），不说条件（若需…则…）
• 不要用括号补充说明，如「（表示可切换）」「（收起状态）」
• 问题简述不超过 15 字

禁止的表述：

• 「若需还原设计稿」「确认产品期望」「确认产品状态」
• 「建议确认」「需确认」「需同步更新」
• 「避免…」「保持…」「确保…」
• 「强调…」「体现…」「表示…」

正确示例：

#### 1. 底部按钮文案和样式不同 `确定`
- **位置：**底部固定按钮
- **设计稿：**黄色按钮，「应付总额 ¥500  立即支付」
- **实际截图：**蓝色按钮「提交订单」，无金额
- **建议修改：**按钮改黄色，补上金额，文案改「立即支付」

#### 2. 标题与副标题间距偏大 `高度疑似`
- **位置：**页面标题下方
- **设计稿：**标题与副标题间距约 4pt
- **实际截图：**间距约 8pt，参照导航栏高度估算
- **建议修改：**标题下间距减半

置信度标签（放在标题末尾）：

• 确定 — 肉眼可见的明显差异
• 高度疑似 — 非常可能有差异，需开发核实具体数值
• 待确认 — 看不清或不确定，需要检查代码

错误示例（太啰嗦）：

#### 1. 底部主操作按钮文案与样式
- **位置：**屏幕底部固定操作区
- **设计稿：**黄色背景横条，左侧展示「应付总额 ¥500」，右侧为「立即支付」文案，强调价格与支付动作。
- **实际截图：**蓝紫色圆角按钮，文案为「提交订单」，无金额展示。
- **建议修改：**若需还原设计稿，应在底部操作区体现总价信息，并将按钮文案改为「立即支付」，背景色调整为黄色。

批量对比时

对每一组输出（注意：文件开头不要写 ---，--- 只用于组与组之间的分隔；每个分类的序号独立，从 1 开始）：

# {文件夹名}

<table>
<tr>
<th>设计稿</th>
<th>实际截图</th>
</tr>
<tr>
<td><img src="{设计稿文件名}" width="375"></td>
<td><img src="{截图文件名}" width="375"></td>
</tr>
</table>

## 差异汇总

共计 {N} 条差异项，其中功能差异 {X} 条，UI 细节差异 {Y} 条。

## 功能差异

涉及交互行为、业务流程、功能缺失等，需要和产品确认。

### 1. {问题简述（不超过 15 字）} `确定`
- **位置：**{2-5 字}
- **设计稿：**{一句话，不超过 30 字}
- **实际截图：**{一句话，不超过 30 字}
- **建议修改：**{一句话，不超过 30 字}

## UI 细节差异

间距、颜色、字号、对齐等纯视觉还原问题，开发可直接修复。

### 1. {问题简述} `高度疑似`
...

## 其他

不确定归类的差异，或需要进一步确认的问题。如果没有则省略此分类。

---

# {下一个文件夹名}
...

单组对比时

# UI 对比结果

<table>
<tr>
<th>设计稿</th>
<th>实际截图</th>
</tr>
<tr>
<td><img src="{设计稿文件名}" width="375"></td>
<td><img src="{截图文件名}" width="375"></td>
</tr>
</table>

## 差异汇总

共计 {N} 条差异项，其中功能差异 {X} 条，UI 细节差异 {Y} 条。

## 功能差异

### 1. {问题简述}
- **位置：**{简短描述}
- **设计稿：**{一句话}
- **实际截图：**{一句话}
- **建议修改：**{一句话}

## UI 细节差异

### 1. {问题简述}
...

## 其他（没有则省略）

忽略项（不要报告为差异）

系统 UI

• 状态栏（时间、信号、电量等）

Debug 工具悬浮按钮

截图中可能出现开发阶段的 debug 悬浮按钮，通常位于屏幕边缘（右下角居多），有三种：

1. H5 调试工具：橙色/灰色齿轮图标悬浮球，可能带有「H5离线」等文字
2. Flutter 调试工具：带有「SIT」「Flutter」等文字的齿轮图标，橙色调
3. iOS 原生调试工具：蓝色甲壳虫（bug）图标，带下载/上传箭头，这是 iOS 端的 debug 入口

以上可能单独出现，也可能多个叠在一起（如 Flutter 齿轮 + H5 齿轮 + iOS 甲壳虫同时出现）。这些是开发调试工具，不属于正式 UI，对比时直接忽略，不要报告为差异。

截图标注

截图上可能有测试人员用工具画的红框、红色数字编号、箭头等标注，这些不是 UI 元素，忽略即可。

业务数据差异

设计稿和截图的业务数据（公司名称、金额、条数、邮箱等）通常不同，这是正常的测试数据差异，不是 UI 问题，不要报告。只有当数据差异导致布局明显变形时才提及。

注意事项

• 基于视觉判断，间距/尺寸的数值是估算，标注为「约 Xpx」
• 如果设计稿和截图的分辨率/比例不同，先说明这一点
• 优先报告影响视觉效果明显的差异，细微的放后面
• 不要编造差异，看不清的标注「无法确认」