A tooltip gives an icon-only button a short name when the user hovers it or moves keyboard focus to it. Esc hides it.
Tokens, sizes, spacing, states and requirements. Values come from the live token package and from Figma: Tooltip.
Resolved from the live token package.
| State | Part | Token | Value |
|---|
The background is surface-100 at 90% opacity (in the CSS: rgba(0, 0, 0, 0.9), because the opacity applies to the fill only, not to the text). Font is Breuer Condensed regular with ss02, ss03, ss06. The shadow is elevation-b-40: 0 2px 4px at 10% black plus 0 0 1px at 5% black.
| Size | Padding | Type |
|---|---|---|
| Small (default) | 8px 16px | 14/20, 0.36px, regular (body-sm) |
Large (tooltip--lg) | 12px 16px | 18/26, 0.36px, regular |
Use Small for icon buttons in toolbars and table rows. Add tooltip--lg for Large.
Padding and size of each tooltip size. The shaded areas are the padding; the lines show its value.
| Attribute | Small (default) | Large (tooltip--lg) |
|---|---|---|
| Padding, top and bottom | 8px | 12px |
| Padding, left and right | 16px | 16px |
| Line height | 20px | 26px |
| Height, one line | 36px | 50px |
| Maximum width | 280px, and never wider than the window minus 8px on each side | |
| Corners | Square | |
The same padding and the beak and distance values as spacing tokens.
| Size | Vertical | Horizontal |
|---|---|---|
| Small (default) | space-8 | space-16 |
Large (tooltip--lg) | space-12 | space-16 |
| Part | Value |
|---|---|
| Beak size | 6px high, 12.696px wide (rotated for the side types: 6px wide, 12.696px high) |
| Beak offset (Left, Right, Top Left, Top Right, Bottom Left, Bottom Right) | 16px from the edge of the tooltip, to the near edge of the beak |
| Beak offset (Left Top, Right Top) | 16px from the top of the tooltip |
| Distance to the element | The tip of the beak is 4px from the element (space-4), so the tooltip block is 10px away. This is a repo rule: the Figma frame holds no element. |
The shadow is elevation-b-40: 0 2px 4px at 10% black plus 0 0 1px at 5% black.
| Topic | Rule |
|---|---|
| Layer | z-index: var(--tooltip-z, 300), elevation-b-40 shadow. A page with a sticky header sets --tooltip-z below the header’s z-index on :root, so a tooltip never paints over the menu. |
Two triggers: hover and keyboard focus (:focus-visible) fade the tooltip in over duration-fast-2 with ease-standard. The tooltip has pointer-events: none so it never gets in the way.
| State | Preview | Result |
|---|
| Size | Type | Size / line height | Letter spacing | Weight |
|---|---|---|---|---|
| Small (default) | body-sm | 14/20 | 0.36px | Regular |
Large (tooltip--lg) | As drawn in Figma | 18/26 | 0.36px | Regular |
Breuer Condensed with ss02, ss03 and ss06. Never uppercase, also when the tooltip sits inside an uppercase button. Large uses 18/26 as drawn in Figma: no type token has this pair (body-lg is 18/24 on mobile).
| Element | Property | Value |
|---|---|---|
| Container | Fill | Surface 100 at 90% opacity (opacity on the fill only, not on the text) |
| Container | Corners, border | Square, none |
| Label | Length | One to three words |
| Caret (beak) | Size | 6px high, 12.696px wide. Absent on Body. |
| Caret (beak) | Position | Points at the center of the trigger, 4px from it. On the start and end types it sits 16px from the edge of the tooltip. |
| Trigger | Element | Usually an icon button. The tooltip shows when the user hovers it. |
Figma has 11 types in Small and 9 in Large. The Figma name says where the beak sits on the tooltip, not where the tooltip sits next to the element. Figma “Bottom” is a tooltip above the element, with the beak at its bottom. The CSS class names describe the placement, so they are the opposite.
| Figma type | Beak | Tooltip sits | Small | Large | Class |
|---|---|---|---|---|---|
| Body | None | — | Yes | Yes | tooltip--body |
| Bottom | Bottom edge, centered, points down | Above the element | Yes | Yes | tooltip--top |
| Bottom Left | Bottom edge, 16px from the left, points down | Above the element | Yes | Yes | tooltip--top-start |
| Bottom Right | Bottom edge, 16px from the right, points down | Above the element | Yes | Yes | tooltip--top-end |
| Top | Top edge, centered, points up | Below the element | Yes | Yes | tooltip--bottom |
| Top Left | Top edge, 16px from the left, points up | Below the element | Yes | Yes | tooltip--bottom-start |
| Top Right | Top edge, 16px from the right, points up | Below the element | Yes | Yes | tooltip--bottom-end |
| Left Middle | Left edge, vertically centered, points left | Right of the element | Yes | Yes | tooltip--right |
| Right Middle | Right edge, vertically centered, points right | Left of the element | Yes | Yes | tooltip--left |
| Left Top | Left edge, 16px from the top, points left | Right of the element | Yes | No | tooltip--right-start |
| Right Top | Right edge, 16px from the top, points right | Left of the element | Yes | No | tooltip--left-start |
Small widths in Figma are 59px (top/bottom types) and 65px (side types), set by the sample text “Tooltip”. In use, the width follows the text (white-space: nowrap).
One line when the text fits, otherwise it wraps at max-width: min(280px, 100vw − 16px): never wider than 280px and never wider than the window minus the 8px edge margin. The tooltip is width: max-content, so a short label is as wide as its text.
| Property | Duration | Easing |
|---|---|---|
opacity, hover in and out | duration-fast-2 | ease-standard |
Top and Bottom tooltips are automatic by default. components/js/tooltip.js and CSS anchor positioning do the work:
tooltip--align-start or tooltip--align-end.tooltip--flip). CSS alone cannot do this: a browser picks a flip from the layout-time scroll position, which is wrong on a page that scrolls.--tooltip-safe-top (the height of the header), so room above counts from below the header.tooltip--manual to keep a tooltip fixed and centered.position: fixed, so a clipping container cannot cut it off. Where anchor positioning is not supported, the tooltip stays centered, as in manual mode.| Topic | Requirement |
|---|---|
| Trigger | Hover over the wrapper (.tooltip-wrap:hover) or keyboard focus on the trigger (:focus-visible, not the focus a mouse click gives). Esc hides it without moving focus (WCAG 1.4.13 dismissible). |
| Name | aria-label on the button with the same text as the tooltip. The tooltip itself is not announced. |
| Text | One to three words. No information the user needs to complete a task: it disappears when the pointer moves away. |
| Interactive content | None. A tooltip cannot take focus, so it never holds a button, link or image. Use a Toggletip (TBA). |
Open point: hoverable (WCAG 1.4.13). The tooltip has pointer-events: none, so the pointer cannot move onto it to read it. Persistent and dismissible are met (it stays until the pointer or focus leaves, Esc hides it). Hoverable would need a pointer-reachable tooltip, which conflicts with “never in the way”. To be decided.