Accessibility Audit

Comprehensive WCAG 2.1 Level AA accessibility audit using the accessibility-specialist agent.

Usage

/audit-a11y — Full WCAG 2.1 AA audit (standard depth)
/audit-a11y --quick --scope=current-pr — Pre-commit check on PR changes
/audit-a11y --comprehensive --format=summary — Pre-release deep audit with executive summary
/audit-a11y --standard --format=json — CI/CD integration output
/audit-a11y contrast — Legacy focus area (still supported)

Arguments

Depth Modes

--quick — Critical WCAG AA failures only (~5 min)
--standard — Full WCAG AA audit (default, ~15 min)
--comprehensive — WCAG AA + AAA + best practices (~30 min)

Scope Control

--scope=current-pr — Only files changed in current PR (uses git diff)
--scope=module=<name> — Specific module/directory
--scope=file=<path> — Single file
--scope=entire — Full codebase (default)

Output Formats

--format=report — Detailed markdown report (default)
--format=json — Structured JSON for CI/CD
--format=summary — Executive summary
--format=checklist — Simple pass/fail checklist

Legacy Focus Areas (Still Supported)

contrast, keyboard, aria, semantic-html, headings, forms, alt-text

Environment Detection

Tier 1 — Portable (Claude Desktop, Codex, any environment)

When Task() or bash tools are unavailable, perform accessibility analysis directly:

Parse arguments — Determine depth mode, scope, format, and any legacy focus area from the user's request
Identify files to analyze — Read project structure using Glob and Grep to find relevant HTML, PHP, Twig, and template files
Analyze accessibility directly:
- Use Read to examine files for semantic HTML, ARIA attributes, form labels, alt text
- Calculate color contrast from CSS/SCSS color values
- Check heading hierarchy and landmark regions
- Review keyboard accessibility patterns
- Identify CMS-specific patterns (Drupal Form API, WordPress block markup)
Generate report — Format findings per requested output format, prioritized Critical → Serious → Moderate → Minor
Save report — Write to audit-a11y-YYYY-MM-DD-HHMM.md and present path to user

Supported checks in Tier 1: semantic HTML, ARIA usage, form labels, alt text, heading hierarchy, color values in CSS, keyboard patterns visible in code.

Tier 2 — Claude Code Enhanced

When running in Claude Code with Task() available:

Parse arguments — Determine depth, scope, format, and focus area

Determine files — For --scope=current-pr, run:

git diff --name-only origin/main...HEAD | grep -E '\.(php|tsx?|jsx?|twig|html|css|scss)$'

Spawn accessibility-specialist:

Task(cms-cultivator:accessibility-specialist:accessibility-specialist,
     prompt="Perform a comprehensive WCAG 2.1 Level AA accessibility audit with:
       - Depth mode: {depth}
       - Scope: {scope}
       - Format: {format}
       - Focus area: {focus or 'complete audit'}
       - Files to analyze: {file_list}
     Check semantic HTML, ARIA, keyboard navigation, color contrast, and screen reader compatibility for both Drupal and WordPress patterns. Save the comprehensive audit report to audit-a11y-YYYY-MM-DD-HHMM.md and present the file path to the user.")

Present results to user with file path

What Gets Audited

Perceivable (WCAG Principle 1)

Alt text on images (1.1.1), decorative images have alt=""
Color contrast ≥ 4.5:1 normal text, ≥ 3:1 large text (1.4.3, 1.4.11)
Color not sole indicator of information (1.4.1)
Semantic HTML structure and logical reading order (1.3.1, 1.3.2)

Operable (WCAG Principle 2)

All functionality via keyboard, no keyboard traps (2.1.1, 2.1.2)
Skip links, descriptive titles, logical focus order (2.4.1–2.4.7)
Visible focus indicators on all interactive elements

Understandable (WCAG Principle 3)

Page language defined (3.1.1), language changes marked (3.1.2)
Consistent navigation and component identification (3.2.3, 3.2.4)
Form errors identified, labels provided, error suggestions offered (3.3.1–3.3.4)

Robust (WCAG Principle 4)

Valid HTML markup (4.1.1), name/role/value for UI components (4.1.2)
Status messages accessible without focus (4.1.3)

CMS-Specific Checks

Drupal: Form API label usage, Views table captions, block landmark regions, menu aria-labels, admin keyboard navigation

WordPress: Block editor aria-labels, widget headings, theme template skip links, navigation aria attributes, Customizer focus management

Output Report Format

# Accessibility Audit Report

**Scope**: [files audited]
**Date**: [date]
**WCAG Version**: 2.1 Level AA

## Executive Summary
- Total Issues: [count]
- Critical: [count] | Serious: [count] | Moderate: [count] | Minor: [count]
- Overall Status: [Pass/Partial/Non-Conformance]

## Critical Issues 🔴
## Serious Issues 🟡
## Moderate Issues 🟠
## Minor Issues 🔵
## Accessibility Wins ✅
## Priority Actions

Quick Start (Kanopi Projects)

ddev exec npx axe [url]
ddev exec npx pa11y [url]
ddev exec npx lighthouse [url] --only-categories=accessibility

Related Skills

accessibility-checker — Quick element-specific checks during development (auto-activates on "is this accessible?")
audit-export — Export findings to CSV for project management tools
audit-report — Generate client-facing executive summary from audit file

accessibility-audit