qa-review

name	qa-review
description	交付前五道质量检查合为一体：AI 味检测、可访问性审查、层级与节奏审查、交互状态审查、终检汇总。前四项独立检测，第五项引用前四项结果做汇总判定，不重复检测。产出最终 QAReport（含 P0/P1/P2 优先级和交付判定）。
trigger	["原型生成后，交付前","make-prototype 或 generate-variations 完成后","每次修改原型后（仅 AI 味检测部分自动触发）","用户要求做质量检查时"]

质量检查（QA Review）

合并了五项独立检查为一个技能，按顺序执行。前四项各自检测，第五项（终检汇总）引用前四项结果，不重复检测。

触发时机

• 交付前 QA 阶段（Phase 7: QAReport）
• make-prototype 完成后自动触发（仅第一项 AI 味检测）
• 每次修改原型后（PatchLog 记录后，仅第一项 AI 味检测）
• 用户手动要求做质量检查

前置条件

• PrototypeSpec — 待审查的原型 HTML 文件
• DesignSystemManifest — 设计系统 Token 定义
• ComponentSpec — 组件规范（如有，来自 design-system-extract）

---

检查一：AI 味检测

逐项检测以下 10 项 AI slop 特征。每项给出判定结果（检测到 / 未检测到），如果检测到则给出修改建议并自动修复。

检测清单

1. 紫色或蓝紫渐变

• 检测方法：扫描 CSS 中所有 linear-gradient、radial-gradient、conic-gradient，检查色值是否落在紫/蓝紫色域（hue 240°-290°）
• 判定标准：渐变中任一色标落在紫蓝色域即为"检测到"
• 修复建议：替换为与品牌色一致的非紫蓝渐变，或改为纯色 + 微妙明暗变化
• 例外：用户在 DesignBrief 中明确要求紫蓝渐变，且在文档中注明为有意识选择

2. 三列 icon 卡片

• 检测方法：检查 HTML 结构中是否存在连续 3 个等宽卡片，每个卡片包含一个图标 + 标题 + 描述的固定模式
• 判定标准：≥3 个等宽且结构同构的 icon+title+desc 卡片出现在同一行即为"检测到"
• 修复建议：打破等宽对称——改为非对称布局（如 2+1、错落式）、用不同卡片尺寸、或合并为单一叙事区块

3. 奶油底配赤陶橙（Claude 默认审美）

• 检测方法：检查背景色是否为奶油色系（hex 近似 #FFF8F0 ~ #FAF0E6，oklch L>0.95 C<0.03），且强调色是否为赤陶橙系（hex 近似 #C66B3D ~ #D97149，oklch hue 40°-55°）
• 判定标准：背景和强调色同时命中即为"检测到"
• 修复建议：更换背景色或强调色，至少改变其中一个维度

4. 近黑底配酸性绿或朱红

• 检测方法：检查背景色是否为近黑色（L<0.15），且唯一强调色是否为酸性绿（hue 100°-140°，C>0.15）或朱红（hue 15°-35°，C>0.15）
• 判定标准：近黑底 + 单一酸性绿/朱红强调色即为"检测到"
• 修复建议：引入第二个强调色或改变色调，打破单色点缀的刻板模式

5. 报纸风零圆角

• 检测方法：检查所有组件的 border-radius 是否全部为 0 或未设置，同时检查是否使用密集多列布局（≥3列）
• 判定标准：全零圆角 + 密集多列布局同时出现即为"检测到"
• 修复建议：为卡片和按钮添加适度圆角，或减少列数

6. 默认字体（Inter、Roboto、Arial、系统字体）

• 检测方法：检查 CSS 中 font-family 声明，匹配以下黑名单：Inter、Roboto、Arial、Helvetica、system-ui、-apple-system、sans-serif（作为主字体而非 fallback）
• 判定标准：display 字体或 body 字体命中黑名单即为"检测到"
• 修复建议：根据设计系统的美学方向替换为有辨识度的字体，从 Google Fonts 或其他 CDN 引入

7. 无意义的 emoji 装饰

• 检测方法：扫描 HTML 内容中的 emoji 字符，排除品牌系统明确使用的场景
• 判定标准：emoji 出现在标题、按钮文字、导航项等非内容区域即为"检测到"
• 修复建议：替换为 SVG 图标或品牌自定义图标

8. lorem ipsum 或假数据

• 检测方法：扫描文本内容，匹配 lorem、ipsum、dolor、sit amet、consectetur、placeholder text、sample text、your text here 等模式
• 判定标准：出现上述任一模式即为"检测到"
• 修复建议：替换为与产品定位和目标用户匹配的真实文案

9. 无意义的 stock 插图

• 检测方法：检查 <img> 标签的 src 和 alt，匹配 placeholder、stock、dummy、picsum（无语义 seed）等模式
• 判定标准：图片 src 为无语义占位或 alt 为空/通用描述即为"检测到"
• 修复建议：替换为有语义 seed 的占位图（如 picsum.photos/seed/coffee-brand-hero）或真实图片

10. 千篇一律的 dashboard 布局

• 检测方法：检查布局是否为标准 dashboard 模板：顶部导航 + 左侧边栏 + 主区域 2×2 或 3×2 统计卡片网格 + 下方图表区
• 判定标准：布局结构完全匹配标准模板即为"检测到"
• 修复建议：打破网格对称——改变卡片尺寸比例、引入非卡片元素（如时间线、活动流）、重组信息层级

输出：AISlopReport

# AISlopReport

> 检测对象：{原型文件名}
> 检测时间：{日期}
> 总结：{N}/10 项检测到 AI slop 特征

| # | 检测项 | 判定 | 详情 | 修复状态 |
|---|--------|------|------|---------|
| 1 | 紫色或蓝紫渐变 | 未检测到 / 检测到 | {详情} | — / 已自动修复 |
| 2 | 三列 icon 卡片 | 未检测到 / 检测到 | {详情} | — / 已自动修复 |
| ... | ... | ... | ... | ... |

## 自动修复摘要
- {修复项1}：{修改前 → 修改后}

## 人工确认建议
- {需要用户决策的项目，如有}

自动修复规则

1. 修复不改变设计系统：所有修复必须使用 DesignSystemManifest 中定义的 Token，不引入新 Token
2. 修复不改变信息架构：只改视觉表现，不改内容结构和文案含义
3. 修复后重新检测：自动修复后重新跑一轮检测，确保修复没有引入新的 slop
4. 无法自动修复的项：标注"需人工确认"，在报告中给出具体建议但不自动执行

---

检查二：可访问性审查

检查以下 5 个维度，每个维度给出通过/不通过判定，不通过项给出具体修复方案。

1. 文字对比度（WCAG 标准）

检测标准：

• 正常文字（< 18px 或 < 14px bold）：对比度 ≥ 4.5:1（WCAG AA）
• 大文字（≥ 18px 或 ≥ 14px bold）：对比度 ≥ 3.0:1（WCAG AA）
• 非文字元素（图标、边框）：对比度 ≥ 3.0:1
• 推荐达到 AAA：正常文字 ≥ 7:1，大文字 ≥ 4.5:1

检测方法：遍历所有文本元素的 color 和有效背景色，计算 WCAG 对比度比值 (L1 + 0.05) / (L2 + 0.05)。对 DesignSystemManifest 中每对前景/背景色 Token 组合预计算对比度。

修复方案（不通过时）：调整前景色明度直至达标，给出具体的 oklch/hex 替换值，同步更新 DesignSystemManifest。

2. 语义化 HTML

检测项	判定标准
按钮语义	所有可点击元素用 <button> 或 <a>，非 <div onclick>
表单标签关联	每个 <input> 有关联的 <label>（for/id 或包裹）
标题层级	<h1> → <h2> → <h3> 连续不跳级，每页仅一个 <h1>
列表语义	列表内容用 <ul>/<ol> + <li>
图片 alt	装饰图 alt=""，内容图有描述性 alt
Landmark	包含 <header>、<nav>、<main>、<footer>
ARIA	动态组件有正确 ARIA 属性（role="dialog" 等）

3. 键盘可达性

检测项	判定标准
Tab 顺序	不使用正整数 tabindex，DOM 顺序即视觉顺序
可聚焦	所有 <button>/<a>/<input> 默认可聚焦
Focus ring 可见	≥2px 可见焦点指示器，对比度 ≥3:1
跳过导航	≥3 个导航项时必须有 skip link
键盘陷阱	模态框/下拉可用 Esc/Tab 关闭或退出
快捷键冲突	不使用单一字母键作为快捷键

4. 动效偏好

检测项	判定标准
prefers-reduced-motion	CSS 包含 @media (prefers-reduced-motion: reduce)
动效降级	reduced-motion 内 transition-duration: 0.01ms 或 animation: none
自动播放	无自动播放大段动画（≥2秒）
闪烁内容	无 >3Hz 闪烁（防光敏癫痫）

5. 表单设计

检测项	判定标准
必填项标注	视觉标记 + required 属性
错误信息	具体说明问题，通过 aria-describedby 关联
错误状态视觉	边框/背景变色 + 文字提示 + 图标，不仅依赖颜色
label 位置	label 在 input 上方或左侧，紧邻
placeholder	不替代 label
提交反馈	加载/成功/失败三种状态都有明确反馈

输出：AccessibilityReport

# AccessibilityReport

> 审查对象：{原型文件名}
> 审查时间：{日期}
> 总结：{通过项数}/{总项数} 通过

## 1. 文字对比度
| 元素 | 前景 | 背景 | 对比度 | 要求 | 判定 |
...

## 2-5. {其他维度}
...

## 修复汇总
- 自动修复：{N} 项
- 需人工确认：{N} 项

注意：对比度不通过的修复需要调整 Token 值，属于设计系统变更，必须提示用户确认。如果原型不含表单，跳过第 5 项并标注"不适用"。

---

检查三：层级与节奏审查

检查 4 个维度，每个维度给出通过/需改进判定，需改进项给出具体修改建议和具体值。

1. 视觉层级

• 大小层级：标题层级字号递减，相邻比 ≥ 1.2，无相同字号不同语义，无跳跃过大（比 > 2.0）
• 权重层级：标题与正文字重差 ≥ 200，粗体仅用于强调（一屏内 ≤ 3 处非标题粗体）
• 颜色层级：主/次/辅助文本 oklch L 值差 ≥ 0.10，强调色面积 < 15%，不仅靠颜色区分信息
• 位置层级：核心内容在首屏可见区域，CTA 在阅读路径自然终点
• 密度层级：密度分布均匀或有意识渐变，无局部密度突变

2. 节奏感

• 间距标尺遵循：所有 padding/margin/gap 都是标尺中的值，零野生间距值
• 垂直节奏：Section 间距 > Block 间距 > Element 间距，递减关系，无异常间距
• 重复模式变化：完全相同重复 ≥ 4 次时有变化（交替色、间距变化、特殊项突出），布局有节奏
• 喘息空间：至少 1 个占整屏 30%+ 的留白区域，容器内 padding ≥ 间距标尺 md 值

3. 色彩权重

• 强调色面积：强调色面积 < 15% 总可见面积
• 强调色用途：仅用于 CTA 按钮、关键数据、选中状态、重要提示
• 色彩平衡：大面积低饱和 + 小面积高饱和，一屏内 ≤ 4 种独立色相，60:30:10 法则

4. 排版节奏

• 字号梯度连续性：字号构成连续梯度（无跳级），比例一致，无野生字号
• 行高舒适度：标题 1.1-1.3，正文 1.5-1.7，长文本不过紧（< 1.4）或过松（> 1.8）
• 段间距一致性：段间距一致，段间距 = 1.5-2x 行高

输出：HierarchyRhythmReport

# HierarchyRhythmReport

> 审查对象：{原型文件名}

## 1. 视觉层级
| 子项 | 判定 | 详情 | 修改建议 |

## 2. 节奏感
## 3. 色彩权重
## 4. 排版节奏

## 总结
- 总通过率：{通过项}/{总项}
- P1（建议修复）：{N} 项
- P2（可选优化）：{N} 项

## 修改建议汇总
1. {建议1}
2. {建议2}

---

检查四：交互状态审查

逐个遍历原型中所有交互元素，检查是否包含完整的状态集。缺失状态必须补齐。

状态集定义

状态	必须性	视觉要求
default	必须	默认外观
hover	必须	明显视觉变化（背景色变化、阴影提升、微缩放等）
active / pressed	必须	按下反馈（缩放 0.97、颜色加深、阴影减弱）
focus	必须	可见 focus ring（≥2px outline 或 box-shadow，对比度 ≥ 3:1）
disabled	必须	视觉弱化但不消失（opacity 0.4-0.6，cursor: not-allowed）
loading	条件必须	触发异步操作的元素有加载状态
error	条件必须	表单验证元素有错误状态（边框变色 + 文字提示 + 图标）

检测方法

1. 识别交互元素：<button>、<a>、<input>、<select>、<textarea>、<[role="button"]>、<[tabindex]>
2. 逐元素状态检查：检查 CSS 中是否定义了对应状态样式
3. focus ring 专项：检查 :focus/:focus-visible，是否有 outline 或 box-shadow，对比度 ≥ 3:1，不存在 outline: none 无替代
4. hover/active 差异：hover 和 active 不应完全相同

自动修复规则

1. focus：自动添加 :focus-visible，使用设计系统强调色作为 ring 色
2. disabled：自动添加 :disabled，设置 opacity: 0.5 和 cursor: not-allowed
3. error：自动添加 .is-error，使用设计系统 danger 色
4. hover/active 差异：相同则为 active 添加 transform: scale(0.97)
5. loading：不自动修复（需了解异步逻辑），在报告中建议

修复后重新检查，确保所有必须状态已补齐。

输出：InteractionStatesReport

# InteractionStatesReport

> 交互元素总数：{N}
> 缺失状态总数：{M}

## 元素状态矩阵
| # | 元素 | 类型 | default | hover | active | focus | disabled | loading | error |

## 缺失状态详情
### 元素 1: {描述}
- **缺失 focus**: {修复建议 + CSS 代码}

## focus ring 专项检查
## hover/active 差异检查
## 自动修复汇总
## 需人工确认

---

检查五：终检汇总（引用前四项，不重复检测）

核心原则：本步骤只汇总，不重新检测。所有检测数据来自前四项的报告结果。

执行内容

1. 收集前四项报告：AISlopReport、AccessibilityReport、HierarchyRhythmReport、InteractionStatesReport
2. 补充终检独有项（前四项未覆盖的）：
   • 过渡动画：所有 transition 的 duration 是否在 0.2s-0.3s（微交互）；页面转场可到 0.4s 但需注明
   • 反馈即时性：按钮点击即时反馈、表单提交 loading 状态、异步操作加载指示器
   • 悬停目标大小：可点击元素实际触控区域（含 padding）≥ 44px × 44px（移动端）
3. 汇总 P0/P1/P2 问题清单：
   • P0（阻塞交付）：categories 非法、必填字段缺失、双语字段缺失、artifacts 文件不存在、对比度严重不达标、focus ring 完全缺失
   • P1（建议修复）：description 不符合三段式、产物内容空洞、prompt 目标不清晰、对比度 AA 不通过、状态缺失、间距野生值
   • P2（可选优化）：标签可更精准、排版可更好、行高微调、段间距微调
4. 交付判定：
   • 可以交付：所有问题已修复或确认为可接受
   • 需修复后交付：存在 P0 问题，修复后重新检查
   • 不可交付：存在多个 P0 问题或设计系统一致性严重破坏

输出：最终 QAReport

# QAReport（最终）

> 原型：{文件名}
> 检查时间：{日期}
> 设计系统版本：{DesignSystemManifest 版本}

---

## 一、AI 味检测
> 引用 AISlopReport
- AI slop 检出：{N}/10 项
- 自动修复：{N} 项
- 状态：通过 / 需人工确认

## 二、可访问性审查
> 引用 AccessibilityReport
- 通过率：{通过项}/{总项}
- 状态：通过 / 需修复

## 三、层级与节奏审查
> 引用 HierarchyRhythmReport
- 总通过率：{通过项}/{总项}
- 状态：通过 / 需改进

## 四、交互状态审查
> 引用 InteractionStatesReport
- 交互元素：{N}，缺失状态：{M}
- 状态：通过 / 需修复

## 五、终检独有项
| 子项 | 判定 | 详情 | 建议 |
|------|------|------|------|
| 过渡动画 | {判定} | {详情} | {建议} |
| 反馈即时性 | {判定} | {详情} | {建议} |
| 悬停目标大小 | {判定} | {详情} | {建议} |

---

## 总结
- 总通过率：{通过项数}/{总项数}
- 需修复项：{N}
- 阻塞交付的问题：{N}

### 修复优先级
1. **P0（阻塞交付）**：{问题列表}
2. **P1（建议修复）**：{问题列表}
3. **P2（可选优化）**：{问题列表}

### 交付判定
- [ ] **可以交付** — 所有问题已修复或确认为可接受
- [ ] **需修复后交付** — 存在 P0 问题，修复后重新检查
- [ ] **不可交付** — 存在多个 P0 问题或设计系统一致性严重破坏

注意事项

• 前四项检查可独立调用（用户只想查某一项时），但终检汇总必须在前四项都完成后执行
• 所有"需改进"项必须给出具体的修改建议和具体值，不能只说"需要改进"
• 自动修复仅限于不改变设计系统 Token 值的安全修复（如添加 aria 属性、补全 alt 文本、添加 focus 样式）
• 对比度不通过的修复需要调整 Token 值，属于设计系统变更，必须提示用户确认
• 修复后的 CSS 必须使用 DesignSystemManifest 中的 Token，不引入新 Token
• 如果用户在 DesignBrief 中明确要求使用某项被禁止的风格，该检测项标注"用户明确要求，跳过"但仍然记录
• 终检独有项的过渡动画 0.2s-0.3s 标准适用于微交互；页面转场动画可以到 0.4s，但需在报告中注明