Accessibility Tester Assistant

A senior accessibility testing agent with deep expertise in WCAG 2.1/3.0 standards, assistive technologies, and inclusive design principles, helping you identify and fix accessibility barriers across visual, auditory, motor, and cognitive dimensions.

When to Use This Agent

Choose Accessibility Tester Assistant when:

• Auditing web or mobile applications against WCAG 2.1 AA/AAA standards
• Fixing accessibility issues flagged by automated tools like axe or Lighthouse
• Implementing ARIA patterns for complex interactive components
• Testing keyboard navigation and screen reader compatibility
• Preparing for legal compliance requirements (ADA, Section 508, EAA)

Consider alternatives when:

• Designing new components from scratch (use a UI Designer agent first, then audit)
• Conducting user research with disabled users (use a UX research agent)
• Implementing visual design changes unrelated to accessibility (use a UI agent)

Quick Start

Copy
# .claude/agents/accessibility-tester-assistant.yml
name: Accessibility Tester Assistant
description: Audit and fix accessibility issues against WCAG standards
model: claude-sonnet
tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep

Example invocation:

claude "Audit src/components/Modal.tsx for WCAG 2.1 AA compliance and fix all issues found"

Core Concepts

WCAG Compliance Levels

Level	Criteria	Impact	Examples
A	30 criteria	Basic access	Alt text, keyboard access, no seizure triggers
AA	20 criteria	Usable experience	Color contrast 4.5:1, resize to 200%, focus visible
AAA	28 criteria	Optimal access	Contrast 7:1, sign language, reading level

Automated Audit Workflow

Copy
// Integration with axe-core for automated testing
import { AxeBuilder } from '@axe-core/playwright';
import { test, expect } from '@playwright/test';

test('page should have no accessibility violations', async ({ page }) => {
  await page.goto('/dashboard');

  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
    .exclude('.third-party-widget') // Exclude elements you cannot control
    .analyze();

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

// Targeted component audit
test('modal should be accessible', async ({ page }) => {
  await page.goto('/settings');
  await page.click('[data-testid="open-modal"]');

  const results = await new AxeBuilder({ page })
    .include('[role="dialog"]')
    .analyze();

  // Log detailed violation info
  results.violations.forEach(v => {
    console.log(`${v.id}: ${v.help}`);
    v.nodes.forEach(n => console.log(`  ${n.html}`));
  });

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

ARIA Pattern Reference

Copy
// Accessible modal dialog
function Modal({ isOpen, onClose, title, children }: ModalProps) {
  const titleId = useId();
  const descId = useId();

  useEffect(() => {
    if (isOpen) {
      // Trap focus inside modal
      const previousFocus = document.activeElement as HTMLElement;
      return () => previousFocus?.focus();
    }
  }, [isOpen]);

  if (!isOpen) return null;

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby={titleId}
      aria-describedby={descId}
      onKeyDown={(e) => e.key === 'Escape' && onClose()}
    >
      <h2 id={titleId}>{title}</h2>
      <div id={descId}>{children}</div>
      <button onClick={onClose} aria-label="Close dialog">
        <XIcon aria-hidden="true" />
      </button>
    </div>
  );
}

Configuration

Parameter	Description	Default
compliance_level	WCAG compliance target (A, AA, AAA)	AA
wcag_version	WCAG version to audit against (2.1, 2.2, 3.0)	2.1
audit_tool	Primary audit tool (axe, lighthouse, pa11y)	axe
test_framework	Test framework for automated checks	Auto-detect
include_best_practices	Include non-WCAG best practices	true
screen_readers	Screen readers to test (voiceover, nvda, jaws)	["voiceover"]

Best Practices

1. Run automated audits first, then do manual testing. Automated tools like axe-core catch roughly 30-40% of accessibility issues (missing alt text, insufficient contrast, missing labels). Always run them first to handle the low-hanging fruit. Then manually test keyboard navigation, screen reader announcements, and cognitive clarity — the issues automation cannot detect.

2. Implement focus management for every route change and dynamic content update. When a single-page app navigates to a new route, focus must move to the main content heading or a skip-to-content landmark. When dynamic content appears (toasts, modals, inline errors), announce it with aria-live regions or move focus to the new content. Without explicit focus management, keyboard and screen reader users get lost.

3. Use semantic HTML before reaching for ARIA. A native <button> element provides keyboard interaction, focus management, and screen reader announcements for free. A <div onClick> requires role="button", tabIndex={0}, onKeyDown for Enter and Space, and often still misses edge cases. The first rule of ARIA is "don't use ARIA" when a native element works. Reserve ARIA for patterns with no native equivalent (tabs, tree views, comboboxes).

4. Test with actual assistive technology, not just automated tools. Turn on VoiceOver (Mac) or NVDA (Windows) and navigate your application using only the keyboard. Listen to how content is announced. Interactive elements should state their name, role, and state. Form errors should be announced when they appear. This testing reveals the real user experience that no automated tool can measure.

5. Document accessibility patterns in your component library. For every component, document the keyboard interactions it supports, the ARIA attributes it uses, and the screen reader announcements it produces. Include accessibility testing instructions in the component's README. This prevents regressions when components are modified and helps new developers maintain accessibility standards.

Common Issues

Custom interactive elements are not keyboard accessible. Divs and spans with click handlers are invisible to keyboard users. Every interactive element must be focusable (tabIndex={0} or use a native focusable element), respond to Enter and Space key presses, and have a visible focus indicator. Convert <div onClick> to <button> where possible. For custom components like dropdowns, implement the full keyboard interaction pattern from the WAI-ARIA Authoring Practices Guide.

Dynamic content updates are not announced to screen readers. When content changes on the page without a full reload (toast notifications, form validation errors, live data updates), screen readers do not automatically announce the change. Use aria-live="polite" for non-urgent updates and aria-live="assertive" for critical alerts. Place the live region in the DOM before the content changes — dynamically added live regions may not be detected by all screen readers.

Color is used as the only means of conveying information. Marking required fields with red text, indicating errors with red borders, or showing status with colored dots fails for colorblind users. Supplement color with text labels, icons, or patterns. A form error needs both a red border and an error message. A status indicator needs both a colored dot and a text label. Test with a colorblind simulation tool (Chrome DevTools → Rendering → Emulate vision deficiencies) to verify.