Accessibility Assistant

Audits web applications against WCAG 2.1 standards and generates prioritized remediation plans with code fixes.

When to Use This Agent

Choose this agent when you need to:

• Perform a comprehensive WCAG 2.1 Level AA compliance audit on HTML, JSX, or template markup
• Remediate Lighthouse accessibility findings with concrete code fixes and ARIA corrections
• Establish accessibility testing workflows including screen reader and keyboard navigation checks

Consider alternatives when:

• You need automated CI/CD scanning without human-guided analysis (use axe-core or pa11y)
• The project requires WCAG 2.2 or Section 508 compliance beyond standard web guidelines

Quick Start

Configuration

Copy
name: accessibility-assistant
type: agent
category: web-tools

Example Invocation

Copy
claude agent:invoke accessibility-assistant "Audit the login form for WCAG 2.1 AA compliance"

Example Output

WCAG 2.1 AA Audit - Login Form
================================
CRITICAL (Level A):
  1. [1.1.1] img missing alt attribute (line 24)
     Fix: Add alt="Company logo"
  2. [4.1.2] Button lacks accessible name (line 47)
     Fix: Add aria-label="Submit login form"

MAJOR (Level AA):
  1. [1.4.3] Contrast ratio 3.2:1 on placeholder (requires 4.5:1)
     Fix: Change color from #999 to #767676

Score: 62/100 | 4 critical, 3 major, 2 minor

Core Concepts

WCAG Compliance Framework

Aspect	Details
Perceivable	Text alternatives, captions, adaptable content, and sufficient color contrast ratios
Operable	Keyboard accessible, sufficient time limits, no seizure triggers, navigable landmarks
Understandable	Readable text, predictable behavior, input assistance, and error identification
Robust	Assistive technology compatibility, valid markup, proper name-role-value patterns
Conformance	Level A (minimum), AA (legal standard), AAA (enhanced) with criteria per level

Audit Pipeline Architecture

+------------------+     +------------------+     +-------------------+
|  Markup          |---->|  WCAG Rule       |---->|  Violation        |
|  Ingestion       |     |  Engine          |     |  Classification   |
+------------------+     +------------------+     +-------------------+
                                                          |
         +-------------------+     +-------------------+  |
         |  Remediation      |<----|  Priority &       |<-+
         |  Report           |     |  Impact Scoring   |
         +-------------------+     +-------------------+

Configuration

Parameter	Type	Default	Description
conformance_level	string	"AA"	Target WCAG level: "A", "AA", or "AAA"
include_best_practices	boolean	true	Report best practices beyond strict WCAG
framework	string	"html"	Markup context: "html", "react", "angular", "vue"
contrast_mode	string	"normal"	Contrast checking: "normal" or "large-text" thresholds
report_format	string	"detailed"	Output: "summary", "detailed", or "developer" with fixes

Best Practices

1. Audit Early in Development - Integrate accessibility checks during component creation rather than after full page assembly. Retrofitting ARIA attributes into complex component trees costs significantly more than building them in from the start.

2. Test with Real Assistive Technologies - Automated rule engines catch approximately 30-40% of barriers. Complement audits with NVDA or VoiceOver testing to verify screen reader announcements, focus order, and live region updates.

3. Prioritize by User Impact - A missing form label blocks blind users from critical flows, while a decorative image without empty alt creates noise. Use impact scoring to triage fixes by affected users and barrier severity.

4. Maintain a Living Checklist - Treat audit output as a persistent checklist that evolves with the application. Re-run targeted audits against new components rather than waiting for full-page sweeps.

5. Document ARIA Decisions - Record the rationale for ARIA roles and properties alongside the implementation. This prevents future developers from removing attributes they do not understand, a common source of regression.

Common Issues

1. Dynamic Content Not Audited - Content rendered after interaction (modals, accordions) may not appear in static audits. Trigger all interactive states before running the agent to ensure dynamically injected elements are covered.

2. Framework ARIA Conflicts - React's synthetic events and Angular's change detection can interfere with live region announcements. Specify the framework parameter for framework-compatible ARIA recommendations.

3. Gradient Contrast False Positives - Text on gradient backgrounds may trigger failures based on the lightest portion. Verify manually at the actual text position and consider a semi-transparent backdrop.