webcraft-skills 0.1.1

package/skills/webcraft-skills/references/workflows/review-ui.zh.md

@@ -0,0 +1,207 @@
+# UI Review Workflow
+
+用于审查已有页面、组件、截图、代码变更或 PR 中的 UI 风险。`review-ui` 是轻量到中等深度的 UI code review，不是全量体检。
+
+Review 的目标是指出真实风险、解释影响、给出修复方向。不要把 review 写成审美散文，也不要默认展开完整 audit。
+
+## 1. Review 与 Audit 的边界
+
+- `review-ui`：适合 PR、diff、单页、单组件、局部改动、快速风险检查。
+- `audit-ui`：适合整站、上线前、严格排查、深度响应式和状态检查。
+
+Review 默认不做评分、不做完整视口矩阵、不做完整 Content Stress Test、不输出完整 Fix Order。Review 只关注当前范围内最有修复价值的风险。
+
+如果 review 中发现系统性问题，例如全站 token 混乱、多个页面响应式崩坏、组件状态体系缺失，可以建议升级为 audit，但不要擅自扩大审查范围。
+
+## 2. 确认审查范围
+
+先确认或推断：
+
+- Scope：PR / diff / 单文件 / 单组件 / 单页 / 截图 / 整站局部。
+- Change type：新增页面、重构组件、样式调整、交互状态、响应式修复、文案调整。
+- Page type：landing page、dashboard、app screen、form、docs、portfolio 等。
+- Existing visual system：当前颜色、字体、spacing、圆角、边框、组件风格和页面语气。
+- Verification level：代码审查、截图审查、浏览器验证，或混合审查。
+
+如果用户只说“检查一下首页”，默认做 `Standard Review`，按现有网站风格检查，不套用 preset。
+
+## 3. 审查模式
+
+### Quick Review
+
+- 用户说“快速看看”“有没有明显问题”时使用。
+- 最多 5 条 finding。
+- 只报告 Critical 和明显 Major。
+- 不报告低价值 Minor。
+
+### Standard Review
+
+- 默认模式。
+- 建议 5 到 10 条 finding。
+- 聚焦可用性、响应式、组件状态、视觉一致性和明显 AI 模板感。
+- 不输出评分。
+
+### PR Review
+
+- 用户给出 diff、PR 或变更范围时使用。
+- 只审查变更引入的问题，以及变更可能影响的相邻 UI。
+- 不把旧问题全部翻出来，除非它会被本次变更放大。
+- 历史遗留问题只在三种情况下报告：本次改动引入回归、本次改动让旧问题更严重、旧问题会阻断本次改动的核心体验。
+- 不审查与本次 PR 无关的整站风格问题。
+
+## 4. 输入类型分支
+
+### PR / Diff
+
+- 先看改动文件和影响范围。
+- 优先找回归风险：布局破坏、状态丢失、响应式断点变化、样式覆盖范围过大。
+- 只指出与本次改动相关的问题。
+
+### 单页
+
+- 检查首屏主次、核心任务、响应式、导航、CTA、内容压力和明显视觉体系问题。
+- 不默认做整站一致性审查。
+
+### 单组件
+
+- 检查尺寸、状态、长内容、禁用/错误/加载、可访问名称、组合变体。
+- 不按整页标准审查一个组件。
+
+### 截图
+
+- 只能审查可见视觉和布局。
+- 不断言 hover、focus、loading、弹窗关闭、键盘路径等无法从截图验证的行为。
+- 需要验证的交互放到 `Open Questions`。
+
+### 代码静态审查
+
+- 基于结构、CSS、组件状态和断点推断风险。
+- 对未运行页面的问题标明“基于代码推断”。
+
+## 5. 审查重点
+
+按优先级检查：
+
+1. 回归风险：本次改动是否破坏已有布局、状态、响应式或可访问性。
+2. 可用性：核心内容是否可读，核心操作是否可点击，关键路径是否可完成。
+3. 响应式：常见移动端、平板、桌面是否有明显风险。
+4. 组件状态：hover、active、focus-visible、disabled、loading、error、empty、success。
+5. 视觉一致性：颜色、spacing、字体层级、圆角、边框、阴影是否符合现有体系。
+6. 内容压力：长文案、中英文混排、列表数量变化、图片比例变化。
+7. AI 模板感：过度 badge、bento grid、渐变光斑、空泛口号、虚构数据。
+
+不要为了覆盖所有分类而强行输出问题。
+
+## 6. 严重程度
+
+- `Critical`：导致核心内容不可读、核心操作不可用、主要视口崩坏、关键流程中断。
+- `Major`：显著降低可用性、响应式稳定性、一致性、可信度或扫描效率。
+- `Minor`：不影响主要使用，但降低精致度或局部完成度。
+
+Review 中不要输出太多 Minor。除非用户要求 polish，否则 Minor 应该少而准。
+
+## 7. Finding 质量标准
+
+好的 review finding 应该短、准、可定位、能修复。
+
+必须做到：
+
+- 指明位置：文件、组件、页面区域或截图区域。
+- 给出证据：具体视口、状态、代码结构或可见现象。
+- 说明影响：为什么这会影响用户、产品质感或回归风险。
+- 给出修复方向：至少说明应该从哪里改。
+
+不要写：
+
+```text
+这里不够高级。
+```
+
+要写：
+
+```text
+在 375px 宽度下，主按钮文案会换成两行并撑高按钮，导致 CTA 组高度跳动。建议给按钮组改为纵向排列，或限制按钮文案换行策略。
+```
+
+## 8. 输出格式
+
+```markdown
+## Context
+
+- Scope:
+- Review mode:
+- Change type:
+- Page type:
+- Verification level:
+
+## Findings / 问题列表
+
+### Critical
+
+#### 1. 问题标题
+Location:
+Evidence:
+Impact:
+Fix:
+
+### Major
+
+...
+
+### Minor
+
+...
+
+## Open Questions
+
+- 需要用户确认或运行页面才能判断的问题。
+
+## Suggested Next Step / 建议下一步
+
+- 建议先修什么，是否需要升级为 audit。
+```
+
+规则：
+
+- 没有问题的级别不要输出。
+- 每个 finding 必须可定位、有证据、有影响、有修复方向。
+- 对截图或未运行页面，不要把推断写成事实。
+- 如果没有发现问题，明确说“未发现 Critical/Major UI 问题”，并说明剩余未验证风险。
+
+如果没有发现问题，使用：
+
+```markdown
+## Findings / 问题列表
+
+未发现 Critical / Major UI 问题。
+
+## Residual Risk / 剩余风险
+
+- 未运行浏览器，移动端交互状态未验证。
+```
+
+## 9. Review 后的流转
+
+- 如果 findings 明确、范围小、修复路径清楚，建议进入 `fix-ui`。
+- 如果问题系统性强、涉及多个页面、多个组件或需要评分，建议进入 `audit-ui`。
+- 如果问题依赖产品信息、品牌决策或真实数据，放入 `Open Questions`，不要直接修。
+- 如果 review 未发现 Critical/Major，只给出剩余风险，不要强行建议修复。
+
+## 10. 何时升级为 Audit
+
+建议升级为 `audit-ui` 的情况：
+
+- 用户要检查整站或上线前质量。
+- 发现多个页面共享同一系统性问题。
+- 需要严格检查多个视口、状态和内容压力。
+- 需要评分、Top Findings、Fix Order 和完整报告。
+- 需要从 UI 质量角度做全量体检。
+
+## 11. 禁止事项
+
+- 不要把 review 变成 redesign。
+- 不要因为个人审美否定现有产品风格。
+- 不要在用户未指定 preset 时强行套用 preset。
+- 不要输出没有证据、没有位置、没有修复方向的问题。
+- 不要扩大 PR/diff 审查范围，除非发现明确回归风险。
+- 不要为了显得全面而列出低价值 Minor。