--- name: tooltip-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit Tooltip for supplemental hover/focus help using the Zag.js tooltip wrapper, supported timing, placement, interaction, controlled state, and token styling props. metadata: component_version: "2.0.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "https://zagjs.com/components/react/tooltip" contributor_sources: "libs/ui/src/atoms/tooltip.tsx libs/ui/src/tokens/components/atoms/_tooltip.css libs/ui/stories/atoms/tooltip.stories.tsx libs/ui/src/atoms/tooltip.figma.ts" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Tooltip Usage Use Tooltip for short supplemental information on hover/focus. Do not use it for required instructions, blocking errors, or primary content. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `Tooltip`. **Use it when** - Short, non-essential hints on hover and focus: icon-button names, truncated text, keyboard shortcuts. **Use something else when** | Need | Use instead | | --- | --- | | Required information or instructions | visible help text | | Interactive content | Popover | | Errors | inline StatusText / field error | **Do** - Keep to a few words; repeat the ActionIcon's `aria-label`. - Attach to focusable triggers so keyboard users get it too. - Use for the full value of truncated cells. **Don't** - Put tooltips on disabled buttons (they don't receive hover/focus) — explain next to the control. - Put links or buttons inside a tooltip. - Use tooltips on touch-only surfaces as the only explanation. **Copy and states** - No trailing period for fragments; sentence case. **Behaviour (from the UX spec)** - The task must make sense without the hint, including on touch screens where there is no hover. - The bubble stays open while the pointer moves onto it (`interactive`, default) and Escape closes it without moving focus. - Never the only place for a format or instruction a field needs; show that as help text. **Figma → code** | Figma | Code | | --- | --- | | `placement=…` (8 values) | `placement` (any Zag placement; flips on collision) | | `Tooltip/md/default/right-start` frame | `size="md" appearance="solid" placement="right-start"` | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/Tooltip → UX guidelines*. ## Setup ```tsx import { ActionIcon } from "@techsio/ui-kit/atoms/action-icon" import { Tooltip } from "@techsio/ui-kit/atoms/tooltip" ``` Supported UI-kit props: ```text content: ReactNode size: sm | md | lg appearance: solid | outline openDelay, closeDelay, interactive, defaultOpen, open, onOpenChange, disabled closeOnEscape, closeOnPointerDown, closeOnScroll, closeOnClick placement, gutter, offset, flip, sameWidth, boundary, listeners, strategy ``` ## Core Patterns ### Use for supplemental help only ```tsx ``` If the text is required to complete the task, render visible help text instead. ### Prefer component triggers ```tsx ``` Use UI-kit triggers (ActionIcon for icon-only, Button for text) instead of native buttons. ### Use Zag positioning props through the wrapper ```tsx ``` The wrapper maps placement/timing/dismiss behavior to the Zag machine. ## Common Mistakes ### HIGH Native title tooltip Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/atoms/tooltip.tsx ### HIGH Custom hover popover Wrong: ```tsx
{open &&
Help
}
``` Correct: ```tsx ``` Source: https://zagjs.com/components/react/tooltip ### HIGH Inline tooltip appearance Wrong: ```tsx ``` Correct: ```tsx ``` Use `_tooltip.css` or app token overrides for visual changes. Source: libs/ui/src/tokens/components/atoms/_tooltip.css ### MEDIUM Critical information hidden in tooltip Wrong: ```tsx ``` Correct: ```tsx ``` Visible field help should not depend on hover/focus discovery. ## Validation Commands ```sh rg -n "title=\"|onMouseEnter|onMouseLeave" apps rg -n "]*className=.*(bg-|text-|rounded-|px-|py-)" apps rg -U -n "