308 lines
12 KiB
Markdown
308 lines
12 KiB
Markdown
# 前言
|
||
- 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
|
||
|
||
让CodeX安装Figma Mcp以及Skill之后，CodeX会自动连接Figma并要求登录。
|
||
|
||
1. 左上角 Plugins
|
||
2. 点击 Figma 旁边的 +
|
||
3. 点击 Install Figma
|
||
4. 浏览器会跳转到 Figma 授权页
|
||
5. 登录并授权
|
||
6. 回到 Codex
|
||
|
||
# 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` |
|