ux-tooltips
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTooltips Skill
Tooltips Skill
How this skill behaves (read first)
此 Skill 的行为方式(请先阅读)
This is a generative skill. The default failure modes: tooltip-as-crutch (an unclear interface "fixed" by sprinkling hover hints everywhere), redundancy ("Submit" button + "Click to submit" tooltip), and vital info in hover space (content users must see, hidden behind an interaction many will never perform — and that touch devices can't perform reliably). A tooltip is a supplement for genuinely ambiguous elements — never a load-bearing part of the flow. This skill gates:
- Gate each tooltip's existence — is the element actually ambiguous, or is the design unclear?
- Apply the always-true core — placement, brevity, styling, cursor signaling.
- Surface the escalation decisions — when a tooltip is the wrong tool entirely.
Then it hands off to , , , and for validation.
ux-heuristics-auditux-accessibility-auditux-aesthetics-auditux-microcopy-audit这是一个生成型 Skill。常见失败模式包括:以 Tooltip 充当拐杖(用到处散落的悬停提示来“修复”一个不清晰的界面)、冗余(“提交”按钮加上“点击以提交”Tooltip),以及将关键信息藏在悬停空间(把用户必须看到的内容隐藏在一种许多用户永远不会执行的交互之后,而触屏设备也无法可靠地执行这种交互)。Tooltip 是对真正含义模糊的元素的补充——绝不能成为流程中不可或缺的关键环节。此 Skill 会把关以下事项:
- 审查每个 Tooltip 是否应该存在——究竟是元素本身存在歧义,还是设计本身不清晰?
- 应用始终适用的核心规则——位置、简洁性、样式和光标提示。
- 明确需要升级处理的情形——Tooltip 完全不是正确工具时。
随后,它会将结果移交给 、、 和 进行验证。
ux-heuristics-auditux-accessibility-auditux-aesthetics-auditux-microcopy-auditStep 0 — Gate each tooltip's existence
第 0 步——审查每个 Tooltip 是否应该存在
Three questions per tooltip:
- Is the element genuinely ambiguous? A camera icon that could mean "take photo" or "open gallery" → tooltip earns its place. A button labeled "Submit" → no tooltip; it would only repeat the label.
- Is the information vital to the task? Tooltips are user-triggered — many users never hover, and touch devices have no hover. Anything required to complete the flow goes in the interface (label, helper text, inline message), never in a tooltip.
- Is this papering over a design problem? If a screen needs many tooltips, the labels, icons, or layout are failing. Fix the element; don't annotate it. (Better universal icon, visible label, or icon + label — see and
ux-buttons.)ux-menus
每个 Tooltip 都要回答三个问题:
- 元素是否确实存在歧义? 一个可能表示“拍照”或“打开相册”的相机图标 → Tooltip 值得占有一席之地。一个标为“提交”的按钮 → 不需要 Tooltip;它只会重复按钮标签。
- 信息对任务是否至关重要? Tooltip 由用户主动触发——许多用户从不悬停,触屏设备也没有悬停功能。任何完成任务所必需的信息都应置于界面中(标签、辅助文本、内联消息),绝不能放进 Tooltip。
- 这是否是在掩盖设计问题? 如果一个界面需要很多 Tooltip,说明标签、图标或布局出了问题。修复元素;不要为它添加注记。(更好的通用图标、可见标签,或图标 + 标签——参见 和
ux-buttons。)ux-menus
The always-apply core (for tooltips that survive the gate)
始终适用的核心规则(适用于通过审查的 Tooltip)
- Concise, essentials-only content — a bite-sized clarification ("Capture photo"), no redundancy, nothing users must strain to read.
- Placement never blocks — the tooltip and its trigger element both stay fully visible; never cover the input or button it describes, never get cut off at screen edges.
- Pointer cursor on hoverable triggers — signals that more information is available and ties the cursor to the pop-up.
- Left-aligned text (LTR), modest styling, no decorative frames, ≥4.5:1 contrast between text and tooltip background.
- Consistent treatment product-wide — one tooltip style, one trigger behavior.
- 只保留必要信息,内容简洁——一句简明说明(“拍摄照片”),不重复,也不应让用户费力阅读。
- 位置绝不遮挡内容——Tooltip 及其触发元素必须完整可见;绝不能遮住所说明的输入框或按钮,也不能在屏幕边缘被截断。
- 可悬停触发器使用指针光标——提示还有更多信息可用,并将光标与弹出内容关联起来。
- 文字左对齐(LTR)、样式克制、无装饰性边框,文字与 Tooltip 背景之间的对比度 ≥4.5:1。
- 全产品统一处理方式——一种 Tooltip 样式、一种触发行为。
The escalation decisions (when a tooltip is the wrong tool)
需要升级处理的情形(Tooltip 是错误工具时)
| Situation | Don't reach for | Use instead |
|---|---|---|
| Information needed to complete a form field | Tooltip on an info icon | Helper text below the input (→ |
| Visual question (where's the CVV?) | Text-only tooltip on mobile | Inline icon/graphic, tooltip as desktop supplement |
| First-run feature education | Permanent tooltips everywhere | Onboarding walkthrough patterns (→ |
| Anything on touch-first products | Hover-dependent tooltips | Visible labels, helper text, or tap-triggered popovers (→ |
| Rich content (images, multiple actions) | An overstuffed tooltip | A popover |
| Truncated text needing full display | Hoping users guess | Tooltip is right here — truncation + tooltip is a legitimate pairing (→ tables, menus, breadcrumbs) |
| 情况 | 不要使用 | 改用 |
|---|---|---|
| 完成表单字段所需的信息 | 信息图标上的 Tooltip | 输入框下方的辅助文本(→ |
| 视觉问题(CVV 在哪里?) | 移动端上的纯文本 Tooltip | 内联图标/图形,并将 Tooltip 作为桌面端补充 |
| 首次使用功能的教育 | 到处常驻 Tooltip | 新手引导流程模式(→ |
| 任何触屏优先产品中的内容 | 依赖悬停的 Tooltip | 可见标签、辅助文本或点击触发的 Popover(Popover 相关内容参见 |
| 丰富内容(图片、多个操作) | 内容过度拥挤的 Tooltip | Popover |
| 需要完整显示的截断文本 | 指望用户猜测 | 此时 Tooltip 是正确选择——截断 + Tooltip 是合理搭配(→ 表格、菜单、面包屑) |
Validate the result (orchestration)
验证结果(编排)
Hand-offs name each lens by its installable skill. Invoke one only if that skill is installed; if it isn't, this skill's own core already carries these rules — proceed without it rather than blocking.name
After generating or revising, hand the result to the audit lenses rather than declaring it done. These are candidate lenses — posture is set by , or route the whole thing through . Here, and are Tier A (auto-run); , , and are Tier B (offered) — under an existing design system is suppressed and narrows to usage; applies only on mobile. If the user invoked this skill for one specific thing, respect that scope.
docs/orchestration-policy.mdux-design-reviewheuristicsmicrocopyaccessibilityaestheticsmobile-responsivenessaestheticsaccessibilitymobile-responsiveness- (Tier A) — recognition over recall (is the interface self-explanatory without the tooltips?), consistency of treatment.
ux-heuristics-audit - (Tier B — offer; narrow under a design system) — keyboard/focus access to tooltip content, touch alternatives, contrast, no hover-only vital information.
ux-accessibility-audit - (Tier B — offer; suppress under a design system) — styling restraint, placement cleanliness.
ux-aesthetics-audit - (Tier A) — tooltip text brevity and clarity.
ux-microcopy-audit - (Tier B — offer; applies only on mobile) — when the context is mobile: hover-dependence is a defect there by default.
ux-mobile-responsiveness-audit
If the audits surface a conflict, resolve back toward the primary task: a user who needs a tooltip is already slightly lost — the goal is an interface where they rarely need one.
交接内容按可安装 Skill 的指明每一种审查视角。仅在相应 Skill 已安装时调用;若未安装,此 Skill 自身的核心规则已涵盖这些要求——直接继续,不要因此阻塞。name
生成或修改后,不要直接宣告完成,而应将结果交给各审计视角。这些都是候选视角——执行方式由 决定,或将整个任务交由 路由处理。这里, 和 属于 Tier A(自动运行);、 和 属于 Tier B(可选择提供)——如果已有设计系统,则不运行 ,并将 范围收窄至实际使用问题; 仅在移动端适用。如果用户仅针对某个具体事项调用此 Skill,请遵循该范围。
docs/orchestration-policy.mdux-design-reviewheuristicsmicrocopyaccessibilityaestheticsmobile-responsivenessaestheticsaccessibilitymobile-responsiveness- (Tier A) — 识别优于回忆(没有 Tooltip 时,界面是否仍能自我说明?)、处理方式的一致性。
ux-heuristics-audit - (Tier B — 可选择提供;在设计系统下收窄范围) — 通过键盘/焦点访问 Tooltip 内容、触屏替代方案、对比度,以及不得将关键信息设为仅悬停可见。
ux-accessibility-audit - (Tier B — 可选择提供;在设计系统下抑制运行) — 克制的样式、整洁的位置安排。
ux-aesthetics-audit - (Tier A) — Tooltip 文案的简洁性与清晰度。
ux-microcopy-audit - (Tier B — 可选择提供;仅在移动端适用) — 当上下文为移动端时:默认将依赖悬停视为缺陷。
ux-mobile-responsiveness-audit
如果审计发现冲突,应回到首要任务来解决:需要 Tooltip 的用户本身已经有些迷失——目标是打造一个很少需要 Tooltip 的界面。
Common do/don't patterns
常见的推荐与不推荐模式
| ❌ Don't | ✅ Do |
|---|---|
| "Click to submit" on a Submit button | Tooltips only where meaning is genuinely ambiguous |
| Required instructions hidden in hover | Vital info in the interface; tooltips are optional extras |
| Ten tooltips patching an unclear screen | Fix labels/icons; tooltips as rare supplements |
| Tooltip covering the field it explains | Placement that keeps trigger + tooltip both visible |
| Tooltip cut off at the viewport edge | Edge-aware positioning |
| Decorative frames, low-contrast text | Modest styling, ≥4.5:1 contrast, left-aligned |
| A paragraph in a tooltip | One bite-sized clarification |
| Hover-only help on touch products | Visible labels or tap-triggered popovers |
| Ship without checking | Hand off to heuristics + accessibility + aesthetics + microcopy |
| ❌ 不要 | ✅ 应该 |
|---|---|
| 在“提交”按钮上放“点击以提交” | 仅在含义确实模糊的地方使用 Tooltip |
| 将必需说明隐藏在悬停提示中 | 将关键信息置于界面中;Tooltip 只是可选补充 |
| 用十个 Tooltip 修补一个不清晰的界面 | 修复标签/图标;Tooltip 仅作为少见的补充 |
| Tooltip 遮住所说明的字段 | 安排位置,让触发器和 Tooltip 都完整可见 |
| Tooltip 在视口边缘被截断 | 采用感知边缘的位置策略 |
| 装饰性边框、低对比度文字 | 克制的样式、对比度 ≥4.5:1、文字左对齐 |
| 在 Tooltip 中放一整段话 | 只放一句简明说明 |
| 在触屏产品中提供仅悬停的帮助 | 可见标签或点击触发的 Popover |
| 未经验证就发布 | 移交给 heuristics + accessibility + aesthetics + microcopy |