Chapter 98: Capstone 1 — Production Documentation Site

Accessibility Auditing & WCAG 2.2 AA Compliance

Conducting enterprise accessibility audits: Automated test harnesses with `axe-core`, color contrast validation, keyboard navigation testing, and screen reader verification (NVDA & VoiceOver).

LEARNING OBJECTIVES ⌵

Audit web applications against the latest WCAG 2.2 Level AA success criteria (including 2.4.11 Focus Not Obscured and 2.5.8 Target Size).
Integrate automated accessibility assertion suites using axe-core within CI/CD pipelines.
Execute rigorous manual keyboard audit workflows without a mouse or pointer device.
Conduct screen reader validation runs using NVDA (Windows) and VoiceOver (macOS / iOS).

🎬 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 constructing a multimillion-dollar public museum. The architecture is visually stunning, featuring sleek black marble staircases, artistic hidden doors, and minimalist typography.

However, if the entrance lacks a wheelchair ramp, elevators have no braille buttons, and emergency exit signs blend invisibly into the dark wallpaper, the building fails basic safety codes and locks out millions of patrons.

In frontend engineering, Accessibility (a11y) is not an afterthought or an optional decorative feature—it is the foundational building code of the web.

A documentation portal is used by developers with diverse physical abilities: engineers who are completely blind using NVDA/VoiceOver screen readers, developers with motor impairments navigating exclusively via keyboard switches, and engineers with low vision or color vision deficiencies relying on 4.5:1 contrast ratios.

Achieving zero-violation WCAG 2.2 AA compliance ensures every developer can read, search, and run your code without friction.

Technical Deep Dive & Specifications

2.1 The WCAG 2.2 AA Critical Checklist for Documentation Sites

+---------------------------------------------------------------------------------------------------------+
| WCAG 2.2 LEVEL AA AUDIT MATRIX                                                                          |
|                                                                                                         |
| 1. PERCEIVABLE                                                                                          |
|    • SC 1.3.1 Info & Relationships: Landmarks (<header>, <nav>, <main>, <article>, <aside>, <footer>)  |
|    • SC 1.4.3 Contrast (Minimum): 4.5:1 for body text; 3.0:1 for large text (>18pt/24px) & UI borders   |
|    • SC 1.4.11 Non-Text Contrast: 3:1 for interactive element boundaries and focus rings                |
|                                                                                                         |
| 2. OPERABLE                                                                                             |
|    • SC 2.1.1 Keyboard: All interactive elements (<button>, <a>, <details>, <dialog>) keyboard reachable|
|    • SC 2.1.2 No Keyboard Trap: Focus must never get permanently trapped in iframes or widgets         |
|    • SC 2.4.1 Bypass Blocks: Visible skip-to-content link present as first focusable element            |
|    • SC 2.4.7 Focus Visible: Clear, high-contrast outline on :focus-visible (never outline: none)      |
|    • SC 2.4.11 Focus Not Obscured (Minimum): Focused elements must not be hidden by sticky headers      |
|    • SC 2.5.8 Target Size (Minimum): Interactive click targets must be at least 24x24 CSS pixels        |
|                                                                                                         |
| 3. UNDERSTANDABLE & ROBUST                                                                              |
|    • SC 3.1.1 Language of Page: Valid <html lang="en"> attribute declared                              |
|    • SC 4.1.2 Name, Role, Value: Valid ARIA attributes (role="switch", aria-expanded, aria-controls)   |
|    • SC 4.1.3 Status Messages: Dynamic updates announced politely via aria-live="polite"              |
+---------------------------------------------------------------------------------------------------------+

2.2 Automated Auditing with `axe-core`

Automated test engines detect approximately 40–57% of WCAG violations instantly. Integrating axe-core in test runners (such as Vitest, Jest, Playwright, or Cypress) ensures zero regressions during code reviews:

import axe from 'axe-core';

async function auditAccessibility(htmlDocument) {
  const results = await axe.run(htmlDocument, {
    runOnly: {
      type: 'tag',
      values: ['wcag2a', 'wcag2aa', 'wcag22aa', 'best-practice']
    }
  });

  if (results.violations.length > 0) {
    console.error(`🚨 ${results.violations.length} Accessibility Violations Detected:`);
    results.violations.forEach(v => {
      console.error(`- [${v.impact.toUpperCase()}] ${v.help} (${v.helpUrl})`);
      v.nodes.forEach(n => console.error(`   Target: ${n.target.join(' ')}`));
    });
    throw new Error('Accessibility Audit Failed!');
  }

  console.log('✅ 100% Zero axe-core Violations!');
}

2.3 Focus Ring Ergonomics & Focus Not Obscured (WCAG 2.2)

Never declare outline: none without providing an enhanced, visible alternative:

/* Accessible Modern Focus Rings */
:focus {
  outline: none; /* Only remove browser default if replacing immediately */
}

:focus-visible {
  outline: 2px solid var(--brand-focus);
  outline-offset: 3px;
  border-radius: 4px;
}

/* Ensure sticky elements never obscure keyboard focus (WCAG 2.2 SC 2.4.11) */
:target {
  scroll-margin-top: calc(var(--header-height) + 1.5rem);
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Line 2: <html lang="en"> satisfies WCAG 3.1.1 by declaring the primary language for speech synthesizers.
Lines 8–14: CSS color tokens guarantee high contrast ratios (15.6:1 for body text, 4.6:1 for buttons), exceeding the 4.5:1 minimum threshold.
Lines 23–37: .skip-link provides an immediate bypass block, becoming visible and highlighted with high-contrast amber (#d97706) on :focus-visible.
Lines 40–53: .a11y-btn enforces min-height: 44px; min-width: 44px;, easily satisfying WCAG 2.2 SC 2.5.8 (Target Size).
Line 81: <main id="main-area" tabindex="-1"> ensures smooth programmatic focus landing when the skip link is triggered.
Lines 98–117: JavaScript runs automated DOM checks validating language attributes, landmark uniqueness, button names, and image alt tags.

Expected Browser Render Output

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>WCAG 2.2 AA Audited Interface</title>
  <style>
    :root {
      /* Contrast Ratios: #0f172a on #ffffff = 15.6:1 (Passes AAA) */
      --bg: #ffffff;
      --text: #0f172a;
      /* #2563eb on #ffffff = 4.6:1 (Passes AA Normal Text) */
      --brand: #2563eb;
      --focus-ring: #d97706; /* High-visibility amber focus */
    }
    body {
      font-family: system-ui, sans-serif;
      background: var(--bg);
      color: var(--text);
      line-height: 1.6;
      padding: 2rem;
      margin: 0;
    }
    
    /* Skip Link */
    .skip-link {
      position: absolute;
      top: -100px;
      left: 1rem;
      background: #000000;
      color: #ffffff;
      padding: 0.75rem 1.25rem;
      font-weight: bold;
      text-decoration: none;
      border-radius: 4px;
      z-index: 1000;
      transition: top 0.15s ease;
    }
    .skip-link:focus-visible {
      top: 1rem;
      outline: 3px solid var(--focus-ring);
      outline-offset: 2px;
    }

/* Interactive Buttons with Min 24px Target Size (WCAG 2.2 SC 2.5.8) */
    .a11y-btn {
      min-height: 44px;
      min-width: 44px;
      padding: 0.6rem 1.2rem;
      background: var(--brand);
      color: #ffffff;
      font-weight: 600;
      border: 2px solid transparent;
      border-radius: 6px;
      cursor: pointer;
      display: inline-flex;
      align-items: center;
      justify-content: center;
    }
    .a11y-btn:focus-visible {
      outline: 3px solid var(--focus-ring);
      outline-offset: 3px;
    }

/* Live Audit Results Panel */
    .audit-panel {
      border: 2px solid #cbd5e1;
      border-radius: 8px;
      padding: 1.5rem;
      margin-top: 2rem;
      background: #f8fafc;
    }
    .status-badge {
      display: inline-block;
      padding: 0.25rem 0.75rem;
      border-radius: 4px;
      font-weight: bold;
      font-size: 0.875rem;
    }
    .status-pass { background: #dcfce7; color: #15803d; }
    .status-fail { background: #fee2e2; color: #b91c1c; }
  </style>
</head>
<body>

<a href="#main-area" class="skip-link">Skip to main content</a>

<header role="banner">
    <h2>⚡ Accessible Docs Shell</h2>
  </header>

<main id="main-area" tabindex="-1">
    <h1>WCAG 2.2 AA Compliance Demonstration</h1>
    <p>Test keyboard navigation by pressing <kbd>Tab</kbd> to reveal the skip link and focus rings.</p>

<button type="button" class="a11y-btn" id="run-audit-btn">
      🛡️ Run In-Browser axe-core Audit
    </button>

<div class="audit-panel" role="region" aria-label="Accessibility Audit Telemetry">
      <h3>Audit Results</h3>
      <div id="audit-status">
        <span class="status-badge status-pass">Ready to Audit</span>
      </div>
      <pre id="audit-log" style="font-family:monospace; margin-top:1rem;">Click the button above to execute automated DOM rules.</pre>
    </div>
  </main>

auditBtn.addEventListener('click', () => {
      // In-browser simulated axe-core rule evaluation
      const checks = [
        { name: 'HTML Lang Attribute (SC 3.1.1)', pass: Boolean(document.documentElement.lang) },
        { name: 'Unique Landmark Roles (SC 1.3.1)', pass: document.querySelectorAll('header, main, footer').length >= 2 },
        { name: 'Accessible Skip Link (SC 2.4.1)', pass: Boolean(document.querySelector('.skip-link')) },
        { name: 'Button Accessible Names (SC 4.1.2)', pass: Array.from(document.querySelectorAll('button')).every(b => b.textContent.trim().length > 0) },
        { name: 'Image Alt Texts (SC 1.1.1)', pass: Array.from(document.querySelectorAll('img')).every(img => img.hasAttribute('alt')) }
      ];

const allPassed = checks.every(c => c.pass);
      
      statusBox.innerHTML = allPassed 
        ? '<span class="status-badge status-pass">✅ 100% WCAG 2.2 AA Rules Passed</span>'
        : '<span class="status-badge status-fail">❌ Accessibility Violations Detected</span>';

log.textContent = checks.map(c => `[${c.pass ? 'PASS' : 'FAIL'}] ${c.name}`).join('\n');
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

+--------------------------------------------------------------------------+
| ⚡ Accessible Docs Shell                                                 |
|                                                                          |
| # WCAG 2.2 AA Compliance Demonstration                                   |
| Test keyboard navigation by pressing Tab...                              |
|                                                                          |
| [ 🛡️ Run In-Browser axe-core Audit ]                                     |
|                                                                          |
| +----------------------------------------------------------------------+ |
| | Audit Results: [ ✅ 100% WCAG 2.2 AA Rules Passed ]                  | |
| | [PASS] HTML Lang Attribute (SC 3.1.1)                                | |
| | [PASS] Unique Landmark Roles (SC 1.3.1)                              | |
| | [PASS] Accessible Skip Link (SC 2.4.1)                               | |
| | [PASS] Button Accessible Names (SC 4.1.2)                            | |
| | [PASS] Image Alt Texts (SC 1.1.1)                                    | |
| +----------------------------------------------------------------------+ |
+--------------------------------------------------------------------------+

🏋️ Hands-On Exercise

🎯 The Challenge: Fix the Accessibility Violations in Legacy Markup

Instructions:

Identify and fix all 4 critical accessibility defects in the broken legacy snippet:
- Defect 1: Icon-only button with missing accessible text.
- Defect 2: Low-contrast text styling (#a0aec0 on #ffffff).
- Defect 3: Missing skip link.
- Defect 4: Bad outline suppression (outline: none without replacement).
Refactor the code to achieve 100% WCAG 2.2 AA compliance.

🏁 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>Fixed A11y Sandbox Solution</title>
  <style>
    :root {
      --text-muted: #475569; /* 5.3:1 Contrast against white - PASS */
      --brand: #2563eb;
    }
    body { font-family: system-ui, sans-serif; padding: 2rem; margin: 0; }
    
    .skip-link {
      position: absolute;
      top: -100px;
      left: 1rem;
      background: #000;
      color: #fff;
      padding: 0.5rem 1rem;
      font-weight: bold;
      text-decoration: none;
      border-radius: 4px;
    }
    .skip-link:focus-visible { top: 1rem; outline: 3px solid #f59e0b; }

    p.subtitle { color: var(--text-muted); font-size: 1rem; }

    button {
      padding: 0.5rem 1rem;
      cursor: pointer;
    }
    button:focus-visible {
      outline: 3px solid var(--brand);
      outline-offset: 2px;
    }
  </style>
</head>
<body>

  <a href="#main-content" class="skip-link">Skip to main content</a>

  <header role="banner">
    <button type="button" aria-label="Toggle navigation menu">
      <span aria-hidden="true">☰</span>
    </button>
  </header>

  <main id="main-content" tabindex="-1">
    <h1>Fixed Documentation</h1>
    <p class="subtitle">Developer documentation guidelines</p>
  </main>

</body>
</html>

Why this works:

<html lang="en"> specifies page language.
aria-label="Toggle navigation menu" gives the icon button a clear, descriptive accessible name, while aria-hidden="true" prevents screen readers from reading the raw unicode character.
#475569 achieves a 5.3:1 contrast ratio against #ffffff, easily exceeding the WCAG 4.5:1 minimum threshold.
:focus-visible provides a prominent 3px outline without disturbing mouse clicks.

⚠️ Common Pitfalls

Removing Focus Outlines with * { outline: none !important; }: This is considered an anti-pattern. Sighted keyboard navigators rely entirely on focus rings to know which button, input, or link is active.
Relying Solely on Automated Tools: Automated scanners like axe-core only catch ~50% of accessibility issues. They cannot tell if keyboard focus order is logical, if your video captions match audio, or if custom keyboard widgets work properly. Manual keyboard and screen reader testing is mandatory.
Using Clickable <div> Elements Without Keydown Handlers: If you write <div onclick="...">, screen readers treat it as static text and keyboard users cannot tab to or press Enter/Space on it. Always use native <button type="button">.

💡 Pro Tips

Automated CI Pull Request Gates: Run axe-core inside continuous integration (CI) tests using Playwright. Set assertions to fail the build if violations.length > 0, preventing accessibility regressions from ever reaching production.
VoiceOver Testing Shortcut on macOS: Press Cmd + F5 to instantly toggle VoiceOver on macOS. Navigate landmarks using Ctrl + Option + U (Web Rotor), and jump between landmarks with Ctrl + Option + Right Arrow.

📌 Key Takeaways

WCAG 2.2 Level AA is the worldwide legal and engineering standard for web accessibility.
Normal text requires at least a 4.5:1 color contrast ratio; UI components and large text require at least 3.0:1.
Interactive click targets must satisfy WCAG 2.2 SC 2.5.8 by measuring at least 24x24 CSS pixels.
Automated testing tools like axe-core should be integrated directly into CI/CD build pipelines.
All interactive widgets must be 100% operable via keyboard (Tab, Enter, Space, Escape, Arrows) with clearly visible focus rings.
--

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

? Question 1 / 3

What is the minimum color contrast ratio required by WCAG 2.2 AA for standard body text (below 18pt/24px normal font)?

Topic: HTML Fundamentals

? Question 2 / 3

What new requirement was introduced in WCAG 2.2 under Success Criterion 2.4.11 (Focus Not Obscured)?

Topic: HTML Fundamentals

? Question 3 / 3

Approximately what percentage of all web accessibility violations can be detected purely through automated scanners like `axe-core`?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

2.1 The WCAG 2.2 AA Critical Checklist for Documentation Sites

2.2 Automated Auditing with axe-core

2.3 Focus Ring Ergonomics & Focus Not Obscured (WCAG 2.2)

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Fix the Accessibility Violations in Legacy Markup

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What is the minimum color contrast ratio required by WCAG 2.2 AA for standard body text (below 18pt/24px normal font)?

What new requirement was introduced in WCAG 2.2 under Success Criterion 2.4.11 (Focus Not Obscured)?

Approximately what percentage of all web accessibility violations can be detected purely through automated scanners like axe-core?

2.2 Automated Auditing with `axe-core`

Approximately what percentage of all web accessibility violations can be detected purely through automated scanners like `axe-core`?