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-buttons
```
and
```
ux-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

Source lessons (Uxcel)

Tooltips & When to Use Them

ux-tooltips

NPX Install

Tags

SKILL.md Content