Tooltip

A short label for a control whose meaning is not obvious — and the one place where a disabled action can say why it is off. <Tooltip> opens on hover and on keyboard focus after 80 ms, portals the bubble to <body> and puts it above everything else (z-index: 120), so it is never clipped (packages/ui/src/components/Tooltip.tsx, .acrm-tooltip in apps/web/src/ds.css).

The native title attribute is not used on controls: it is slow, unstyled and invisible to touch.

When to use

• An icon-only control: the tooltip says on screen what aria-label says to a screen reader.
• A disabled action: one sentence about what is missing (Doplňte adresáta a předmět).
• A value shortened in a row: the bubble carries the full text.

When not to use

• Information the user needs in order to act — put it in the UI. A tooltip is not a hiding place for a label or a hint.
• Anything interactive: the bubble is pointer-events: none, so it holds no links or buttons.
• Long explanations, tables or lists — those belong in the screen or in a dialog.
• Touch-only surfaces as the sole channel: there is no hover on a phone.

Anatomy

• Wrapper .acrm-tooltip-wrap: an inline-flex span around the trigger; it listens for pointer enter/leave and focus/blur.
• Bubble .acrm-tooltip: fixed, z-index: 120, max-width: 280px, padding var(--sp-1) var(--sp-2), --ink-900 fill with white text, font: var(--small) at 500, radius-sm, --shadow-pop, pointer-events: none.
• Placement: centred above the trigger, flipping below when there is no room, clamped 8px from the viewport edges. There is no left/right placement and no arrow.
• Delay: 80 ms on show, immediate on hide.

Best practices

Do

• Keep it to one sentence that would fit on a button if there were room.
• Pair it with aria-label on icon-only controls — the tooltip is the visual half, the label the spoken one.
• Use it on disabled actions; that is the case where users most often get stuck.
• Wrap exactly one focusable element: the component clones aria-describedby onto a single child.

Don't

• Put a heading, a list or a link inside it.
• Explain a label with a tooltip when the label itself could be clearer.
• Use title next to it — two bubbles for one control.
• Rely on it for anything essential on touch.

Content

• One sentence, sentence case, no trailing period unless it is a full sentence with a verb.
• Say the act or the obstacle: Přidat přílohu, Doplňte adresáta a předmět.
• Never repeat the visible label word for word.

Related

• popover — for anything the user must click.
• entity-preview — the hover card for record references (300 ms, interactive).
• icon-button — the control that most often needs a tooltip.
• Stories: components--tooltip--default, --variants, --states, --composition; legacy overview components--tooltip.