# Tooltip

One line of text next to a control, shown on pointer rest or keyboard focus, that names it, shows its shortcut, shows a truncated value in full or says why it is unavailable.

* Kind: component
* Page: https://design.werklist.com/components/tooltip
* Version: 2.1.2

## When to use it

* An icon button without a visible label
* A control with a keyboard shortcut
* A truncated value, to show it in full
* An unavailable control, to say what would make it available

## When not to use it

* Anything people need to finish a task
* Links, buttons or formatted text: use a popover
* System feedback: use a toast or an inline message
* Touch screens: tooltips do not show there
* Repeating a visible label
* Tips that open by themselves to teach a feature

## Anatomy

* Layer: above the page (--layer-popover)
* Text: 12 px on an 18 px line, weight 400 (--text)
* Padding: 4 px above and below, 8 px at the sides (--space-1, --space-2)
* Height: 26 px, 30 px with a keycap
* Radius: 8 px (--radius-lg)
* Surface: translucent glass under a 36 px blur, with an inset top highlight, a 1 px inset rim and a soft shadow. Solid where the blur cannot render or transparency is reduced
* Gap and window margin: 8 px and at least 8 px (--space-2)
* Maximum width: the window width less 16 px
* Keycap: 11 px on a 16 px line, weight 500, tabular, at least 26 px wide, 22 px high, radius 6 px, a 1 px inset edge in the border ink (--surface-control, --border, --text-label, --radius-md)

## States

* Showing on pointer rest: After 500 ms, fades in over 150 ms with 4 px of travel away from the control (--duration-fast, --ease-soft)
* Showing on keyboard focus: At once, same fade (--duration-fast)
* Moving between triggers: The next shows at once while one is showing
* Hiding: When the pointer leaves both the control and the tooltip, when focus leaves, on Escape, on a press. Fades over 150 ms (--duration-fast, --ease-standard)
* Reduced motion: The fade stays, the travel goes (--duration-fast)
* Touch screen: Does not show

## Keyboard

* Tab onto the control: Shows the tooltip at once
* Escape: Hides the tooltip. Focus stays on the control

## Accessibility

* role tooltip with an id. The control references it with aria-describedby when the tooltip adds to the name
* When the tooltip repeats an icon button's aria-label, the tooltip is aria-hidden true
* aria-keyshortcuts on the control for its shortcut
* Unavailable controls that explain themselves use aria-disabled true, not disabled, so they receive hover and focus
* The native title attribute is removed from any control with a tooltip
* People can move the pointer onto the tooltip. It stays while hovered or focused and does not time out
* Escape hides the tooltip before it closes anything behind it

## Content

* A verb phrase or a noun phrase in sentence case, with no full stop
* Not the visible label again
* For an unavailable control, the condition: Select a candidate first
* At most 60 characters

## Tokens

* --layer-popover
* --radius-lg
* --radius-md
* --space-1
* --space-2
* --text
* --text-label
* --surface-control
* --border
* --duration-fast
* --ease-soft
* --ease-standard