# Tooltip

> A short label that appears on hover or focus.

- **Level**: molecule · **Status**: stable · **Role**: overlay
- **Import**: `import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@rrios-forge/ui/molecules/tooltip";`
- **Source**: `packages/ui/src/molecules/tooltip`

**Purpose.** A short label that describes a target on hover or focus. Composes `@radix-ui/react-tooltip` for the ARIA contract: `role="tooltip"`, focus + hover triggers, escape-to-dismiss, single-trigger inheritance.

**When to use.**
- Reveal the name of an `IconButton` whose glyph is the only visible affordance.
- Reveal a keyboard shortcut paired with a labelled control (`Save` + `⌘ S`).
- Disambiguate a truncated text or a status glyph in a dense surface.

**When NOT to use.**
- Critical information the user must read → use visible copy. Tooltips are not always exposed by assistive tech and disappear on blur.
- An interactive payload (links, buttons, forms) → use `Popover`. Tooltip is non-interactive.
- A long description that exceeds one line → use `Popover` or inline text.
- Mobile-first surfaces where there is no hover → use visible labels.

**Composes with.**
- `IconButton` (the canonical pairing — Tooltip names the icon-only control).
- `Kbd` (inside `TooltipContent` for shortcut hints).
- `TooltipProvider` wraps the whole tree once at the app root; consumers do not nest it per-tooltip.

**Accessibility.**
- Renders `role="tooltip"`; the trigger element receives `aria-describedby` automatically.
- Keyboard contract: focusing the trigger opens the tooltip; `Escape` dismisses; blur dismisses. Hover is the secondary trigger, not the primary.
- The tooltip must never be the sole source of meaning. The trigger element keeps its own accessible name (`aria-label` on `IconButton`).

**Related patterns.**
- `Patterns/Overlays · OverlayChoice` — Tooltip vs Popover vs DropdownMenu vs Dialog.
- `Patterns/Iconography · ConsumingComponents` — Tooltip is the canonical companion for `IconButton`.
- `Patterns/Decision Matrix · ComponentChoice` — when a Tooltip earns its ceremony.

## Use it for

- Tooltip / popover / contextual menu → `Tooltip` / `Popover` / `DropdownMenu`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `tone` | — | `neutral` `inverse` | `neutral` | Which semantic colour family the element speaks in. |

## Stories

- [Playground](/?path=/story/components-molecules-tooltip--playground) · frame: `/iframe.html?id=components-molecules-tooltip--playground&viewMode=story`
- [Tones](/?path=/story/components-molecules-tooltip--tones) · frame: `/iframe.html?id=components-molecules-tooltip--tones&viewMode=story`
- [With shortcut](/?path=/story/components-molecules-tooltip--with-shortcut) · frame: `/iframe.html?id=components-molecules-tooltip--with-shortcut&viewMode=story`
- [In toolbar](/?path=/story/components-molecules-tooltip--in-toolbar) · frame: `/iframe.html?id=components-molecules-tooltip--in-toolbar&viewMode=story`

## Patterns consulted

- Patterns/Overlays · OverlayChoice
- Patterns/Decision Matrix · ComponentChoice
- Patterns/Iconography · ConsumingComponents

## Decisions that name it

- ADR-007 — Material highlight on raised surfaces
- ADR-018 — Motion language as a Pattern Layer contract

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).