# Tooltips

Tooltips provide concise, supplemental context for a focused or hovered control or value. Kantoku and Superviso both register the PrimeVue tooltip directive and use tooltips for icon meaning, exact timestamps, truncated values, disabled-action reasons, and short metadata explanations.

The visual and behavioral contract is shared; the framework wrapper remains application-owned while the products use different PrimeVue versions.

## Appropriate uses

- Explain an unfamiliar icon while retaining an accessible name on the control.
- Reveal a complete timestamp or truncated value already represented on screen.
- Give a short reason why an action is unavailable.
- Clarify compact metadata when displaying it inline would create disproportionate noise.

Do not use a tooltip for required instructions, validation, critical warnings, long definitions, or interactive content. Use visible help text, a banner, a popover, or documentation instead.

## Behavior

1. Open on pointer hover and keyboard focus.
2. Dismiss when hover or focus leaves, and on Escape.
3. Prefer automatic positioning; use top placement when there is sufficient room.
4. Keep the tooltip within the viewport and avoid covering the trigger or the next likely target.
5. For disabled controls that cannot receive focus or pointer events, attach the tooltip to a focusable wrapper and expose the unavailable reason programmatically.
6. Do not make tooltip content selectable or interactive. Use a popover when the content contains actions or links.

## Content

Write one concise phrase or, at most, two short lines. Do not repeat visible text. Sentence case is preferred; terminal punctuation is optional for a short label and expected for a complete sentence.

Use a maximum width of approximately 240px. Tooltips use the inverse surface and text tokens, a compact 6px radius, and restrained elevation.

## Accessibility

Associate the tooltip with its trigger using `aria-describedby`. An icon-only button still requires its own `aria-label`; the tooltip is supplemental and must not be the control's only accessible name.

Do not rely on hover alone. Ensure the same content is available on keyboard focus and consider a visible alternative for touch-only workflows where the information is necessary.