React 组件开发蓝图

目标

把"从零写一个 React 组件"变成可审查、可验收的固定流程：接口先于实现，检查先于交付。

工作流

Phase 1：需求边界

• 明确组件的功能边界、交互逻辑与数据流
• 确定该组件是纯展示、受控还是内部自治
• 写下一句话的组件契约（做什么、不做什么）

Phase 2：接口设计（先于实现）

• 完整 TypeScript Props 类型定义；对外部传入的复杂对象定义独立 interface
• 状态策略选型并说明理由：useState / useReducer / Context / 外部 store
• 副作用与生命周期：何时发请求、何时清理
• 对外回调命名遵循 onXxx 约定，事件对象与语义值分开

Phase 3：实现编码

• 函数组件 + Hooks，Tailwind 样式使用语义 token（禁止硬编码色值）
• 关键逻辑附一行注释说明设计意图
• 一次输出完整可运行代码

Phase 4：自审查（交付前必做）

逐项检查：

• 类型安全：无 any，无 class 组件
• a11y：可点击元素有键盘可达性、图标有 aria-label、表单有 label
• 性能：渲染路径无隐式大对象重建；必要时 useMemo/useCallback 并说明依据
• 边界：空数据、超长文本、加载中、错误态
• 样式规范：无硬编码色值、无任意圆角/阴影值、明暗主题均可用

Phase 5：交付

• 附最小使用示例
• 说明扩展方向与注意事项
• 组件文件落盘后调用 declare_artifact 声明

输出规范

• 先给组件契约与 Props 设计，再给实现
• 状态策略选择必须说明理由（为什么不选更简单的方案）
• 自审查结论逐项列出（通过 / 不通过 + 修复点）