♿ Lesson 10.3: Accessibility (a11y)

🌟 Introduction to Web Accessibility

Web accessibility (often abbreviated as a11y — the letter "a", then 11 letters, then "y", the same way "internationalization" becomes "i18n") means building websites and applications that everyone can use, including people with disabilities. That's a broader group than many developers first imagine. It includes people with:

• Visual impairments: blindness, low vision, or color blindness (roughly 1 in 12 men has some form of color-vision deficiency)
• Hearing impairments: deafness or hearing loss
• Motor impairments: limited ability to use a mouse, so they rely on the keyboard, switch devices, or voice control
• Cognitive impairments: learning disabilities, memory or attention differences
• Temporary or situational limitations: a broken arm, holding a baby one-handed, or squinting at a phone on a sunny sidewalk

That last group is the key insight: accessibility is not a niche feature for "other people." Over a long enough life, almost everyone experiences some limitation — permanent, temporary, or situational. When you build for the edges, the middle gets better too.

🌍 The Statistics

Consider these important facts:

⚖️ Legal Requirements

Accessibility isn't just good practice—it's often required by law:

💭 Why Accessibility Matters

Beyond legal compliance, there are many compelling reasons to prioritize accessibility:

🎯 Business Benefits

👥 User Benefits

Accessibility features benefit many users, not just those with disabilities:

// Example: Keyboard shortcuts help power users
// Screen reader labels help voice control users
// High contrast modes help users in bright sunlight
// Captions help users in noisy environments

// A real-world example:
interface AccessibilityBenefits {
  feature: string;
  primaryUsers: string;
  secondaryUsers: string[];
}

const benefits: AccessibilityBenefits[] = [
  {
    feature: "Keyboard navigation",
    primaryUsers: "Motor impaired users",
    secondaryUsers: ["Power users", "Users without mouse"]
  },
  {
    feature: "Video captions",
    primaryUsers: "Deaf/hard of hearing",
    secondaryUsers: ["Non-native speakers", "Users in quiet spaces", "Users in noisy environments"]
  },
  {
    feature: "Clear language",
    primaryUsers: "Cognitive disabilities",
    secondaryUsers: ["Non-native speakers", "Users under stress", "All users!"]
  },
  {
    feature: "Large click targets",
    primaryUsers: "Motor impaired users",
    secondaryUsers: ["Mobile users", "Elderly users", "Users with tremors"]
  }
];

🔄 The Virtuous Cycle

📋 WCAG Guidelines Overview

The Web Content Accessibility Guidelines (WCAG) are the international standard for web accessibility. Published by the W3C, these guidelines help make web content more accessible to people with disabilities.

🎯 The Four Principles (POUR)

WCAG is organized around four core principles. Content must be:

1️⃣ Perceivable

Information and UI components must be presentable to users in ways they can perceive.

2️⃣ Operable

UI components and navigation must be operable by all users.

3️⃣ Understandable

Information and operation of the UI must be understandable.

4️⃣ Robust

Content must be robust enough to work with current and future technologies.

📊 Conformance Levels

WCAG has three levels of conformance:

🎯 Key Success Criteria for React Developers

Here are the most important WCAG criteria that React developers should focus on:

🏗️ Semantic HTML in React

Semantic HTML means using the right HTML elements for their intended purpose. This provides meaning and structure that assistive technologies can understand and communicate to users.

Here's the core idea in one picture. On the left, everything is a <div> — a screen reader sees a flat, meaningless wall of "group, group, group." On the right, semantic elements create real landmarks the user can navigate to directly:

❌ Non-Semantic vs ✅ Semantic

Let's compare non-semantic and semantic approaches:

// ❌ BAD: Non-semantic "div soup"
function BadApp() {
  return (
    <div className="app">
      <div className="header">
        <div className="logo">My Site</div>
        <div className="menu">
          <div className="link">Home</div>
          <div className="link">About</div>
          <div className="link">Contact</div>
        </div>
      </div>
      <div className="content">
        <div className="post">
          <div className="title">Blog Post</div>
          <div className="text">Post content...</div>
        </div>
      </div>
      <div className="footer">
        <div>© 2026 My Site</div>
      </div>
    </div>
  );
}

// ✅ GOOD: Semantic HTML
function GoodApp() {
  return (
    <div className="app">
      <header>
        <h1>My Site</h1>
        <nav aria-label="Main navigation">
          <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/about">About</a></li>
            <li><a href="/contact">Contact</a></li>
          </ul>
        </nav>
      </header>
      
      <main>
        <article>
          <h2>Blog Post</h2>
          <p>Post content...</p>
        </article>
      </main>
      
      <footer>
        <p>© 2026 My Site</p>
      </footer>
    </div>
  );
}

🗺️ Landmark Elements

Landmark elements define regions of your page that screen reader users can navigate to directly:

📝 Practical Example: Blog Layout

interface BlogPost {
  id: string;
  title: string;
  content: string;
  author: string;
  date: string;
}

interface BlogLayoutProps {
  posts: BlogPost[];
}

function BlogLayout({ posts }: BlogLayoutProps) {
  return (
    <>
      {/* Page header with site branding */}
      <header>
        <h1>My Tech Blog</h1>
        <p>Thoughts on web development and accessibility</p>
      </header>

      {/* Main navigation */}
      <nav aria-label="Main navigation">
        <ul>
          <li><a href="/">Home</a></li>
          <li><a href="/about">About</a></li>
          <li><a href="/archive">Archive</a></li>
        </ul>
      </nav>

      {/* Main content area - must be unique per page */}
      <main>
        <h2>Recent Posts</h2>
        
        {posts.map(post => (
          <article key={post.id}>
            <header>
              {/* Article header (different from page header) */}
              <h3>{post.title}</h3>
              <p>
                By {post.author} on <time dateTime={post.date}>
                  {new Date(post.date).toLocaleDateString()}
                </time>
              </p>
            </header>
            
            <p>{post.content}</p>
            
            <footer>
              <a href={`/post/${post.id}`}>Read more</a>
            </footer>
          </article>
        ))}
      </main>

      {/* Sidebar with related content */}
      <aside aria-label="Sidebar">
        <section>
          <h2>Categories</h2>
          <ul>
            <li><a href="/category/react">React</a></li>
            <li><a href="/category/typescript">TypeScript</a></li>
            <li><a href="/category/a11y">Accessibility</a></li>
          </ul>
        </section>
      </aside>

      {/* Page footer */}
      <footer>
        <p>© 2024 My Tech Blog. All rights reserved.</p>
        <nav aria-label="Footer navigation">
          <ul>
            <li><a href="/privacy">Privacy Policy</a></li>
            <li><a href="/terms">Terms of Service</a></li>
          </ul>
        </nav>
      </footer>
    </>
  );
}

🔤 Heading Hierarchy

Proper heading structure is crucial for navigation and understanding:

// ❌ BAD: Skipped heading levels, no hierarchy
function BadHeadingStructure() {
  return (
    <div>
      <h1>Page Title</h1>
      <h4>Section Title</h4>  {/* Skipped h2 and h3! */}
      <h2>Another Section</h2>  {/* Out of order */}
      <h5>Subsection</h5>
    </div>
  );
}

// ✅ GOOD: Logical heading hierarchy
function GoodHeadingStructure() {
  return (
    <div>
      <h1>Page Title</h1>
      
      <h2>First Main Section</h2>
      <p>Content here...</p>
      
      <h3>Subsection of First Section</h3>
      <p>More specific content...</p>
      
      <h3>Another Subsection</h3>
      <p>Content here...</p>
      
      <h2>Second Main Section</h2>
      <p>Content here...</p>
      
      <h3>Subsection of Second Section</h3>
      <p>Content here...</p>
    </div>
  );
}

🔗 Links vs Buttons

Use the right element for the right purpose:

// ❌ BAD: Wrong elements for the job
function BadInteractiveElements() {
  return (
    <div>
      {/* Don't use divs as buttons */}
      <div onClick={() => handleSubmit()}>Submit</div>
      
      {/* Don't use buttons as links */}
      <button onClick={() => window.location.href = '/about'}>
        About Us
      </button>
      
      {/* Don't use spans as clickable elements */}
      <span onClick={() => openModal()}>Open</span>
    </div>
  );
}

// ✅ GOOD: Right elements for the job
function GoodInteractiveElements() {
  const navigate = useNavigate();
  
  return (
    <div>
      {/* Use button for actions */}
      <button onClick={handleSubmit} type="button">
        Submit
      </button>
      
      {/* Use link for navigation */}
      <a href="/about">About Us</a>
      
      {/* Or use React Router Link */}
      <Link to="/about">About Us</Link>
      
      {/* Use button for modal trigger */}
      <button onClick={openModal} type="button">
        Open
      </button>
    </div>
  );
}

🎭 ARIA Attributes Basics

ARIA (Accessible Rich Internet Applications) is a set of attributes that define ways to make web content and applications more accessible to people with disabilities. ARIA fills in the gaps where HTML semantics fall short.

⚖️ The Five Rules of ARIA

Before using ARIA, understand these fundamental rules from the W3C:

// ❌ BAD: Unnecessary ARIA
<div role="button" tabIndex={0} onClick={handleClick}>Click me</div>

// ✅ GOOD: Use native button
<button onClick={handleClick}>Click me</button>


// ❌ BAD: Unnecessary role
<nav role="navigation">...</nav>

// ✅ GOOD: nav element already has role="navigation"
<nav>...</nav>

// ❌ BAD: Changing semantic meaning
<h2 role="button">Click me</h2>

// ✅ GOOD: Use proper structure
<h2>Section Title</h2>
<button>Click me</button>

🎯 ARIA Attribute Categories

ARIA attributes fall into three main categories:

1️⃣ ARIA Roles

Roles define what an element is or does:

// Common ARIA roles
interface ARIARoleExamples {
  widget: string[];  // Interactive elements
  composite: string[]; // Composite widgets
  document: string[]; // Document structure
  landmark: string[]; // Page regions
}

const roles: ARIARoleExamples = {
  // Widget roles
  widget: [
    'button',      // A clickable button
    'checkbox',    // A checkable input
    'link',        // A hyperlink
    'menuitem',    // An option in a menu
    'option',      // An item in a listbox
    'radio',       // A radio button
    'searchbox',   // A search input
    'slider',      // A slider control
    'spinbutton',  // A number input with up/down
    'switch',      // An on/off switch
    'tab',         // A tab in a tablist
    'textbox',     // A text input
  ],
  
  // Composite widget roles
  composite: [
    'combobox',    // Input + listbox combo
    'menu',        // A menu of options
    'listbox',     // A list of options
    'tablist',     // A list of tabs
    'tree',        // A tree view
  ],
  
  // Document structure roles
  document: [
    'article',     // Self-contained content
    'heading',     // A heading
    'img',         // An image
    'list',        // A list of items
    'listitem',    // An item in a list
    'row',         // A row in a table
    'table',       // A table
  ],
  
  // Landmark roles
  landmark: [
    'banner',      // Page header (use <header> instead)
    'navigation',  // Navigation (use <nav> instead)
    'main',        // Main content (use <main> instead)
    'complementary', // Aside (use <aside> instead)
    'contentinfo', // Footer (use <footer> instead)
    'form',        // Form (use <form> instead)
    'region',      // Generic landmark
    'search',      // Search functionality
  ]
};

2️⃣ ARIA Properties

Properties describe characteristics that don't usually change:

3️⃣ ARIA States

States describe conditions that change over time:

📝 Practical ARIA Examples

Example 1: Accessible Button Icon

// ❌ BAD: Icon button with no label
function BadIconButton() {
  return (
    <button onClick={handleDelete}>
      <TrashIcon />
    </button>
  );
}

// ✅ GOOD: Icon button with aria-label
function GoodIconButton() {
  return (
    <button 
      onClick={handleDelete}
      aria-label="Delete item"
    >
      <TrashIcon aria-hidden="true" />
    </button>
  );
}

// ✅ ALSO GOOD: Icon button with visible text
function BetterIconButton() {
  return (
    <button onClick={handleDelete}>
      <TrashIcon aria-hidden="true" />
      <span>Delete</span>
    </button>
  );
}

Example 2: Expandable Section

import { useState, useId, type ReactNode } from 'react';

interface AccordionProps {
  title: string;
  children: ReactNode;
}

function Accordion({ title, children }: AccordionProps) {
  const [isExpanded, setIsExpanded] = useState(false);
  // useId gives a stable, unique, SSR-safe id — never build ids from user text
  const contentId = useId();
  const buttonId = useId();

  return (
    <div className="accordion">
      <h3>
        <button
          type="button"
          id={buttonId}
          onClick={() => setIsExpanded((open) => !open)}
          aria-expanded={isExpanded}
          aria-controls={contentId}
        >
          {title}
          <span aria-hidden="true">{isExpanded ? '▼' : '▶'}</span>
        </button>
      </h3>

      <div
        id={contentId}
        role="region"
        aria-labelledby={buttonId}
        hidden={!isExpanded}
      >
        {children}
      </div>
    </div>
  );
}

// Usage
function AccordionDemo() {
  return (
    <Accordion title="What is accessibility?">
      <p>Accessibility means making your website usable by everyone...</p>
    </Accordion>
  );
}

Example 3: Form Field with Error

import { useState, useId } from 'react';

function AccessibleFormField() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState('');

  // One useId() call gives a unique prefix we derive related ids from —
  // safe even if this component renders many times on the page.
  const baseId = useId();
  const fieldId = `${baseId}-input`;
  const errorId = `${baseId}-error`;
  const hintId = `${baseId}-hint`;

  const validateEmail = (value: string) => {
    if (!value) {
      setError('Email is required');
      return false;
    }
    if (!value.includes('@')) {
      setError('Please enter a valid email address');
      return false;
    }
    setError('');
    return true;
  };

  return (
    <div className="form-field">
      <label htmlFor={fieldId}>
        Email Address
        <span aria-label="required">*</span>
      </label>
      
      <p id={hintId} className="hint">
        We'll never share your email with anyone else.
      </p>
      
      <input
        type="email"
        id={fieldId}
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        onBlur={() => validateEmail(email)}
        aria-required="true"
        aria-invalid={error ? 'true' : 'false'}
        aria-describedby={`${hintId} ${error ? errorId : ''}`}
      />
      
      {error && (
        <p id={errorId} className="error" role="alert">
          {error}
        </p>
      )}
    </div>
  );
}

⌨️ Keyboard Navigation

Many users navigate websites exclusively with a keyboard—whether by necessity (motor impairments), preference (power users), or temporary circumstance (broken trackpad). Every interactive element must be fully keyboard accessible.

⌨️ Essential Keyboard Shortcuts

These are the standard keyboard interactions users expect:

🎯 Making Elements Keyboard Accessible

When you need to make a non-interactive element keyboard accessible, follow these requirements:

// ❌ BAD: Div with click handler but no keyboard support
function BadClickableDiv() {
  return (
    <div onClick={handleClick} className="card">
      Click me
    </div>
  );
}

// ✅ GOOD: Proper button element
function GoodButton() {
  return (
    <button onClick={handleClick} className="card-button">
      Click me
    </button>
  );
}

// ✅ ACCEPTABLE: Div made keyboard accessible (if button isn't possible)
function AccessibleDiv() {
  const handleKeyDown = (e: React.KeyboardEvent) => {
    // Both Enter and Space should activate
    if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault(); // Prevent page scroll on Space
      handleClick();
    }
  };

  return (
    <div
      onClick={handleClick}
      onKeyDown={handleKeyDown}
      tabIndex={0}
      role="button"
      className="card"
    >
      Click me
    </div>
  );
}

📍 Focus Indicators

Users must be able to see which element has focus. Never remove focus outlines without providing an alternative!

// ❌ BAD: Removing focus outline with no replacement
const badStyles = {
  button: {
    outline: 'none' // Never do this!
  }
};

// ✅ GOOD: Custom focus styles that are visible
const goodStyles = `
  button:focus {
    outline: 3px solid #667eea;
    outline-offset: 2px;
  }

  /* Or use box-shadow for a subtler look */
  button:focus {
    outline: none; /* Only if you provide alternative */
    box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.5);
  }

  /* Modern approach with :focus-visible */
  button:focus-visible {
    outline: 3px solid #667eea;
    outline-offset: 2px;
  }
`;

🔢 Tab Order and tabIndex

The tab order should follow the visual flow of the page. Control it with the tabIndex attribute:

⌨️ Keyboard Event Handling

Here's a reusable hook for handling keyboard interactions:

import { KeyboardEvent } from 'react';

// Custom hook for keyboard interactions
function useKeyboardInteraction(
  onActivate: () => void,
  options: {
    enableSpace?: boolean;
    enableEnter?: boolean;
    preventDefault?: boolean;
  } = {}
) {
  const {
    enableSpace = true,
    enableEnter = true,
    preventDefault = true
  } = options;

  const handleKeyDown = (e: KeyboardEvent) => {
    const isSpace = e.key === ' ' || e.key === 'Spacebar';
    const isEnter = e.key === 'Enter';

    if ((enableSpace && isSpace) || (enableEnter && isEnter)) {
      if (preventDefault) {
        e.preventDefault();
      }
      onActivate();
    }
  };

  return { onKeyDown: handleKeyDown };
}

// Usage example
function CustomButton({ onClick, children }: { 
  onClick: () => void; 
  children: React.ReactNode;
}) {
  const keyboardProps = useKeyboardInteraction(onClick);

  return (
    <div
      role="button"
      tabIndex={0}
      onClick={onClick}
      {...keyboardProps}
      className="custom-button"
    >
      {children}
    </div>
  );
}

🎮 Advanced Keyboard Patterns

Some widgets require more complex keyboard interactions. Here's a tab component with proper keyboard support:

import { useState, useRef, useEffect, KeyboardEvent } from 'react';

interface Tab {
  id: string;
  label: string;
  content: React.ReactNode;
}

interface TabsProps {
  tabs: Tab[];
  defaultTab?: string;
}

function AccessibleTabs({ tabs, defaultTab }: TabsProps) {
  const [activeTab, setActiveTab] = useState(defaultTab || tabs[0]?.id);
  const tabRefs = useRef<(HTMLButtonElement | null)[]>([]);

  const handleKeyDown = (e: KeyboardEvent, index: number) => {
    let newIndex = index;

    switch (e.key) {
      case 'ArrowLeft':
        e.preventDefault();
        newIndex = index === 0 ? tabs.length - 1 : index - 1;
        break;
      case 'ArrowRight':
        e.preventDefault();
        newIndex = index === tabs.length - 1 ? 0 : index + 1;
        break;
      case 'Home':
        e.preventDefault();
        newIndex = 0;
        break;
      case 'End':
        e.preventDefault();
        newIndex = tabs.length - 1;
        break;
      default:
        return;
    }

    // Focus and activate the new tab
    tabRefs.current[newIndex]?.focus();
    setActiveTab(tabs[newIndex].id);
  };

  return (
    <div className="tabs">
      {/* Tab list */}
      <div role="tablist" aria-label="Content tabs">
        {tabs.map((tab, index) => {
          const isActive = tab.id === activeTab;
          
          return (
            <button
              key={tab.id}
              ref={el => tabRefs.current[index] = el}
              role="tab"
              id={`tab-${tab.id}`}
              aria-selected={isActive}
              aria-controls={`panel-${tab.id}`}
              tabIndex={isActive ? 0 : -1}
              onClick={() => setActiveTab(tab.id)}
              onKeyDown={(e) => handleKeyDown(e, index)}
              className={isActive ? 'tab active' : 'tab'}
            >
              {tab.label}
            </button>
          );
        })}
      </div>

      {/* Tab panels */}
      {tabs.map(tab => (
        <div
          key={tab.id}
          role="tabpanel"
          id={`panel-${tab.id}`}
          aria-labelledby={`tab-${tab.id}`}
          hidden={tab.id !== activeTab}
          tabIndex={0}
        >
          {tab.content}
        </div>
      ))}
    </div>
  );
}

🎯 Focus Management in SPAs

Single-page applications (SPAs) present unique focus management challenges. When content changes without a page reload, we must manually manage focus to ensure keyboard and screen reader users aren't lost.

A modal is the classic case. Here's the full lifecycle of focus when a dialog opens and closes — every arrow is a step you're responsible for in an SPA:

🔄 Focus Management on Route Changes

When users navigate to a new route, focus should move to the new page's main content:

import { useEffect, useRef } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();
  const mainRef = useRef<HTMLElement>(null);

  // Focus main content area on route change
  useEffect(() => {
    mainRef.current?.focus();
  }, [location.pathname]);

  return (
    <div>
      <header>
        <nav>{/* Navigation */}</nav>
      </header>

      <main 
        ref={mainRef}
        tabIndex={-1}
        className="main-content"
      >
        {/* Route content */}
      </main>
    </div>
  );
}

🪟 Focus Management in Modals

Modals require careful focus management to create a proper "focus trap":

import { useEffect, useRef, KeyboardEvent } from 'react';

interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
}

function AccessibleModal({ isOpen, onClose, title, children }: ModalProps) {
  const modalRef = useRef<HTMLDivElement>(null);
  const previousFocusRef = useRef<HTMLElement | null>(null);

  // Save focus when modal opens, restore when it closes
  useEffect(() => {
    if (isOpen) {
      // Save currently focused element
      previousFocusRef.current = document.activeElement as HTMLElement;
      
      // Focus the modal
      modalRef.current?.focus();

      // Prevent body scroll
      document.body.style.overflow = 'hidden';
    } else {
      // Restore focus to element that opened modal
      previousFocusRef.current?.focus();
      
      // Restore body scroll
      document.body.style.overflow = '';
    }

    return () => {
      document.body.style.overflow = '';
    };
  }, [isOpen]);

  // Handle Escape key
  useEffect(() => {
    const handleEscape = (e: globalThis.KeyboardEvent) => {
      if (e.key === 'Escape' && isOpen) {
        onClose();
      }
    };

    document.addEventListener('keydown', handleEscape);
    return () => document.removeEventListener('keydown', handleEscape);
  }, [isOpen, onClose]);

  // Trap focus within modal
  const handleKeyDown = (e: KeyboardEvent) => {
    if (e.key !== 'Tab') return;

    const focusableElements = modalRef.current?.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );

    if (!focusableElements || focusableElements.length === 0) return;

    const firstElement = focusableElements[0] as HTMLElement;
    const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;

    if (e.shiftKey && document.activeElement === firstElement) {
      // Tab backwards from first element
      e.preventDefault();
      lastElement.focus();
    } else if (!e.shiftKey && document.activeElement === lastElement) {
      // Tab forward from last element
      e.preventDefault();
      firstElement.focus();
    }
  };

  if (!isOpen) return null;

  return (
    <div className="modal-overlay" onClick={onClose}>
      <div
        ref={modalRef}
        role="dialog"
        aria-modal="true"
        aria-labelledby="modal-title"
        className="modal"
        onClick={(e) => e.stopPropagation()}
        onKeyDown={handleKeyDown}
        tabIndex={-1}
      >
        <header className="modal-header">
          <h2 id="modal-title">{title}</h2>
          <button
            onClick={onClose}
            aria-label="Close dialog"
            className="modal-close"
          >
            ×
          </button>
        </header>

        <div className="modal-content">
          {children}
        </div>

        <footer className="modal-footer">
          <button onClick={onClose}>Cancel</button>
          <button onClick={onClose} className="primary">Confirm</button>
        </footer>
      </div>
    </div>
  );
}

⚡ Focus Management Hook

Create a reusable hook for focus management:

import { useRef, useEffect } from 'react';

// Hook to manage focus for dynamic content
function useFocusManagement(isVisible: boolean) {
  const elementRef = useRef<HTMLElement>(null);
  const previousFocusRef = useRef<HTMLElement | null>(null);

  useEffect(() => {
    if (isVisible) {
      // Save current focus
      previousFocusRef.current = document.activeElement as HTMLElement;
      
      // Move focus to the element
      elementRef.current?.focus();
    } else if (previousFocusRef.current) {
      // Restore focus
      previousFocusRef.current.focus();
    }
  }, [isVisible]);

  return elementRef;
}

// Usage
function Dropdown({ isOpen, onClose }: DropdownProps) {
  const dropdownRef = useFocusManagement(isOpen);

  if (!isOpen) return null;

  return (
    <div
      ref={dropdownRef}
      tabIndex={-1}
      className="dropdown"
    >
      {/* Dropdown content */}
    </div>
  );
}

📍 Skip Links

Skip links allow keyboard users to bypass repetitive content:

function PageLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      {/* Skip link - first focusable element */}
      <a href="#main-content" className="skip-link">
        Skip to main content
      </a>

      <header>
        <nav>
          {/* Long navigation menu */}
        </nav>
      </header>

      <main id="main-content" tabIndex={-1}>
        {children}
      </main>
    </>
  );
}

// CSS for skip link
const skipLinkStyles = `
  .skip-link {
    position: absolute;
    top: -40px;
    left: 0;
    background: #667eea;
    color: white;
    padding: 8px;
    text-decoration: none;
    z-index: 1000;
  }

  .skip-link:focus {
    top: 0;
  }
`;

📢 ARIA Live Regions

ARIA live regions announce dynamic content changes to screen reader users. When content updates without a page reload, screen readers won't notice unless you tell them with live regions.

🔊 ARIA Live Politeness Levels

Live regions have different politeness levels that control how urgently changes are announced:

📝 Practical Examples

Example 1: Form Validation Messages

import { useState } from 'react';

function FormWithLiveValidation() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState('');

  const validateEmail = (value: string) => {
    if (!value.includes('@')) {
      setError('Please enter a valid email address');
    } else {
      setError('');
    }
  };

  return (
    <form>
      <label htmlFor="email">Email Address</label>
      <input
        type="email"
        id="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        onBlur={() => validateEmail(email)}
        aria-invalid={error ? 'true' : 'false'}
        aria-describedby={error ? 'email-error' : undefined}
      />
      
      {/* Live region for error - announces immediately */}
      {error && (
        <p 
          id="email-error" 
          role="alert"
          className="error"
        >
          {error}
        </p>
      )}
    </form>
  );
}

Example 2: Loading States

interface DataItem {
  id: string;
  name: string;
}

function DataList() {
  const [data, setData] = useState<DataItem[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  return (
    <div>
      <button type="button" onClick={fetchData}>Load Data</button>

      {/* Loading status - polite announcement */}
      <div 
        role="status" 
        aria-live="polite"
        aria-atomic="true"
      >
        {isLoading && 'Loading data...'}
        {!isLoading && data.length > 0 && `Loaded ${data.length} items`}
      </div>

      <ul>
        {data.map(item => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
    </div>
  );
}

Example 3: Toast Notifications

import { useState, useEffect } from 'react';

interface Toast {
  id: string;
  message: string;
  type: 'success' | 'error' | 'info';
}

function ToastContainer() {
  const [toasts, setToasts] = useState<Toast[]>([]);

  const addToast = (message: string, type: Toast['type']) => {
    const id = Date.now().toString();
    setToasts(prev => [...prev, { id, message, type }]);

    // Auto-dismiss after 5 seconds
    setTimeout(() => {
      setToasts(prev => prev.filter(t => t.id !== id));
    }, 5000);
  };

  return (
    <>
      {/* Live region for announcements */}
      <div
        role="status"
        aria-live="polite"
        aria-atomic="true"
        className="sr-only"
      >
        {toasts[toasts.length - 1]?.message}
      </div>

      {/* Visual toasts */}
      <div className="toast-container" aria-label="Notifications">
        {toasts.map(toast => (
          <div
            key={toast.id}
            className={`toast toast-${toast.type}`}
            role={toast.type === 'error' ? 'alert' : 'status'}
          >
            {toast.message}
            <button
              onClick={() => setToasts(prev => prev.filter(t => t.id !== toast.id))}
              aria-label="Dismiss notification"
            >
              ×
            </button>
          </div>
        ))}
      </div>
    </>
  );
}

// Screen reader only styles
const srOnlyStyles = `
  .sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border-width: 0;
  }
`;

🔄 Live Region Hook

Create a reusable hook for announcements:

import { useEffect, useRef } from 'react';

function useAnnounce() {
  const liveRegionRef = useRef<HTMLDivElement | null>(null);

  useEffect(() => {
    // Create live region if it doesn't exist
    if (!liveRegionRef.current) {
      const liveRegion = document.createElement('div');
      liveRegion.setAttribute('role', 'status');
      liveRegion.setAttribute('aria-live', 'polite');
      liveRegion.setAttribute('aria-atomic', 'true');
      liveRegion.className = 'sr-only';
      document.body.appendChild(liveRegion);
      liveRegionRef.current = liveRegion;
    }

    return () => {
      // Cleanup on unmount
      if (liveRegionRef.current) {
        document.body.removeChild(liveRegionRef.current);
        liveRegionRef.current = null;
      }
    };
  }, []);

  const announce = (message: string, priority: 'polite' | 'assertive' = 'polite') => {
    if (!liveRegionRef.current) return;

    // Clear previous message
    liveRegionRef.current.textContent = '';

    // Set priority
    liveRegionRef.current.setAttribute('aria-live', priority);

    // Small delay ensures screen readers notice the change
    setTimeout(() => {
      if (liveRegionRef.current) {
        liveRegionRef.current.textContent = message;
      }
    }, 100);
  };

  return announce;
}

// Usage
interface SearchResult {
  id: string;
  title: string;
}

function SearchResults() {
  const [results, setResults] = useState<SearchResult[]>([]);
  const announce = useAnnounce();

  const handleSearch = async (query: string) => {
    const data = await fetchResults(query);
    setResults(data);
    announce(`Found ${data.length} results for ${query}`);
  };

  return (
    <div>
      {/* Search UI */}
    </div>
  );
}

🏋️ Hands-on Exercises

Let's practice what we've learned! These exercises will help you apply accessibility concepts to real-world scenarios.

// ❌ BROKEN: Multiple accessibility issues
function BrokenNav() {
  const [isOpen, setIsOpen] = useState(false);
  
  return (
    <div className="nav">
      <div onClick={() => setIsOpen(!isOpen)}>
        Menu ☰
      </div>
      
      {isOpen && (
        <div className="menu">
          <div onClick={() => navigate('/')}>Home</div>
          <div onClick={() => navigate('/about')}>About</div>
          <div onClick={() => navigate('/contact')}>Contact</div>
        </div>
      )}
    </div>
  );
}

// ✅ FIXED: Fully accessible navigation
function AccessibleNav() {
  const [isOpen, setIsOpen] = useState(false);
  const menuRef = useRef<HTMLElement>(null);
  
  const toggleMenu = () => {
    setIsOpen(!isOpen);
  };
  
  // Close on Escape
  useEffect(() => {
    const handleEscape = (e: KeyboardEvent) => {
      if (e.key === 'Escape' && isOpen) {
        setIsOpen(false);
      }
    };
    
    document.addEventListener('keydown', handleEscape);
    return () => document.removeEventListener('keydown', handleEscape);
  }, [isOpen]);
  
  return (
    <nav aria-label="Main navigation">
      <button
        onClick={toggleMenu}
        aria-expanded={isOpen}
        aria-controls="main-menu"
        aria-label="Toggle navigation menu"
      >
        Menu ☰
      </button>
      
      {isOpen && (
        <ul id="main-menu" ref={menuRef}>
          <li><Link to="/">Home</Link></li>
          <li><Link to="/about">About</Link></li>
          <li><Link to="/contact">Contact</Link></li>
        </ul>
      )}
    </nav>
  );
}

interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
}

function Modal({ isOpen, onClose, title, children }: ModalProps) {
  // Your implementation here
  // Don't forget:
  // - useRef for modal element
  // - useRef for previous focus
  // - useEffect for focus management
  // - useEffect for Escape key
  // - useEffect for body scroll
  // - Focus trap in onKeyDown
  
  return (
    // Your JSX here
  );
}

npm install --save-dev vitest-axe @testing-library/react jsdom

import { render } from '@testing-library/react';
import { axe } from 'vitest-axe';
import { expect, test } from 'vitest';
import { SignupForm } from './SignupForm';

test('SignupForm has no detectable a11y violations', async () => {
  const { container } = render(<SignupForm />);

  // axe-core scans the rendered DOM and reports WCAG violations
  const results = await axe(container);

  expect(results).toHaveNoViolations();
});

📚 Summary

Congratulations! You've learned the fundamentals of web accessibility in React. Let's recap the key concepts:

🎯 Key Takeaways

🎨 The Accessibility Mindset

Building accessible applications isn't just about following rules—it's about adopting a mindset:

🛠️ Essential Tools

Keep these tools in your accessibility toolkit:

📖 Quick Reference

// Button
<button type="button">Click Me</button>

// Icon button
<button aria-label="Delete"><TrashIcon aria-hidden="true" /></button>

// Toggle button
<button aria-pressed={isPressed}>Bold</button>

// Expandable section
<button aria-expanded={isOpen} aria-controls="content-id">
  Section Title
</button>
<div id="content-id" hidden={!isOpen}>Content</div>

// Modal
<div role="dialog" aria-modal="true" aria-labelledby="title">
  <h2 id="title">Dialog Title</h2>
</div>

// Alert
<div role="alert">Error message</div>

// Status
<div role="status" aria-live="polite">Loading...</div>

// Tab interface
<div role="tablist">
  <button role="tab" aria-selected={isActive}>Tab 1</button>
</div>
<div role="tabpanel">Panel content</div>

🚀 What's Next?

You've mastered accessibility fundamentals! Here's how to continue your journey:

📚 Further Learning

• Next Lesson: Lesson 10.4 - Build and Deployment
• Practice: Audit and fix accessibility issues in your existing projects
• Read: WCAG 2.2 Quick Reference and the ARIA Authoring Practices Guide
• Test: Use screen readers (NVDA, VoiceOver) to experience your sites
• Learn: The A11Y Project for practical tips

🎯 Immediate Action Items

🌟 Continue Building

Apply what you've learned in the next lesson where we'll deploy our accessible applications to production!