Tooltips Skill
How this skill behaves (read first)
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 ux-heuristics-audit, ux-accessibility-audit, ux-aesthetics-audit, and ux-microcopy-audit for validation.
Step 0 — Gate each tooltip's existence
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-buttonsandux-menus.)
The always-apply core (for tooltips that survive the gate)
- 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.
The escalation decisions (when a tooltip is the wrong tool)
| Situation | Don't reach for | Use instead |
|---|---|---|
| Information needed to complete a form field | Tooltip on an info icon | Helper text below the input (→ ux-inputs-and-forms) |
| 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 (→ ux-onboarding) |
| Anything on touch-first products | Hover-dependent tooltips | Visible labels, helper text, or tap-triggered popovers (→ ux-modals-and-dialogs for 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) |
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.
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 |
