# UI Diff

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

- Skill: `iammccc/ui-diff` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add iammccc/ui-diff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iammccc/ui-diff/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: iAmMccc (https://skillmd.com/u/iammccc)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/iammccc/ui-diff

---


# UI 对比 Skill

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

## 使用方式

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

```
/ui-diff <目录路径>
```

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

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

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

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

**正确示例：**

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

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

置信度标签（放在标题末尾）：
- **`确定`** — 肉眼可见的明显差异
- **`高度疑似`** — 非常可能有差异，需开发核实具体数值
- **`待确认`** — 看不清或不确定，需要检查代码

**错误示例（太啰嗦）：**

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

### 批量对比时

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

```markdown
# {文件夹名}

<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. {问题简述} `高度疑似`
...

## 其他

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

---

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

### 单组对比时

```markdown
# 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」
- 如果设计稿和截图的分辨率/比例不同，先说明这一点
- 优先报告影响视觉效果明显的差异，细微的放后面
- 不要编造差异，看不清的标注「无法确认」