Tooltip

1import { Tooltip } from '@/ui/Display'23// The label is on the BUTTON. The tooltip repeats it for sighted pointer4// users — it is never the accessible name.5<Tooltip content="Archive deployment" shortcut="E">6  <IconButton label="Archive deployment" icon={<Archive />} />7</Tooltip>89// A disabled control fires no pointer or focus events, so the tooltip needs10// a reachable host — and the reason is exactly what makes the dead end useful.11<Tooltip content="You need write access to deploy">12  <span tabIndex={0} className="inline-flex">13    <Button disabled>Deploy</Button>14  </span>15</Tooltip>1617// The delay is doing real work: a pointer crossing a toolbar must not trigger18// anything, but once one tooltip is open the next should be instant.19const warm = React.useRef(false)20const show = () => {21  const delay = warm.current ? 0 : 40022  timer.current = window.setTimeout(() => {23    setOpen(true)24    warm.current = true25  }, delay)26}27const hide = () => {28  window.clearTimeout(timer.current)29  setOpen(false)30  // Grace period: scanning a toolbar stays instant for a moment.31  window.setTimeout(() => { warm.current = false }, 300)32}3334// WCAG 1.4.13: dismissible without moving the pointer or focus.35React.useEffect(() => {36  if (!open) return37  const onKey = (e: KeyboardEvent) => e.key === 'Escape' && setOpen(false)38  document.addEventListener('keydown', onKey)39  return () => document.removeEventListener('keydown', onKey)40}, [open])

<!-- aria-label is the name. The tooltip DESCRIBES; it does not name. -->
<button
  type="button"
  aria-label="Archive deployment"
  aria-describedby="tip-archive"
>
  <svg aria-hidden="true">…</svg>
</button>

<div id="tip-archive" role="tooltip">
  Archive deployment
  <kbd>E</kbd>
</div>

<!-- A disabled control fires no events: give the tooltip a reachable host. -->
<span tabindex="0" aria-describedby="tip-deploy">
  <button type="button" disabled>Deploy</button>
</span>
<div id="tip-deploy" role="tooltip">You need write access to deploy</div>

[role='tooltip'] {
  position: absolute;
  z-index: 90;
  /* Inverted, so it never reads as a panel you could click into. */
  background: var(--ds-fg);
  color: var(--ds-fg-inverse);
  padding: 6px 10px;
  border-radius: var(--radius-md);
  font-size: 12px;
  line-height: 1.4;
  /* The ceiling is the point: three lines means it should be a Popover. */
  max-inline-size: 16rem;
  box-shadow: var(--shadow-e3);
  /* Never intercepts the pointer — a tooltip must not block what it labels. */
  pointer-events: none;
  animation: tooltip-in 120ms ease-out both;
}

@keyframes tooltip-in {
  from { opacity: 0; translate: 0 2px; }
  to   { opacity: 1; translate: 0 0; }
}

/* A Kbd on an already-inverted surface needs its own colours, not the ones
   tuned for a light panel. */
[role='tooltip'] kbd {
  border-color: rgb(255 255 255 / 0.25);
  background: rgb(255 255 255 / 0.1);
  color: inherit;
}

/* The only signal that a run of text has a tooltip at all. */
[data-tooltip-trigger='text'] {
  border-block-end: 1px dotted var(--ds-border-strong);
  cursor: help;
}

@media (prefers-reduced-motion: reduce) {
  [role='tooltip'] { animation: none; }
}

/* There is no hover here, and long-press belongs to the platform. */
@media (pointer: coarse) {
  [role='tooltip'] { display: none; }
}