| name | tooltips |
| description | Load this skill whenever the project contains tooltip components, hover- triggered informational popups, title attribute tooltips, or any content revealed on hover or focus. Under no circumstances create tooltips that are only triggered by hover without keyboard equivalent access. Absolutely always ensure tooltips are dismissible, persistent enough to read, and not the sole source of essential information.
|
Tooltips Accessibility Skill
Canonical source: examples/TOOLTIP_ACCESSIBILITY_BEST_PRACTICES.md in mgifford/ACCESSIBILITY.md
This skill is derived from that file. When in doubt, the example is authoritative.
Apply these rules when implementing or reviewing tooltip components.
Only load this skill if the project contains tooltips.
Core Mandate
Tooltips must convey supplementary information to all users regardless of input
method. A tooltip unreachable by keyboard is an accessibility barrier.
Tooltips are non-interactive supplementary labels only. If the content is
essential, or contains links/buttons, use persistent text or a popover instead.
Severity Scale (this skill)
| Level | Meaning |
|---|
| Critical | Tooltip contains essential information with no other access route |
| Serious | Tooltip unreachable by keyboard or AT |
| Moderate | Tooltip accessible but WCAG 1.4.13 requirements not fully met |
| Minor | Best-practice gap; marginal impact |
Critical: Essential Information Must Not Live Only in a Tooltip
A tooltip is supplementary by definition. If the information it contains is
required to complete a task, it must also appear as persistent visible text.
Hiding essential content behind hover/focus only is Critical.
Serious: Tooltips Must Appear on Both Hover and Focus
A tooltip that only appears on hover is Serious — keyboard users cannot
trigger it.
function showTooltip() { tooltip.removeAttribute('hidden'); }
function hideTooltip() { tooltip.setAttribute('hidden', ''); }
trigger.addEventListener('mouseenter', showTooltip);
trigger.addEventListener('mouseleave', hideTooltip);
trigger.addEventListener('focusin', showTooltip);
trigger.addEventListener('focusout', hideTooltip);
trigger.addEventListener('keydown', (e) => {
if (e.key === 'Escape') hideTooltip();
});
Serious: ARIA Pattern Must Be Correct
Incorrect ARIA on tooltips is Serious — AT users receive wrong or no
supplementary information.
<button type="button" aria-describedby="save-tooltip">Save</button>
<div id="save-tooltip" role="tooltip" hidden>
Save changes to your draft
</div>
Rules:
- Tooltip element must have
role="tooltip"
- Trigger must reference tooltip via
aria-describedby (not aria-labelledby)
- Use
hidden to conceal; never aria-hidden="true" on an active tooltip
- Each tooltip must have a unique
id
- Do not put
role="tooltip" on the trigger itself
- Tooltips must not be focusable — no
tabindex on the tooltip container
For icon-only triggers, add aria-label for the accessible name:
<button type="button"
aria-label="Delete item"
aria-describedby="delete-tip">
</button>
<div id="delete-tip" role="tooltip" hidden>
Permanently removes this item from your account
</div>
Moderate: WCAG 1.4.13 — Content on Hover or Focus
| Requirement | Description | Severity if failing |
|---|
| Dismissible | Escape dismisses without moving pointer or focus | Serious |
| Hoverable | User can move pointer over tooltip without it disappearing | Moderate |
| Persistent | Stays visible until trigger loses focus/hover | Moderate |
Moderate: Touch / Mobile — Toggletip Pattern
Hover tooltips do not work on touch screens. Use the toggletip pattern:
<button type="button"
aria-expanded="false"
aria-controls="info-tip"
aria-label="More information about password requirements">
<span aria-hidden="true">ⓘ</span>
</button>
<div id="info-tip" hidden>
Your password must be at least 12 characters and include a number.
</div>
Toggle aria-expanded and hidden together on click.
Moderate: Visual Design
- Tooltip text: 4.5:1 contrast against tooltip background
- Tooltip background: 3:1 contrast against adjacent surfaces
- Respect
prefers-reduced-motion:
@media (prefers-reduced-motion: no-preference) {
[role="tooltip"] { transition: opacity 0.15s ease; }
}
When NOT to Use a Tooltip
- Label of control is self-explanatory
- Information must be readable at all times → use persistent help text
- Touch-only interface → use toggletip or persistent help text
- Content is long → use a popover or disclosure
- Content contains interactive elements (links, buttons) → use a popover
Definition of Done Checklist
Key WCAG Criteria
- 1.4.3 Contrast Minimum (AA)
- 1.4.13 Content on Hover or Focus (AA) — Serious if hover-only
- 2.1.1 Keyboard (A) — Serious if keyboard cannot trigger tooltip
- 4.1.2 Name, Role, Value (A)
References
Standards horizon: WCAG 3.0 is in development; 1.4.13 requirements are
expected to carry forward.
Monitor: https://www.w3.org/TR/wcag-3.0/
