ux-tooltips

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tooltips 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:
  1. Gate each tooltip's existence — is the element actually ambiguous, or is the design unclear?
  2. Apply the always-true core — placement, brevity, styling, cursor signaling.
  3. Surface the escalation decisions — when a tooltip is the wrong tool entirely.
Then it hands off to
ux-heuristics-audit
,
ux-accessibility-audit
,
ux-aesthetics-audit
, and
ux-microcopy-audit
for validation.

这是一个生成型 Skill。常见失败模式包括:以 Tooltip 充当拐杖(用到处散落的悬停提示来“修复”一个不清晰的界面)、冗余(“提交”按钮加上“点击以提交”Tooltip),以及将关键信息藏在悬停空间(把用户必须看到的内容隐藏在一种许多用户永远不会执行的交互之后,而触屏设备也无法可靠地执行这种交互)。Tooltip 是对真正含义模糊的元素的补充——绝不能成为流程中不可或缺的关键环节。此 Skill 会把关以下事项:
  1. 审查每个 Tooltip 是否应该存在——究竟是元素本身存在歧义,还是设计本身不清晰?
  2. 应用始终适用的核心规则——位置、简洁性、样式和光标提示。
  3. 明确需要升级处理的情形——Tooltip 完全不是正确工具时。
随后,它会将结果移交给
ux-heuristics-audit
、
ux-accessibility-audit
、
ux-aesthetics-audit
和
ux-microcopy-audit
进行验证。

Step 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
    ux-buttons
    and
    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 是错误工具时)

SituationDon't reach forUse instead
Information needed to complete a form fieldTooltip on an info iconHelper text below the input (→
ux-inputs-and-forms
)
Visual question (where's the CVV?)Text-only tooltip on mobileInline icon/graphic, tooltip as desktop supplement
First-run feature educationPermanent tooltips everywhereOnboarding walkthrough patterns (→
ux-onboarding
)
Anything on touch-first productsHover-dependent tooltipsVisible labels, helper text, or tap-triggered popovers (→
ux-modals-and-dialogs
for popovers)
Rich content (images, multiple actions)An overstuffed tooltipA popover
Truncated text needing full displayHoping users guessTooltip is right here — truncation + tooltip is a legitimate pairing (→ tables, menus, breadcrumbs)

情况不要使用改用
完成表单字段所需的信息信息图标上的 Tooltip输入框下方的辅助文本(→
ux-inputs-and-forms
)
视觉问题(CVV 在哪里?)移动端上的纯文本 Tooltip内联图标/图形,并将 Tooltip 作为桌面端补充
首次使用功能的教育到处常驻 Tooltip新手引导流程模式(→
ux-onboarding
)
任何触屏优先产品中的内容依赖悬停的 Tooltip可见标签、辅助文本或点击触发的 Popover(Popover 相关内容参见
ux-modals-and-dialogs
)
丰富内容(图片、多个操作)内容过度拥挤的 TooltipPopover
需要完整显示的截断文本指望用户猜测此时 Tooltip 是正确选择——截断 + Tooltip 是合理搭配(→ 表格、菜单、面包屑)

Validate the result (orchestration)

验证结果(编排)

Hand-offs name each lens by its installable skill
name
. 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.
After generating or revising, hand the result to the audit lenses rather than declaring it done. These are candidate lenses — posture is set by
docs/orchestration-policy.md
, or route the whole thing through
ux-design-review
. Here,
heuristics
and
microcopy
are Tier A (auto-run);
accessibility
,
aesthetics
, and
mobile-responsiveness
are Tier B (offered)
— under an existing design system
aesthetics
is suppressed and
accessibility
narrows to usage;
mobile-responsiveness
applies only on mobile. If the user invoked this skill for one specific thing, respect that scope.
  • ux-heuristics-audit
    (Tier A) — recognition over recall (is the interface self-explanatory without the tooltips?), consistency of treatment.
  • ux-accessibility-audit
    (Tier B — offer; narrow under a design system) — keyboard/focus access to tooltip content, touch alternatives, contrast, no hover-only vital information.
  • ux-aesthetics-audit
    (Tier B — offer; suppress under a design system) — styling restraint, placement cleanliness.
  • ux-microcopy-audit
    (Tier A) — tooltip text brevity and clarity.
  • ux-mobile-responsiveness-audit
    (Tier B — offer; applies only on mobile) — when the context is mobile: hover-dependence is a defect there by default.
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 的
name
指明每一种审查视角。仅在相应 Skill 已安装时调用;若未安装,此 Skill 自身的核心规则已涵盖这些要求——直接继续,不要因此阻塞。
生成或修改后,不要直接宣告完成,而应将结果交给各审计视角。这些都是候选视角——执行方式由
docs/orchestration-policy.md
决定,或将整个任务交由
ux-design-review
路由处理。这里,
heuristics
和
microcopy
属于 Tier A(自动运行);
accessibility
、
aesthetics
和
mobile-responsiveness
属于 Tier B(可选择提供)
——如果已有设计系统,则不运行
aesthetics
,并将
accessibility
范围收窄至实际使用问题;
mobile-responsiveness
仅在移动端适用。如果用户仅针对某个具体事项调用此 Skill,请遵循该范围。
  • ux-heuristics-audit
    (Tier A) — 识别优于回忆(没有 Tooltip 时,界面是否仍能自我说明?)、处理方式的一致性。
  • ux-accessibility-audit
    (Tier B — 可选择提供;在设计系统下收窄范围) — 通过键盘/焦点访问 Tooltip 内容、触屏替代方案、对比度,以及不得将关键信息设为仅悬停可见。
  • ux-aesthetics-audit
    (Tier B — 可选择提供;在设计系统下抑制运行) — 克制的样式、整洁的位置安排。
  • ux-microcopy-audit
    (Tier A) — Tooltip 文案的简洁性与清晰度。
  • ux-mobile-responsiveness-audit
    (Tier B — 可选择提供;仅在移动端适用) — 当上下文为移动端时:默认将依赖悬停视为缺陷。
如果审计发现冲突,应回到首要任务来解决:需要 Tooltip 的用户本身已经有些迷失——目标是打造一个很少需要 Tooltip 的界面。

Common do/don't patterns

常见的推荐与不推荐模式

❌ Don't✅ Do
"Click to submit" on a Submit buttonTooltips only where meaning is genuinely ambiguous
Required instructions hidden in hoverVital info in the interface; tooltips are optional extras
Ten tooltips patching an unclear screenFix labels/icons; tooltips as rare supplements
Tooltip covering the field it explainsPlacement that keeps trigger + tooltip both visible
Tooltip cut off at the viewport edgeEdge-aware positioning
Decorative frames, low-contrast textModest styling, ≥4.5:1 contrast, left-aligned
A paragraph in a tooltipOne bite-sized clarification
Hover-only help on touch productsVisible labels or tap-triggered popovers
Ship without checkingHand off to heuristics + accessibility + aesthetics + microcopy

❌ 不要✅ 应该
在“提交”按钮上放“点击以提交”仅在含义确实模糊的地方使用 Tooltip
将必需说明隐藏在悬停提示中将关键信息置于界面中;Tooltip 只是可选补充
用十个 Tooltip 修补一个不清晰的界面修复标签/图标;Tooltip 仅作为少见的补充
Tooltip 遮住所说明的字段安排位置,让触发器和 Tooltip 都完整可见
Tooltip 在视口边缘被截断采用感知边缘的位置策略
装饰性边框、低对比度文字克制的样式、对比度 ≥4.5:1、文字左对齐
在 Tooltip 中放一整段话只放一句简明说明
在触屏产品中提供仅悬停的帮助可见标签或点击触发的 Popover
未经验证就发布移交给 heuristics + accessibility + aesthetics + microcopy

Source lessons (Uxcel)

来源经验(Uxcel)