octopus-workflow/core/checklists/frontend.md

前端实现自检清单

开发者在编写前端代码前后自检使用。确保组件结构合理、样式一致、状态完整、 可访问且可测试。分为"实现前"（PRE）和"实现后"（POST）两部分。 全部通过后方可提交代码评审。

---

使用说明

1. PRE 项在开始写组件前检查；
2. POST 项在完成编码和所有验证命令后检查；
3. 对"不通过"项必须在代码评审前修复；
4. 无法满足的项标记 [N/A: <原因>]。

---

实现前（PRE — Pre-Implementation）

1. 上下文完备性

#	检查项	通过	不通过	N/A	备注
PRE-1	已确定项目框架（React / Vue / Svelte / SolidJS / Angular）	☐	☐	☐
PRE-2	已确定样式方案（Tailwind / CSS Modules / styled-components / ...）	☐	☐	☐
PRE-3	已读取至少 3 个同模块的现有文件（UI 工作同类组件），理解命名、结构和样式模式（共享 brownfield 规则，规范出处：.octopus/skills/review-code/SKILL.md §"Greenfield vs. Brownfield"）	☐	☐	☐
PRE-4	已确认路由模式（file-based / config-based）和新组件路由位置	☐	☐	☐
PRE-5	已确认项目使用的 UI 基础库（Kobalte / Radix / Headless UI / ...）	☐	☐	☐
PRE-6	若项目有设计系统（token / theme / spacing），已确认取值方式	☐	☐	☐
PRE-7	Pipeline 模式：已读取设计文档的组件设计、接口设计、NFR 章节（DAG 路由：设计输入解析自冻结 DAG 副本 {epic-slug}/dag 节点规格 + 跨 session 边契约，见 implementation.md 使用说明第 5 条）	☐	☐	☐

2. 组件边界

#	检查项	通过	不通过	N/A	备注
PRE-8	组件职责单一——一个组件只做一件事	☐	☐	☐
PRE-9	Props 类型已列出（TypeScript 接口 / PropTypes / defineProps）	☐	☐	☐
PRE-10	所有需要的 UI 状态已识别：loading / empty / error / success / edge	☐	☐	☐

---

实现后（POST — Post-Implementation）

3. 组件结构

#	检查项	通过	不通过	N/A	备注
POST-1	组件命名清晰、遵循项目约定（PascalCase / kebab-case）	☐	☐	☐
POST-2	所有 Props 有完整类型，无 any 类型	☐	☐	☐
POST-3	组件文件结构符合项目约定（单文件 / 目录+index / co-located）	☐	☐	☐
POST-4	无巨型组件（> 200 行）——必要时已拆分为子组件	☐	☐	☐
POST-5	事件处理器和回调遵循项目命名规范（on* / handle*）	☐	☐	☐

4. 样式与设计系统

#	检查项	通过	不通过	N/A	备注
POST-6	使用项目统一的样式方案，未引入新的样式库	☐	☐	☐
POST-7	若使用 Tailwind：无冗余类名堆积，复杂样式已提取为 @apply 或组件	☐	☐	☐
POST-8	响应式断点已处理（移动端/平板/桌面），无横向溢出	☐	☐	☐
POST-9	若项目有暗色模式：组件在亮/暗主题下均可正常显示	☐	☐	☐
POST-10	使用项目设计 token（颜色/间距/字体），无硬编码魔法数值	☐	☐	☐
POST-11	动画/过渡遵循项目约定（motion / CSS transition / ...），无突兀跳动	☐	☐	☐

5. 状态覆盖

#	检查项	通过	不通过	N/A	备注
POST-12	Loading 状态：数据加载时有骨架屏/加载指示器，布局不跳动	☐	☐	☐
POST-13	Empty 状态：无数据时有友好提示和操作引导（非空白页）	☐	☐	☐
POST-14	Error 状态：请求失败时显示错误信息和重试/恢复操作	☐	☐	☐
POST-15	Edge cases：超长文本截断、特殊字符、空数组、null/undefined 值均已处理	☐	☐	☐
POST-16	数据更新后 UI 正确反映最新状态（无过期数据残留）	☐	☐	☐

6. 可访问性（a11y）

#	检查项	通过	不通过	N/A	备注
POST-17	使用语义化 HTML 元素（<button> 而非 <div onclick>）	☐	☐	☐
POST-18	图片/图标有有意义的 alt 文本（纯装饰性图片使用 alt=""）	☐	☐	☐
POST-19	表单控件有关联的 <label>（非仅 placeholder）	☐	☐	☐
POST-20	所有交互元素可通过键盘访问（Tab 导航，Enter/Space 激活）	☐	☐	☐
POST-21	弹窗/模态框：打开时焦点移入，关闭时焦点回退，ESC 可关闭	☐	☐	☐
POST-22	动态内容更新（加载完成/错误提示/列表变化）有适当的 aria-live 通知	☐	☐	☐
POST-23	色彩对比度：正文 ≥ 4.5:1，大文本 ≥ 3:1，非仅靠颜色传达信息	☐	☐	☐
POST-24	页面有逻辑的标题层级（h1 → h2 → h3），无跳级	☐	☐	☐

7. 性能

#	检查项	通过	不通过	N/A	备注
POST-25	无不必要的重渲染——列表子项 key 稳定、事件处理器引用稳定	☐	☐	☐
POST-26	大列表使用虚拟滚动或分页（非一次性渲染全部）	☐	☐	☐
POST-27	图片使用懒加载（loading="lazy"），有合适的 width/height 防止布局偏移	☐	☐	☐
POST-28	非首屏组件考虑代码分割（lazy() / defineAsyncComponent）	☐	☐	☐

8. 代码质量

#	检查项	通过	不通过	N/A	备注
POST-29	bun typecheck（或项目等效命令）通过，无类型错误	☐	☐	☐
POST-30	bun lint（或项目等效命令）通过，无错误或警告	☐	☐	☐
POST-31	无注释掉的代码块或 console.log 调试语句	☐	☐	☐
POST-32	无硬编码的 API 地址、密钥或环境特定值——使用环境变量或配置	☐	☐	☐
POST-33	没有因 UI 改动导致的不相关组件样式错乱	☐	☐	☐

9. 前端测试

#	检查项	通过	不通过	N/A	备注
POST-34	新组件有基础渲染测试（"does it render without crashing"）	☐	☐	☐
POST-35	关键交互有行为测试（点击/输入/提交触发预期回调或状态变化）	☐	☐	☐
POST-36	至少覆盖 loading / error / empty 其中一种边界状态的测试	☐	☐	☐
POST-37	若项目使用 Storybook：新组件有至少一个 story	☐	☐	☐
POST-38	bun run test:parallel（或项目等效命令）全部通过	☐	☐	☐