visual-qa

视觉 QA

使用视觉模型，根据设计意图自我审查截图。在发布前发现间距问题、对齐问题、颜色不一致、响应式问题和无障碍性缺漏。

适用场景

• 用户要求“审查这个设计”或“检查这张截图”
• 页面或组件构建完成后、发布前
• 用户想要比较实现与样稿／参考设计
• 用户询问“看起来对吗？”或“哪里不对？”
• 构建工作流中的自动化设计 QA 步骤

核心理念

• 先看截图，再做评审。 始终检查实际渲染结果，而不只是代码。
• 具体说明。 “间距看起来不对”毫无用处。“标题和段落之间的间距是 32px，但按照周围的间距节奏应该是 16px”才有帮助。
• 优先处理影响大的问题。 并非每个像素都重要。重点关注用户实际会注意到的问题。
• 参考设计意图。 对照设计令牌、样稿或明确说明的设计目标。

---

如何审查

步骤 1：截取截图

使用以下一种方法截取截图：

通过浏览器工具：

browser: screenshot (captures the current page)

通过 node 屏幕截图（如果可用）：

nodes: screen_record

通过 Peekaboo（macOS）：

exec: peekaboo screenshot

用户提供： 用户可能会直接粘贴／附上截图。

步骤 2：使用视觉模型分析

使用 image 工具分析截图：

image: [path or URL to screenshot]
prompt: "Review this UI screenshot for design quality..."

步骤 3：结构化评审

按照以下类别（按优先级排序）分析截图：

---

评审类别

1. 布局与间距

检查以下内容：

• 间距节奏是否一致（所有元素是否都遵循间距网格？）
• 对齐情况——应该对齐的元素是否确实对齐？
• 相似组件内部的内边距是否一致
• 容器宽度和最大宽度
• 响应式表现（如果有多个视口的截图）

常见问题：

• 卡片内边距不一致（例如，顶部 24px，左右 16px）
• 元素略微偏离网格（15px，而不是 16px）
• 文本未与相邻元素对齐
• 各个区块的垂直间距差异很大

2. 排版

检查以下内容：

• 层级——标题、正文和说明文字是否一目了然？
• 行长——每行正文应为 45–75 个字符
• 行高——对于字号来说是否过紧或过松？
• 字重的使用——同一用途的字重是否一致？
• 孤行／寡行——标题中是否有单个词独占一行？

常见问题：

• 标题看起来不像标题（字重／字号与正文过于接近）
• 正文行长超过 80 个字符（难以阅读）
• 各区块的标题字号不一致
• 全大写文本未调整字间距

3. 颜色与对比度

检查以下内容：

• 文本与背景的对比度（是否易于阅读？）
• 品牌色的使用是否一致
• 颜色含义是否一致（链接和错误是否使用同一种蓝色？）
• 深色模式问题（如适用）
• 悬停／激活状态是否清晰可见

常见问题：

• 白色背景上的浅灰色文本（对比度不达标）
• 主色被用于太多不同用途
• 边框几乎不可见
• 状态颜色相互冲突（危险状态用绿色，成功状态用红色）

4. 视觉层级

检查以下内容：

• 视觉动线——视线首先落在哪里？这是否合理？
• CTA 是否醒目——主要操作是否是最显眼的元素？
• 信息密度——过于稀疏还是过于拥挤？
• 分组——相关项目是否在视觉上归为一组？
• 留白——是有意安排的，还是仅仅因为有剩余空间？

常见问题：

• 两个同样醒目的 CTA 相互争夺注意力
• 重要信息被埋在不太重要的内容下方
• 各区块之间缺乏联系感
• 大段密集文本缺少视觉间隔

5. 组件质量

检查以下方面：

• 按钮尺寸和内边距是否一致
• 输入框样式是否一致
• 卡片样式是否一致（阴影、边框、圆角）
• 图标尺寸以及与文本的对齐方式
• 图像宽高比和裁剪方式

常见问题：

• 按钮的内边距或高度不一致
• 圆角值混用（有些是 8px，有些是 12px，还有些是 4px）
• 图标与相邻文本的基线未对齐
• 图像被拉伸或裁剪不当

6. 润色与微小细节

检查以下方面：

• 是否存在清晰可见的悬停状态
• 是否有键盘导航的焦点状态
• 是否有加载状态（骨架屏、旋转加载图标）
• 是否有空状态（没有数据时显示什么？）
• 状态之间的过渡效果（生硬还是平滑）
• 网站图标和 OG 图像（如果审查的是完整页面）

常见问题：

• 交互元素没有悬停状态
• 移除了焦点环，却没有替代样式
• 数据加载时内容突然移位
• 没有空状态——只显示一片空白区域

7. 响应式问题（如果有多个视口可供检查）

检查以下方面：

• 移动设备上的内容是否易于阅读（不会太小）
• 移动设备上的触控目标是否 ≥ 44px
• 小屏幕上是否能正常使用导航
• 图像是否未溢出容器
• 是否存在水平滚动（几乎总是一个 bug）

---

输出格式

完整审查

### Visual QA Review

**Overall impression:** [One sentence — first gut reaction]
**Quality score:** [1-10] / 10

#### 🔴 Critical Issues (fix before shipping)
1. **[Category]:** [Specific issue with exact details]
   → **Fix:** [Actionable recommendation]

#### 🟡 Improvements (should fix)
1. **[Category]:** [Specific issue]
   → **Fix:** [Recommendation]

#### 🟢 Minor Polish (nice to fix)
1. **[Category]:** [Specific issue]
   → **Fix:** [Recommendation]

#### ✅ What's Working Well
- [Specific praise — what's well-executed]
- [Another positive]

快速审查

### Quick QA: [Page/Component Name]

Score: [X]/10

Top 3 fixes:
1. [Most impactful issue + fix]
2. [Second issue + fix]
3. [Third issue + fix]

Looks good: [What's working]

对比审查（实现与样稿）

### Design vs Implementation Review

**Fidelity score:** [1-10] / 10

#### Deviations Found
1. **[Element]:** Mockup shows [X], implementation has [Y]
   Impact: [High/Medium/Low]
   → **Fix:** [How to match the mockup]

#### Matching Well
- [Elements that accurately match the design]

---

视觉模型审查提示词

根据需要，使用以下提示词调用 image 工具：

常规审查

Review this UI screenshot for design quality. Check spacing consistency,
typography hierarchy, color contrast, visual hierarchy, and component
quality. Be specific about issues — reference exact elements and suggest
fixes. Prioritize by impact.

重点检查间距与布局

Analyze the spacing and layout of this UI. Check if elements follow a
consistent spacing grid, if padding within similar components matches,
if alignment is correct, and if the overall spacing rhythm feels right.
Note any elements that appear off-grid or inconsistently spaced.

对比审查

Compare these two images. The first is the design mockup, the second is
the implementation. Identify every deviation — differences in spacing,
color, typography, alignment, or missing elements. Rate the fidelity
on a 1-10 scale.

响应式检查

Review this mobile screenshot for responsive design quality. Check that
text is readable, touch targets are large enough (≥44px), nothing
overflows the viewport, and the layout adapts well to the narrow width.

重点检查无障碍

Review this UI screenshot for visual accessibility. Check text contrast
against backgrounds, focus indicator visibility, touch target sizes,
color-only information (anything that relies solely on color to convey
meaning), and text readability at the shown sizes.

---

与构建工作流集成

构建组件后

1. 在浏览器中渲染组件
2. 截取屏幕截图
3. 运行视觉 QA 审查
4. 修复问题
5. 重新截图并验证

构建完整页面后

1. 分别在桌面端（1440px）、平板端（768px）和移动端（375px）截取屏幕截图
2. 在这三种尺寸下运行响应式审查
3. 对桌面端版本运行完整审查
4. 修复问题，优先处理严重问题

与样稿对比

1. 获取样稿图像（Figma 导出图、屏幕截图或用户提供的图像）
2. 在相同视口尺寸下截取实现版本的屏幕截图
3. 运行对比审查
4. 按优先级修复偏差

---

示例

示例 1：“审查这个落地页截图”

image: [screenshot path]
prompt: "Review this landing page for design quality. Check spacing
consistency, typography hierarchy, visual hierarchy (where does the eye
go first?), CTA prominence, color contrast, and overall polish. Be
specific about issues and suggest fixes. Rate 1-10."

示例 2：“我的实现符合这个 Figma 设计吗？”

image: [mockup.png, implementation.png]
prompt: "Compare these two images. First is the Figma mockup, second
is the implementation. Identify every deviation in spacing, color,
typography, alignment, and missing elements. Rate fidelity 1-10."

示例 3：“检查这个组件在移动设备上的显示效果”

image: [mobile-screenshot.png]
prompt: "Review this mobile UI. Is text readable? Are touch targets
large enough (≥44px)? Does anything overflow? Is the layout well-adapted
to mobile width? Check contrast and spacing."