Web Accessibility: Building Inclusive Applications

Accessibility ensures everyone can use your application, including people with disabilities. This guide covers WCAG guidelines, ARIA patterns, and practical implementation techniques.

WCAG Principles (POUR)#

1. Perceivable#

Content must be presentable in ways users can perceive:

<!-- Provide text alternatives for images -->
<img src="chart.png" alt="Sales increased 25% from Q1 to Q2 2024">

<!-- Don't rely on color alone -->
<span class="status error">
  <span class="icon" aria-hidden="true">✕</span>
  Error: Invalid email address
</span>

<!-- Provide captions for videos -->
<video controls>
  <source src="demo.mp4" type="video/mp4">
  <track kind="captions" src="captions.vtt" srclang="en" label="English">
</video>

2. Operable#

Interface must be operable by all users:

<!-- Keyboard accessible -->
<button onclick="submitForm()">Submit</button>

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

<!-- Sufficient time for interactions -->
<div role="alert" aria-live="polite">
  Session expires in 5 minutes.
  <button onclick="extendSession()">Extend session</button>
</div>

3. Understandable#

Content and operation must be understandable:

<!-- Specify page language -->
<html lang="en">

<!-- Label form inputs -->
<label for="email">Email address</label>
<input type="email" id="email" name="email" required>

<!-- Provide error guidance -->
<div class="error" id="email-error" role="alert">
  Please enter a valid email address (e.g., name@example.com)
</div>

4. Robust#

Content must be robust for various technologies:

<!-- Use semantic HTML -->
<nav aria-label="Main navigation">
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

<!-- Valid HTML -->
<button type="submit">Send</button>
<!-- Not: <div onclick="send()">Send</div> -->

Semantic HTML#

Document Structure#

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Page Title - Site Name</title>
</head>
<body>
  <a href="#main" class="skip-link">Skip to main content</a>

  <header>
    <nav aria-label="Main">
      <!-- Navigation -->
    </nav>
  </header>

  <main id="main">
    <h1>Page Title</h1>

    <article>
      <h2>Article Title</h2>
      <p>Content...</p>
    </article>

    <aside aria-label="Related content">
      <!-- Sidebar -->
    </aside>
  </main>

  <footer>
    <!-- Footer content -->
  </footer>
</body>
</html>

Heading Hierarchy#

<!-- Correct: Sequential headings -->
<h1>Main Title</h1>
  <h2>Section 1</h2>
    <h3>Subsection 1.1</h3>
    <h3>Subsection 1.2</h3>
  <h2>Section 2</h2>
    <h3>Subsection 2.1</h3>

<!-- Wrong: Skipping levels -->
<h1>Main Title</h1>
  <h3>Section</h3>  <!-- Skipped h2 -->

ARIA Patterns#

Live Regions#

<!-- Polite: Announced when idle -->
<div role="status" aria-live="polite">
  3 items in your cart
</div>

<!-- Assertive: Announced immediately -->
<div role="alert" aria-live="assertive">
  Error: Payment failed. Please try again.
</div>

<!-- React implementation -->
function Notification({ message, type }) {
  return (
    <div
      role={type === 'error' ? 'alert' : 'status'}
      aria-live={type === 'error' ? 'assertive' : 'polite'}
    >
      {message}
    </div>
  );
}

function Modal({ isOpen, onClose, title, children }) {
  const modalRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (isOpen) {
      // Focus the modal when opened
      modalRef.current?.focus();

      // Trap focus inside modal
      const handleTab = (e: KeyboardEvent) => {
        if (e.key === 'Tab') {
          const focusable = modalRef.current?.querySelectorAll(
            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
          );
          if (focusable) {
            const first = focusable[0] as HTMLElement;
            const last = focusable[focusable.length - 1] as HTMLElement;

            if (e.shiftKey && document.activeElement === first) {
              e.preventDefault();
              last.focus();
            } else if (!e.shiftKey && document.activeElement === last) {
              e.preventDefault();
              first.focus();
            }
          }
        }
        if (e.key === 'Escape') {
          onClose();
        }
      };

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

  if (!isOpen) return null;

  return (
    <div
      className="modal-overlay"
      onClick={onClose}
      aria-hidden="true"
    >
      <div
        ref={modalRef}
        role="dialog"
        aria-modal="true"
        aria-labelledby="modal-title"
        tabIndex={-1}
        onClick={e => e.stopPropagation()}
      >
        <h2 id="modal-title">{title}</h2>
        {children}
        <button onClick={onClose}>Close</button>
      </div>
    </div>
  );
}

Tabs#

function Tabs({ tabs }) {
  const [activeIndex, setActiveIndex] = useState(0);

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

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

    e.preventDefault();
    setActiveIndex(newIndex);
  };

  return (
    <div>
      <div role="tablist" aria-label="Content tabs">
        {tabs.map((tab, index) => (
          <button
            key={tab.id}
            role="tab"
            id={`tab-${tab.id}`}
            aria-selected={index === activeIndex}
            aria-controls={`panel-${tab.id}`}
            tabIndex={index === activeIndex ? 0 : -1}
            onClick={() => setActiveIndex(index)}
            onKeyDown={(e) => handleKeyDown(e, index)}
          >
            {tab.label}
          </button>
        ))}
      </div>

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

Forms#

Accessible Form Pattern#

function ContactForm() {
  const [errors, setErrors] = useState<Record<string, string>>({});

  return (
    <form onSubmit={handleSubmit} noValidate>
      <div className="form-group">
        <label htmlFor="name">
          Name <span aria-hidden="true">*</span>
          <span className="visually-hidden">(required)</span>
        </label>
        <input
          type="text"
          id="name"
          name="name"
          required
          aria-required="true"
          aria-invalid={!!errors.name}
          aria-describedby={errors.name ? 'name-error' : undefined}
        />
        {errors.name && (
          <div id="name-error" className="error" role="alert">
            {errors.name}
          </div>
        )}
      </div>

      <fieldset>
        <legend>Contact preference</legend>
        <div>
          <input type="radio" id="email-pref" name="contact" value="email" />
          <label htmlFor="email-pref">Email</label>
        </div>
        <div>
          <input type="radio" id="phone-pref" name="contact" value="phone" />
          <label htmlFor="phone-pref">Phone</label>
        </div>
      </fieldset>

      <button type="submit">Send message</button>
    </form>
  );
}

Error Handling#

function FormWithValidation() {
  const [errors, setErrors] = useState<string[]>([]);
  const errorSummaryRef = useRef<HTMLDivElement>(null);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const newErrors = validate(formData);

    if (newErrors.length > 0) {
      setErrors(newErrors);
      // Focus error summary
      errorSummaryRef.current?.focus();
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      {errors.length > 0 && (
        <div
          ref={errorSummaryRef}
          role="alert"
          tabIndex={-1}
          className="error-summary"
        >
          <h2>There are {errors.length} errors in this form</h2>
          <ul>
            {errors.map((error, index) => (
              <li key={index}>
                <a href={`#${error.field}`}>{error.message}</a>
              </li>
            ))}
          </ul>
        </div>
      )}
      {/* Form fields */}
    </form>
  );
}

Focus Management#

Visible Focus Styles#

/* Never remove focus outlines completely */
:focus {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

/* Use :focus-visible for keyboard-only focus */
:focus:not(:focus-visible) {
  outline: none;
}

:focus-visible {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

/* Skip link */
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  padding: 8px;
  background: #000;
  color: #fff;
  z-index: 100;
}

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

Managing Focus in SPAs#

function usePageFocus(pageTitle: string) {
  const headingRef = useRef<HTMLHeadingElement>(null);

  useEffect(() => {
    // Update document title
    document.title = pageTitle;

    // Focus main heading
    headingRef.current?.focus();

    // Announce page change
    const announcement = document.createElement('div');
    announcement.setAttribute('role', 'status');
    announcement.setAttribute('aria-live', 'polite');
    announcement.className = 'visually-hidden';
    announcement.textContent = `Navigated to ${pageTitle}`;
    document.body.appendChild(announcement);

    return () => {
      document.body.removeChild(announcement);
    };
  }, [pageTitle]);

  return headingRef;
}

function Page({ title, children }) {
  const headingRef = usePageFocus(title);

  return (
    <main>
      <h1 ref={headingRef} tabIndex={-1}>{title}</h1>
      {children}
    </main>
  );
}

Testing Accessibility#

Automated Testing#

// Jest + Testing Library
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('form is accessible', async () => {
  const { container } = render(<ContactForm />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

// Playwright
test('page meets accessibility standards', async ({ page }) => {
  await page.goto('/');

  const accessibilityScanResults = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();

  expect(accessibilityScanResults.violations).toEqual([]);
});

Manual Testing Checklist#

Navigate using keyboard only (Tab, Enter, Space, Arrows)
Test with screen reader (VoiceOver, NVDA, JAWS)
Zoom to 200% - ensure content remains usable
Use high contrast mode
Disable images - check alt text adequacy
Check color contrast ratios (4.5:1 for text)

Conclusion#

Accessibility benefits everyone. Start with semantic HTML, add ARIA only when needed, and test with real assistive technologies. Build accessibility into your development process from the beginning.

Share this article