构建或重构产品 UI 时用 UX/UI…

当用户希望前端代码不只是能用，而是更专业、更有设计感、符合 UX 启发式与无障碍标准时，按风格层加工艺层生成或审查 UI。

适用场景

解决思路

1. 建立风格来源：若存在 `docs/design.md`，解析其 token 目录（颜色、排版、圆角、间距、组件）及 markdown 规则（高度/阴影、形状、Do's and Don'ts）；若不存在，识别代码库现有设计约定（如 Tailwind/`tokens` 主题配置、CSS custom properties、组件库）并以其作为风格来源，同时建议运行 **Design System** skill 以建立单一令牌真源。
2. 确认范围与权重：重述界面类型（signup / dashboard / chat / settings / detail / marketing），并确定主导启发式类别；如 signup 偏 Forms+States+Accessibility+Microcopy，数据 dashboard 偏 Hierarchy+IA+Cognitive Load，AI chat 偏 AI-product 子集。
3. 生成或审查时双层执行：每个视觉决策使用风格来源（`docs/design.md` token 或代码库约定）；每个工艺决策应用 50 条启发式目录和 UX 定律；审查中按编号引用启发式、按名称引用定律，如 "H22 — disabled instead of erroring after submit"、"Hick's Law — too many options in one step"。
4. 交付前预检：每个交互元素有 default、hover/focus-visible、active、disabled、loading（异步时）状态。
5. 交付前预检：每个异步界面设计和编码四种状态：empty、loading、error、success。
6. 交付前预检：每个表单输入有程序关联的 `<label>`、正确的 `inputmode`/`type`、`autocomplete` 属性、`onBlur` 校验。
7. 交付前预检：每个动效为 150–400 ms，按方向缓动（进入 out、退出 in、屏幕上移动 in-out），只动画 `transform`/`opacity`，并遵守 `prefers-reduced-motion`。
8. 交付前预检：正文对比度 ≥ 4.5:1，UI 组件 ≥ 3:1，焦点环 ≥ 3:1 且 ≥ 2 px。
9. 交付前预检：指针目标 ≥ 24×24 CSS px（触控 ≥ 44×44）。
10. 交付前预检：布局在 320 CSS px 宽可用且无横向滚动。
11. 交付前预检：主操作是视图中唯一视觉占主导的元素。
12. 交付前预检：每个视觉决策引用 `docs/design.md` token（无设计系统时引用代码库约定）；缺失 token 标记为 New Pattern，不内联发明。
13. 交付时说明主导的启发式类别与 UX 定律，并暴露有意跳过某启发式或定律的权衡。
14. H1. 每个视图只设一个主操作（Von Restorff）：主 CTA 是唯一视觉独特元素，用最突出的 design token 颜色和最大按钮尺寸；次级操作使用更安静 token。
15. H2. 用尺寸+字重+颜色建立层级，不只靠尺寸：先降低字重或切换次级文本颜色 token，再考虑减小字号。
16. H3. 邻近分组、留白分隔：相关字段用小 `gap` 堆叠，不相关组用更大 spacing token 分隔。
17. H4. 共同区域界定分组：邻近不够时用 card、divider 或 tinted surface 包围，使用设计系统 elevation/surface token。
18. H5. 留白是工具，默认偏多：宽松 padding 显得自信；收紧必须刻意，不能作为默认。
19. H6. 吸附到 spacing scale，不要偏离 1px：每个 margin/padding/gap 都是 design token；网格对齐区分“设计过”和“草稿”。
20. H7. 优先语义 HTML 而非 divs+ARIA：用 `<main>`、`<nav>`、`<header>`、`<section>`、`<article>`、`<button>`、`<label>`；仅当没有原生元素匹配时才用 `role=`。
21. H8. 阅读行长 50–75ch：用 `max-width: 65ch`（或类似值）限制正文容器。
22. H9. 在 320 CSS px 重排：每个视图在 320 px 宽无横向滚动。
23. H10. 容忍文本间距：布局需承受用户覆盖 line-height ≥ 1.5×、letter-spacing ≥ 0.12em、word-spacing ≥ 0.16em。
24. H11. 只使用文档化的类型层级：每个 `font-size`/`font-weight` 引用 typography token。
25. H12. 数据中使用表格数字：`font-variant-numeric: tabular-nums`，使表格/仪表盘/账本数字垂直对齐。
26. H13. 使用现代 text-wrap：标题用 `text-wrap: balance`，正文用 `text-wrap: pretty` 避免孤行。
27. H14. 正文对比度 ≥ 4.5:1（WCAG 1.4.3 AA）：验证每个正文/背景 token 对；大文本（≥18.66 px bold 或 ≥24 px）需 ≥3:1。
28. H15. UI 组件对比度 ≥3:1（WCAG 1.4.11）：表单边框、纯图标按钮、焦点环、图表描边等对相邻颜色需 ≥3:1。
29. H16. 颜色永不作为唯一信号：每个颜色编码状态搭配图标、标签或图案。
30. H17. 100 ms 内反馈（Doherty/Norman）：每个触发逻辑的操作在 100 ms 内视觉确认（按压状态、ripple、乐观更新、skeleton）。
31. H18. 交互元素至少三态：default、hover 或 focus-visible、active、disabled；异步时 loading 为第五态。
32. H19. 可供性信号交互性：按钮看起来可按；链接与正文明显不同；视觉处理使用 design token。
33. H20. 可发现性优先于隐藏交互（Norman）：关键操作默认可见，绝不只藏在 hover、long-press 或未披露手势后。
34. H21. 易于撤销（Shneiderman）：破坏性操作提供 Undo；每个 modal 有 Cancel；Back 不丢数据；软删除可恢复。
35. H22. 约束预防错误（Norman）：禁用无效选项；在输入上使用 `min`、`max`、`step`、`pattern`、`type`；submit 前用有效性门控。
36. H23. 表单单列布局、顶部对齐标签：垂直堆叠；标签在输入上方；绝不用 placeholder 当 label。
37. H24. 为移动键盘设置 `inputmode` + `type`：`type="email"`、`inputmode="numeric"`/`"decimal"`、`type="tel"`、`type="url"`。
38. H25. 设置 `autocomplete` 属性：`email`、`name`、`new-password`、`one-time-code`、`postal-code` 等；节省时间并尊重密码管理器。
39. H26. blur 时行内校验，change 时清除：`onBlur` 校验；一旦有效，`onChange` 清除错误；不要每次按键都校验。
40. H27. 智能默认吸收复杂度（Tesler）：检测 timezone、locale、currency；预选安全选项；解析自然语言（"tomorrow 3 pm"）；从上一次输入预填。
41. H28. 每个数据视图四种状态：empty、loading、error、success，均用 design token 设计和编码。
42. H29. 内容用 skeleton 而非 spinner（NN/g）：使用与最终布局尺寸匹配的形状占位符，防止 CLS。
43. H30. 低风险操作用乐观 UI：likes、toggles、follows 立即更新；静默 reconcile；失败时用 toast 回滚。
44. H31. 空状态是第一印象：每个空列表有一行说明应有什么 + 主 CTA。
45. H32. 错误说明 what/why/how to fix：绝不只写“Something went wrong.”；始终提供重试或恢复路径。
46. H33. UI 动效在 150–400 ms 区间（NN/g, Material 3）：micro 100–150 ms（hover、toggle）；standard 200–300 ms（menu、modal）；large 300–400 ms（page transition）；重复 UI 绝不超过 500 ms。
47. H34. 缓动匹配方向：进入用 ease-out（`cubic-bezier(0, 0, 0.2, 1)`）；退出用 ease-in；两个屏幕状态间移动用 ease-in-out。
48. H35. 只动画 `transform` 和 `opacity`：GPU 加速；绝不动画 `width`/`height`/`top`/`left`。
49. H36. 遵守 `prefers-reduced-motion`：在 `@media (prefers-reduced-motion: reduce)` 中包裹非必要动效；用即时变化或短 opacity 淡入淡出替代 transform；绝不彻底移除反馈信号。
50. H37. 一切可用键盘操作（WCAG 2.1.1）：每个交互元素可通过 Tab/Shift+Tab/Enter/Space/Arrow 到达；modal 焦点陷阱有效。
51. H38. 可见焦点环（WCAG 2.4.7）：绝不无 `:focus-visible` 等价物就 `outline: none`；≥2 px、≥3:1 对比度；若有 design system focus token 则使用。
52. H39. 指针目标 ≥24×24（WCAG 2.5.8）：每个可点击元素 ≥24×24 CSS px；触控目标争取 44×44（Apple HIG）或 48×48（Material 3）。
53. H40. 程序关联标签（WCAG 3.3.2）：每个输入有 `<label htmlFor=id>` 或包裹输入；仅在视觉上确实无标签时才用 `aria-label`。
54. H41. 焦点不被遮挡（WCAG 2.4.11）：sticky header/footer 不得覆盖聚焦元素；设置 `scroll-padding-top`/`-bottom` 等于 sticky 高度。
55. H42. 可访问认证（WCAG 3.3.8）：登录不用认知谜题；允许在 password 字段粘贴；OTP 搭配 `autocomplete="one-time-code"`。
56. H43. 移动端主 CTA 放拇指区：主操作位于屏幕下半部；高频操作避免顶部角落。
57. H44. 尊重安全区域 inset：在 fixed/sticky 底部栏和全出血 header 使用 `env(safe-area-inset-*)`。
58. H45. 无 hover-only 关键信息：只在 `:hover` 显示的 tooltip 在触控不可见；关键内容默认显示。
59. H46. 拖拽有点击替代（WCAG 2.5.7）：每个 drag-to-sort/delete/resize 有按钮或菜单等价操作。
60. H47. 导航 ≤5–9 项（Miller）：顶层导航保持在 magic number 内；其余放进 menu、command palette 或 settings。
61. H48. 识别优先于回忆（NN/g #6）：显示已选 filter、当前页面（active nav state）、breadcrumbs、recent items；绝不让用户记住上一屏的值。
62. H49. Stream + Stop 是主控制：AI 响应边生成边 stream；streaming 时可见 Stop 按钮处于主可供性权重，中止底层请求而非只停 UI；tool calls/thinking/searching 作为有标签步骤显示。
63. H50. AI 输出是可编辑草稿：模型响应作为草稿，用户可编辑、部分接受、重新生成或拒绝；行内引用来源并一键打开；区分错误类别（network、rate limit、content filter、model error），每类有各自恢复路径。
64. Law of Proximity：把相关字段和控件用小 `gap` 堆叠，不相关组用更大 spacing token 分隔。↔ H3
65. Law of Common Region：邻近不够时，用 card、divider 或 tinted surface 包围相关项，使用 elevation/surface token。↔ H4
66. Law of Similarity：相同功能元素给相同处理（所有主操作同一 button token，所有链接同一风格）；真正不同的东西看起来要不同。↔ H16, H19
67. Law of Uniform Connectedness：用共享容器、背景或连接线连接相关控件（segmented control、带标签字段组），不要只靠邻近。
68. Law of Prägnanz：偏向简单规则形状和干净布局；减少视觉复杂度，让底层结构一眼可见。
69. Aesthetic-Usability Effect：投资视觉工艺（间距、字体、打磨按启发式），但绝不让表面打磨掩盖测试发现的真实可用性问题。
70. Hick's Law：减少每步选项，使用 progressive disclosure，预选安全默认值，把长流程拆成步骤。↔ H47
71. Choice Overload：策展并排序选项，提供 recommended default，过滤或折叠长尾，而不是一次显示全部。
72. Miller's Law：把内容和导航分块成小分组；顶层导航保持在 magic number 内，其余放进 menu 或 command palette。↔ H47
73. Chunking：格式化长字符串（电话号码、卡号、ID），把表单字段、导航、内容分组为可消化集合。↔ H3
74. Cognitive Load：削减额外认知负荷，把记忆卸载给界面（显示，不让用户回忆），移除装饰噪音，每屏只保留一个主任务。
75. Working Memory：替用户携带上下文，显示已选 filter、先前输入和当前步骤，绝不要求跨屏重新输入或记忆。↔ H48
76. Selective Attention：把关键信息和操作放在目标路径中，不要藏在广告式区域或易被关闭的 chrome 里。
77. Occam's Razor：等价方案中选元素最少者；移除任何不挣得位置的元素、选项或步骤。
78. Tesler's Law：把系统固有复杂度推给系统而非用户，使用 smart defaults、推理和合理自动化，而不是额外字段和选择。↔ H27
79. Cognitive Bias：诚实围绕用户偏见设计以帮助决策，绝不用 dark patterns、forced continuity 或误导性框架。
80. Pareto Principle：识别 20% 高频路径并让其快速明显；不要让低频功能挤占常用功能。
81. Von Restorff Effect：让唯一主操作视觉独特；克制使用强调，以保持其含义。↔ H1
82. Serial Position Effect：把最重要导航项和操作放在列表、菜单或栏的开头和结尾，最不重要的放中间。
83. Zeigarnik Effect：用 progress indicators、checklists 和“X of Y complete”提示推动完成 onboarding、setup 和多步流程。
84. Goal-Gradient Effect：显示进度并让剩余步骤感觉小——用 progress bars、step counters、预填第一步让势头从零以上开始。
85. Peak-End Rule：投资峰值（magic moment）和结尾（success、first-win、sign-off 状态）；成功时刻值得真正设计，而不是裸 toast。
86. Jakob's Law：常见 UI（nav、forms、icons、gestures）遵循既有约定和平台模式；只在真正有回报处创新。↔ H20
87. Mental Model：匹配用户期望的标签、隐喻和流程；缩小用户模型与系统模型的差距，不要强迫学习新模型。↔ H48
88. Paradox of the Active User：让 happy path 自明，把指导放在上下文内而不是 docs 中，设计成无需说明也能成功。
89. Postel's Law：宽进严出——接受杂乱输入（trim whitespace、解析日期和电话格式、不区分大小写），输出清晰、一致、格式良好。↔ H26, H27
90. Parkinson's Law：用 autofill、smart defaults 和合理约束缩短完成时间，让用户更快完成。↔ H27
91. Flow：保护专注，减少打断，避免任务中无谓 modal 和确认，保留状态，保持完成路径不中断。
92. Doherty Threshold：在 400 ms 内响应用户——用 optimistic UI、skeletons 和即时按压反馈，让用户不为界面等待。↔ H17
93. Fitts's Law：让高频和主目标更大且靠近用户当前位置；保持充足 tap targets，移动端主操作放拇指区。↔ H39, H43
94. 处理 New Patterns：当启发式需要 `docs/design.md` 未定义的视觉属性（新颜色角色、缺失 spacing step、未记录组件变体）时，绝不内联发明值。
95. 若 `docs/design.md` 存在：在交付说明中标记为 **New Pattern**（什么属性、启发式暗示什么值、哪里需要），并建议通过 **Design System** skill 加入 `docs/design.md`；同时使用最接近的现有 token。
96. 若 `docs/design.md` 不存在：遵循代码库现有约定（theme config、CSS custom property、component library）为该属性处理，记录这样做了，并建议运行 **Design System** skill 以获得有文档的真源。
97. 完成标准：生成或审查 UI 时让 workflow step 4 的预检清单全部通过；每个视觉决策引用 `docs/design.md` token（无设计系统时引用代码库约定）；主操作是唯一视觉主导元素（H1）；microcopy 用平实语言；错误说明 what/why/how-to-fix（H32）；投资成功时刻（Peak-End Rule）；缺失 token 标记为 New Pattern 而非内联发明。
98. 建议搭配 **Build Loop**：其 review step（`/review`，敏感 surface 用 `/security-review`）捕获 token drift 和无障碍回归；commit 前把任何 New Patterns 通过 **Design System** skill 反馈回 `docs/design.md`。

适用边界 · 注意事项

• 没有前端/UI 代码可生成或审查时，例如纯后端、数据管道、CLI 或无界面逻辑任务。
• 用户明确只想要最低限度功能验证，且不关心设计质量、UX 启发式或无障碍时。
• 受限于遗留平台或第三方组件，无法控制语义 HTML、CSS、动效或焦点行为时，只能选择性应用可落地的规则。