Chapter 42: WAI-ARIA Roles & Semantics

The WAI-ARIA Accordion Pattern

Building enterprise-grade, keyboard-accessible FAQ and multi-section accordions with header button bindings, aria-expanded, and aria-controls.

LEARNING OBJECTIVES ⌵

Understand the structural anatomy of the W3C APG Accordion pattern.
Correctly nest native <button> triggers inside semantic heading tags (<h3>).
Synchronize dynamic disclosure states using aria-expanded="true|false" and aria-controls.
Compare native HTML5 <details>/<summary> with custom WAI-ARIA Accordion implementations.

🎬 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 an accordion musical instrument. When compressed, its pleated bellows take up very little physical space. When the musician pulls the handles apart, the bellows expand, allowing air to flow through the internal reeds and create rich sound.

In user interface design, an Accordion operates on the exact same principle of spatial efficiency. When you have a massive FAQ page containing 25 extensive answers, presenting all 25 answers expanded simultaneously creates a 10,000-pixel vertical wall of text.

By grouping related content into collapsible panels, users can quickly scan the compressed headers to find what they need, and selectively expand only the specific answer they wish to read.

Without ARIA, custom accordions built with <div> click handlers leave screen reader users completely unaware of whether a section is open, closed, or what content appeared when clicked.

The WAI-ARIA Accordion Pattern provides clear audio feedback: "Frequently Asked Questions. Heading level 3, button: How do I reset my password? collapsed. Press Space to expand."

Technical Deep Dive & Specifications

The Accordion Structural Anatomy

+-----------------------------------------------------------------------------+
|                          ACCORDION SECTION ANATOMY                          |
+-----------------------------------------------------------------------------+
|                                                                             |
|  <h3>                                                                       |
|    <button                                                                  |
|      type="button"                                                          |
|      id="acc-header-1"                                                      |
|      aria-expanded="false"                                                  |
|      aria-controls="acc-panel-1">                                           |
|      What is your refund policy?                                            |
|    </button>                                                                |
|  </h3>                                                                      |
|                                                                             |
|  <div                                                                       |
|    role="region"                                                            |
|    id="acc-panel-1"                                                         |
|    aria-labelledby="acc-header-1"                                           |
|    hidden>                                                                  |
|    <p>We offer a 30-day money-back guarantee with zero hassle...</p>        |
|  </div>                                                                     |
|                                                                             |
+-----------------------------------------------------------------------------+

The 3 Core Requirements of WAI-ARIA Accordions

Heading Containment (<h3><button>...</button></h3>):
- The accordion trigger must be a native <button> nested inside a semantic heading (<h2> through <h6>).
- This ensures screen reader users can navigate the page using both heading shortcuts (H key) and form/button shortcuts.
State & Association Attributes:
- aria-expanded="true|false" on the <button>: Conveys whether the controlled panel is visible.
- aria-controls="panel-id" on the <button>: Identifies which panel container is toggled.
- aria-labelledby="header-btn-id" on the panel: Links the panel back to its header.
- role="region" on the panel: Exposes the expanded panel as a distinct landmark region once open.
Panel Visibility Management:
- Inactive panels must be hidden using the HTML5 hidden attribute or CSS display: none.
- Collapsed content must never be accessible in the keyboard tab order while hidden.

Keyboard Interaction Contract

Keystroke	Behavior
`Enter` or `Space`	Toggles the expanded/collapsed state of the focused accordion header button.
`Tab`	Moves focus to the next focusable element (either the next accordion header or an interactive link/button inside an open panel).
`Shift + Tab`	Moves focus to the previous focusable element.
`ArrowDown` (Optional APG Enhancement)	Moves focus to the next accordion header button.
`ArrowUp` (Optional APG Enhancement)	Moves focus to the previous accordion header button.
`Home` / `End` (Optional APG)	Moves focus to the first or last accordion header button.

Native HTML5 `<details>` vs. Custom ARIA Accordion

Modern HTML provides the native <details> and <summary> disclosure element:

<!-- Native HTML5 Disclosure Element -->
<details>
  <summary>What is your refund policy?</summary>
  <p>We offer a 30-day money-back guarantee.</p>
</details>

Dimension	Native `<details>` / `<summary>`	Custom WAI-ARIA Accordion
JavaScript Required	❌ Zero JS (Browser handles toggling natively)	✅ Requires JS for state toggling
Heading Hierarchy	Requires nesting `<h3><summary>` (some browsers have styling quirks)	Full semantic heading integration (`<h3><button>`)
CSS Animation Support	Limited (improving with modern CSS `interpolate-size`)	Full control over JavaScript height animations
Exclusive Accordion Grouping	Requires `name="group-name"` attribute (HTML 2024+)	Custom JS logic for single-open vs multi-open behavior

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL example.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

💻 Interactive Code Playground

Starter Code: Production-Grade Accessible FAQ Accordion

Line-by-Line Code Breakdown

Lines 49–57 (<h2><button ...>): Semantic <h2> preserves the document outline; the inner <button> provides native focusability, keyboard triggers (Space/Enter), and ARIA bindings.
Line 52 (aria-expanded="true"): Informs assistive technology that the first item is open by default.
Line 53 (aria-controls="acc-panel-1"): Explicitly pairs the toggle button with the panel container.
Line 59 (role="region" id="acc-panel-1" aria-labelledby="acc-btn-1"): Exposes the panel as a region landmark labeled by the header button.
Line 55 (aria-hidden="true" on the arrow icon): Hides the visual downward arrow character ▼ so screen readers don't read "down pointing triangle" aloud.
Lines 108–137 (JavaScript Toggle Logic): Inverts aria-expanded and toggles the HTML5 hidden attribute synchronously on click.

Expected Browser Render Output

(Clicking any header toggles its panel and updates aria-expanded immediately).

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Accessible WAI-ARIA Accordion</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; background: #f8fafc; }
    .accordion-wrapper { max-width: 650px; margin: auto; background: white; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
    
    /* ACCORDION HEADING & BUTTON */
    .accordion-heading { margin: 0; border-bottom: 1px solid #e2e8f0; }
    .accordion-btn {
      width: 100%;
      text-align: left;
      background: none;
      border: none;
      padding: 1.25rem 1.5rem;
      font-size: 1.1rem;
      font-weight: 600;
      color: #1e293b;
      cursor: pointer;
      display: flex;
      justify-content: space-between;
      align-items: center;
    }
    .accordion-btn:focus-visible {
      outline: 3px solid #2563eb;
      outline-offset: -3px;
      background-color: #f0fdf4;
    }
    .accordion-icon {
      transition: transform 0.25s ease;
      font-size: 0.85rem;
      color: #64748b;
    }
    .accordion-btn[aria-expanded="true"] .accordion-icon {
      transform: rotate(180deg);
    }
    
    /* ACCORDION PANEL */
    .accordion-panel {
      padding: 1.25rem 1.5rem;
      color: #475569;
      line-height: 1.6;
      border-bottom: 1px solid #e2e8f0;
    }
    .accordion-panel[hidden] {
      display: none;
    }
  </style>
</head>
<body>

<main class="accordion-wrapper">
    <h1 style="padding: 1.5rem 1.5rem 0.5rem; margin: 0;">Frequently Asked Questions</h1>

<h2 class="accordion-heading">
      <button 
        type="button" 
        id="acc-btn-1" 
        aria-expanded="true" 
        aria-controls="acc-panel-1" 
        class="accordion-btn">
        <span>How do I invite team members to my organization?</span>
        <span class="accordion-icon" aria-hidden="true">▼</span>
      </button>
    </h2>
    <div 
      role="region" 
      id="acc-panel-1" 
      aria-labelledby="acc-btn-1" 
      class="accordion-panel">
      <p>
        Navigate to <strong>Settings &gt; Organization &gt; Members</strong> and click "Invite New Member". You can assign Administrator, Developer, or Billing roles.
      </p>
    </div>

<h2 class="accordion-heading">
      <button 
        type="button" 
        id="acc-btn-2" 
        aria-expanded="false" 
        aria-controls="acc-panel-2" 
        class="accordion-btn">
        <span>What payment methods do you accept?</span>
        <span class="accordion-icon" aria-hidden="true">▼</span>
      </button>
    </h2>
    <div 
      role="region" 
      id="acc-panel-2" 
      aria-labelledby="acc-btn-2" 
      hidden 
      class="accordion-panel">
      <p>
        We accept Visa, MasterCard, American Express, PayPal, and ACH Wire transfers for annual enterprise contracts.
      </p>
    </div>

<h2 class="accordion-heading">
      <button 
        type="button" 
        id="acc-btn-3" 
        aria-expanded="false" 
        aria-controls="acc-panel-3" 
        class="accordion-btn">
        <span>Can I export my analytics data?</span>
        <span class="accordion-icon" aria-hidden="true">▼</span>
      </button>
    </h2>
    <div 
      role="region" 
      id="acc-panel-3" 
      aria-labelledby="acc-btn-3" 
      hidden 
      class="accordion-panel">
      <p>
        Yes! All dashboard metrics can be exported as CSV, JSON, or streamed via our real-time Webhook API.
      </p>
    </div>
  </main>

accordionButtons.forEach(button => {
      button.addEventListener('click', () => {
        const isExpanded = button.getAttribute('aria-expanded') === 'true';
        const panelId = button.getAttribute('aria-controls');
        const targetPanel = document.getElementById(panelId);

// Toggle state
        if (isExpanded) {
          button.setAttribute('aria-expanded', 'false');
          targetPanel.setAttribute('hidden', '');
        } else {
          button.setAttribute('aria-expanded', 'true');
          targetPanel.removeAttribute('hidden');
        }
      });

// Optional Arrow Key Traversal between headers
      button.addEventListener('keydown', (e) => {
        const currentIndex = accordionButtons.indexOf(button);
        if (e.key === 'ArrowDown') {
          e.preventDefault();
          const nextIndex = (currentIndex + 1) % accordionButtons.length;
          accordionButtons[nextIndex].focus();
        } else if (e.key === 'ArrowUp') {
          e.preventDefault();
          const prevIndex = (currentIndex - 1 + accordionButtons.length) % accordionButtons.length;
          accordionButtons[prevIndex].focus();
        }
      });
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

Frequently Asked Questions
─────────────────────────────────────────────────────────────
How do I invite team members to my organization?           ▲
Navigate to Settings > Organization > Members and click...
─────────────────────────────────────────────────────────────
What payment methods do you accept?                        ▼
─────────────────────────────────────────────────────────────
Can I export my analytics data?                            ▼
─────────────────────────────────────────────────────────────

🏋️ Hands-On Exercise

🎯 The Challenge: Build an Accessible Multi-Step Checkout Accordion

Build an accessible 3-step checkout accordion featuring:

Step 1: Shipping Address
Step 2: Delivery Options
Step 3: Payment Details

Instructions:

Wrap each step header in an <h3> tag containing a <button type="button">.
Connect each header button to its respective panel using aria-controls and aria-expanded.
Give each panel role="region" and aria-labelledby referencing its header button ID.
Ensure Step 1 is expanded initially, while Steps 2 and 3 are collapsed with the hidden attribute.
Write JavaScript to toggle panels on button click.

🏁 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">
  <title>Accessible Checkout Accordion - Solution</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 600px; margin: auto; }
    .step-heading { margin: 0; border-top: 1px solid #cbd5e1; }
    .step-heading:first-of-type { border-top: none; }
    .step-btn {
      width: 100%;
      text-align: left;
      padding: 1rem;
      background: #f8fafc;
      border: none;
      font-size: 1.1rem;
      font-weight: bold;
      cursor: pointer;
      display: flex;
      justify-content: space-between;
    }
    .step-btn:focus-visible { outline: 2px solid #2563eb; }
    .step-btn[aria-expanded="true"] { background: #eff6ff; color: #1d4ed8; }
    .step-panel {
      padding: 1.5rem;
      background: white;
      border-bottom: 1px solid #e2e8f0;
    }
    .step-panel[hidden] { display: none; }
    .form-row { margin-bottom: 1rem; display: flex; flex-direction: column; gap: 0.25rem; }
    .form-row input[type="text"] { padding: 0.5rem; border: 1px solid #cbd5e1; border-radius: 4px; }
  </style>
</head>
<body>

  <main>
    <h1>Secure Checkout</h1>

    <div class="checkout-accordion">
      <!-- STEP 1 -->
      <h2 class="step-heading">
        <button 
          type="button" 
          id="btn-step1" 
          aria-expanded="true" 
          aria-controls="panel-step1" 
          class="step-btn">
          <span>1. Shipping Address</span>
          <span aria-hidden="true">▾</span>
        </button>
      </h2>
      <div 
        role="region" 
        id="panel-step1" 
        aria-labelledby="btn-step1" 
        class="step-panel">
        <div class="form-row">
          <label for="street">Street Address:</label>
          <input type="text" id="street" required>
        </div>
      </div>

      <!-- STEP 2 -->
      <h2 class="step-heading">
        <button 
          type="button" 
          id="btn-step2" 
          aria-expanded="false" 
          aria-controls="panel-step2" 
          class="step-btn">
          <span>2. Delivery Options</span>
          <span aria-hidden="true">▾</span>
        </button>
      </h2>
      <div 
        role="region" 
        id="panel-step2" 
        aria-labelledby="btn-step2" 
        hidden 
        class="step-panel">
        <p>Select delivery speed:</p>
        <label><input type="radio" name="shipping" checked> Standard Delivery (Free)</label><br>
        <label><input type="radio" name="shipping"> Express Courier ($15.00)</label>
      </div>

      <!-- STEP 3 -->
      <h2 class="step-heading">
        <button 
          type="button" 
          id="btn-step3" 
          aria-expanded="false" 
          aria-controls="panel-step3" 
          class="step-btn">
          <span>3. Payment Details</span>
          <span aria-hidden="true">▾</span>
        </button>
      </h2>
      <div 
        role="region" 
        id="panel-step3" 
        aria-labelledby="btn-step3" 
        hidden 
        class="step-panel">
        <div class="form-row">
          <label for="cardNumber">Card Number:</label>
          <input type="text" id="cardNumber" placeholder="4532 •••• •••• ••••">
        </div>
      </div>
    </div>
  </main>

  <script>
    const stepButtons = Array.from(document.querySelectorAll('.step-btn'));

    stepButtons.forEach(btn => {
      btn.addEventListener('click', () => {
        const isExpanded = btn.getAttribute('aria-expanded') === 'true';
        const panel = document.getElementById(btn.getAttribute('aria-controls'));

        btn.setAttribute('aria-expanded', String(!isExpanded));
        if (isExpanded) {
          panel.setAttribute('hidden', '');
        } else {
          panel.removeAttribute('hidden');
        }
      });
    });
  </script>
</body>
</html>

Why this works:

Every section is rooted in a semantic <h2> tag containing a native <button type="button">.
aria-expanded and aria-controls maintain bidirectional state between triggers and disclosure regions.
Hidden panels use the native hidden attribute, preventing invisible form inputs from being focused via Tab.

⚠️ Common Pitfalls

Putting role="button" Directly on the Heading: Writing <h2 role="button">. This strips the <h2> level from the document outline. Always nest <button> inside <h2>.
Using CSS opacity: 0 or height: 0 Without display: none or visibility: hidden: If a collapsed panel is merely visually invisible, keyboard users will still tab into the invisible inputs and links inside it. Always apply hidden or display: none when collapsed.
Missing aria-controls Linkage: Forgetting aria-controls="panel-id" on the accordion button prevents assistive technologies from offering direct jumping between the header and panel.

💡 Pro Tips

Exclusive Accordions: To create an accordion where opening one panel automatically closes all others, loop through all other buttons in your click handler and set aria-expanded="false" and hidden before opening the targeted panel.
Deep-Linking via URL Hash: Parse window.location.hash on page load. If the hash matches an accordion panel ID, automatically expand that section and scroll it into view.

📌 Key Takeaways

The WAI-ARIA Accordion pattern requires nesting native <button> elements inside semantic heading tags (<h2>-<h6>).
aria-expanded="true|false" on the trigger button communicates the disclosure state.
aria-controls links the trigger button to the collapsible content panel's ID.
Collapsible panels must use role="region" with aria-labelledby linking back to the header button.
Inactive panels must be hidden using the hidden attribute or display: none to prevent keyboard focus leaks.
--

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

? Question 1 / 3

Why must the interactive toggle of an accordion item be placed inside a heading tag (e.g. `<h3><button>...</button></h3>`) rather than replacing the heading tag with a button?

Topic: HTML Fundamentals

? Question 2 / 3

Which attribute must be toggled on the accordion trigger button when its panel is opened or closed?

Topic: HTML Fundamentals

? Question 3 / 3

Why is applying `display: none` or the `hidden` attribute required when collapsing an accordion panel?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The Accordion Structural Anatomy

The 3 Core Requirements of WAI-ARIA Accordions

Keyboard Interaction Contract

Native HTML5 <details> vs. Custom ARIA Accordion

💻 Interactive Code Playground

Starter Code: Production-Grade Accessible FAQ Accordion

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build an Accessible Multi-Step Checkout Accordion

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Why must the interactive toggle of an accordion item be placed inside a heading tag (e.g. <h3><button>...</button></h3>) rather than replacing the heading tag with a button?

Which attribute must be toggled on the accordion trigger button when its panel is opened or closed?

Why is applying display: none or the hidden attribute required when collapsing an accordion panel?

Native HTML5 `<details>` vs. Custom ARIA Accordion

Why must the interactive toggle of an accordion item be placed inside a heading tag (e.g. `<h3><button>...</button></h3>`) rather than replacing the heading tag with a button?

Why is applying `display: none` or the `hidden` attribute required when collapsing an accordion panel?