Accessibility Auditor

Level A (Minimum):
  - All non-text content has text alternatives
  - Captions for prerecorded audio
  - Content is meaningful without color alone
  - Keyboard accessible (no keyboard traps)
  - No content that flashes more than 3 times/second
  - Pages have descriptive titles
  - Focus order is logical
  - Link purpose is determinable

Level AA (Standard -- target for most projects):
  - Everything in A, plus:
  - Captions for live audio
  - Color contrast 4.5:1 (text), 3:1 (large text)
  - Text resizable to 200% without loss
  - Images of text avoided (use real text)
  - Multiple ways to find pages (nav, search, sitemap)
  - Headings and labels are descriptive
  - Focus visible
  - Consistent navigation and identification
  - Error suggestion and prevention on forms

Level AAA (Enhanced):
  - Everything in AA, plus:
  - Sign language for prerecorded audio
  - Color contrast 7:1 (text), 4.5:1 (large text)
  - No timing limits
  - No interruptions (user controls all)
  - Re-authentication without data loss

Tools to run:
  1. axe-core (via browser extension or CI)
  2. Lighthouse accessibility audit
  3. WAVE browser extension
  4. ESLint with eslint-plugin-jsx-a11y

Automated tests catch:
  - Missing alt text
  - Missing form labels
  - Color contrast violations
  - Missing document language
  - Duplicate IDs
  - Missing landmark regions
  - Invalid ARIA attributes

Keyboard testing checklist:
  [ ] Tab through entire page -- can you reach all interactive elements?
  [ ] Shift+Tab -- does reverse order make sense?
  [ ] Enter/Space -- do buttons and links activate?
  [ ] Arrow keys -- do composite widgets (tabs, menus, listboxes) work?
  [ ] Escape -- do modals and dropdowns close?
  [ ] Focus is never trapped (except modals -- which should trap)
  [ ] Focus indicator is always visible
  [ ] Skip link present and functional
  [ ] Focus order matches visual order
  [ ] No unexpected focus changes

Test with at minimum:
  - NVDA + Firefox (Windows)
  - VoiceOver + Safari (macOS/iOS)
  - TalkBack + Chrome (Android)

Screen reader testing checklist:
  [ ] Page title announced on load
  [ ] Headings create logical outline (h1 -> h2 -> h3)
  [ ] Landmarks navigable (main, nav, aside, footer)
  [ ] Images have meaningful alt text (or empty alt for decorative)
  [ ] Form fields announce labels, required state, errors
  [ ] Dynamic content changes announced (live regions)
  [ ] Tables have headers and captions
  [ ] Links and buttons announce their purpose
  [ ] Custom components announce role, name, state
  [ ] Modal focus management works correctly

Manual checks:
  [ ] Content is understandable at 200% zoom
  [ ] Content reflows at 320px width (no horizontal scroll)
  [ ] Motion/animation respects prefers-reduced-motion
  [ ] Touch targets are at least 24x24px (WCAG 2.2)
  [ ] Error messages are clear and suggest fixes
  [ ] Timeout warnings given with option to extend
  [ ] Content makes sense with CSS disabled
  [ ] Reading order matches visual order

Priority order:
  1. Use native HTML elements (button, input, select, dialog, details)
  2. If native element exists but needs styling, style the native element
  3. Only use ARIA when no native element provides the semantics

Native HTML equivalents:
  <button>           instead of  <div role="button">
  <a href>           instead of  <span role="link">
  <input type="checkbox">  instead of  <div role="checkbox">
  <dialog>           instead of  <div role="dialog">
  <nav>              instead of  <div role="navigation">
  <details> ./<summary> instead of custom accordion

<!-- Tabs -->
<div role="tablist" aria-label="Account settings">
  <button role="tab" id="tab-1" aria-selected="true" aria-controls="panel-1">
    Profile
  </button>
  <button role="tab" id="tab-2" aria-selected="false" aria-controls="panel-2" tabindex="-1">
    Security
  </button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
  <!-- Profile content -->
</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
  <!-- Security content -->
</div>

<!-- Disclosure (use <details> if possible) -->
<button aria-expanded="false" aria-controls="faq-1">
  What is your return policy?
</button>
<div id="faq-1" hidden>
  <p>You can return items within 30 days.</p>
# ... (condensed) ...
<div role="alert">
  Your session will expire in 5 minutes.
</div>

<!-- Status -->
<div role="status" aria-live="polite">
  3 results found
</div>

aria-expanded="true|false"    -> Disclosure, accordion, dropdown
aria-selected="true|false"    -> Tabs, options, tree items
aria-checked="true|false|mixed" -> Checkboxes, switches
aria-pressed="true|false"     -> Toggle buttons
aria-current="page|step|location|date|true" -> Current item
aria-disabled="true"          -> Disabled (but still focusable)
aria-hidden="true"            -> Hidden from assistive tech (NOT visually)
aria-invalid="true"           -> Form validation error
aria-required="true"          -> Required field
aria-busy="true"              -> Loading state
aria-describedby="id"         -> Additional description
aria-labelledby="id"          -> Labelled by another element
aria-errormessage="id"        -> Error message reference

// Focus trap for modals
function Modal({ isOpen, onClose, children }: ModalProps) {
  const modalRef = useRef<HTMLDivElement>(null);
  const previousFocus = useRef<HTMLElement | null>(null);

  useEffect(() => {
    if (isOpen) {
      previousFocus.current = document.activeElement as HTMLElement;
      // Focus first focusable element in modal
      const firstFocusable = modalRef.current?.querySelector<HTMLElement>(
        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
      );
      firstFocusable?.focus();
    }
    return () => {
      // Restore focus on close
      previousFocus.current?.focus();
    };
  }, [isOpen]);

  // Trap Tab key within modal
  function handleKeyDown(e: KeyboardEvent) {
    # ... (condensed) ...
    <div className="modal-overlay" onClick={onClose}>
      <div ref={modalRef} role="dialog" aria-modal="true" aria-labelledby="modal-title"
           onKeyDown={handleKeyDown} onClick={e => e.stopPropagation()}>
        {children}
      </div>
    </div>
  );
}

<body>
  <a href="#main-content" class="skip-link">Skip to main content</a>
  <header><!-- navigation --></header>
  <main id="main-content" tabindex="-1">
    <!-- Main content -->
  </main>
</body>

<style>
.skip-link {
  position: absolute;
  top: -100%;
  left: 0;
  z-index: 9999;
  padding: 1rem;
  background: var(--color-brand);
  color: white;
}
.skip-link:focus {
  top: 0;
}
</style>

// For composite widgets: tabs, toolbars, menu bars
function Toolbar({ items }: ToolbarProps) {
  const [activeIndex, setActiveIndex] = useState(0);

  function handleKeyDown(e: React.KeyboardEvent, index: number) {
    let newIndex = index;
    switch (e.key) {
      case 'ArrowRight': newIndex = (index + 1) % items.length; break;
      case 'ArrowLeft': newIndex = (index - 1 + items.length) % items.length; break;
      case 'Home': newIndex = 0; break;
      case 'End': newIndex = items.length - 1; break;
      default: return;
    }
    e.preventDefault();
    setActiveIndex(newIndex);
  }

  useEffect(() => {
    document.getElementById(`tool-${activeIndex}`)?.focus();
  }, [activeIndex]);

  return (
    <div role="toolbar" aria-label="Formatting">
      {items.map((item, i) => (
        <button key={i} id={`tool-${i}`} tabIndex={i === activeIndex ? 0 : -1}
                onKeyDown={(e) => handleKeyDown(e, i)}>
          {item.label}
        </button>
      ))}
    </div>
  );
}

WCAG AA Requirements:
  Normal text (< 18pt or < 14pt bold):  4.5:1 contrast ratio
  Large text (>= 18pt or >= 14pt bold): 3:1 contrast ratio
  UI components and graphical objects:   3:1 contrast ratio

WCAG AAA Requirements:
  Normal text: 7:1
  Large text:  4.5:1

Tools:
  - Chrome DevTools (inspect element -> color picker shows ratio)
  - WebAIM Contrast Checker: [reference URL]
  - Stark browser extension
  - Polypane browser

Common failures:
  - Placeholder text with insufficient contrast
  - Disabled state text that is too faint
  - Text over images without overlay
  - Focus indicators that blend into background
  - Links distinguished only by color (no underline)

<!-- Properly labeled input -->
<label for="email">Email address</label>
<input id="email" type="email" required aria-describedby="email-hint email-error"
       aria-invalid="true" />
<p id="email-hint" class="hint">We'll never share your email.</p>
<p id="email-error" class="error" role="alert">Please enter a valid email address.</p>

<!-- Group related inputs -->
<fieldset>
  <legend>Shipping Address</legend>
  <label for="street">Street</label>
  <input id="street" type="text" autocomplete="street-address" />
  <label for="city">City</label>
  <input id="city" type="text" autocomplete="address-level2" />
</fieldset>

<!-- Radio group -->
<fieldset>
  <legend>Preferred contact method</legend>
  <label><input type="radio" name="contact" value="email" /> Email</label>
  <label><input type="radio" name="contact" value="phone" /> Phone</label>
  <label><input type="radio" name="contact" value="mail" /> Mail</label>
</fieldset>

<!-- Error summary at top of form -->
<div role="alert" aria-labelledby="error-heading">
  <h2 id="error-heading">There are 2 errors in your form</h2>
  <ul>
    <li><a href="#email">Email address is required</a></li>
    <li><a href="#password">Password must be at least 8 characters</a></li>
  </ul>
</div>

<!-- Polite: announced when screen reader is idle -->
<div aria-live="polite">
  Search returned 42 results
</div>

<!-- Assertive: interrupts current announcement -->
<div aria-live="assertive">
  Your session has expired. Please log in again.
</div>

<!-- Role shortcuts -->
<div role="status">...</div>   <!-- Equivalent to aria-live="polite" -->
<div role="alert">...</div>    <!-- Equivalent to aria-live="assertive" -->

<!-- aria-atomic: announce entire region or just changes -->
<div aria-live="polite" aria-atomic="true">
  Cart total: $42.00  <!-- Announces full text on change -->
</div>

<!-- Skeleton loading -->
<div aria-busy="true" aria-label="Loading user profile">
  <div class="skeleton" aria-hidden="true"></div>
</div>

<!-- After load -->
<div aria-busy="false">
  <h2>John Doe</h2>
  <p>john@example.com</p>
</div>

<!-- Inline loading indicator -->
<button aria-disabled="true">
  <span class="spinner" aria-hidden="true"></span>
  Saving...
  <span class="sr-only">Please wait, saving your changes</span>
</button>

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

/* Focusable variant (for skip links) */
.sr-only-focusable:focus,
.sr-only-focusable:active {
  position: static;
  width: auto;
  height: auto;
  padding: inherit;
  margin: inherit;
  overflow: visible;
  clip: auto;
  white-space: inherit;
}

// vitest + @testing-library + jest-axe
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('LoginForm has no accessibility violations', async () => {
  const { container } = render(<LoginForm />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

// Playwright accessibility testing
test('homepage meets accessibility standards', async ({ page }) => {
  await page.goto('/');
  const accessibilityScanResults = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
    .analyze();
  expect(accessibilityScanResults.violations).toEqual([]);
});