ux-tooltips

工具提示技能

此技能的行为方式（请先阅读）

这是一项生成式技能。默认的失败模式包括：把工具提示当拐杖（界面含糊不清，却试图靠到处添加悬停提示来“修复”）、内容重复（“提交”按钮 + “点击以提交”工具提示），以及把关键信息藏在悬停内容里（用户必须看到的内容，却藏在许多人永远不会进行的交互之后——而触屏设备也无法可靠地进行这种交互）。工具提示是对确实存在歧义的元素的补充，绝不能成为流程中不可或缺的一环。此技能会把关：

1. 判断每个工具提示是否有存在的必要——元素确实有歧义，还是设计不清晰？
2. 应用始终适用的核心原则——位置、简洁度、样式、光标提示。
3. 指出需要升级处理的情况——何时工具提示根本不是合适的工具。

随后，它会将工作交给 ux-heuristics-audit、ux-accessibility-audit、ux-aesthetics-audit 和 ux-microcopy-audit 进行验证。

---

第 0 步——判断每个工具提示是否有存在的必要

针对每个工具提示，问自己三个问题：

• 元素是否确实有歧义？ 相机图标可能表示“拍照”或“打开图库” → 添加工具提示有其价值。标有“提交”的按钮 → 无需工具提示；它只会重复标签。
• 这些信息对完成任务是否至关重要？ 工具提示由用户主动触发——许多用户从不悬停，触屏设备也没有悬停功能。完成流程所需的内容应放在界面中（标签、辅助文本、内联消息），绝不能放在工具提示里。
• 这是否在掩盖设计问题？ 如果一个屏幕需要许多工具提示，说明标签、图标或布局存在问题。应修复元素，而不是添加注释。（更通用的图标、可见标签，或图标 + 标签——参见 ux-buttons 和 ux-menus。）

---

始终适用的核心原则（适用于通过上述判断的工具提示）

• 内容简洁，只保留必要信息——用简短的说明消除歧义（“拍摄照片”），不重复内容，也不包含用户必须费力阅读的信息。
• 位置不得造成遮挡——工具提示及其触发元素都应始终完整可见；绝不遮挡它所说明的输入框或按钮，也不能被屏幕边缘截断。
• 对可悬停的触发元素使用指针光标——表明有更多信息可查看，并使光标与弹出提示相呼应。
• 文本左对齐（LTR），样式适度，不加装饰性边框，文本与工具提示背景之间的对比度 ≥4.5:1。
• 在整个产品中保持一致——统一工具提示样式，统一触发行为。

---

需要升级处理的情况（工具提示不合适时）

情况	不要使用	改用
完成表单字段所需的信息	信息图标上的工具提示	输入框下方的辅助文本（→ ux-inputs-and-forms）
视觉问题（CVV 在哪里？）	移动设备上仅含文字的工具提示	内联图标/图形，工具提示作为桌面端补充
首次使用时的功能介绍	到处显示永久性工具提示	引导式演练模式（→ ux-onboarding）
任何以触屏为主的产品	依赖悬停的工具提示	可见标签、辅助文本或点击触发的弹出层（弹出层参见 ux-modals-and-dialogs）
丰富内容（图片、多项操作）	内容过多的工具提示	弹出层
需要完整显示的截断文本	指望用户猜测	这里的工具提示正合适——截断文本 + 工具提示是合理的组合（→ 表格、菜单、面包屑）

---

验证结果（编排）

交接时使用各审查视角对应的可安装技能 name。只有在该技能已安装时才调用；如果未安装，此技能本身已包含这些规则，可直接继续，不要因此停滞。

生成或修改后，将结果交由审查视角检查，而不是直接宣布完成。这些是候选审查视角——具体策略由 docs/orchestration-policy.md 设定，也可以将整个内容交由 ux-design-review 审查。此处，heuristics 和 microcopy 属于 A 级（自动运行）；accessibility、aesthetics 和 mobile-responsiveness 属于 B 级（提供选项）——使用现有设计系统时，aesthetics 将不再审查，accessibility 的审查范围将缩小为使用层面；mobile-responsiveness 仅适用于移动端。如果用户调用此技能是为了处理某个特定事项，请尊重其范围。

• ux-heuristics-audit （A 级） — 优先识别而非回忆（不看工具提示，界面是否能让人一目了然？）、处理方式是否一致。
• ux-accessibility-audit （B 级——提供选项；使用设计系统时缩小审查范围） — 能否通过键盘或焦点访问工具提示内容、是否提供触控替代方式、对比度，以及是否避免仅通过悬停才能获取关键信息。
• ux-aesthetics-audit （B 级——提供选项；使用设计系统时不审查） — 样式是否克制、位置是否清晰。
• ux-microcopy-audit （A 级） — 工具提示文字是否简洁明了。
• ux-mobile-responsiveness-audit （B 级——提供选项；仅适用于移动端） — 如果场景是移动端，默认将依赖悬停视为缺陷。

如果审查发现冲突，应优先回到主要任务：需要工具提示的用户已经有些迷茫——目标应是打造一个让用户很少需要工具提示的界面。

---

常见的应做与不应做

❌ 不要	✅ 应当
在“提交”按钮上显示“点击以提交”	只在含义确实模糊时使用工具提示
将必需说明隐藏在悬停提示中	在界面中显示关键信息；工具提示只是可选补充
用十个工具提示弥补界面不清晰的问题	改进标签和图标；工具提示仅作为少见的补充
让工具提示遮住它所说明的字段	合理放置，确保触发元素和工具提示均可见
让工具提示在视口边缘被截断	根据边缘调整位置
使用装饰性边框和低对比度文字	样式简洁，对比度 ≥4.5:1，文字左对齐
在工具提示中放入一段文字	只提供一条简短易懂的说明
在触控设备上仅通过悬停提供帮助	使用可见标签或点击触发的弹出层
未经检查就发布	交由启发式、无障碍、美学和微文案审查

---

来源经验（Uxcel）

• 工具提示及其使用时机