Ui Review Contract

UI Review Contract — 四信号门触发协议

> 背景（Codex P9 → P4 提前）：ce:work 已有 Figma Design Sync 步骤，但缺乏统一的触发协议。 > 本 overlay 收敛现有 UI 检测行为为可预期的四信号门规则。

---

四信号门定义

| 信号 | 类型 | 检测内容 | |------|------|----------| | Plan Signal | 计划/需求 | 出现 UI 相关词：component、page、screen、layout、style、design、responsive、visual、UI、UX、界面、页面、样式、组件 | | File Signal | 改动文件 | 匹配：*.css、*.scss、*.tsx、*.jsx、*.vue、*.html、components/、pages/、views/、styles/、design-tokens/ | | Artifact Signal | 工件引用 | 出现：Figma URL、screenshot、visual diff、design spec、mockup | | Exclusion Signal | 排除条件 | 匹配：API design、database design、schema、纯 CLI/后端任务（无 File Signal 匹配时排除） |

触发规则

满足以下任意一组组合才触发 Design Review（单个信号不触发）：

| 组合 | 说明 | |------|------| | Plan + File | 计划提到 UI + 有前端文件改动 | | File + Artifact | 有前端文件改动 + 有设计工件引用 | | Plan + Artifact | 计划提到 UI + 有设计工件 |

Exclusion Signal 覆盖：如果 Exclusion Signal 触发且 File Signal 未触发，不做 Design Review。

---

触发后行为

当四信号门判断需要 Design Review 时，在 ce:review 的 Advisory Tier 中增加 UI 审查：

1. 加载设计审查代理（并行）

design-implementation-reviewer — 视觉对齐检查（如有 Figma URL）
figma-design-sync              — Figma 设计同步检查（如有 Figma URL）
design-iterator                — 迭代改进建议（N 轮截图-分析-改进循环）

2. 设计审查输出格式

使用 Review Contract 的 Advisory Tier 规则（autofix_class: advisory），额外字段：

# 设计 finding 额外字段
design_check:
  figma_url: "https://figma.com/..."    # 如有
  screenshot: "path/to/screenshot.png"  # 如有
  visual_diff: "描述视觉差异"
  severity: P2 | P3                     # 设计问题最高 P2（不 blocking）

3. 输出 Checklist

设计审查完成后生成 checklist（插入 review.md）：

## UI Review Checklist

- [ ] 组件间距符合设计规范
- [ ] 颜色/字体与 design token 一致
- [ ] 响应式布局在移动端正常
- [ ] 无障碍性（aria labels、contrast ratio）
- [ ] 加载/空/错误状态已实现

---

与现有工作流集成

ce:work 中的集成点

在 ce:work Phase 3 质量检查阶段，已有 Figma Design Sync 步骤：

# 原有步骤（保留）
6. Figma Design Sync (if applicable)

# 本 overlay 增加
6.5 四信号门检查：是否需要 Design Review？
    └─ 是 → 加载 design-implementation-reviewer
    └─ 否 → 跳过

ce:review 中的集成点

ce:review 的 persona-catalog 决定哪些 reviewer 被派发。本 overlay 增加：

如果四信号门触发 → 在 Advisory Tier 中自动添加 design-implementation-reviewer
如果有 Figma URL → 同时添加 figma-design-sync

---

信号门检测命令

在 ce:work Phase 1 完成环境扫描后，运行信号检测：

# Plan Signal: 检查计划文件中的 UI 关键词
# $PLAN_FILE = 当前任务的计划文件路径，如 docs/plans/2026-04-08-*.md
# 调用前需确定计划文件路径，或用 $(ls docs/plans/*.md | tail -1) 取最新文件
PLAN_FILE="${PLAN_FILE:-$(ls docs/plans/*.md 2>/dev/null | tail -1)}"
grep -i "component\|page\|screen\|layout\|style\|design\|UI\|UX" "$PLAN_FILE" 2>/dev/null || true

# File Signal: 检查改动文件
git diff --name-only HEAD | grep -E "\.(css|scss|tsx|jsx|vue|html)$|components/|pages/"

# Artifact Signal: 检查工件引用
DIFF_OUTPUT="${DIFF_OUTPUT:-$(git diff HEAD 2>/dev/null)}"
grep -ri "figma\.com\|screenshot\|visual.diff\|design.spec" "$PLAN_FILE" 2>/dev/null || true
echo "$DIFF_OUTPUT" | grep -i "figma\.com\|screenshot" || true

# Exclusion Signal
grep -i "API.design\|database.design\|schema" "$PLAN_FILE" 2>/dev/null || true

---

不触发示例（避免过度审查）

| 任务 | 信号 | 结果 | |------|------|------| | 修复 SQL 注入 | 仅 Exclusion Signal | ❌ 不触发 | | 更新 README | 无任何信号 | ❌ 不触发 | | 添加 API 端点 | Plan: "API design" (Exclusion) | ❌ 不触发 | | 修复 Button 样式 | File: button.css + Plan: "style fix" | ✅ Plan+File 触发 | | Figma 设计同步 | Artifact: Figma URL + File: *.tsx | ✅ File+Artifact 触发 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jerrylalala
• Source: Jerrylalala/compound-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.