构建生产级可访问响应式前端 UI 时，用组件化、设计系统与…

在开发或修改用户界面、组件、布局、交互与状态时，按设计系统、WCAG 2.1 AA 和响应式标准交付，避免通用 AI 美感。

适用场景

解决思路

1. 构建或修改用户界面、页面、组件、布局、交互、状态或修复视觉/UX 问题时，按生产级标准交付，而不是 AI 生成感。
2. 组件文件结构：把组件相关内容 colocate 到 `src/components/TaskList/`，包含 `TaskList.tsx`、`TaskList.test.tsx`、`TaskList.stories.tsx`（如使用 Storybook）、`use-task-list.ts`（复杂状态时）、`types.ts`（需要时）。
3. 优先组合而非配置：使用 `<Card><CardHeader><CardTitle>Tasks</CardTitle></CardHeader><CardBody><TaskList tasks={tasks} /></CardBody></Card>` 这类可组合子组件，避免 `<Card title=... headerVariant=... bodyPadding=... content=... />` 式过度配置。
4. 保持组件聚焦：像 `TaskItem({ task, onToggle, onDelete })` 只做一件事，渲染 `li`、`Checkbox`、完成态文本和删除 `Button`。
5. 分离数据获取与展示：容器组件用 `useTasks()` 处理 `isLoading`、`error`、空数据，分别返回 `TaskListSkeleton`、`ErrorState`、`EmptyState`、`TaskList`；展示组件 `TaskList({ tasks })` 只负责渲染列表。
6. 选择能工作的最简单状态方案：`useState` 用于组件局部 UI 状态；提升状态用于 2-3 个兄弟组件共享；Context 用于主题、认证、语言等读多写少场景；URL state（`searchParams`）用于筛选、分页、可分享 UI 状态；Server state（React Query、SWR）用于带缓存的远程数据；全局 store（Zustand、Redux）用于跨应用共享的复杂客户端状态。
7. 避免 prop drilling 超过 3 层；如果 props 穿过不使用它们的组件，引入 context 或重构组件树。
8. 当产品需要独特视觉方向时，先收集证据再选布局。
9. 搜索可信参考目录，或使用产品团队提供的参考。
10. 研究 2-3 个相关屏幕，记录关于层级、密度、导航、控件、响应式行为、交互状态的决策。
11. 实施前把决策转成简短设计契约：写明页面职责、主操作、必需状态、响应式规则、要拒绝的模式。
12. 用产品自己的组件、tokens、内容、视觉语言重建有用结构；绝不复制其他产品品牌、专有文本、图片或精确布局。
13. 把参考当证据而非模板；参考不可用时记录假设，并用产品现有设计系统验证结果。
14. 避免 AI 默认紫色/靛蓝：使用项目实际调色板。
15. 避免过度渐变：使用扁平或与设计系统匹配的细微渐变。
16. 避免全部大圆角（如 `rounded-2xl`）：使用设计系统中一致的 `border-radius`。
17. 避免通用 hero 区块：使用内容优先布局。
18. 避免 Lorem ipsum 式占位文案：使用真实感占位内容，以暴露长度、换行、溢出问题。
19. 避免到处过大 padding：使用一致间距尺度，保留视觉层级和屏幕空间。
20. 避免 stock card grids：按信息优先级和扫描模式设计目的驱动布局。
21. 避免重阴影：除非设计系统指定，使用轻微或无阴影，减少渲染负担。
22. 使用一致间距尺度，不发明值：按项目尺度（如 0.25rem 增量），使用 `padding: 1rem`、`gap: 0.75rem`；避免 `padding: 13px`、`margin-top: 2.3rem`。
23. 尊重字体层级：`h1` 页面标题（每页一个），`h2` 区块标题，`h3` 子区块标题，body 默认文本，small 次要/辅助文本。
24. 不要跳过标题层级；不要对非标题内容使用标题样式。
25. 使用语义颜色 token：`text-primary`、`bg-surface`、`border-default`，不用原始 hex 值。
26. 确保对比度：普通文本 4.5:1，大文本 3:1。
27. 不要仅靠颜色传达信息；同时使用图标、文本或图案。
28. 每个组件满足 WCAG 2.1 AA。
29. 键盘导航：每个交互元素必须键盘可访问；优先 `<button>`，因为默认可聚焦；避免 `<div onClick>`；若必须用 `<div role='button' tabIndex={0} onClick={...} onKeyDown={...} onKeyUp={...}>`，处理 Enter 和 Space。
30. ARIA labels：给缺少可见文本的交互元素加 `aria-label`，如 `<button aria-label='Close dialog'><XIcon /></button>`。
31. 表单输入用 `<label htmlFor='email'>Email</label>` 和 `<input id='email' type='email' />`，或无可见标签时用 `aria-label`，如 `<input aria-label='Search tasks' type='search' />`。
32. 焦点管理：内容变化时移动焦点；`Dialog` 打开时调用 `closeRef.current?.focus()`。
33. 对话框打开时把焦点困在 dialog 内。
34. 有意义的空状态和错误状态：不要显示空白屏；无任务时返回 `role='status'` 区域，包含空状态图标、`<h3>No tasks</h3>`、说明文本和 `Create Task` 按钮。
35. 响应式设计 mobile first，再扩展；Tailwind 示例：`grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4`。
36. 在 320px、768px、1024px、1440px 断点测试。
37. 内容加载使用 skeleton，不用 spinner；`TaskListSkeleton` 带 `aria-busy='true'`、`aria-label='Loading tasks'` 和 `animate-pulse` 占位块。
38. 用 optimistic updates 提升感知速度；`useToggleTask` 中 mutation 的 `onMutate` 取消 `queries`、保存 previous、用 `setQueryData` 立即更新，`onError` 时回滚。
39. 查看 `../../references/accessibility-checklist.md` 获取详细无障碍要求和测试工具。
40. 拒绝合理化：可访问性不是可有可无，它是许多地区的法律要求，也是工程质量标准。
41. 拒绝合理化：不要“以后再做响应式”，从开始就做，返工成本约为 3 倍。
42. 拒绝合理化：不要因设计未定就跳过样式；使用设计系统默认值，避免给评审者破碎第一印象。
43. 拒绝合理化：不要认为“只是原型”；原型会变成生产代码，基础要打对。
44. 拒绝合理化：不要认为 AI aesthetic 暂时可以；它传递低质量信号，从开始就使用项目实际设计系统。
45. 监控红牌：组件超过 200 行就拆分。
46. 监控红牌：避免 inline styles 或任意像素值。
47. 监控红牌：不要缺少 error、loading、empty 状态。
48. 监控红牌：不要不做键盘导航测试。
49. 监控红牌：不要仅用颜色作为状态指示（红/绿没有文本或图标）。
50. 监控红牌：避免通用 AI 外观（紫色渐变、超大卡片、stock 布局）。
51. 构建 UI 后验证：组件渲染无 console errors。
52. 验证：用 Tab 遍历页面，所有交互元素键盘可访问。
53. 验证：屏幕阅读器能传达页面内容和结构。
54. 验证：响应式在 320px、768px、1024px、1440px 可用。
55. 验证：适用时处理 loading、empty、error、success、permission 状态。
56. 验证：遵循项目设计系统（spacing、colors、typography）。
57. 验证：渲染结果通过最终 UI-specific finish-gate review。
58. 验证：dev tools 或 axe-core 无 accessibility warnings。

适用边界 · 注意事项

• 纯后端、CLI、无用户界面或无需考虑 WCAG 的任务不适用。
• 产品已有完整且权威的设计系统与设计交付时，不需要外部参考驱动的视觉方向探索。
• 完全无法访问可信参考且团队未提供参考时，不要强行模仿参考；应记录假设并依据现有设计系统验证。