Accessibility Auditor (WCAG 2.1)

When to use this skill

• User asks about accessibility or a11y
• User mentions WCAG or compliance levels
• User wants to audit a component or page
• User asks about aria labels or roles
• User needs accessible alternative patterns

Workflow

• Identify scope (component, page, site)
• Run automated audits
• Review manual checkpoints
• Categorize violations by severity
• Provide remediation examples
• Validate fixes

Instructions

Step 1: Run Automated Audits

axe-core (CLI):

npm install -D @axe-core/cli
npx axe http://localhost:3000 --exit

Lighthouse accessibility audit:

npx lighthouse http://localhost:3000 --only-categories=accessibility --output=json

ESLint accessibility plugin:

npm install -D eslint-plugin-jsx-a11y

// eslint.config.js
import jsxA11y from "eslint-plugin-jsx-a11y";

export default [jsxA11y.flatConfigs.recommended];

Step 2: WCAG 2.1 AA Checklist

Step 3: Common Violations & Fixes

Missing alt text:

// ❌ Violation
<img src="/hero.jpg" />

// ✅ Fixed - Informative image
<img src="/hero.jpg" alt="Team collaborating in modern office" />

// ✅ Fixed - Decorative image
<img src="/divider.svg" alt="" role="presentation" />

Low color contrast (4.5:1 minimum for AA):

/* ❌ Violation - 2.5:1 ratio */
.text-muted {
  color: #999999;
  background: #ffffff;
}

/* ✅ Fixed - 4.6:1 ratio */
.text-muted {
  color: #767676;
  background: #ffffff;
}

Missing form labels:

// ❌ Violation
<input type="email" placeholder="Email" />

// ✅ Fixed - Visible label
<label htmlFor="email">Email</label>
<input id="email" type="email" />

// ✅ Fixed - Visually hidden label
<label htmlFor="email" className="sr-only">Email</label>
<input id="email" type="email" placeholder="Email" />

Missing focus indicators:

/* ❌ Violation */
button:focus {
  outline: none;
}

/* ✅ Fixed */
button:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

Improper heading hierarchy:

// ❌ Violation - Skips h2
<h1>Page Title</h1>
<h3>Section Title</h3>

// ✅ Fixed
<h1>Page Title</h1>
<h2>Section Title</h2>

Non-semantic buttons:

// ❌ Violation
<div onClick={handleClick}>Click me</div>

// ✅ Fixed
<button type="button" onClick={handleClick}>Click me</button>

Missing skip link:

// ✅ Add at top of page
<a href="#main-content" className="skip-link">
  Skip to main content
</a>

// ... header/nav ...

<main id="main-content">
  {/* Page content */}
</main>

.skip-link {
  position: absolute;
  left: -9999px;
  z-index: 999;
  padding: 1rem;
  background: var(--color-background);
  color: var(--color-text);
}

.skip-link:focus {
  left: 1rem;
  top: 1rem;
}

Step 4: Interactive Component Patterns

Accessible modal:

import { useEffect, useRef } from "react";

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

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

  useEffect(() => {
    if (isOpen) {
      closeButtonRef.current?.focus();
      document.body.style.overflow = "hidden";
    }
    return () => {
      document.body.style.overflow = "";
    };
  }, [isOpen]);

  // Trap focus inside modal
  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === "Escape") onClose();
    if (e.key === "Tab") {
      const focusable = modalRef.current?.querySelectorAll<HTMLElement>(
        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
      );
      if (!focusable?.length) return;

      const first = focusable[0];
      const last = focusable[focusable.length - 1];

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

  if (!isOpen) return null;

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
      ref={modalRef}
      onKeyDown={handleKeyDown}
    >
      <div className="modal-backdrop" onClick={onClose} aria-hidden="true" />
      <div className="modal-content">
        <h2 id="modal-title">{title}</h2>
        {children}
        <button ref={closeButtonRef} onClick={onClose} aria-label="Close modal">
          ×
        </button>
      </div>
    </div>
  );
}

Accessible dropdown menu:

import { useState, useRef } from "react";

export function Dropdown({ label, items }: { label: string; items: string[] }) {
  const [isOpen, setIsOpen] = useState(false);
  const [activeIndex, setActiveIndex] = useState(-1);
  const buttonRef = useRef<HTMLButtonElement>(null);

  const handleKeyDown = (e: React.KeyboardEvent) => {
    switch (e.key) {
      case "ArrowDown":
        e.preventDefault();
        setActiveIndex((i) => Math.min(i + 1, items.length - 1));
        break;
      case "ArrowUp":
        e.preventDefault();
        setActiveIndex((i) => Math.max(i - 1, 0));
        break;
      case "Escape":
        setIsOpen(false);
        buttonRef.current?.focus();
        break;
      case "Enter":
      case " ":
        if (!isOpen) {
          setIsOpen(true);
          setActiveIndex(0);
        }
        break;
    }
  };

  return (
    <div onKeyDown={handleKeyDown}>
      <button
        ref={buttonRef}
        aria-expanded={isOpen}
        aria-haspopup="listbox"
        onClick={() => setIsOpen(!isOpen)}
      >
        {label}
      </button>
      {isOpen && (
        <ul role="listbox" aria-activedescendant={`item-${activeIndex}`}>
          {items.map((item, i) => (
            <li
              key={item}
              id={`item-${i}`}
              role="option"
              aria-selected={i === activeIndex}
            >
              {item}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Step 5: Testing Tools

Screen reader testing:

• macOS: VoiceOver (Cmd+F5)
• Windows: NVDA (free) or JAWS
• Browser: ChromeVox extension

Browser extensions:

• axe DevTools
• WAVE Evaluation Tool
• Accessibility Insights

Keyboard testing checklist:

• All interactive elements reachable via Tab
• Focus order matches visual order
• Focus visible on all elements
• Escape closes modals/dropdowns
• Arrow keys navigate within components

Step 6: Audit Report Template

## Accessibility Audit Report

**URL**: https://example.com
**Date**: 2026-01-18
**Standard**: WCAG 2.1 AA
**Tools**: axe-core, Lighthouse, manual testing

### Summary

| Severity | Count |
| -------- | ----- |
| Critical | 2     |
| Serious  | 5     |
| Moderate | 8     |
| Minor    | 3     |

### Critical Issues

#### 1. Images missing alt text

- **WCAG**: 1.1.1 Non-text Content
- **Location**: Homepage hero, product cards
- **Impact**: Screen reader users cannot understand image content
- **Fix**: Add descriptive alt text to all informative images

#### 2. Form inputs missing labels

- **WCAG**: 1.3.1 Info and Relationships
- **Location**: Contact form, search box
- **Impact**: Users cannot identify form field purpose
- **Fix**: Associate `<label>` with each input via `for`/`id`

### Recommendations

1. Add eslint-plugin-jsx-a11y to catch issues during development
2. Include accessibility testing in CI pipeline
3. Train team on keyboard navigation testing

Validation

Before completing:

• axe-core reports zero violations
• Lighthouse accessibility score ≥ 90
• Keyboard navigation works throughout
• Screen reader announces content correctly
• Color contrast meets 4.5:1 (text) / 3:1 (large text)
• Focus is visible on all interactive elements

Error Handling

• False positives: Some automated tools flag valid patterns; verify manually.
• Dynamic content: Re-run audits after JavaScript loads; use axe-core in tests.
• Third-party widgets: Document inaccessible third-party components for vendor follow-up.
• Complex widgets: Reference WAI-ARIA Authoring Practices for correct patterns.

Resources

• WCAG 2.1 Quick Reference
• WAI-ARIA Authoring Practices
• axe-core Rules
• A11y Project Checklist