- MCP & Skill
	- ClaudeCode:
		- https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/#claude-code
		- https://claude.com/plugins/figma
	- CodeX Skill:
		- https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/#claude-code
		- https://github.com/openai/skills/blob/main/skills/.curated/figma-implement-design/SKILL.md



# Skill
---
name: ui-review
description: "使用 Chrome DevTools MCP + Figma MCP 对 Web 页面进行自动化 UI 走查，对比 Figma 设计稿与实际页面的字体、颜色、间距、布局等差异，检测响应式溢出问题，生成含 CSS 选择器和修复代码的 Bug 清单。当用户提到 UI 走查、设计还原度检查、对比设计稿、帮我走查页面、页面和设计稿对不上、CSS 样式不对、像素级还原、检查页面实现、视觉回归、前端还原度、responsive 问题、移动端适配检查、设计稿 diff 时触发。即使用户只说"帮我看看这个页面"或"这个实现和设计稿差多少"，只要涉及设计稿与实现的对比，都应该触发本技能。"
user-invokable: true
args:
  - name: figma-url
    description: Figma 设计稿链接（含 fileKey 和 nodeId）
    required: true
  - name: page-url
    description: 要走查的实际页面 URL
    required: true
  - name: breakpoints
    description: "要测试的响应式断点，默认: 375,768,1440"
    required: false
---

# UI 走查 Skill — Chrome DevTools MCP + Figma MCP

通过 AI 连接真实浏览器和 Figma 设计稿，自动化完成 UI 走查工作。产出一份开发可直接使用的 Bug 修复清单。

走查的核心价值在于**发现实现与设计的偏差**——这些偏差在开发时往往难以察觉，但会累积成用户可感知的粗糙感。本技能通过结构化流程确保不遗漏。

---

## 第零步：环境检查

走查依赖两个 MCP Server。如果工具列表中缺少对应工具，引导用户配置。

### Chrome DevTools MCP

需要 `take_screenshot`、`take_snapshot`、`evaluate_script`、`navigate_page` 等工具。如果缺失：

1. 安装：`npm install -g chrome-devtools-mcp@latest`（需 Node.js >= 20.19.0）
2. 在 `.vscode/mcp.json` 中添加：
```json
{ "servers": { "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"], "type": "stdio" } } }
```
3. `Cmd+Shift+P` → `Reload Window`，确认 MCP 启用

### Figma MCP

需要 `get_figma_data`、`download_figma_images` 工具。如果缺失：

1. 获取 API Key：Figma → 头像 → Settings → Personal access tokens → 生成
2. 在 `.vscode/mcp.json` 中添加：
```json
{
  "servers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-developer-mcp", "--stdio"],
      "env": {
        "FIGMA_API_KEY": "<替换为你的 Figma API Key>"
      },
      "type": "stdio"
    }
  }
}
```
3. `Cmd+Shift+P` → `Reload Window`，确认 MCP 启用

两个 MCP 都就绪后，进入走查流程。

---

## 第一步：需求确认与走查规划

### 1.1 确认走查范围

向用户确认：
- **走查页面**：单页面还是多步骤流程（如弹窗步骤 1→2→3→完成）？
- **是否需要登录**：需要则请用户提供测试账号
- **交互前置条件**：如"点击按钮后出现弹窗"
- **关注的断点**：默认 375px / 768px / 1440px，可自定义
- **输出格式**：HTML 报告（含一键复制、可局域网分享）或 Markdown（适合 Git/飞书/Notion）

### 1.2 多步骤流程规划

如果是多步骤流程，列出所有步骤，每个步骤都在**桌面端和移动端**分别走查：

```
例：艺术家入驻流程
├── 步骤 0: 欢迎弹窗
├── 步骤 1: 行为准则
├── 步骤 2: 基本信息 1/3
└── 步骤 3: 完成页
```

---

## 第二步：获取设计稿数据

从 Figma URL 提取 `fileKey` 和 `nodeId`，用 `get_figma_data` 获取设计数据。

重点提取的属性（这些是设计还原度对比的基准）：

| 类别 | 属性 |
|------|------|
| 字体 | fontFamily, fontSize, fontWeight, lineHeight, letterSpacing |
| 颜色 | fill colors, text colors（记录 HEX 值和 Design Token 名） |
| 间距 | padding, gap, itemSpacing |
| 圆角 | cornerRadius |
| 尺寸 | width, height |
| 布局 | layoutMode, layoutAlign |
| 效果 | effects (shadow), strokes |

如果 Figma 有多端设计（移动端/桌面端分开），需分别获取对应的 nodeId。记录 Design Token 名称（如 `--color-primary`），报告中会用到。

---

## 第三步：获取实际页面数据

### 3.1 导航与登录

用 `navigate_page` 打开目标 URL（timeout: 60000）。

SPA 应用常超时但页面已加载——超时后先用 `list_pages` + `take_screenshot` 确认状态，不必盲目重试。

登录流程：`take_snapshot` → `fill` 表单 → `click` 登录 → `wait_for` 成功标志 → 导航到目标页。

### 3.2 多步骤交互

弹窗/模态框需先触发才能看到。流程：`take_snapshot` 找触发按钮 → `click` → 等待弹窗出现 → 截图+提取样式。

> ⚠️ SPA 中弹窗可能不响应普通 click。遇到此情况时，阅读 `references/troubleshooting.md` 中的"SPA 弹窗交互"章节获取详细解决方案（包括 Vue/React 组件直接调用、移动端行为差异等）。

### 3.3 截图

- 视口截图：`take_screenshot`
- 全页截图：`take_screenshot({ fullPage: true })`
- 始终用 `filePath` 保存到 `screenshots/`，命名规则：
  ```
  d01-welcome-desktop.png     ← 桌面端
  m01-welcome-mobile.png      ← 移动端
  ```
  截图是 Bug 报告的证据，会嵌入最终报告。

### 3.4 提取样式

用 `evaluate_script` 注入 JavaScript 提取关键元素的 computed styles。需覆盖：标题(h1-h4)、正文(p, span)、按钮(button, a)、容器(section, [class*=card])、表单(input, textarea, select)、图片(img)、弹窗外层容器。

> 📄 高效提取脚本见 `references/extract-styles.md`——一次调用即可获取弹窗内所有元素的样式，避免多次 evaluate_script。

---

## 第四步：逐项对比 — 设计还原度

这是走查的**核心工作**。

### 4.1 先抓全局，再看局部

在逐页对比之前，先扫描所有页面中**反复出现的组件**。如果某个组件在所有页面中有相同偏差，记录为**全局问题（Global Issue）**，只写一次。这样做是因为全局组件的修复只需改一处 CSS，在每页重复报告只会让开发者困惑。

常见全局组件：XXL 按钮、标准输入框、文本域、弹窗容器、标签/徽章。

识别方法：第一页提取样式 → 对比 Figma → 如有偏差，后续页面验证是否一致 → 一致则为全局问题。

### 4.2 对比维度与容差

| 检查项 | 容差标准 | 说明 |
|--------|---------|------|
| fontFamily | 精确匹配 | 字体族必须完全一致 |
| fontSize | ≤1px | 亚像素渲染可能有微小差异 |
| fontWeight | 精确匹配 | 400 vs 500 视觉差异明显 |
| lineHeight | ≤2px | 行高差 1-2px 在正文中不易察觉 |
| letterSpacing | ≤0.5px | 字间距非常敏感 |
| color (RGB各通道) | ≤5 | 颜色管理可能引入微小偏差 |
| padding/margin/gap | ≤2px | 盒模型差异在 2px 内可接受 |
| borderRadius | 精确匹配 | 圆角差异视觉上很明显 |
| box-shadow | 逐项对比 x/y/blur/spread/color | 阴影差异需要拆开比较 |

对比时注意带透明度的颜色（如 `rgba(28,28,30,0.2)`），alpha 值也要比较。

**凡是超出容差的，全部记录为 Bug，包含：Figma 值 → 实际值、CSS 选择器、可复制的修复代码。**

---

## 第五步：响应式走查

用 `emulate` 模拟不同断点：

```
emulate({ viewport: "375x812x2,mobile,touch" })   // 手机
emulate({ viewport: "768x1024x2,mobile,touch" })   // 平板
emulate({ viewport: "1440x900x1" })                 // 桌面
```

每个断点执行：
1. **全页截图** — 记录布局
2. **溢出检测** — 水平溢出是移动端最常见的 Bug，用 `evaluate_script` 检查 `scrollWidth > innerWidth` 的元素
3. **字号梯度** — 标题在不同断点下字号变化应平滑
4. **布局断点** — 卡片网格列数、导航折叠是否合理

### 移动端深度检查（375px）

移动端不能只看截图，以下问题截图中看不出来：

| 检查项 | 原因 | 检测方法 |
|--------|------|----------|
| 弹窗 max-height ≤ 80vh | 超出会被系统裁剪，用户无法操作 | 检查 `.modal` computedStyle.maxHeight |
| 弹窗内部滚动 | 内容溢出时弹窗应内滚，而非页面滚 | 检查 `overflow-y: auto/scroll` |
| 遮罩层 z-index | header/footer 可能穿透遮罩 | 对比 z-index |
| 动画溢出 | 庆祝动画常产生水平滚动条 | 检查容器 `overflow: hidden` |
| 触摸区域 ≥ 44×44px | Apple HIG 最低要求 | 提取 offsetWidth/Height |
| Safe Area | iOS 刘海屏遮挡 | 检查 `env(safe-area-inset-*)` |
| 图片缩放 | 避免拉伸变形 | 检查 `object-fit` |

---

## 第六步：生成 Bug 修复清单

### 输出原则

- **精简、可执行**：开发拿到就能改，不做鼓励、不做设计评审
- **每个 Bug 附修复代码**：含 CSS 选择器和可复制代码
- **全局问题只写一次**：页面级 Bug 只注明"受 G1 影响"

### 优先级

| 级别 | 定义 |
|------|------|
| **P0** | 设计还原度差异 + 影响用户体验（字体/颜色/间距不一致；全断点溢出） |
| **P1** | 建议修复（某些断点溢出；缺交互反馈） |
| **P2** | 可优化（布局建议；排版优化） |

### 报告结构

```
📋 UI 走查报告
├── 🌐 全局问题（Global Issues）
├── 📄 页面/步骤 N: [名称]（P0 → P1 → P2 排序）
├── 📱 移动端专项检查（375px）
└── 📊 溢出检测汇总表（元素 × 断点矩阵）
```

### Bug 卡片格式

```
#编号  Bug 标题                                    [P0/P1/P2]
      问题描述（元素 / CSS 选择器 / 影响断点）
      [标签: 还原度 / 响应式 / 体验]
      Figma: xxx  →  实际: yyy
      📸 screenshots/d01-xxx.png
      修复代码（可直接复制）
```

### HTML 报告（默认）

单文件 HTML，含：页头信息、全局问题区、分步 Bug 卡片（一键复制按钮）、截图嵌入、移动端专项、溢出矩阵。报告本身也应响应式。可通过 `python3 -m http.server 9090 --bind 0.0.0.0` 局域网分享。

### Markdown 报告

标准 GFM 格式，截图用相对路径引用 `screenshots/`，适合 Git/飞书/Notion。

---

## 走查范围

### ✅ 必须关注

1. **设计还原度**：任何与 Figma 的偏差（字体/颜色/间距/圆角/阴影/尺寸）
2. **全局组件一致性**：按钮、输入框、弹窗等全站统一组件
3. **响应式布局**：各断点溢出、布局断裂、内容裁剪
4. **移动端交互**：弹窗高度、内部滚动、触摸区域、z-index
5. **图标还原**：设计稿矢量图标 vs 实现用 emoji/位图
6. **表单元素**：输入框/文本域/下拉框的边框/圆角/颜色
7. **动画溢出**：过渡效果产生意外滚动条

### ❌ 不关注

1. 测试环境特有内容（vConsole、测试数据）
2. 设计决策（对比度、文案、配色——那是设计过程的决定）
3. 功能逻辑（业务逻辑是功能测试的工作）
4. 后端数据正确性
5. 浏览器兼容性（除非用户明确要求）
6. 性能、SEO、可访问性（除非用户明确要求）

---

## 参考文件

遇到以下场景时，阅读对应的参考文件：

| 场景 | 参考文件 |
|------|---------|
| SPA 弹窗不弹出、导航超时、页面太多 | `references/troubleshooting.md` |
| 需要批量提取 CSS 样式的 JS 脚本 | `references/extract-styles.md` |
| 走查过程中对照检查项清单 | `references/checklist.md` |