Build Assets
UI Component
Tooltip
Contextual label that appears on hover/focus to clarify a UI element.
Platform: bothTags: tooltip, hint, label, help, hover
Purpose
Reveals supplementary information on hover or focus for elements whose purpose is not self-evident. Use for icon-only buttons, truncated text, and keyboard shortcuts. Not for critical information — users on touch devices cannot hover.
Anatomy
- Container: dark pill or rect (navy or #1E1E2E), 6–8px radius
- Text: 12–13px, white, max 1–2 lines (~40 chars)
- Arrow: 6px triangle pointing to the trigger
- Position: top by default, auto-flip to avoid viewport edge
States
- Hidden: invisible, no space reserved
- Visible: fade in (150ms) after 300ms hover delay
- Focus-visible: shown immediately on keyboard focus (no delay)
- Exit: fade out 100ms on mouse leave
Tokens
spacing
padding: 6px 10pxarrowSize: 6pxoffset: 8px
sizing
maxWidth: 240pxborderRadius: 6px
Do
- Use for icon-only buttons — always provide a tooltip label
- Keep content to one short sentence or a keyboard shortcut
- Delay appearance by 300ms to avoid flickering during mouse movement
- Position to avoid covering related content
Don't
- Put critical information only in a tooltip — touch users will never see it
- Use tooltips for long explanations — use a popover or inline help instead
- Show tooltips on mobile touch — use a visible label instead
- Use tooltips on disabled elements without explaining why it's disabled
Accessibility
- role="tooltip" on the container
- aria-describedby on the trigger pointing to tooltip id
- Shown on focus-visible (keyboard), not just on mouse hover
- Never put interactive content (links, buttons) inside a tooltip