{
  "generatedFrom": "tooltip.contract.json",
  "component": "Tooltip",
  "slug": "tooltip",
  "group": "Data Display",
  "tier": "leaf-lit",
  "summary": "A short, transient hint shown on hover or focus of its trigger.",
  "install": {
    "package": "@ahaslides-product/design",
    "registry": "https://npm.pkg.github.com",
    "scope": "@ahaslides-product",
    "auth": "Published to GitHub Packages — needs a GitHub token with read:packages. Configure the @ahaslides-product scope in .npmrc before installing.",
    "npmrc": "@ahaslides-product:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}   # a GitHub token with read:packages",
    "command": "npm i @ahaslides-product/design",
    "tokenLayer": "import '@ahaslides-product/design/tokens.css';",
    "import": "import '@ahaslides-product/design/aha-tooltip';",
    "element": "aha-tooltip",
    "registers": "aha-tooltip"
  },
  "feeds": {
    "doc": "https://ahaslides-product.github.io/ahaslides-design/tooltip/index.html",
    "md": "https://ahaslides-product.github.io/ahaslides-design/tooltip/tooltip.md",
    "agentJson": "https://ahaslides-product.github.io/ahaslides-design/tooltip.agent.json",
    "llms": "https://ahaslides-product.github.io/ahaslides-design/tooltip.llms.txt",
    "index": "https://ahaslides-product.github.io/ahaslides-design/llms.txt"
  },
  "recommendedSnippet": "html",
  "vibeCode": "Emit the HTML snippet by default — <aha-tooltip> is a standard custom element that renders on open — React/Vue are thin adapters over the same element. Paste into an .html file and it renders with no build step.",
  "frameworks": {
    "react": {
      "via": "web-component",
      "ref": "aha-tooltip"
    },
    "vue": {
      "via": "web-component",
      "ref": "aha-tooltip"
    },
    "html": {
      "via": "web-component",
      "ref": "aha-tooltip",
      "runnable": "paste-and-run — no build step, renders on open"
    }
  },
  "props": [
    {
      "name": "text",
      "type": "string",
      "default": "—",
      "desc": "The hint text shown in the bubble"
    },
    {
      "name": "placement",
      "type": "'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end'",
      "default": "top",
      "desc": "Which side of the trigger the bubble + arrow sit on. The 4 cardinal values centre the bubble; the 8 edge-aligned values (…-start / …-end) align it to the trigger's start/end edge with the arrow offset near that edge (AntD naming)"
    },
    {
      "name": "color",
      "type": "'dark' | 'brand'",
      "default": "dark",
      "desc": "Bubble fill: dark-navy #1A1A2E or brand color-primary #6A1EBB"
    },
    {
      "name": "arrow",
      "type": "boolean",
      "default": "true",
      "desc": "Show the caret pointing at the trigger; arrow=\"false\" hides it"
    },
    {
      "name": "trigger",
      "type": "'hover' | 'focus' | 'click'",
      "default": "hover",
      "desc": "How it opens: hover+focus · focus only · click to toggle"
    },
    {
      "name": "open",
      "type": "boolean",
      "default": "false",
      "desc": "Force the bubble visible (demos/tests); otherwise the trigger opens it"
    },
    {
      "name": "help",
      "type": "boolean",
      "default": "false",
      "desc": "Render a built-in `?` help trigger — a focusable button carrying the DS <aha-icon name=\"system-question-mark\"> (16px, muted → brand on hover/focus) — instead of requiring a slotted trigger. The settings-label help-glyph pattern; shows on focus as well as hover"
    }
  ],
  "tokens": [
    "bg-dark",
    "color-primary",
    "text-inverse",
    "radius-sm",
    "font-product",
    "motion-mid",
    "ease-out",
    "icon-muted",
    "motion-fast",
    "radius-pill"
  ],
  "spec": [
    {
      "label": "Bubble",
      "value": "dark-navy #1A1A2E (or brand #6A1EBB), white text, radius 6, padding 6 10"
    },
    {
      "label": "Text",
      "value": "Plus Jakarta 12/18"
    },
    {
      "label": "Arrow",
      "value": "anchored to the trigger, matches the fill; `arrow=false` hides it"
    },
    {
      "label": "Placement",
      "value": "top (default) · bottom · left · right centred, PLUS 8 edge-aligned (top-start/-end, bottom-start/-end, left-start/-end, right-start/-end) — same side, aligned to the trigger edge with the arrow offset near it"
    },
    {
      "label": "Trigger",
      "value": "hover + focus (default) · focus · click (toggle, Esc/click-away to close); `open` forces it visible"
    },
    {
      "label": "Help",
      "value": "`help` renders a built-in `?` trigger — a DS <aha-icon name=\"system-question-mark\"> at 16px, muted (--aha-icon-muted #8A8A8A) → brand (#6A1EBB) on hover/focus — the settings-label help glyph; focusable, so it shows on focus, not hover-only"
    },
    {
      "label": "a11y",
      "value": "role=tooltip, aria-describedby wired to the active trigger (slotted, or the built-in help button), shows on focus, no leaked listeners"
    }
  ],
  "opinion": {
    "whenToUse": [
      {
        "what": "Tooltip",
        "when": "a brief, non-essential hint — an icon-only button's name, a ? help elaboration"
      },
      {
        "what": "help text",
        "when": "a must-see consequence that is hard to undo — put it inline, not in a tooltip"
      },
      {
        "what": "Popover",
        "when": "richer content or interactive controls — a tooltip is text only"
      }
    ],
    "note": "Never hide essential information in a tooltip — it is unavailable on touch and to keyboard users who don't focus the trigger. Keep it to a short phrase; the trigger must be focusable.",
    "dsv3": "COVERED — enumerated from the DS V3 / AntD Tooltip matrix: `placement` now ships the FULL 12-placement set — the 4 cardinal sides (top/bottom/left/right, centred) PLUS the 8 edge-aligned ones (top-start, top-end, bottom-start, bottom-end, left-start, left-end, right-start, right-end — same side, aligned to the trigger's start/end edge with the arrow offset near that edge, AntD naming) — a `title` (our `text`), a `color` (default dark vs a brand fill), an `arrow` on/off, and `trigger` (hover/focus/click). All ship on the element. The measured DS V3 `tooltip|card` cell is a distinct rich 260px info CARD (white text, 16px padding, an icon) — a popover, not this simple text hint — and remains a separate future component. This `aha-tooltip` is the dark-navy hint bubble the settings skill's `?` help tooltip points to; spec derived from that convention + tokens (bg-dark, color-primary, text-inverse, radius-sm, 12/18). Motion is the shared .2s ease-out pop on a PERSISTENT node (class/attr toggle, never a subtree rebuild — the historic MOTION_DEBT trap is clean)."
  },
  "surfaces": [
    "editor",
    "dashboard",
    "settings",
    "audience"
  ],
  "snippets": {
    "html": "<!-- Paste-and-run: save as .html and open in a browser. No build step.\n     <aha-tooltip> is the SAME shared custom element React and Vue consume — here in its\n     native form. Theming comes only from the --aha-* tokens in tokens.css. Hover the trigger. -->\n<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/gh/ahaslides-product/ahaslides-design@master/lib/tokens.css\">\n<script type=\"module\">\n  import 'https://cdn.jsdelivr.net/gh/ahaslides-product/ahaslides-design@master/lib/aha-tooltip.js';   // registers <aha-tooltip>\n</script>\n\n<div style=\"padding:48px; display:flex; gap:40px\">\n  <!-- default: dark navy, above, arrow on, shows on hover/focus -->\n  <aha-tooltip text=\"Copy share link\">\n    <button style=\"font-family:'Plus Jakarta Sans',sans-serif\">Share</button>\n  </aha-tooltip>\n\n  <!-- placement + a brand fill + no arrow + click to toggle -->\n  <aha-tooltip text=\"Opens below on click\" placement=\"bottom\" color=\"brand\" arrow=\"false\" trigger=\"click\">\n    <button style=\"font-family:'Plus Jakarta Sans',sans-serif\">More</button>\n  </aha-tooltip>\n\n  <!-- edge-aligned: same side, aligned to the trigger's start edge, arrow offset near it -->\n  <aha-tooltip text=\"Aligned to the left edge\" placement=\"bottom-start\">\n    <button style=\"font-family:'Plus Jakarta Sans',sans-serif\">Aligned</button>\n  </aha-tooltip>\n\n  <!-- help: the built-in `?` trigger — a DS <aha-icon name=\"system-question-mark\"> at 16px, muted →\n       brand on hover/focus. No slotted trigger needed; it's focusable, so it shows on focus too.\n       The settings-label help-glyph pattern (sits next to a setting name). -->\n  <label style=\"display:inline-flex; align-items:center; gap:6px; font-family:'Plus Jakarta Sans',sans-serif\">\n    Shuffle options\n    <aha-tooltip help text=\"Randomise the order options appear in for each participant\"></aha-tooltip>\n  </label>\n</div>\n",
    "react": "import '@ahaslides-product/design/aha-tooltip';   // registers <aha-tooltip>\n\n// Attributes + slotted trigger only — no events — so React 18/19 can render it directly.\n// placement: top | bottom | left | right (centred) OR edge-aligned top-start | top-end |\n//   bottom-start | bottom-end | left-start | left-end | right-start | right-end\n// color: dark | brand · arrow: true|false · trigger: hover|focus|click · help: built-in ? trigger\nfunction AhaTooltip({ text, placement, color, arrow, trigger, help, children }) {\n  return (\n    <aha-tooltip text={text} placement={placement} color={color} arrow={arrow} trigger={trigger} help={help ? '' : undefined}>\n      {children}\n    </aha-tooltip>\n  );\n}\n\n// usage — wrap the focusable trigger; never hide essential info in a tooltip\n// edge-aligned: same side as `bottom`, aligned to the trigger's start edge, arrow near it\n<AhaTooltip text=\"Copy share link\" placement=\"bottom-start\" color=\"brand\">\n  <button aria-label=\"Copy share link\">Share</button>\n</AhaTooltip>\n\n// help — the built-in `?` trigger (DS <aha-icon>, 16px muted → brand); no slotted child needed,\n// focusable so it shows on focus, not hover-only. The settings-label help-glyph pattern.\n<label style={{ display: 'inline-flex', alignItems: 'center', gap: 6 }}>\n  Shuffle options\n  <AhaTooltip help text=\"Randomise the order options appear in for each participant\" />\n</label>\n",
    "vue": "// main.ts — register the element + mark aha-* as custom elements\nimport '@ahaslides-product/design/aha-tooltip';\napp.config.compilerOptions.isCustomElement = (tag) => tag.startsWith('aha-');\n\n// Component.vue — placement: top|bottom|left|right (centred) OR edge-aligned\n//   top-start|top-end|bottom-start|bottom-end|left-start|left-end|right-start|right-end\n//   · color: dark|brand · arrow: true|false · trigger: hover|focus|click · help: built-in ? trigger\n<template>\n  <aha-tooltip text=\"Copy share link\" placement=\"bottom-start\" color=\"brand\">\n    <button aria-label=\"Copy share link\">Share</button>\n  </aha-tooltip>\n\n  <!-- help — the built-in `?` trigger (DS <aha-icon>, 16px muted → brand); no slotted child,\n       focusable so it shows on focus, not hover-only. The settings-label help-glyph pattern. -->\n  <label style=\"display:inline-flex; align-items:center; gap:6px\">\n    Shuffle options\n    <aha-tooltip help text=\"Randomise the order options appear in for each participant\" />\n  </label>\n</template>\n"
  }
}