usability-heuristics

概述

此技能将 Nielsen 的 10 条可用性启发式原则应用于用户界面代码的审查和审计。它有两个用途：

1. 审计模式：依据全部 10 条启发式原则，系统地评估现有 UI 代码，并生成结构化问题日志，其中包含严重性评级、证据和修复建议。
2. 指导模式：构建新功能时主动应用启发式原则，防止可用性问题在发布前出现。

此技能侧重于评估方法和结构化报告。当某条启发式原则与 UX 定律重合时，此技能会交叉引用相关定律，而不重复提供指导。将两种技能结合使用，可获得全面的覆盖：

• usability-heuristics（此技能）= 审计方法 + 结构化问题日志
• laws-of-ux = 理论基础 + 详细的 UX 原则

审查代码时，先查看审计清单，确定最相关的启发式原则，然后参考详细章节获取指导和示例。始终按照下方的问题日志格式记录发现。

关键词：启发式评估、可用性审计、Nielsen 启发式原则、UI 审计、可用性审查、启发式审查、UX 合规性、可用性问题

---

问题日志格式

进行启发式评估时，按此结构化格式记录所有发现。

汇总表

每次审计都从严重性汇总开始：

## Heuristic Evaluation Summary

| Severity | Count |
|----------|-------|
| Critical | X     |
| Major    | X     |
| Minor    | X     |
| Advisory | X     |
| **Total** | **X** |

严重性定义

• 严重：用户无法完成核心任务。例如：提交表单时无法从错误中恢复、无法撤销破坏性操作、系统对异步操作完全没有反馈。
• 主要：用户会遇到明显的阻碍或困惑。例如：异步操作没有加载反馈、不同页面间的导航模式不一致、错误消息使用原始技术术语。
• 次要：用户会感到不便，但可以绕过问题继续操作。例如：缺少占位文本、Tab 键顺序不理想、仅含图标的按钮没有工具提示。
• 建议：改进机会，可提升体验，但不会妨碍任务完成。例如：可为高级用户添加键盘快捷键、可添加空状态指引、可优化确认消息的文案。

发现格式

每条发现均遵循以下结构：

### [H#] Heuristic Name — Finding Title

- **Severity**: Critical | Major | Minor | Advisory
- **Heuristic**: #N — Heuristic Name
- **Location**: `file_path:line_range` or component/view name
- **Description**: What the issue is and why it matters for usability.
- **Evidence**:
  ```html
  

• 建议：

• 交叉引用：laws-of-ux：定律名称（如适用）

### Audit Completion

End every audit with:

```markdown
## Recommendations Priority

1. **Fix immediately** (Critical): List critical findings by ID
2. **Fix soon** (Major): List major findings by ID
3. **Plan for next iteration** (Minor): List minor findings by ID
4. **Consider for enhancement** (Advisory): List advisory findings by ID

---

审核清单

使用此表快速检查。每项检查都对应一条启发式原则，并说明要在代码中查找什么。

检查项	启发式原则	查找内容
所有异步操作都有加载／进度反馈	H1：系统状态的可见性	加载动画、骨架屏、disabled 状态、aria-busy、aria-live 区域、data-disable-with
系统使用通俗易懂的语言，而非开发者术语	H2：系统与现实世界的匹配	错误消息、标签、帮助文本——检查是否出现 HTTP 状态码、模型名称和技术术语
危险操作或多步骤操作提供撤销／返回／取消选项	H3：用户控制与自由	取消按钮、撤销模式、data-turbo-confirm、模态框关闭方式（X 和 Escape）、返回链接
UI 元素的样式和行为保持一致	H4：一致性与标准	按钮类、表单布局、术语、导航模式、设计令牌的使用
危险操作需要确认；输入控件限制无效值	H5：错误预防	data-turbo-confirm、disabled 状态、输入项的 type／required／min／max／pattern
标签、图标和操作提示始终可见	H6：识别而非回忆	可见标签、面包屑、持久显示的导航、图标与文本组合、自动补全
为有经验的用户提供快捷键和加速操作	H7：灵活高效地使用	键盘快捷键、accesskey、搜索、批量操作、可自定义视图
UI 仅显示必要信息	H8：美观与极简设计	内容密度、相互竞争的 CTA、装饰性与功能性元素、展开／收起控件
错误消息说明发生了什么并建议修复方法	H9：帮助用户从错误中恢复	Flash 消息、内联验证、错误摘要、字段级错误位置
在需要的地方提供上下文帮助	H10：帮助与文档	工具提示、aria-describedby、帮助文本、空状态指引、<details> 元素

---

10 条可用性启发式原则

H1：系统状态的可见性

定义：设计应始终通过适当的反馈，在合理的时间内让用户了解当前发生的情况。

要点：每项用户操作都应产生可见反馈。异步操作需要加载状态。状态变化需要视觉确认。用户不应疑惑“操作成功了吗？”

在代码中查找：

• 表单提交按钮：检查是否有 data-disable-with，或是否有会显示加载状态的 Stimulus 控制器
• 异步数据加载：查找骨架屏、加载动画或 aria-busy="true"
• 实时区域：检查动态内容更新是否使用 aria-live="polite" 或 aria-live="assertive"
• 状态变化：确认操作后是否有 Toast 通知、Flash 消息或内联确认信息
• Turbo Frames：检查替换 Frame 时是否显示加载指示器
• 文件上传：查找进度条或百分比指示器

示例：

良好

<form data-controller="form-submit" data-action="submit->form-submit#disable">
  <button type="submit" class="btn btn--primary"
          data-disable-with="Saving..."
          data-form-submit-target="button">
    Save Changes
  </button>
</form>

<div aria-live="polite" class="notification-area">
  
</div>

较差

<form>
  <button type="submit" class="btn btn--primary">Save Changes</button>
  
  
</form>

提交时没有任何反馈——用户可能会多次点击，导致重复提交。

审核标记：

• 标记没有加载／禁用状态的表单提交按钮
• 标记没有可见加载指示器的异步操作（fetch、Turbo Frame 加载）
• 标记没有确认反馈的状态变化（添加、删除、更新）
• 标记没有用于动态状态更新的 aria-live 区域的页面
• 标记没有进度指示的文件上传输入项

交叉参考： laws-of-ux：多尔蒂阈值（在 400ms 内响应）、目标梯度效应（进度可视化）

---

H2：系统与现实世界的匹配

定义：设计应使用用户的语言。使用用户熟悉的词语、短语和概念，而不是内部术语。遵循现实世界的惯例，让信息以自然、合乎逻辑的顺序呈现。

关键要点：标签、错误消息和说明应使用用户能理解的通俗语言。信息应按照用户的视角，而非系统的视角，以合乎逻辑的顺序排列。

代码审查要点：

• 错误消息：检查是否包含 HTTP 状态码、模型／属性名称、堆栈跟踪或数据库术语
• 表单标签：检查是否将数据库列名用作标签（例如，用 created_at 代替“创建日期”）
• 导航顺序：确认顺序遵循用户的任务流程，而非数据库架构的顺序
• 图标：检查图标是否采用了普遍易懂的隐喻
• 日期／时间格式：确认格式符合用户的地区习惯

示例：

正确

<div class="alert alert--error" role="alert">
  <p>We couldn't save your changes. Please check the highlighted fields below.</p>
</div>

<label for="start_date">Start date</label>
<input type="date" id="start_date" name="project[start_date]">

错误

<div class="alert alert--error" role="alert">
  <p>422 Unprocessable Entity: Validation failed: start_date can't be blank,
     end_date must be after start_date</p>
</div>

<label for="project_created_at">project_created_at</label>
<input type="text" id="project_created_at" name="project[created_at]">

原始技术错误消息和数据库列名被用作标签——用户不应看到系统内部信息。

审查标记：

• 标记包含 HTTP 状态码、模型名称或属性名称的错误消息
• 标记与数据库列名完全相同的表单标签（snake_case、缩写）
• 标记仅有图标、没有文本或工具提示，且使用了特定领域隐喻的操作
• 标记按系统逻辑（按字段名的字母顺序）而非用户任务流程排列的内容
• 标记与用户地区习惯不符的日期／数字格式

交叉引用： laws-of-ux：Jakob 定律（用户会期待熟悉界面中的惯例）

---

H3：用户控制权与自由度

定义：用户经常会误操作。他们需要一个清晰标示的“紧急出口”，以便无需经历冗长流程即可退出不需要的操作。

关键要点：每项破坏性操作或确认操作都应提供退出途径。用户应能随时撤销、取消、返回或关闭，而不会受到惩罚。

代码审查要点：

• 破坏性操作（删除、移除、归档）：检查是否有确认对话框（data-turbo-confirm）
• 多步骤表单／向导：检查是否有“上一步”按钮，以及返回先前步骤的功能
• 模态框／对话框：检查是否有关闭按钮（X）、Escape 键处理程序，以及点击背景关闭的功能
• 批量操作：检查是否支持撤销，或是否会在执行前要求确认
• 导航：检查表单页面和编辑视图中是否有取消／返回链接
• 筛选／搜索：检查是否有清除／重置功能

示例：

正确

<a href="/projects/5" data-turbo-method="delete"
   data-turbo-confirm="Delete this project? This cannot be undone."
   class="btn btn--danger">
  Delete Project
</a>


<dialog class="modal" data-controller="modal"
        data-action="keydown.esc->modal#close click->modal#closeOnBackdrop">
  <button class="modal__close" data-action="click->modal#close" aria-label="Close">
    &times;
  </button>
  <div class="modal__body">
    
  </div>
  <div class="modal__footer">
    <button class="btn btn--outline" data-action="click->modal#close">Cancel</button>
    <button class="btn btn--primary">Confirm</button>
  </div>
</dialog>

错误

<a href="/projects/5" data-turbo-method="delete" class="btn btn--danger">
  Delete
</a>


<div class="modal">
  <div class="modal__body">
    <p>Are you sure?</p>
    <button class="btn btn--primary">Yes, continue</button>
    
  </div>
</div>

破坏性操作没有确认步骤。模态框困住了用户，只提供前进路径。

审查标记：

• 标记没有确认对话框的删除／移除／归档操作
• 标记没有关闭按钮、Escape 键处理程序或取消选项的模态框
• 标记没有“上一步”／“上一页”按钮的多步骤流程
• 标记没有可返回上一视图的取消链接的表单页面
• 标记没有撤销或确认机制的批量操作
• 标记没有清除／重置选项的筛选／搜索界面

交叉引用： laws-of-ux：峰终定律（错误恢复是体验中的关键“高峰”时刻）

---

H4：一致性与标准

定义：用户不应疑惑不同的词语、情境或操作是否表达相同的意思。遵循平台和行业惯例。

要点：同时保持内部一致性（在整个应用中使用相同的模式）和外部一致性（遵循平台惯例）。相同功能 = 在任何地方都有相同的外观和行为。

代码检查要点：

• 按钮样式：检查相同类型的操作是否在所有视图中使用相同的 CSS 类
• 术语：检查相同操作是否在所有地方使用相同的标签（不要这里写“保存”，那里写“提交”）
• 表单布局：检查标签位置（上方还是旁边）、字段顺序和验证模式是否一致
• 导航模式：检查各页面的菜单结构、链接样式和图标用法是否一致
• 设计令牌：检查是否一致地使用令牌，而非硬编码值（参见 optics-context 技能）
• 组件结构：检查 BEM 命名和 HTML 结构是否一致（参见 bem-structure 技能）

示例：

正确

<div class="actions">
  <a href="/projects/5/edit" class="btn btn--primary">Edit</a>
  <a href="/projects" class="btn btn--outline">Back</a>
</div>


<div class="actions">
  <a href="/tasks/12/edit" class="btn btn--primary">Edit</a>
  <a href="/tasks" class="btn btn--outline">Back</a>
</div>

错误

<div class="actions">
  <a href="/projects/5/edit" class="btn btn--primary">Edit</a>
  <a href="/projects" class="btn btn--outline">Back</a>
</div>


<div class="task-buttons">
  <button class="btn btn--secondary" onclick="location='/tasks/12/edit'">Modify</button>
  <a href="/tasks" class="link">Return to list</a>
</div>

相同概念的操作（“编辑”和“返回”）使用了不同的标签、HTML 元素、CSS 类和交互模式。

审查标记：

• 标记在不同视图中使用不同标签的相同操作（“保存”与“提交”与“更新”与“确认”）
• 标记在不同视图中使用不同 CSS 类或 HTML 结构的相同类型元素
• 标记同一属性混用设计令牌和硬编码值的情况
• 标记应用不同部分之间不一致的导航模式
• 标记自定义实现的标准平台控件（自定义选择框、自定义日期选择器），且其行为与原生控件不一致的情况

交叉引用：laws-of-ux：雅各布定律（遵循平台惯例）、相似律（样式一致表明元素相关）、审美易用性效应（视觉一致性会提升感知质量）。另请参阅 optics-context，了解设计令牌一致性；参阅 bem-structure，了解 CSS 命名一致性。

---

H5：错误预防

定义：良好的错误消息很重要，但最好的设计会仔细防止问题发生。要么消除容易出错的条件，要么检查这些条件，并在用户执行操作前提供确认选项。

要点：将输入限制在有效值范围内。执行破坏性操作前先确认。使用恰当的输入类型。系统应让用户难以做出错误操作。

代码检查要点：

• 输入类型：检查字段是否使用恰当的 type 属性（email、tel、url、number、date）
• 限制条件：检查是否设置了 required、min、max、minlength、maxlength、pattern、step 属性
• 破坏性操作：检查不可逆操作前是否显示确认对话框
• 行内验证：检查表单提交前是否提供实时验证反馈
• 禁用状态：检查必填字段填写完整前，提交按钮是否处于禁用状态
• 默认值：检查是否提供合理的默认值以降低出错概率

示例：

正确

<form data-controller="form-validation">
  <label for="email">Email address</label>
  <input type="email" id="email" name="user[email]" required
         aria-describedby="email-hint"
         data-action="blur->form-validation#validate">
  <span id="email-hint" class="hint">We'll send a confirmation to this address.</span>
  <span class="field-error" data-form-validation-target="error" hidden></span>

  <label for="age">Age</label>
  <input type="number" id="age" name="user[age]" min="13" max="120" required>

  <label for="start_date">Start date</label>
  <input type="date" id="start_date" name="project[start_date]"
         min="2024-01-01" max="2030-12-31">
</form>

错误

<form>
  <label for="email">Email</label>
  <input type="text" id="email" name="user[email]">
  

  <label for="age">Age</label>
  <input type="text" id="age" name="user[age]">
  

  <label for="start_date">Start date (YYYY-MM-DD)</label>
  <input type="text" id="start_date" name="project[start_date]">
  
</form>

所有字段都使用 type="text"，且没有任何限制条件——所有输入错误都只能在服务器端提交时发现。

审查标记：

• 标记本应使用 email、tel、url、number 或 date 的字段却设置为 type="text" 的情况
• 标记必须填写的字段缺少 required 属性的情况
• 标记缺少 min/max 限制的数字字段
• 标记没有客户端验证的表单（所有验证都交由服务器处理）
• 标记没有确认步骤的破坏性操作（删除、发布、发送）
• 在存在合理默认值的情况下，标记缺少合理默认值的情况

交叉引用：laws-of-ux：特斯勒定律（系统替用户承担复杂性）、波斯特尔定律（接受灵活的输入格式）

---

H6：识别而非回忆

定义：通过让元素、操作和选项清晰可见，尽量减轻用户的记忆负担。用户不应需要记住界面某一部分的信息，再在另一部分使用。使用设计所需的信息应清晰可见或易于查找。

关键要点：展示出来，而不是让用户去记。标签应清晰可见（不能只有占位符）。导航应始终保留。应在上下文中显示之前输入的信息。

代码检查要点：

• 标签与占位符：检查表单字段是否有可见的 <label> 元素，而不只是 placeholder 文本
• 面包屑：检查深层级结构中是否有面包屑导航
• 常驻导航：检查主导航是否始终可访问，而不是在桌面端隐藏在汉堡菜单后
• 图标标签：检查只有图标的按钮是否有可见文本标签，或至少有 aria-label 和工具提示
• 自动补全：检查搜索和选择字段是否支持输入提示/自动补全
• 上下文：检查编辑表单是否显示当前值，而不是空字段

示例：

良好

<div class="form__group">
  <label for="search" class="form__label">Search projects</label>
  <input type="search" id="search" placeholder="e.g., Marketing website"
         list="recent-searches" autocomplete="on">
  <datalist id="recent-searches">
    <option value="Marketing website">
    <option value="Q4 Report">
  </datalist>
</div>


<button class="btn btn--icon-text">
  <svg aria-hidden="true"></svg>
  <span>Edit</span>
</button>


<nav aria-label="Breadcrumb">
  <ol class="breadcrumb">
    <li><a href="/projects">Projects</a></li>
    <li><a href="/projects/5">Marketing</a></li>
    <li aria-current="page">Settings</li>
  </ol>
</nav>

不佳

<input type="text" placeholder="Search...">



<div class="toolbar">
  <button><svg></svg></button>
  <button><svg></svg></button>
  <button><svg></svg></button>
  <button><svg></svg></button>
</div>

字段获得焦点时，只有占位符的标签会消失。只有图标的工具栏会迫使用户回忆图标的含义。

审查标记：

• 标记有 placeholder、但没有可见 <label> 元素的表单字段
• 标记没有 aria-label、title 或可见文本的纯图标按钮
• 标记没有面包屑导航的深层级页面结构
• 标记在桌面视口中隐藏在汉堡菜单后的主导航
• 标记显示空字段而非预填当前值的编辑表单
• 标记要求用户记住代码或 ID 的下拉/选择字段

交叉引用： laws-of-ux：米勒定律（工作记忆限制）、序列位置效应（关键可发现项的放置位置）

---

H7：灵活性与使用效率

定义：对新手隐藏的快捷方式可以加快专家用户的操作，从而让设计同时满足缺乏经验和经验丰富的用户的需求。允许用户自定义常用操作。

关键要点：为高级用户提供加速操作的方式，同时避免让新手觉得界面复杂。支持键盘导航、批量操作和自定义。

代码检查要点：

• 键盘快捷键：检查是否有 accesskey 属性、自定义键盘事件处理程序或快捷键提示界面
• 批量操作：检查列表视图是否有“全选”和批量操作模式
• 搜索：检查是否有全局或上下文搜索功能
• Tab 键导航：检查所有交互元素是否都可通过 Tab 键访问
• 跳转链接：检查是否有供键盘和屏幕阅读器用户使用的“跳转到内容”链接
• 自定义：检查是否有可排序的列、可配置视图或已保存的筛选条件

示例：

良好

<a href="#main-content" class="skip-link">Skip to main content</a>


<div class="list-controls">
  <label class="checkbox">
    <input type="checkbox" data-action="change->bulk-select#toggleAll">
    Select all
  </label>
  <div class="bulk-actions" data-bulk-select-target="actions" hidden>
    <button class="btn btn--outline" data-action="click->bulk-select#archive">
      Archive selected
    </button>
    <button class="btn btn--danger" data-action="click->bulk-select#delete">
      Delete selected
    </button>
  </div>
</div>


<button class="btn btn--primary" title="New project (N)">
  New Project
  <kbd class="shortcut-hint">N</kbd>
</button>

不佳

<ul class="project-list">
  <li>Project A <a href="/projects/1/edit">Edit</a> <a href="/projects/1" data-method="delete">Delete</a></li>
  <li>Project B <a href="/projects/2/edit">Edit</a> <a href="/projects/2" data-method="delete">Delete</a></li>
  
</ul>

没有批量操作、没有键盘快捷键、没有跳转链接——对于需要管理大量项目的高级用户来说效率低下。

审查标记：

• 标记没有批量选择或批量操作的列表视图
• 标记没有常用操作键盘快捷键的应用
• 标记缺少“跳转到内容”链接的页面
• 标记无法通过 Tab 键访问的交互元素
• 标记缺少搜索输入框、但工作流高度依赖搜索的页面
• 标记没有可排序列或已保存筛选选项的数据表格

交叉引用： laws-of-ux：帕累托原则（优先处理 80% 时间里会用到的 20% 操作）

---

H8：美观简约的设计

定义：界面不应包含无关或很少需要的信息。界面中的每一条额外信息都会与相关信息争夺注意力，降低相关信息的相对可见度。

关键要点：只展示当前任务所需的内容。将次要信息收纳在渐进式披露中。减少视觉干扰，让主要操作和内容更加醒目。

代码审查要点：

• 内容密度：检查首屏可见的信息量
• 相互竞争的 CTA：统计每个视图中视觉强调程度相同的操作按钮数量
• 渐进式披露：查找 <details>/<summary>、展开/折叠模式或“显示更多”链接
• 装饰元素：检查是否存在增加视觉权重但没有功能价值的元素
• 留白：检查间距设计令牌是否为各个区块留出充足空间
• 表格：检查列数——是否可以将某些列收纳在展开视图或详情视图中？

示例：

GOOD

<div class="settings-section">
  <h3>Notifications</h3>
  <label class="toggle">
    <input type="checkbox" name="email_notifications" checked>
    Email notifications
  </label>
  <label class="toggle">
    <input type="checkbox" name="push_notifications">
    Push notifications
  </label>

  <details class="settings-advanced">
    <summary>Advanced notification settings</summary>
    <div class="settings-advanced__body">
      
    </div>
  </details>
</div>

BAD

<div class="settings-page">
  <h3>Notifications</h3>
  <label><input type="checkbox" checked> Email notifications</label>
  <label><input type="checkbox"> Push notifications</label>
  <label><input type="checkbox"> SMS notifications</label>
  <label><input type="checkbox"> Slack notifications</label>
  <label><input type="checkbox"> Weekly digest</label>
  <label><input type="checkbox"> Daily summary</label>

  <h4>Email frequency</h4>
  <select><option>Immediate</option><option>Hourly</option><option>Daily</option></select>

  <h4>Quiet hours</h4>
  <input type="time" name="quiet_start"> to <input type="time" name="quiet_end">

  <h4>Per-channel overrides</h4>
  
</div>

所有设置都堆在同一页面，没有层级或渐进式披露。高级选项与基本选项争夺用户注意力。

审查标记：

• 标记含有超过 2–3 个视觉强调程度相同的 CTA 的视图
• 标记没有为高级选项提供渐进式披露的设置页或配置页
• 标记所有小组件视觉权重都相同的仪表板
• 标记没有任何功能用途的装饰性图片、插图或图标
• 标记同时显示超过 6–7 列的数据表格
• 标记以操作为导向的场景（表单、对话框、工具栏）中冗长的正文

交叉参考：laws-of-ux：奥卡姆剃刀（最简单的解决方案）、完形定律（视觉简洁）、希克定律（选项越少，决策越快）。另请参阅 optics-context，了解简约的、基于令牌的样式。

---

H9：帮助用户识别、诊断并从错误中恢复

定义：错误消息应使用通俗易懂的语言（不含错误代码），准确指出问题，并提出有助于解决问题的建议。

关键要点：发生错误时，用通俗易懂的方式告诉用户出了什么问题，指出问题所在，并提供清晰的解决路径。绝不要显示原始系统错误。

代码审查要点：

• 闪现/Toast 消息：检查错误内容是否具体且可操作，而非笼统表述（“出了点问题”）
• 表单验证：检查字段旁是否显示内联错误，而非只在顶部显示错误摘要
• 错误摘要：检查表单错误摘要是否链接到出错的字段
• HTTP 错误页面（404、500）：检查是否提供有用内容和导航选项
• 字段突出显示：检查出错字段是否有视觉提示（红色边框、图标）
• 焦点管理：检查表单提交失败时，焦点是否移至第一个错误

示例：

GOOD

<div class="error-summary" role="alert" tabindex="-1">
  <h3>There were 2 problems with your submission:</h3>
  <ul>
    <li><a href="#user_email">Email address is not valid</a></li>
    <li><a href="#user_password">Password must be at least 8 characters</a></li>
  </ul>
</div>


<div class="form__group form__group--error">
  <label for="user_email">Email address</label>
  <input type="email" id="user_email" class="input--error"
         aria-describedby="email-error" aria-invalid="true">
  <span id="email-error" class="field-error" role="alert">
    Please enter a valid email address, e.g., [email protected]
  </span>
</div>

BAD

<div class="alert alert--error">
  <p>There were errors.</p>
</div>


<div class="form__group">
  <label for="user_email">Email</label>
  <input type="text" id="user_email">
  
</div>

笼统的错误横幅，既没有指出哪些字段出错，也没有说明如何修复。

审查标记：

• 标记没有具体说明的笼统错误消息（“错误”“出了点问题”“输入无效”）
• 标记仅在页面顶部显示表单错误摘要、而没有字段内联错误的情况
• 标记缺少 aria-invalid="true"，或缺少通过 aria-describedby 链接到错误消息的错误状态
• 标记没有说明如何修复问题的错误消息
• 标记缺少导航选项或搜索功能的 404/500 错误页面
• 标记提交失败时焦点不会移至错误摘要或第一个出错字段的表单

交叉参考：laws-of-ux：峰终定律（错误恢复是塑造整体体验的“峰值”时刻）、波斯特尔定律（接受灵活的输入可以从源头上减少错误）

---

H10：帮助与文档

定义：最好让系统不需要任何额外说明。不过，有时可能需要提供文档，帮助用户了解如何完成任务。此类信息应便于搜索、聚焦于用户的任务、列出需要执行的具体步骤，且篇幅不宜过长。

关键要点：在用户需要的地方提供情境化帮助——复杂字段的工具提示、空状态引导、入门提示。帮助内容应聚焦于任务并出现在当前情境中，而不应要求用户跳转到单独的页面。

代码审查要点：

• 工具提示：检查复杂字段是否使用了 title、aria-describedby 或 Stimulus 工具提示控制器
• 空状态：检查空列表或空表格是否提供了下一步操作指引
• 入门引导：检查是否有首次运行提示、设置清单或引导式教程
• 帮助文本：检查复杂表单字段下方是否有 <span class="hint"> 或类似元素
• 内联文档：检查是否使用 <details>/<summary> 展示可展开的帮助内容
• 文档链接：检查复杂功能附近是否有情境化的“了解更多”链接

示例：

良好

<div class="empty-state">
  <svg class="empty-state__icon" aria-hidden="true"></svg>
  <h3>No projects yet</h3>
  <p>Projects help you organize your work and track progress with your team.</p>
  <a href="/projects/new" class="btn btn--primary">Create your first project</a>
  <a href="/help/projects" class="link">Learn more about projects</a>
</div>


<div class="form__group">
  <label for="api_key">API Key</label>
  <input type="text" id="api_key" aria-describedby="api-key-help">
  <span id="api-key-help" class="hint">
    Find your API key in your
    <a href="/account/integrations" target="_blank">integration settings</a>.
  </span>
</div>

较差

<div class="empty-state">
  <p>No projects.</p>
</div>


<div class="form__group">
  <label for="cron">Schedule (cron expression)</label>
  <input type="text" id="cron" name="schedule[cron]" placeholder="* * * * *">
  
</div>

空状态没有说明项目是什么，也没有说明如何创建项目。复杂字段需要专业知识，却没有提供帮助。

审查标记：

• 标记只显示“No items”或“No results”，却未提供指引或行动号召（CTA）的空状态
• 标记没有帮助文本或工具提示的复杂或技术性表单字段
• 标记没有入门引导或首次运行说明的功能
• 标记关联了帮助文本却缺少 aria-describedby 的字段
• 标记需要离开当前任务情境才能查看的帮助内容
• 标记没有示例或链接的文档密集型字段（如 cron、regex、API 配置）

交叉引用： laws-of-ux：Zeigarnik 效应（推动用户完成设置和入门任务）

---

跨领域关注点

多项启发式原则会相互强化。审查时，应将相关问题归类，而不是在多项启发式原则下重复报告同一问题。

反馈循环：H1 + H9 + H3

这三项启发式原则构成了一个完整的反馈循环：

• H1（可见性）：系统展示当前正在发生的事情
• H9（错误恢复）：发生问题时，系统清楚地解释问题
• H3（用户控制）：用户可以退出、撤销或重试

审查表单或工作流时，应同时检查这三项。缺少加载反馈（H1）、显示通用错误（H9）且没有取消按钮（H3）的表单，会造成叠加的可用性问题——应将其作为一组问题报告。

一致性组合：H4 + H6 + H8

这三项启发式原则相互支持：

• H4（一致性）：各处使用相同的模式
• H6（识别）：一致的模式易于识别
• H8（极简主义）：一致性可减少视觉干扰

不一致的 UI 会迫使用户依赖回忆（违反 H6），并增加视觉复杂度（违反 H8）。发现不一致时，应检查它是否也造成了识别或极简主义方面的问题。

预防与恢复：H5 + H9

这两项是错误处理的两个方面：

• H5（预防）：在错误发生前阻止错误
• H9（恢复）：帮助用户修正已经发生的错误

审查错误处理时，应同时检查两者。既不防止无效输入（H5），也不清楚解释错误（H9）的表单，会造成叠加的问题。

语言与帮助：H2 + H10

这两项启发式原则都关注沟通：

• H2（贴合现实）：使用用户的语言
• H10（帮助与文档）：在需要时提供指引

如果系统使用了行话（违反 H2），用户对文档的需求就会增加（H10）。修复 H2 相关问题时，应检查是否也需要补充 H10 方面的支持。

---

配套技能

• laws-of-ux：当某项启发式评估发现对应到特定定律时，用于获取详细的 UX 定律指导。启发式评估提供审核方法；laws-of-ux 提供理论依据和额外的代码级示例。
• bem-structure：实现启发式评估违规项的修复时，用于 CSS 类命名规范，尤其适用于 H4（一致性）和 H8（极简主义）。
• optics-context：实现视觉修复时，用于设计令牌的使用，尤其适用于 H4（一致性——令牌与硬编码值）、H8（极简主义——简洁的样式）和 H1（可见性——反馈状态的颜色和间距）。