design-better

打造更出色的设计

为任何生成或审查 UI 的编码 Agent 提供工艺层。样式由 docs/design.md 负责；本技能则负责经久不变的 UX/UI 工艺启发式——借鉴 Nielsen Norman Group、Laws of UX、Shneiderman、Refactoring UI、WCAG 2.2、Don Norman、Apple HIG、Material 3 以及 2025–2026 年 AI 产品模式——这些启发式能让产品从“已交付”迈向“精心设计”。

边界。 当某项启发式涉及视觉属性时，按名称引用 docs/design.md 中的设计令牌（{colors.primary}、{rounded.md}）。如果 docs/design.md 中没有相应令牌，请将其标记为要通过 Design System 技能添加的新模式——绝不要直接写入十六进制颜色、字体名称或任意 px 值。如果 docs/design.md 根本不存在，请遵循代码库中该属性的现有惯例（主题配置、CSS 自定义属性、组件库），并注明这一点。

输入

• docs/design.md——样式层（建议提供，但非必需）。如果存在，每项视觉决策都应按名称引用其中的设计令牌。如果不存在，本技能仍然适用：沿用代码库现有的设计惯例（主题配置、CSS 自定义属性、现有组件）作为样式来源，并建议运行 Design System 技能，以建立单一的设计令牌事实来源（属于 BuilderOS：https://github.com/BuildGreatProducts/builder-os）。
• 正在构建或重构的内容——概要、文件或未提交的差异。
• docs/product-vision.md——可选。其战略和品牌理念会影响微文案的语气，并有助于判断哪些启发式类别更为重要。

工作流

1. 确定样式来源。 如果 docs/design.md 存在，请解析其中的设计令牌目录（颜色、字体排印、圆角、间距、组件）和 Markdown 规则（层级、形状、注意事项与禁忌）。如果不存在，请找出代码库现有的设计惯例——主题配置（例如 Tailwind/tokens）、CSS 自定义属性、所用的组件库——并将其作为样式来源，然后建议使用 Design System 技能，为后续工作建立有文档记录的事实来源。

2. 确认范围和侧重点。 重述界面类型（注册 / 仪表盘 / 聊天 / 设置 / 详情 / 营销），以及占主导地位的启发式类别——注册页面侧重表单 + 状态 + 无障碍 + 微文案；数据仪表盘侧重层级 + 信息架构 + 认知负荷；AI 聊天则侧重 AI 产品相关子集。

3. 结合两层内容进行生成或审查。 每项视觉决策都依据样式来源（docs/design.md 中的设计令牌，或代码库惯例）；每项工艺决策都依据启发式目录和 Laws of UX。在审查中通过编号引用启发式，通过名称引用法则（“H22——提交后禁用，而不是报错”；“Hick's Law——一个步骤中的选项过多”）。

4. 交付前检查清单：

   • 每个交互元素都有默认、悬停 / 键盘焦点可见、激活、禁用和加载（适用于异步操作）状态。
   • 每个异步界面都设计并实现全部四种状态：空、加载、错误、成功。
   • 每个表单输入项都有通过程序关联的 <label>、正确的 inputmode/type、autocomplete 属性，以及 onBlur 校验。
   • 每种动效时长为 150–400 ms，按方向选择缓动（进入时 ease-out / 退出时 ease-in / 移动时 ease-in-out），且只对 transform/opacity 添加动画，并遵循 prefers-reduced-motion 设置。
   • 正文文本对比度 ≥ 4.5:1，UI 组件 ≥ 3:1，焦点环 ≥ 3:1 且宽度 ≥ 2 px。
   • 指针目标尺寸 ≥ 24×24 CSS px（触摸目标 ≥ 44×44）。
   • 布局在宽度为 320 CSS px 的视口中正常显示，且不出现水平滚动。
   • 每个视图中，主要操作是视觉上唯一突出的元素。
   • 每项视觉决策都引用 docs/design.md 中的设计令牌（如果没有设计系统，则引用代码库惯例）。缺失的设计令牌应标记为新模式，而不是凭空内联定义。

5. 交付。 说明哪些启发式类别和 Laws of UX 占主导地位，并指出任何明知而未遵循启发式或法则的权衡。

启发式原则目录（50 项）

每项包括：编号（评审时引用）+ 简短名称 + 一行规则 + 代码操作。全程保持风格中立——所有视觉属性均遵循 docs/design.md（若不存在，则遵循代码库的设计规范）。

视觉层级与强调

H1. 每个视图仅有一个主要操作（冯·雷斯托夫效应）。 将主要 CTA 设为视觉上唯一突出的元素——使用最醒目的设计令牌颜色和最大尺寸的按钮。次要操作使用更低调的令牌。

H2. 通过字号 + 字重 + 颜色建立层级，而非只靠字号（Refactoring UI）。 通过降低字重或改用次要文本颜色令牌来弱化次要文本，再考虑减小字号。

H3. 相近元素归组，留白用于分隔（格式塔）。 将相关字段以较小的 gap 堆叠排列；用更大的间距令牌分隔不相关的组。

H4. 用共同区域划分组别（格式塔）。 仅靠相近排列不足以区分时，使用卡片、分隔线或着色表面划分区域——遵循设计系统的层级／表面令牌。

H5. 留白是一种工具——默认留得多一些（Refactoring UI）。 宽裕的内边距能体现自信。收紧间距应是经过考虑的决定，而非默认做法。

H6. 严格遵循间距比例；不允许偏差一个像素（精修）。 所有外边距、内边距和间隙都必须使用设计令牌。对齐网格，才是“设计完成”与“草稿”的区别。

布局与对齐

H7. 优先使用语义化 HTML，而非 div + ARIA（WCAG 1.3.1）。 使用 <main>、<nav>、<header>、<section>、<article>、<button>、<label>。仅在没有合适的原生元素时才使用 role=。

H8. 阅读行长为 50–75ch。 用 max-width: 65ch（或类似设置）限制正文容器宽度。

H9. 在 320 CSS px 宽度下重新排版（WCAG 1.4.10）。 每个视图在 320 px 宽时都能正常显示，且无需横向滚动。

H10. 文本间距容错（WCAG 1.4.12）。 即使用户覆盖行高（≥ 1.5×）、字间距（≥ 0.12em）、词间距（≥ 0.16em），布局仍应正常。

字体排印

H11. 仅使用有文档说明的字体层级。 每个 font-size／font-weight 都必须引用排版令牌。

H12. 数据使用等宽数字（font-variant-numeric: tabular-nums）。 表格、仪表板和账本中的数字应垂直对齐。

H13. 使用现代文本换行方式（标题用 balance，正文用 pretty）。 标题使用 text-wrap: balance，呈现更均衡的排版；正文段落使用 text-wrap: pretty，避免出现孤行。

颜色与对比度（非风格性）

H14. 正文文本对比度 ≥ 4.5:1（WCAG 1.4.3 AA）。 验证每组正文／背景令牌的搭配。大号文本（粗体 ≥ 18.66 px 或 ≥ 24 px）需要 ≥ 3:1。

H15. UI 组件对比度 ≥ 3:1（WCAG 1.4.11）。 表单边框、仅含图标的按钮、焦点环和图表描边与相邻颜色的对比度都必须 ≥ 3:1。

H16. 绝不只用颜色传达信息。 每种用颜色编码的状态都应搭配图标、标签或图案。

交互与反馈

H17. 在 100 ms 内提供反馈（多尔蒂／诺曼）。 每项会触发逻辑的操作都应在 100 ms 内获得视觉确认（按下状态、涟漪效果、乐观更新、骨架屏）。

H18. 交互元素至少具备三种状态。 默认、悬停或可见焦点、激活、禁用。异步操作还需加载状态。

H19. 用视觉暗示表明可交互性。 按钮应看起来可以按下；链接应与正文文本有明显区别——使用设计令牌控制视觉样式。

H20. 优先保证可发现性，避免隐藏交互（诺曼）。 关键操作默认应可见——绝不可隐藏在悬停、长按或未明示的手势之后。

H21. 易于撤销（施奈德曼）。 破坏性操作提供撤销；每个模态框都提供取消；返回时不丢失数据；软删除后应可恢复。

H22. 通过限制预防错误（诺曼）。 禁用无效选项；为输入项使用 min、max、step、pattern、type；仅在输入有效时允许提交。

表单

H23. 单列布局，标签置顶。 纵向排列；标签位于输入框上方；绝不以占位符代替标签。

H24. 使用 inputmode + type 调用移动端键盘。 type="email"、inputmode="numeric"/"decimal"、type="tel"、type="url"。

H25. 设置 autocomplete 属性。 email、name、new-password、one-time-code、postal-code 等。为用户节省 30 秒，并兼容密码管理器。

H26. 失焦时进行行内验证，输入时清除错误。 在 onBlur 时验证；在 onChange 时，一旦输入有效就清除错误。每敲一个字符就验证会惩罚输入错误。

H27. 用智能默认值化解复杂性（Tesler）。 检测时区、地区设置和货币；预选安全选项；解析自然语言（“明天下午 3 点”）；根据之前的输入预填内容。

状态：空、加载中、错误、成功

H28. 每个数据视图都要涵盖四种状态。 空、加载中、错误、成功——每种状态都要使用设计令牌进行设计和编码。

H29. 内容优先使用骨架屏，而非加载动画（NN/g）。 使用与最终布局尺寸相符的占位形状（防止 CLS）。

H30. 对低风险操作使用乐观 UI。 点赞、切换开关、关注等操作应立即更新；静默协调状态；失败时通过提示消息回滚。

H31. 空状态是第一印象。 每个空列表都应有一行说明这里应该显示什么，以及一个主要 CTA。

H32. 错误信息应说明是什么、为什么，以及如何修复。 绝不要只说“出了点问题”。始终提供重试或恢复途径。

动效

H33. UI 动效时长控制在 150–400 ms（NN/g、Material 3）。 微动效为 100–150 ms（悬停、切换）；标准动效为 200–300 ms（菜单、模态框）；大型动效为 300–400 ms（页面过渡）。重复出现的 UI 动效绝不超过 500 ms。

H34. 缓动曲线应与运动方向匹配。 进入时使用缓出（cubic-bezier(0, 0, 0.2, 1)）；退出时使用缓入；两个屏幕内状态之间移动时使用缓入缓出。

H35. 只为 transform 和 opacity 添加动效。 由 GPU 加速。绝不要为 width/height/top/left 添加动效。

H36. 遵循 prefers-reduced-motion 设置。 将非必要动效放在 @media (prefers-reduced-motion: reduce) 中。将变换替换为即时变化或短暂的透明度渐变——绝不要完全移除反馈信号。

无障碍（WCAG 2.2 AA）

H37. 所有功能均可通过键盘操作（WCAG 2.1.1）。 每个交互元素都可通过 Tab / Shift+Tab / Enter / Space / Arrow 访问。模态框中的焦点陷阱应正常工作。

H38. 显示可见的焦点环（WCAG 2.4.7）。 绝不要使用 outline: none，却不提供等效的 :focus-visible 样式——至少 2 px，且对比度至少为 3:1。如果已定义设计系统焦点令牌，请使用它。

H39. 指针目标尺寸至少为 24×24（WCAG 2.5.8）。 每个可点击元素至少为 24×24 CSS px。在触屏设备上，目标尺寸应为 44×44（Apple HIG）或 48×48（Material 3）。

H40. 以编程方式关联标签（WCAG 3.3.2）。 每个输入框都应有 <label htmlFor=id>，或由 <label> 包裹。仅当输入框在视觉上确实没有标签时，才使用 aria-label。

H41. 焦点不可被遮挡（WCAG 2.4.11）。 粘性页眉/页脚不得遮住当前焦点元素。将 scroll-padding-top/-bottom 设置为与粘性元素高度相等的值。

H42. 提供无障碍身份验证（WCAG 3.3.8）。 登录时不得使用认知谜题。允许在密码框中粘贴内容。使用一次性密码时，配合 autocomplete="one-time-code"。

移动端与触屏

H43. 将主要 CTA 放在拇指可及区域。 在移动端，主要操作应位于屏幕下半部分。高频操作应避免放在顶部角落。

H44. 尊重安全区域内边距。 在固定/粘性底栏和全宽页眉上使用 env(safe-area-inset-*)。

H45. 关键内容不得仅在悬停时显示。 仅在 :hover 时显示的工具提示在触屏设备上不可见。应默认显示关键内容。

H46. 拖动操作应提供点击替代方式（WCAG 2.5.7）。 每个用于排序/删除/调整大小的拖动操作都应提供等效按钮或菜单。

认知负荷与导航

H47. 导航不超过 5–9 个条目（米勒定律）。 顶层导航应控制在这个神奇数字范围内；其余内容放入菜单、命令面板或设置中。

H48. 识别胜于回忆（NN/g #6）。 显示已选筛选条件、当前页面（活动导航状态）、面包屑和最近访问项。绝不要让用户记住上一屏中的某个值。

AI 产品特定原则（2025–2026）

H49. 流式生成 + 停止是主要控件。 AI 响应应在生成时流式显示；流式生成期间，显眼的“停止”按钮应具有主要操作的视觉权重，并中止底层请求，而不只是停止 UI 显示。工具调用、思考和搜索应以带标签的步骤呈现。

H50. AI 输出是可编辑的草稿。 应将模型响应视为草稿，用户可以编辑、部分接受、重新生成或拒绝。来源应以内联形式标注，并支持一键打开。区分不同错误类别（网络、速率限制、内容过滤、模型错误），让每种错误都有对应的恢复方式。

UX 定律

以上 50 条启发式规则是可执行的检查清单；下面的 UX 定律则是这些规则背后的心理学原理，摘自 lawsofux.com。请在相关场景中运用，尤其是没有对应启发式规则的定律。在评审中按名称引用（“希克定律——单个步骤中的选项过多”）。如果某条启发式规则已将某项定律转化为具体做法，↔ H# 交叉引用会指向相应规则；请将两者视为同一规则的两个视角：定律解释原因，启发式规则提供检查项。

感知与分组——用户如何通过视觉解析布局

邻近定律。 彼此靠近的对象会被视为一组。将相关字段和控件紧密排列，使用较小的 gap；使用较大的间距令不相关的组彼此分开。↔ H3

共同区域定律。 位于同一清晰边界区域内的元素会被视为一组。若仅靠邻近不足以实现分组，可使用卡片、分隔线或着色表面将相关项框在一起，并采用层级／表面令牌。↔ H4

相似性定律。 具有相同视觉特征的元素会被视为相关。为功能相同的元素采用一致的样式（所有主要操作使用同一种按钮令牌，所有链接使用同一种样式），并让真正不同的元素看起来有所区别。↔ H16，H19

统一连接性定律。 视觉上相连的元素比仅仅相邻的元素更容易被视为相关。应通过共享容器、背景或连接线（如分段控件、带标签的字段组）连接相关控件，而不是只依赖邻近关系。

简洁性定律。 人们会将模糊或复杂的形式理解为尽可能简单的形态。优先采用简单、规整的形状和整洁的布局；降低视觉复杂度，让底层结构一目了然。

美观—易用性效应。 用户会认为美观的设计更易用，也更能容忍小问题。应在视觉细节上投入精力（根据启发式规则调整间距、字体和润色），但绝不能让表面上的精致掩盖测试发现的实际易用性问题。

选择与认知负荷 — 降低决策和行动所需的精力

Hick 定律。 决策时间会随着选择的数量和复杂度增加。减少每一步的选项，渐进式展示信息，预先选择安全的默认项，并将较长的流程拆分为多个步骤。↔ H47

选择过载。 选项太多会让用户不知所措，难以继续。精心筛选并排列选项，提供推荐的默认项，并过滤或折叠不常用的选项，而不是一次展示所有内容。

Miller 定律。 工作记忆能容纳约 7±2 个项目。将内容和导航分成小组；顶层导航项控制在这个数量范围内，其余内容放入菜单或命令面板。↔ H47

分块。 将信息分成有意义的单元后，更容易处理。将较长的字符串（电话号码、卡号、ID）格式化，并将表单字段、导航和内容分成易于理解的小组。↔ H3

认知负荷。 每增加一个元素、标签或步骤，都会消耗用户的心智资源。减少无关负荷——让界面替用户承担记忆任务（直接展示，而不是让用户回忆），去除装饰性干扰，并确保每个屏幕只有一个主要任务。

工作记忆。 用户无法可靠地记住上一屏中的值。为用户保留上下文——展示已选筛选条件、先前输入和当前步骤；切勿要求用户在不同屏幕间重新输入信息或凭记忆操作。↔ H48

选择性注意。 用户会关注与目标相关的屏幕部分，并忽略其他内容（横幅盲视）。将关键信息和操作放在用户的目标路径上；不要将它们藏在类似广告的区域或容易被关闭的界面装饰中。

奥卡姆剃刀。 在效果相同的方案中，元素最少的方案更胜一筹。移除任何不必要的元素、选项或步骤；最好的界面应尽可能简单，同时仍能完成任务。

Tesler 定律（复杂性守恒定律）。 每个系统都有无法消除的复杂性——唯一的问题是由谁承担。让系统而非用户承担复杂性：优先使用智能默认项、推断和合理的自动化，而不是增加字段和选项。↔ H27

认知偏差。 用户的判断会受到系统性偏差（锚定、框架效应、默认选项）的影响。诚实地围绕这些偏差进行设计，帮助用户做出明智的决定，而不是操纵用户。不得使用暗黑模式、强制延续或误导性框架。

帕累托原则。 约 80% 的使用来自 20% 的功能。找出高频使用路径，让它们快速、直观；不要让罕用功能挤占常用功能的位置。

记忆与注意力 — 用户记住什么，以及什么会吸引他们

Von Restorff 效应（孤立效应）。 在相似的项目中，与众不同的那个更容易被记住。让唯一的主要操作在视觉上突出；谨慎使用强调样式，确保它保持原有的意义。↔ H1

系列位置效应。 人们最容易记住一系列项目中的第一个和最后一个。将最重要的导航项和操作放在列表、菜单或栏的开头和末尾；将最不重要的项目放在中间。

蔡加尼克效应。 未完成的任务更容易被记住，并会促使人们完成它。通过进度指示器、清单和“已完成 X 项，共 Y 项”等提示，推动用户完成引导、设置和多步骤流程。

目标梯度效应。 越接近目标，动机越强。展示进度，让剩余步骤显得不多——使用进度条、步骤计数器，并预填第一步，让用户一开始就能获得进展感。

峰终定律。 人们会根据体验中最强烈的时刻和结尾来评价体验。用心设计高峰时刻（令人惊喜的时刻）和结尾（成功、首次获胜、签收等状态）——成功时刻值得认真设计，而不是只用一个简单的提示消息。

期望与行为 — 匹配用户的实际行为

雅各布定律。 用户大部分时间都在使用其他产品，因此会期望你的产品以相同方式运行。遵循常见 UI（导航、表单、图标、手势）中既定的惯例和平台模式；只有在确实有益时才采用新颖设计。↔ H20

心智模型。 用户会根据自己认为系统是什么、如何运作来采取行动。匹配他们预期的模型——使用熟悉的标签、隐喻和流程——并缩小他们的模型与你的模型之间的差距，而不是迫使他们学习新的模型。↔ H48

活跃用户悖论。 用户会跳过手册并立即开始操作，即使阅读手册能更快完成任务。让理想路径一目了然，将指导直接融入界面并置于相应情境中（而不是放在文档里），并确保用户无需说明也能顺利完成任务。

波斯特尔定律。 接受输入时尽量宽容，输出时保持谨慎。接受杂乱、多样的输入（去除空格、解析不同的日期和电话号码格式、不区分大小写），并给出清晰、一致、格式规范的输出。↔ H26、H27

帕金森定律。 任务会膨胀到填满可用时间。通过自动填充、智能默认值和合理约束缩短完成时间，让用户比原本更快完成任务。↔ H27

心流。 用户全身心投入任务时表现最佳。保护专注力——尽量减少打断，避免在任务进行中无故弹出模态框或要求确认，保留状态，并确保完成任务的路径畅通无阻。

性能与响应速度 — 尊重用户的时间

多尔蒂阈值。 当系统和用户在 400 ms 内彼此响应时，生产力会大幅提升。快速确认操作——使用乐观 UI、骨架屏和即时按压反馈——让用户不必等待界面响应。↔ H17

菲茨定律。 命中目标所需的时间取决于目标的距离和大小。让常用和主要目标足够大，并放在用户当前所在位置附近；触控目标要留足空间，并将移动设备上的主要操作放在拇指易于触及的区域。↔ H39、H43

处理新模式

当某项启发式原则需要 docs/design.md 尚未定义的视觉属性（新的颜色角色、缺失的间距级别、未记录的组件变体）时，绝不要直接在代码中自行编造取值。 应改为：

• 如果存在 docs/design.md — 在交付说明中将该缺口标记为新模式（注明所需属性、该启发式原则所暗示的取值，以及需要应用的位置），并建议通过 Design System 技能将其添加到 docs/design.md。该技能负责编辑设计令牌目录，并确保 docs/design.html 保持同步。在此期间，使用最接近的现有令牌。
• 如果不存在 docs/design.md — 遵循代码库中该属性的现有惯例（主题配置、CSS 自定义属性、组件库），注明你采用了该惯例，并建议运行 Design System 技能，让项目获得有文档记录的唯一可信来源。

什么样才算“完成”

生成或审查后的 UI 应满足以下要求：工作流第 4 步中的预检清单全部通过；每项视觉决策都引用 docs/design.md 中的令牌（如果没有设计系统，则引用代码库惯例）；主要操作是视觉上唯一突出的元素（H1）；微文案使用浅显易懂的语言；错误信息说明问题、原因和修复方法（H32）；重视成功时刻的设计（峰终定律）；设计系统尚未收录的任何令牌都标记为新模式，并建议通过 Design System 技能将其纳入，而不是直接自行编造。

建议搭配使用：将此技能与 Build Loop 一起运行——其审查步骤（/review，以及针对敏感界面的 /security-review）可以发现遗漏的令牌偏差和无障碍问题；提交前，使用 Design System 技能将所有标记的新模式反馈到 docs/design.md。