{
  "id": "tooltip",
  "name": "Tooltip",
  "level": "molecule",
  "status": "stable",
  "purpose": "A short label that appears on hover or focus.",
  "description": "**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.\n\n**When to use.**\n- Reveal the name of an `IconButton` whose glyph is the only visible affordance.\n- Reveal a keyboard shortcut paired with a labelled control (`Save` + `⌘ S`).\n- Disambiguate a truncated text or a status glyph in a dense surface.\n\n**When NOT to use.**\n- Critical information the user must read → use visible copy. Tooltips are not always exposed by assistive tech and disappear on blur.\n- An interactive payload (links, buttons, forms) → use `Popover`. Tooltip is non-interactive.\n- A long description that exceeds one line → use `Popover` or inline text.\n- Mobile-first surfaces where there is no hover → use visible labels.\n\n**Composes with.**\n- `IconButton` (the canonical pairing — Tooltip names the icon-only control).\n- `Kbd` (inside `TooltipContent` for shortcut hints).\n- `TooltipProvider` wraps the whole tree once at the app root; consumers do not nest it per-tooltip.\n\n**Accessibility.**\n- Renders `role=\"tooltip\"`; the trigger element receives `aria-describedby` automatically.\n- Keyboard contract: focusing the trigger opens the tooltip; `Escape` dismisses; blur dismisses. Hover is the secondary trigger, not the primary.\n- The tooltip must never be the sole source of meaning. The trigger element keeps its own accessible name (`aria-label` on `IconButton`).\n\n**Related patterns.**\n- `Patterns/Overlays · OverlayChoice` — Tooltip vs Popover vs DropdownMenu vs Dialog.\n- `Patterns/Iconography · ConsumingComponents` — Tooltip is the canonical companion for `IconButton`.\n- `Patterns/Decision Matrix · ComponentChoice` — when a Tooltip earns its ceremony.",
  "role": "overlay",
  "import": "@rrios-forge/ui/molecules/tooltip",
  "exports": [
    "Tooltip",
    "TooltipContent",
    "TooltipProvider",
    "TooltipTrigger",
    "tooltipContentVariants",
    "TOOLTIP_TONES"
  ],
  "source": "packages/ui/src/molecules/tooltip",
  "axes": [
    {
      "axis": "tone",
      "part": null,
      "values": [
        "neutral",
        "inverse"
      ],
      "default": "neutral",
      "meaning": "Which semantic colour family the element speaks in."
    }
  ],
  "needs": [
    {
      "need": "Tooltip / popover / contextual menu",
      "answer": "`Tooltip` / `Popover` / `DropdownMenu`"
    }
  ],
  "patterns": [
    "Patterns/Overlays · OverlayChoice",
    "Patterns/Decision Matrix · ComponentChoice",
    "Patterns/Iconography · ConsumingComponents"
  ],
  "a11yExceptions": [],
  "decisions": [
    {
      "id": "ADR-007",
      "title": "Material highlight on raised surfaces"
    },
    {
      "id": "ADR-018",
      "title": "Motion language as a Pattern Layer contract"
    }
  ],
  "stories": [
    {
      "name": "Playground",
      "id": "components-molecules-tooltip--playground",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-tooltip--playground",
      "frame": "/iframe.html?id=components-molecules-tooltip--playground&viewMode=story"
    },
    {
      "name": "Tones",
      "id": "components-molecules-tooltip--tones",
      "interaction": false,
      "snapshots": [
        "dark",
        "high-contrast",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-tooltip--tones",
      "frame": "/iframe.html?id=components-molecules-tooltip--tones&viewMode=story"
    },
    {
      "name": "With shortcut",
      "id": "components-molecules-tooltip--with-shortcut",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-tooltip--with-shortcut",
      "frame": "/iframe.html?id=components-molecules-tooltip--with-shortcut&viewMode=story"
    },
    {
      "name": "In toolbar",
      "id": "components-molecules-tooltip--in-toolbar",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-tooltip--in-toolbar",
      "frame": "/iframe.html?id=components-molecules-tooltip--in-toolbar&viewMode=story"
    }
  ],
  "storyFile": "tooling/storybook/stories/components/molecules/tooltip.stories.tsx"
}