` appended directly to ``, `position: fixed`, `z-index: 99999` flat. It is **never** a CSS `::after` pseudo on the trigger, and its z-index is **never** tiered against the owner HUD. This is the only pattern that survives all three failure modes: 1. **`overflow: hidden` clipping.** A `::after` bound to its trigger's box is clipped at a HUD edge regardless of z-index if any ancestor has `overflow: hidden`. Only a `position: fixed` element outside the clipping tree escapes. 2. **Stacking contexts.** A `transform`, `filter`, `isolation`, or `z-index` on any ancestor caps the descendant's effective z-index. A `::after` on a button inside a transformed bar tops out at the bar's z, not 99999. Only a body-reparented fixed element escapes. 3. **Owner-HUD tiering.** Tiering tooltip z to `ownerHud.z + 1` breaks the instant one HUD covers another HUD's button. Do not tier. A tooltip is always topmost. ```html ``` ```css #global-tooltip { position: fixed; z-index: 99999; top: 0; left: 0; transform: translate(var(--tip-x, 0), var(--tip-y, 0)); max-width: min(320px, calc(100vw - 40px)); pointer-events: none; opacity: 0; display: none; /* brand styling */ background: rgba(22,27,34,.96); color: #e6edf3; border: 1px solid rgba(0,184,177,.28); border-radius: 10px; padding: 9px 13px; font: 400 13px/1.4 'Satoshi', sans-serif; box-shadow: 0 12px 40px rgba(0,0,0,.55); backdrop-filter: blur(16px); text-transform: none; letter-spacing: 0; /* see rule 6 */ } #global-tooltip.visible { display: block; } #global-tooltip.shown { opacity: 1; transition: opacity 0.18s ease 0.6s; } ``` ```js const tip = document.createElement('div'); tip.id = 'global-tooltip'; document.body.appendChild(tip); let _cx = 0, _cy = 0; document.addEventListener('mousemove', e => { _cx = e.clientX; _cy = e.clientY; }, true); function show(trigger) { tip.textContent = trigger.getAttribute('data-tooltip') || ''; tip.classList.add('visible'); const { x, y } = pickAnchor(trigger, tip.offsetWidth, tip.offsetHeight, _cx, _cy); tip.style.setProperty('--tip-x', x + 'px'); tip.style.setProperty('--tip-y', y + 'px'); requestAnimationFrame(() => tip.classList.add('shown')); } function hide() { tip.classList.remove('visible', 'shown'); } document.addEventListener('mouseover', e => { const t = e.target.closest('[data-tooltip]'); t ? show(t) : hide(); }); ``` ## 4. Placement: never cover what you are hovering Position is a separate concern from z-index. Anchor the tooltip **relative to the cursor**, offset ~14px into the quadrant that does not cover the cursor or the trigger. Do NOT anchor to the trigger element: inside a dense HUD that lands the tooltip far from the cursor or on top of other controls. The one cardinal sin is a tooltip that covers the thing you are hovering. ```js function pickAnchor(trigger, tipW, tipH, cx, cy) { const O = 14; const cands = [ { x: cx + O, y: cy + O }, // below-right (default) { x: cx - tipW - O, y: cy + O }, // below-left { x: cx + O, y: cy - tipH - O }, // above-right { x: cx - tipW - O, y: cy - tipH - O }, // above-left ]; const tr = trigger.getBoundingClientRect(); const vw = window.innerWidth, vh = window.innerHeight; const score = c => { let p = 0; if (c.x < 8 || c.x + tipW > vw - 8) p += 1000; // off right/left edge if (c.y < 8 || c.y + tipH > vh - 8) p += 1000; // off top/bottom edge const ox = Math.max(0, Math.min(c.x+tipW, tr.right) - Math.max(c.x, tr.left)); const oy = Math.max(0, Math.min(c.y+tipH, tr.bottom) - Math.max(c.y, tr.top)); p += ox * oy; // overlap with trigger return p; }; const best = cands.map(c => ({ c, s: score(c) })).sort((a,b)=>a.s-b.s)[0].c; // final clamp into the viewport (or nearest .panel for chrome-reduced apps) best.x = Math.max(8, Math.min(best.x, vw - tipW - 8)); best.y = Math.max(8, Math.min(best.y, vh - tipH - 8)); return best; } ``` ## 5. Edge-aware: never render off-screen Two guarantees: a `max-width` that fits the viewport (rule 3), and the clamp in `pickAnchor` that keeps the box inside the screen. If you use the simpler `::after` form anywhere, measure the trigger on `mouseenter` and flip: ```js document.addEventListener('mouseenter', e => { const el = e.target; if (!el?.matches?.('[data-tooltip]')) return; const r = el.getBoundingClientRect(), vw = innerWidth, vh = innerHeight; el.toggleAttribute('data-tooltip-v', vh - r.bottom < 240); // <240px below -> flip up el.toggleAttribute('data-tooltip-align', vw - r.left < 340); // near right edge -> right-align }, true); ``` ```css [data-tooltip][data-tooltip-v]::after { top: auto; bottom: calc(100% + 8px); } [data-tooltip][data-tooltip-align]::after { left: auto; right: 0; } ``` ## 6. One at a time, and never ALL CAPS - **One tooltip in the DOM at any moment,** belonging to the innermost `[data-tooltip]` under the cursor. Browsers fire `:hover` on every ancestor, so a button and its parent row both showing is a real bug. Suppress ancestors: ```js document.addEventListener('mouseover', e => { document.querySelectorAll('[data-tooltip-suppress]').forEach(n => n.removeAttribute('data-tooltip-suppress')); let n = e.target.closest?.('[data-tooltip]')?.parentElement; while (n && n !== document.body) { if (n.hasAttribute?.('data-tooltip')) n.setAttribute('data-tooltip-suppress', ''); n = n.parentElement; } }); ``` - **Never ALL CAPS.** `RESET CAMERA` reads as shouting. Write sentence case ("Reset the camera to the default isometric view"). If a parent sets `text-transform: uppercase`, the tooltip inherits it, so reset `text-transform: none; letter-spacing: 0` on the tooltip element (already in rule 3). For emphasis use weight (600 to 700), not caps. ## 7. The z-index ladder Declare these tokens in `:root` and reference them everywhere, never a hardcoded number, so a session can never invert the stacking order by picking a number out of thin air. ```css :root { --z-hud: 50; /* draggable HUDs */ --z-toolbar: 80; /* fixed header / footer / banner */ --z-floating-menu: 200; /* dropdowns, popovers, pickers, autocomplete */ --z-toast: 400; /* non-blocking confirmations */ --z-modal: 600; /* full-screen overlays, dialogs */ --z-tooltip: 99999; /* always on top */ } ``` A floating menu beats a toolbar so a dropdown can escape the toolbar's box. A tooltip sits two orders of magnitude above everything so it always wins. Note the separate, non-z-index trap: `overflow: hidden` on an ancestor clips an absolutely-positioned descendant regardless of z-index. Fix with `overflow-x: clip; overflow-y: visible`, or reposition the element to `position: fixed`. ## Touch and mobile Hover does not exist on a phone, so a hover tooltip can never fire there and must not be the only way to learn a control. Under `@media (hover: none), (pointer: coarse)`, replace the hover tooltip with a visible label, a tap that opens an info sheet, or a long-press. See the `responsive-ui` skill for the full touch treatment. ## Acceptance check - [ ] Every icon-only and jargon control has a `data-tooltip` written for a newcomer. - [ ] Tooltips reveal after 600ms, not instantly. - [ ] Rendered as one body-appended `position:fixed` div at z-index 99999, not a `::after` pseudo. - [ ] The tooltip never covers the cursor or the trigger, and never renders off-screen. - [ ] Only one tooltip shows at a time; nested triggers do not stack. - [ ] No ALL CAPS; `text-transform` reset on the tooltip element. - [ ] `--z-*` tokens declared in `:root`; no hardcoded z-index literals. ## MANDATORY ralph-test before you say tooltips are done (added after repeated failures) Reading the clamp rules is not enough - the off-screen bug keeps shipping because the AI checks one tooltip on a centered control and calls it done. The bug hides at the EDGES. So, non-negotiable: 1. Trigger the tooltip with the LONGEST tip text on the MOST extreme controls: leftmost, rightmost, topmost, bottommost (toolbar corners, panel edges, last row of a list). 2. For each, read the rendered rect and ASSERT it is inside the viewport: `const r = tip.getBoundingClientRect();` `console.assert(r.left >= 0 && r.right <= innerWidth && r.top >= 0 && r.bottom <= innerHeight, 'TOOLTIP OFF-SCREEN', r);` 3. Drive it live (pup/eval) when you can; otherwise compute the clamp arithmetic for the extreme case and show the numbers. Screenshot proof of ONE centered hover does NOT count. 4. Also verify inside iframes: clamp to the IFRAME's viewport (`document.documentElement.clientWidth/Height`), not the parent page's. If any assert fires, fix the clamp (both axes, margin ~8px, flip instead of clip, measure only after layout) and re-run. Never report tooltips complete without stating this test ran and passed. ## Related skills `human-ui-patterns` (the broader interaction rules this was extracted from), `floating-windows` (HUDs that tooltips render above), `toasts` (the sibling transient-feedback element), `responsive-ui` (tooltips on touch), and `adom-ui-design` (the design-system hub that indexes all of these).