design-review

设计审查

依据既定设计标准，评估应用的视觉质量和可用性。此审查能发现通常需要专业设计师才能察觉的问题，包括响应式断点、无障碍合规性、视觉层次、间距一致性和国际化就绪度。

适用场景

以下情况可使用 /design-review：

• 发布 UI，但没有设计师审查
• 发布或演示之前
• 进行重大 UI 更改或重新设计之后
• 检查无障碍合规性（WCAG 2.1 AA）
• 验证应用在不同设备上的响应式表现

参考标准

• WCAG 2.1 Level AA — Web Content Accessibility Guidelines（Web 内容无障碍指南）
• Material Design / Human Interface Guidelines — 间距、触控目标、字体比例
• ISO 9241-110 — 交互原则（适用性、自描述性、符合性）
• APCA — Advanced Perceptual Contrast Algorithm（新一代对比度算法）

阶段概览

Phase 1: EDUCATE   → Brief context on what we check and why
Phase 2: SCOPE     → Identify pages, breakpoints, and focus areas
Phase 3: ANALYZE   → Browser-based checks with evidence capture
Phase 4: REPORT    → Findings with screenshots, scores, confidence
Phase 5: REMEDIATE → Fix guidance + YAML regression tests

---

阶段 1：了解

**为何重要：**94% 的第一印象与设计有关。即使功能正确，糟糕的视觉质量也会削弱信任。无障碍问题影响 15-20% 的用户，还会带来法律风险（自 2018 年以来，ADA 诉讼增加了 300%）。

本审查依据客观、可衡量的设计标准检查应用，而非主观审美。每项发现都会引用具体标准。

---

阶段 2：确定范围

收集上下文

1. 自动检测 — 扫描项目以确定：

   • 框架（React、Vue、Next.js 等）
   • CSS 方案（Tailwind、CSS modules、styled-components 等）
   • 使用的设计系统（如有）
   • 路由结构 → 页面列表
   • 现有的 a11y 工具（eslint-plugin-jsx-a11y、axe-core 等）

2. 询问用户（一次询问一个问题，并提供自动检测的默认值）：

   • 目标 URL：应用运行在哪里？（自动检测开发服务器）
   • 关键页面：哪些页面最重要？（根据路由推荐前 3-5 个页面）
   • 目标设备：仅桌面端？移动端优先？两者都要？（默认：两者都要）
   • 品牌指南：是否有指定的颜色、字体或设计系统？（默认：依据通用最佳实践进行评估）
   • 关注领域：是否有已知问题？（可选）

3. 定义要测试的断点：

   • 移动端：375px（iPhone SE）、390px（iPhone 14）
   • 平板：768px（iPad）
   • 桌面端：1280px、1920px
   • （根据用户的目标受众调整）

---

阶段 3：分析

使用 new_session 打开浏览器会话，并设置 record_evidence: true。针对范围内的每个页面，执行以下检查类别。

类别 A：响应式设计（RES）

检查 ID	检查项	标准	方法
RES-01	存在视口 meta 标签	移动端最佳实践	检查 <meta name="viewport">
RES-02	所有断点均无水平溢出	响应式设计	调整视口大小，检查是否出现水平滚动条
RES-03	移动端触控目标 ≥ 48x48px	WCAG 2.5.8 / Material Design	测量移动端断点下交互元素的尺寸
RES-04	375px 宽度下无需缩放即可阅读文本	WCAG 1.4.4	检查移动端正文的字号是否 ≥ 16px
RES-05	所有断点下均可访问导航	可用性	确认导航会折叠或适配，并验证汉堡菜单可用
RES-06	图片按需缩放	响应式图片	检查是否使用 srcset/sizes 或 CSS 容器约束
RES-07	内容被截断时有明确提示	可用性	检查文本溢出，以及是否提供带工具提示或可展开的省略文本
RES-08	移动端表单输入可用	可用性	检查输入框尺寸及适当的输入类型（tel、email）

**浏览器验证：**针对每个断点，使用 act 调整视口大小，然后使用 inspect_page 获取 DOM 和截图。检查是否存在溢出元素，并通过 JavaScript 测量尺寸。

类别 B：无障碍（A11Y）

检查 ID	检查项	标准	方法
A11Y-01	颜色对比度 ≥ 4.5:1（普通文本）	WCAG 1.4.3 AA	提取计算后的颜色，计算对比度
A11Y-02	颜色对比度 ≥ 3:1（大号文本 ≥ 18pt）	WCAG 1.4.3 AA	对大号文本执行上述检查
A11Y-03	所有图像都有替代文本	WCAG 1.1.1	检查 <img> 元素是否具有 alt 属性
A11Y-04	表单输入项有关联标签	WCAG 1.3.1	检查 <label for=""> 或 aria-label
A11Y-05	标题层级符合逻辑（h1→h2→h3）	WCAG 1.3.1	提取标题级别，检查顺序
A11Y-06	所有交互元素上的焦点均可见	WCAG 2.4.7	使用 Tab 键遍历元素，检查焦点环是否可见
A11Y-07	键盘导航可用（Tab、Enter、Escape）	WCAG 2.1.1	通过键盘浏览整个页面
A11Y-08	存在跳过导航链接	WCAG 2.4.1	检查是否有跳转到内容的链接
A11Y-09	ARIA 角色使用正确	WCAG 4.1.2	检查 ARIA 是否误用或冗余
A11Y-10	页面具有 lang 属性	WCAG 3.1.1	检查 <html lang="">
A11Y-11	模态框焦点限制有效	WCAG 2.4.3	打开模态框，确认 Tab 键焦点始终在框内
A11Y-12	错误消息与输入项相关联	WCAG 3.3.1	检查 aria-describedby 或 aria-errormessage
A11Y-13	遵循减少动态效果的设置	WCAG 2.3.3	检查 prefers-reduced-motion 媒体查询
A11Y-14	不含可能诱发癫痫的内容（每秒闪烁 >3 次）	WCAG 2.3.1	目视检查动画

浏览器验证： 使用 inspect_page 提取 DOM。通过 act 运行 JavaScript，计算对比度、检查 ARIA 属性并提取标题层级。使用键盘导航（Tab、Enter、Escape）测试焦点管理。

类别 C：视觉一致性（VIS）

检查 ID	检查项	标准	方法
VIS-01	间距比例一致	设计系统	提取外边距和内边距，检查比例是否一致（4px/8px 网格）
VIS-02	字体排印比例一致	字体排印层级	提取字号，检查比例或级别是否一致
VIS-03	配色方案精简且有意设计	设计最佳实践	提取所有使用的颜色，若非灰色的独特颜色超过 10 种则标记
VIS-04	交互元素的样式一致	一致性	比较各页面的按钮样式和链接样式
VIS-05	对齐网格一致	布局	检查是否存在破坏视觉网格的未对齐元素
VIS-06	异步操作有加载状态	用户体验最佳实践	触发异步操作，确认存在加载指示器
VIS-07	空状态处理妥当	用户体验最佳实践	浏览无数据的页面，检查是否提供有意义的空状态
VIS-08	错误状态样式一致	用户体验最佳实践	触发验证错误，检查样式
VIS-09	深色模式一致性（如适用）	设计系统	切换深色模式，检查是否有元素未应用主题样式

浏览器验证： 使用 JavaScript 提取计算后的样式，并比较不同元素和页面的样式。通过页面截图对比检查视觉一致性。

类别 D：字体排印与可读性（TYP）

检查 ID	检查项	标准	方法
TYP-01	正文为 16-20px	可读性研究	提取计算后的 font-size
TYP-02	正文行高为 1.4-1.6	可读性	提取计算后的 line-height
TYP-03	行长为 45-75 个字符	可读性（Bringhurst）	测量每行的字符数
TYP-04	字体加载策略（防止 FOUT/FOIT）	Web 性能	检查 font-display CSS 和预加载提示
TYP-05	层级数量充足（≥3 种不同字号）	字体排印	提取并统计不同的标题字号
TYP-06	正文左对齐（非两端对齐）	可读性	检查正文段落的 text-align

类别 E：国际化就绪度（I18N）

检查 ID	检查项	标准	方法
I18N-01	组件中没有硬编码字符串	i18n 最佳实践	扫描源代码，查找 JSX/模板中的字符串字面量
I18N-02	布局可适应文本扩展（+30%）	i18n 设计	注入更长的文本字符串，检查是否溢出
I18N-03	支持 RTL 布局（如适用）	i18n	切换 dir="rtl"，检查布局适配情况
I18N-04	日期/数字格式使用区域设置	i18n	检查是否存在硬编码的日期/数字格式
I18N-05	字体栈包含 CJK/Unicode 后备字体	i18n 排版	检查 font-family 声明
I18N-06	图标/图片不包含文字	i18n	目视检查图片内容

浏览器验证： 使用 JavaScript 修改 dir 属性、注入更长的文本、更改区域设置。在每种状态下截图。

---

阶段 4：报告

生成结构化报告并保存到 shiplight/reports/design-review-{date}.md：

# Design Review Report
**Date:** {date}
**URL:** {url}
**Pages reviewed:** {list}
**Breakpoints tested:** {list}

## Overall Score: {X}/10 | Confidence: {X}%

## Score Breakdown
| Category | Score | Findings |
|----------|-------|----------|
| Responsive (RES) | 7/10 | 2 high, 1 medium |
| Accessibility (A11Y) | 5/10 | 1 critical, 3 high |
| Visual Consistency (VIS) | 8/10 | 1 medium |
| Typography (TYP) | 9/10 | 1 low |
| i18n Readiness (I18N) | 6/10 | 2 medium |

## Findings

### CRITICAL

#### A11Y-01: Insufficient color contrast on primary buttons
- **Standard:** WCAG 1.4.3 AA (minimum 4.5:1)
- **Finding:** Primary button (#4A90D2 on #FFFFFF) has contrast ratio 3.1:1
- **Evidence:** [screenshot with annotation]
- **Pages affected:** All pages with primary CTA
- **Confidence:** 97%

### HIGH
...

### MEDIUM
...

### LOW / INFO
...

置信度评分

• 90-100%：经过浏览器验证，并通过程序测量（已计算对比度、已测量元素尺寸）
• 70-89%：来自 DOM 检查的有力证据，截图可佐证发现
• 50-69%：基于启发式判断，可能因情境而异（例如“间距看起来不一致”）
• 低于 50%：不要报告

---

阶段 5：修复

针对每项发现，提供：

1. 修复指南

#### A11Y-01: Insufficient color contrast
**File:** src/components/Button.tsx:23
**Current:** `background: #4A90D2` (contrast 3.1:1 against white)
**Fix:** `background: #2563EB` (contrast 4.8:1 against white) — maintains blue hue, meets AA
**Alternative:** `background: #1D4ED8` (contrast 7.1:1) — meets AAA

2. YAML 回归测试

- name: a11y-01-button-contrast
  description: Verify primary button meets WCAG AA contrast ratio
  severity: critical
  standard: WCAG-1.4.3-AA
  steps:
    - URL: /
    - VERIFY: Primary action buttons have sufficient color contrast (minimum 4.5:1 ratio for normal text)
      timeout_seconds: 15

将所有 YAML 测试保存到 shiplight/tests/design-review.test.yaml。

---

提示

• 先使用 inspect_page 读取 DOM——这比截图更省资源，并能提供供 act 使用的元素索引。
• 检查对比度时，使用 act 通过 JavaScript 中的 window.getComputedStyle() 提取实际渲染的颜色。
• 使用 act 执行键盘操作（Tab、Enter、Escape、方向键）来测试键盘导航。
• 在多个断点下运行此审查——许多问题只会在特定视口尺寸下出现。
• 要测试 i18n 文本扩展，使用 act 通过 JavaScript 将 textContent 修改为更长的字符串。
• 使用 close_session 关闭会话，并通过 generate_html_report 生成可分享的证据报告。