Guide Web Accessibility Checker

Audit web interfaces for WCAG 2.2 compliance, assistive technology compatibility, and inclusive design patterns across all disability categories.

When to Use This Agent

Choose this agent when you need to:

• Perform WCAG 2.1/2.2 compliance audits at A, AA, or AAA levels with prioritized remediation guidance
• Test components for screen reader compatibility, keyboard navigation flow, and focus management
• Evaluate color contrast ratios, motion sensitivity, and cognitive accessibility across responsive breakpoints

Consider alternatives when:

• Your concern is AI fairness and algorithmic bias rather than interface accessibility
• You need full interface redesign rather than auditing existing implementations

Quick Start

Configuration

Copy
name: guide-web-accessibility-checker
type: agent
category: web-tools

Example Invocation

Copy
claude agent:invoke guide-web-accessibility-checker "Audit our checkout flow for WCAG 2.2 AA compliance"

Example Output

Accessibility Audit Report
===========================
Scope: Checkout Flow (5 pages) | Standard: WCAG 2.2 AA

CRITICAL: Payment fields lack labels (1.3.1), coupon button
unreachable via keyboard (2.1.1), error text contrast 3.1:1 (1.4.3)

SERIOUS: Two H1 elements on shipping page (2.4.6), placeholder-only
labels on email (3.3.2), 18x18px remove buttons (2.5.8)

SCREEN READER: Cart quantities read without context, card field
type not communicated, success message not in live region

Violations: 11 critical, 8 serious, 14 moderate | Conformance: 62%

Core Concepts

WCAG 2.2 Principles Overview

Aspect	Details
Perceivable	Text alternatives, captions, adaptable layouts, sufficient contrast
Operable	Keyboard access, timing adjustability, seizure prevention, navigability
Understandable	Readable text, predictable behavior, input assistance, error prevention
Robust	Name/role/value exposure, status messages, assistive tech compatibility
Testing	Automated scanning (axe-core), manual keyboard testing, screen reader verification

Accessibility Audit Architecture

+------------------+     +------------------+     +------------------+
|  Automated Scan  |---->|  Rule Engine     |---->|  Violation       |
|  axe-core / pa11y|     |  WCAG Criteria   |     |  Classification  |
+------------------+     +------------------+     +------------------+
        |                        |                        |
        v                        v                        v
+------------------+     +------------------+     +------------------+
|  Manual Testing  |     |  Assistive Tech  |     |  Remediation     |
|  Keyboard Flow   |     |  Screen Reader   |     |  Guide + Code    |
+------------------+     +------------------+     +------------------+

Configuration

Parameter	Type	Default	Description
conformance_level	string	"AA"	Target level: A, AA, or AAA
wcag_version	string	"2.2"	Version to audit against: 2.0, 2.1, 2.2
screen_readers	array	["NVDA","VoiceOver"]	Assistive technologies for testing
contrast_standard	string	"enhanced"	Minimum (3:1/4.5:1) or enhanced (4.5:1/7:1)
include_best_practices	boolean	true	Include non-WCAG recommendations

Best Practices

1. Test Keyboard Navigation as Complete Journeys - Navigate entire user flows using only the keyboard to reveal focus traps, illogical tab orders, and missing skip links that component-level testing misses. Document the exact key sequence for each critical task.

2. Pair Automated Scanning with Manual Verification - Automated tools catch roughly 30-40% of WCAG violations. Logical reading order, meaningful link text, and context-dependent alt text quality require human judgment. Use automation for low-hanging fruit, then test what it cannot assess.

3. Write Alt Text by Function, Not Description - Alt text communicates the image's purpose in context. A testimonial photo needs "Sarah Chen, VP Engineering at Acme" not "Woman smiling in office." Decorative images get empty alt attributes, never omitted ones.

4. Design Error Handling for Screen Readers - Form errors must be associated via aria-describedby, announced via live regions when appearing dynamically, and navigable from an error summary. Visual-only indicators are invisible to screen reader users.

5. Respect Motion Preferences - Honor prefers-reduced-motion with alternative non-animated presentations. Provide pause and stop controls for content that moves or auto-updates for more than five seconds.

Common Issues

1. ARIA Misuse Worsening Accessibility - A role="button" on a div without keyboard handlers creates an element announced as interactive but not activatable. Prefer native HTML elements over ARIA-enhanced generic elements whenever possible.

2. Dynamic Content Not Announced - SPA content updates happen without notifying assistive tech. Use aria-live="polite" for non-urgent updates and aria-live="assertive" for critical changes like form submission results.

3. Focus Management After Modals - Opening modals without moving focus inside, or closing without restoring focus to the trigger, strands keyboard users. Implement focus trapping within modals and restore focus on close.