BlueRose/BlueRoseNote

Fork 0

Files

BlueRose 7dcd2a35c2 vault backup: 2026-05-31 13:34:02

2026-05-31 13:34:02 +08:00

12 KiB

Raw Blame History

前言

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并要求登录。

左上角 Plugins
点击 Figma 旁边的 +
点击 Install Figma
浏览器会跳转到 Figma 授权页
登录并授权
回到 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 等工具。如果缺失：

安装：npm install -g chrome-devtools-mcp@latest（需 Node.js >= 20.19.0）
在 .vscode/mcp.json 中添加：

{ "servers": { "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"], "type": "stdio" } } }

Cmd+Shift+P → Reload Window，确认 MCP 启用

Figma MCP

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

获取 API Key：Figma → 头像 → Settings → Personal access tokens → 生成
在 .vscode/mcp.json 中添加：

{
  "servers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-developer-mcp", "--stdio"],
      "env": {
        "FIGMA_API_KEY": "<替换为你的 Figma API Key>"
      },
      "type": "stdio"
    }
  }
}

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" })                 // 桌面

每个断点执行：

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

移动端深度检查（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。

走查范围

✅ 必须关注

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

❌ 不关注

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

参考文件

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

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

12 KiB Raw Blame History Unescape Escape

前言