🧭 Chapter 44: Accessible Navigation & Structure

Accessible Tooltips

Crafting keyboard-operable, screen-reader-linked microcopy with `role="tooltip"`, `aria-describedby`, and WCAG 1.4.13 Content on Hover or Focus compliance.

LEARNING OBJECTIVES ⌵

Understand why native HTML title attributes fail modern accessibility benchmarks.
Implement the WAI-ARIA Tooltip Pattern using role="tooltip" and aria-describedby.
Comply with all three mandates of WCAG 2.2 Success Criterion 1.4.13 (Dismissible, Hoverable, Persistent).
Build responsive CSS and JavaScript triggers that synchronize mouse hover, keyboard focus, and Escape key dismissal.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine walking through an art museum inspecting ancient artifacts. Beside a display case is an obscure bronze dial. As you lean in to look closely, a museum docent quietly whispers in your ear: "That dial was used by Greek sailors to calculate lunar eclipses."

If you lean back, the docent stops talking. If you find the explanation distracting, you can politely hold up your hand, and the docent steps back immediately.

Visual Pointer User:
[Hover over Icon Button] ───> [Tooltip bubble pops up] ───> [Hover over bubble to read]

Keyboard User:
[Tab onto Icon Button] ───> [Tooltip appears & is spoken] ───> [Press Escape to dismiss]

In web interfaces, a Tooltip is that quiet docent. It provides non-essential supplementary context to an interactive control without cluttering the main visual layout.

However, when tooltips are coded poorly, they become nightmares:

They disappear when you try to hover over them to zoom in.
They pop up on screen and permanently obscure the text underneath.
They never appear for keyboard users.
They are completely invisible to screen readers because they rely on fragile CSS :hover hacks.

Technical Deep Dive & Specifications

Why the Native `title` Attribute is Obsolete

For decades, developers relied on <button title="Print Document">. However, the native title attribute suffers from fatal accessibility defects:

Problem	Native `title` Attribute	Accessible ARIA Tooltip
Keyboard Accessibility	❌ Never triggers on keyboard focus in most browsers	✅ Triggers immediately on `:focus` and `:focus-visible`
Touchscreen Devices	❌ No touch trigger support on mobile iOS/Android	✅ Can be toggled on long-press or tap
WCAG 1.4.13 Compliance	❌ Cannot be dismissed via `Escape`, not hoverable	✅ Fully dismissible, hoverable, and persistent
Visual Styling	❌ Hardcoded by OS window manager, microscopic font	✅ Fully styleable with CSS Custom Properties and animations
Screen Magnifiers	❌ Disappears if user moves magnifier cursor over text	✅ User can move mouse over tooltip content safely

The WAI-ARIA Tooltip Architecture

+-------------------------------------------------------------------------------+
|  TRIGGER ELEMENT:                                                             |
|  <button aria-describedby="tip-save" aria-label="Save File">                  |
|    <svg aria-hidden="true">...</svg>                                          |
|  </button>                                                                    |
+-------------------------------------------------------------------------------+
                               │
                       aria-describedby
                               │
                               ▼
+-------------------------------------------------------------------------------+
|  TOOLTIP CONTAINER:                                                           |
|  <div id="tip-save" role="tooltip" class="tooltip-bubble">                    |
|    Saves your changes to cloud storage (Ctrl+S)                               |
|  </div>                                                                       |
+-------------------------------------------------------------------------------+

aria-describedby Relationship: Connects the interactive trigger to the tooltip <div>. Screen readers announce:

"Save File, button. Saves your changes to cloud storage (Ctrl+S)."
role="tooltip": Identifies the element as a temporary supplementary bubble in the Accessibility Tree.
No Interactive Children: A tooltip must never contain links, inputs, or buttons. If content requires user interaction, it is a Popover or Dialog, not a tooltip.

WCAG 2.2 Success Criterion 1.4.13: Content on Hover or Focus

To meet Level AA compliance, every tooltip must satisfy the D.H.P. Rule:

+─────────────────────────────────────────────────────────────────────────────+
|                     WCAG 1.4.13 THREE CORE CRITERIA                         |
+─────────────────────────────────────────────────────────────────────────────+
|  1. DISMISSIBLE   | Pressing [Escape] or triggering an action closes the    |
|                   | tooltip without moving pointer hover or keyboard focus. |
|───────────────────|─────────────────────────────────────────────────────────|
|  2. HOVERABLE     | Pointer can move from the trigger onto the tooltip      |
|                   | container itself without the tooltip closing.           |
|───────────────────|─────────────────────────────────────────────────────────|
|  3. PERSISTENT    | Tooltip remains visible until hover/focus is removed or  |
|                   | explicitly dismissed by the user.                       |
+─────────────────────────────────────────────────────────────────────────────+

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Line 87 (aria-describedby="tooltip-bookmark"): Associates the button with the tooltip message in the browser's accessibility graph.
Line 96 (role="tooltip"): Declares the semantic role of the floating text bubble.
Line 66–71 (.tooltip-wrapper:hover .tooltip-box, .tooltip-box.is-visible): Enables the Hoverable rule. If a low-vision user moves their mouse from the button into the tooltip box to read it under screen magnification, pointer-events: auto ensures the tooltip does not collapse.
Line 106–110 (if (e.key === 'Escape')): Satisfies the Dismissible rule, allowing users to close the overlay with Escape without losing focus.

Expected Browser Render Output

Sighted Display: Hovering over the bookmark icon displays a crisp slate tooltip saying "Save this article to your reading list".
Screen Reader Vocalization:

"Bookmark, button. Save this article to your reading list."

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Accessible Tooltip Component</title>
  <style>
    :root {
      --surface-dark: #0f172a;
      --text-light: #f8fafc;
      --focus-ring: #0284c7;
    }

body {
      font-family: system-ui, -apple-system, sans-serif;
      padding: 4rem;
      background: #f1f5f9;
    }

/* Tooltip Wrapper Positioning */
    .tooltip-wrapper {
      position: relative;
      display: inline-block;
    }

/* Trigger Button */
    .icon-btn {
      display: inline-flex;
      align-items: center;
      justify-content: center;
      width: 44px;
      height: 44px;
      background: white;
      border: 1px solid #cbd5e1;
      border-radius: 8px;
      cursor: pointer;
      color: #334155;
      transition: all 0.15s ease;
    }

.icon-btn:hover {
      background: #e2e8f0;
      color: #0f172a;
    }

.icon-btn:focus-visible {
      outline: 3px solid var(--focus-ring);
      outline-offset: 2px;
    }

/* Tooltip Bubble (WCAG 1.4.13 Compliant) */
    .tooltip-box {
      position: absolute;
      bottom: calc(100% + 8px);
      left: 50%;
      transform: translateX(-50%);
      background: var(--surface-dark);
      color: var(--text-light);
      padding: 0.5rem 0.85rem;
      border-radius: 6px;
      font-size: 0.8rem;
      font-weight: 500;
      white-space: nowrap;
      pointer-events: none;
      opacity: 0;
      visibility: hidden;
      transition: opacity 0.15s ease, visibility 0.15s ease;
      box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
      z-index: 100;
    }

/* Little Caret Arrow */
    .tooltip-box::after {
      content: "";
      position: absolute;
      top: 100%;
      left: 50%;
      transform: translateX(-50%);
      border-width: 5px;
      border-style: solid;
      border-color: var(--surface-dark) transparent transparent transparent;
    }

/* Hoverable bridge: Keep tooltip alive when hovering over the bubble */
    .tooltip-wrapper:hover .tooltip-box,
    .icon-btn:focus + .tooltip-box,
    .tooltip-box.is-visible {
      opacity: 1;
      visibility: visible;
      pointer-events: auto; /* Meets WCAG 1.4.13 Hoverable requirement */
    }

/* Manual Dismissal via Escape */
    .tooltip-box.is-dismissed {
      opacity: 0 !important;
      visibility: hidden !important;
      pointer-events: none !important;
    }
  </style>
</head>
<body>

<h1>Accessible Toolbar</h1>
  <p>Hover over the button or press <code>[Tab]</code> to focus. Press <code>[Escape]</code> to dismiss.</p>

<div id="tooltip-bookmark" role="tooltip" class="tooltip-box">
      Save this article to your reading list
    </div>
  </div>

// Dismiss on Escape key (WCAG 1.4.13 Dismissible)
    document.addEventListener('keydown', (e) => {
      if (e.key === 'Escape') {
        tooltip.classList.add('is-dismissed');
      }
    });

// Reset dismissal when user moves away and re-engages
    btn.addEventListener('blur', () => tooltip.classList.remove('is-dismissed'));
    wrapper.addEventListener('mouseleave', () => tooltip.classList.remove('is-dismissed'));
  </script>

</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Accessible Markdown Toolbar Tooltips

Build an accessible formatting toolbar containing three icon buttons: Bold, Italic, and Insert Code.

Instructions:

Create three <button class="toolbar-btn"> elements.
Mark each button with an aria-label (e.g. aria-label="Bold text") and an aria-describedby pointing to its keyboard shortcut tooltip (e.g., Ctrl+B).
Markup the corresponding <div role="tooltip"> containers.
Support keyboard focus, mouse hover, and Escape key dismissal across all three tooltips.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Markdown Toolbar Tooltips Solution</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; background: #f8fafc; }

    .toolbar {
      display: inline-flex;
      background: white;
      padding: 0.4rem;
      border-radius: 8px;
      border: 1px solid #cbd5e1;
      gap: 0.4rem;
    }

    .tool-group {
      position: relative;
    }

    .tool-btn {
      width: 40px;
      height: 40px;
      display: inline-flex;
      align-items: center;
      justify-content: center;
      background: transparent;
      border: none;
      border-radius: 6px;
      font-weight: bold;
      font-size: 1.1rem;
      cursor: pointer;
      color: #1e293b;
    }

    .tool-btn:hover { background: #f1f5f9; }
    .tool-btn:focus-visible { outline: 2px solid #0284c7; outline-offset: 2px; }

    .tooltip {
      position: absolute;
      top: calc(100% + 8px);
      left: 50%;
      transform: translateX(-50%);
      background: #0f172a;
      color: white;
      font-size: 0.75rem;
      font-weight: 500;
      padding: 0.35rem 0.65rem;
      border-radius: 4px;
      white-space: nowrap;
      opacity: 0;
      visibility: hidden;
      pointer-events: none;
      transition: opacity 0.15s ease;
      z-index: 10;
    }

    .tool-group:hover .tooltip,
    .tool-btn:focus + .tooltip {
      opacity: 1;
      visibility: visible;
      pointer-events: auto;
    }

    .tooltip.dismissed {
      display: none !important;
    }
  </style>
</head>
<body>

  <div class="toolbar" role="toolbar" aria-label="Text Formatting Toolbar">
    
    <!-- Bold -->
    <div class="tool-group">
      <button type="button" class="tool-btn" id="btn-b" aria-label="Bold text" aria-describedby="tip-b">
        <strong>B</strong>
      </button>
      <div id="tip-b" role="tooltip" class="tooltip">Toggle Bold (Ctrl+B)</div>
    </div>

    <!-- Italic -->
    <div class="tool-group">
      <button type="button" class="tool-btn" id="btn-i" aria-label="Italic text" aria-describedby="tip-i">
        <em>I</em>
      </button>
      <div id="tip-i" role="tooltip" class="tooltip">Toggle Italic (Ctrl+I)</div>
    </div>

    <!-- Code Block -->
    <div class="tool-group">
      <button type="button" class="tool-btn" id="btn-c" aria-label="Inline code" aria-describedby="tip-c">
        &lt;/&gt;
      </button>
      <div id="tip-c" role="tooltip" class="tooltip">Insert Code (Ctrl+Shift+C)</div>
    </div>

  </div>

  <script>
    const tooltips = document.querySelectorAll('.tooltip');

    document.addEventListener('keydown', (e) => {
      if (e.key === 'Escape') {
        tooltips.forEach(t => t.classList.add('dismissed'));
      }
    });

    document.querySelectorAll('.tool-btn').forEach(btn => {
      btn.addEventListener('blur', () => tooltips.forEach(t => t.classList.remove('dismissed')));
    });

    document.querySelectorAll('.tool-group').forEach(group => {
      group.addEventListener('mouseleave', () => tooltips.forEach(t => t.classList.remove('dismissed')));
    });
  </script>

</body>
</html>

Why this works:

Uses aria-label for primary function ("Bold text") and aria-describedby for auxiliary shortcut ("Toggle Bold (Ctrl+B)").
Meets WCAG 1.4.13: users can hover over the tooltip itself, and Escape dismisses the bubble cleanly.

⚠️ Common Pitfalls

Placing Interactive Content inside a Tooltip: Putting links, checkboxes, or buttons inside role="tooltip" violates WAI-ARIA authoring practices. Use a Popover or Dialog widget instead.
Using aria-label instead of aria-describedby on the Trigger: Overwriting aria-label replaces the button's accessible name rather than appending supplementary guidance.
Disappearing on Hover Over Bubble: If the tooltip vanishes the moment the pointer moves off the trigger and onto the tooltip text, you fail WCAG 1.4.13 (Hoverable).
No Keyboard Dismissal: Failing to dismiss active tooltips on Escape traps screen magnifier users beneath the floating box.

💡 Pro Tips

Explore the Baseline Popover API: Modern browsers support popover="hint" and interesttarget for declarative native tooltips.
Positioning Engines (Floating UI): For dynamic viewport boundaries (preventing tooltips from clipping off the top or right edges of the screen), use @floating-ui/dom.
Touch Device Strategy: Tooltips generally do not apply to touch screens. Ensure essential information is displayed as permanent text or opened in a modal on tap.

📌 Key Takeaways

Native HTML title attributes fail multiple WCAG standards and should be avoided for primary UI microcopy.
Always link tooltips using aria-describedby="[tooltip-id]" paired with role="tooltip".
WCAG 1.4.13 requires tooltips to be Dismissible (Escape), Hoverable (pointer can hover over bubble), and Persistent (stays until dismissed).
Tooltips must only contain static, non-interactive text strings.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

Why does WCAG Success Criterion 1.4.13 require tooltips to be "Hoverable" (pointer can move over the tooltip content itself)?

Topic: HTML Fundamentals

? Question 2 / 3

What type of content is explicitly FORBIDDEN inside an element with `role="tooltip"`?

Topic: HTML Fundamentals

? Question 3 / 3

Which ARIA attribute connects a trigger button to a supplementary tooltip without replacing the button's primary name?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

Why the Native title Attribute is Obsolete

The WAI-ARIA Tooltip Architecture

WCAG 2.2 Success Criterion 1.4.13: Content on Hover or Focus

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Accessible Markdown Toolbar Tooltips

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Why does WCAG Success Criterion 1.4.13 require tooltips to be "Hoverable" (pointer can move over the tooltip content itself)?

What type of content is explicitly FORBIDDEN inside an element with role="tooltip"?

Which ARIA attribute connects a trigger button to a supplementary tooltip without replacing the button's primary name?

Why the Native `title` Attribute is Obsolete

What type of content is explicitly FORBIDDEN inside an element with `role="tooltip"`?