accessibility-agents

WCAG AA accessibility enforcement for Claude Code. 80 specialist agents + 25 commands that activate automatically when you work on web UI code.

How It Works

Five enforcement layers ensure accessibility-lead always activates for UI tasks:

1. Proactive detection (UserPromptSubmit) — Checks if the current directory is a web project by scanning for package.json with web dependencies, framework config files, and UI file extensions. In a web project, the delegation instruction fires on every prompt regardless of what you typed.
2. Edit gate (PreToolUse) — Hard blocks any Edit/Write to UI files (.jsx, .tsx, .vue, .css, .html, etc.) until the accessibility-lead agent has been consulted. Uses permissionDecision: "deny" to reject the tool call entirely. Not a reminder. A block.
3. Session marker (PostToolUse) — When the accessibility-lead agent completes, creates a session marker that unlocks the edit gate for the rest of the session.
4. Agent tools — accessibility-lead has Task, Read, Glob, Grep only. It MUST delegate to specialists via the Task tool. It cannot write code itself.
5. CLAUDE.md + Skills — Decision matrix and non-negotiable standards load every session. Skills (/aria, /audit, etc.) provide direct specialist access.

See the Hooks Guide for the full technical breakdown of why hooks were chosen over instructions, MCP, or plugin hooks alone.

Documentation

Guide	Description
Getting Started	Installation and setup for Claude Code, Copilot, Gemini CLI, Claude Desktop, Codex CLI
Hooks Guide	How the three-hook enforcement gate works and why
Configuration	Character budget, troubleshooting, environment variables
Architecture	How agents coordinate, decision matrix, knowledge domains
Agent Reference	Per-agent documentation (60 agents)
Advanced Guides	Scanning patterns, cross-platform handoff, platform references

Scan Configuration Templates

Pre-built scan profiles are available in templates/:

• strict -- All rules enabled, all severities reported
• moderate -- All rules enabled, errors and warnings only
• minimal -- Errors only, for quick triage

Copy the appropriate template to your project root as .a11y-office-config.json, .a11y-pdf-config.json, or .a11y-epub-config.json.

Installation

Standard (Recommended)

Register the marketplace and install the plugin:

claude plugin marketplace add Community-Access/accessibility-agents
claude plugin install accessibility-agents@community-access

Or interactively via /plugin in Claude Code.

Scopes:

• --scope user (default) -- personal, all projects
• --scope project -- team-shared via .claude/settings.json (committed to git)
• --scope local -- personal per-project via .claude/settings.local.json (gitignored)

For team projects, add to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "community-access": {
      "source": {
        "source": "github",
        "repo": "Community-Access/accessibility-agents"
      }
    }
  },
  "enabledPlugins": {
    "accessibility-agents@community-access": true
  }
}

Team members are auto-prompted to install when they open the project.

Offline install from a local clone:

claude plugin marketplace add ./path/to/local/clone
claude plugin install accessibility-agents@community-access

Alternative: GitHub Skill Setup

For embedding agents directly into a project directory (self-contained, zero network dependency), use the skill installer and setup commands:

gh skill install Community-Access/accessibility-agents
gh skill setup Community-Access/accessibility-agents

The installer copies agents and skills to your .claude/ directory:

.claude/
  agents/       # 80 agent files (auto-delegation)
  skills/       # 25 skills (manual shortcuts)

Optionally merges a CLAUDE.md snippet into your project root for rules enforcement.

Skills

Skill	Agent	What It Does
/aria	aria-specialist	ARIA patterns - roles, states, properties
/contrast	contrast-master	Color contrast - ratios, themes, visual design
/keyboard	keyboard-navigator	Keyboard nav - tab order, focus, shortcuts
/forms	forms-specialist	Forms - labels, validation, error handling
/alt-text	alt-text-headings	Images/headings - alt text, hierarchy, landmarks
/tables	tables-data-specialist	Tables - headers, scope, caption, sorting
/links	link-checker	Links - ambiguous text detection
/modal	modal-specialist	Modals - focus trap, return, escape
/live-region	live-region-controller	Live regions - dynamic announcements
/audit	web-accessibility-wizard	Full guided web accessibility audit
/document	document-accessibility-wizard	Document audit - Word, Excel, PPT, PDF
/markdown	markdown-a11y-assistant	Markdown audit - links, headings, emoji
/test	testing-coach	Testing - screen reader, keyboard, automated
/wcag	wcag-guide	WCAG reference - criteria explanations
/cognitive	cognitive-accessibility	Cognitive a11y - COGA, plain language
/mobile	mobile-accessibility	Mobile - React Native, touch targets
/design-system	design-system-auditor	Tokens - contrast, focus rings, spacing

Agents (59 total)

User-Facing Specialists

• accessibility-lead - Coordinates all specialists, runs final review on any UI task
• aria-specialist - ARIA roles, states, properties for custom widgets
• contrast-master - Color contrast, visual design, themes
• keyboard-navigator - Tab order, focus management, keyboard interaction
• forms-specialist - Form labels, validation, error handling
• alt-text-headings - Images, alt text, SVGs, heading structure, landmarks
• tables-data-specialist - Data tables, grids, sortable columns
• link-checker - Ambiguous link text detection
• modal-specialist - Dialogs, drawers, overlays, focus trapping
• live-region-controller - Dynamic content updates, toasts, loading states
• cognitive-accessibility - WCAG 2.2 cognitive SC, COGA guidance, plain language
• mobile-accessibility - React Native, Expo, iOS, Android accessibility
• design-system-auditor - Color tokens, focus rings, spacing tokens
• web-accessibility-wizard - Full guided web accessibility audit
• document-accessibility-wizard - Document audit (Word, Excel, PowerPoint, PDF)
• markdown-a11y-assistant - Markdown accessibility audit
• testing-coach - Screen reader, keyboard, automated testing guidance
• wcag-guide - WCAG 2.2 criteria explanations and conformance

Document Format Specialists

• word-accessibility - DOCX scanning and remediation
• excel-accessibility - XLSX scanning and remediation
• powerpoint-accessibility - PPTX scanning and remediation
• pdf-accessibility - PDF scanning and remediation
• epub-accessibility - EPUB scanning and remediation

GitHub Workflow Agents

• github-hub / nexus - GitHub command center orchestrators
• daily-briefing - Daily GitHub summary
• issue-tracker - Issue management
• pr-review - Pull request review
• analytics - Team metrics and velocity
• insiders-a11y-tracker - VS Code accessibility change tracking
• repo-admin - Repository settings and access
• team-manager - Organization team management
• contributions-hub - Community management
• template-builder - Issue/PR template wizard
• repo-manager - Repository infrastructure scaffolding

Internal Helpers (auto-invoked by orchestrators)

• document-inventory - File discovery and delta detection
• cross-document-analyzer - Cross-document pattern detection
• cross-page-analyzer - Cross-page web pattern detection
• web-issue-fixer - Web accessibility fix application
• scanner-bridge - GitHub Accessibility Scanner CI bridge
• lighthouse-bridge - Lighthouse CI audit bridge
• markdown-scanner - Per-file markdown scanning
• markdown-fixer - Markdown fix application
• markdown-csv-reporter - Markdown findings CSV export
• web-csv-reporter - Web findings CSV export
• document-csv-reporter - Document findings CSV export
• office-scan-config - Office scan configuration management
• pdf-scan-config - PDF scan configuration management
• epub-scan-config - EPUB scan configuration management

Auto-Delegation

You do not need to invoke agents manually for most tasks. Claude reads agent descriptions at startup and delegates automatically:

• "Build a login form" - accessibility-lead activates, pulls in forms-specialist + keyboard-navigator + aria-specialist
• "Review this component for accessibility" - accessibility-lead runs a full specialist review
• "Check the contrast on this page" - contrast-master activates directly
• "Audit this PDF" - document-accessibility-wizard activates

Skills are available when you want to target a specific specialist directly.

Verifying Enforcement

After installing, verify the enforcement gate is working:

Check proactive detection

1. Start Claude Code in any web project (has package.json with React/Next/Vue/etc.)
2. Type any prompt — even something generic like "fix the bug"
3. You should see the accessibility instruction in the system reminder: DETECTED: This is a web project

Check edit gate

1. Ask Claude to create or edit a .tsx file without first running the accessibility-lead
2. The Edit/Write should be denied with the message: BLOCKED: Cannot edit UI file...
3. Claude should then delegate to accessibility-lead
4. After the review completes, Claude should retry the edit successfully

Check agent tools

Run /agents in Claude Code. The accessibility-lead agent should show tools: Task, Read, Glob, Grep (no Write, Edit, or Bash). This forces it to delegate via the Task tool.

Troubleshooting

• Agents not loading: Restart Claude Code. Check ~/.claude/plugins/installed_plugins.json for the accessibility-agents entry.
• Edit not blocked: Check ~/.claude/settings.json has the a11y-enforce-edit.sh hook registered under PreToolUse. Verify the script is executable: chmod +x ~/.claude/hooks/a11y-enforce-edit.sh.
• Edit blocked even after review: Check the session marker: ls /tmp/a11y-reviewed-*. If missing, verify a11y-mark-reviewed.sh is registered under PostToolUse with matcher Agent.
• Hooks not firing at all: Verify ~/.claude/settings.json has all three hooks registered. Run cat ~/.claude/hooks/a11y-team-eval.sh to verify scripts exist.
• Wrong agent invoked: All agents use kebab-case names (e.g., accessibility-lead, not Accessibility Lead). Internal helpers are prefixed with "Internal helper agent." in their descriptions to prevent accidental routing.
• accessibility-lead writes code directly: Verify its tools are Task, Read, Glob, Grep. If it has Write or Edit, refresh the install with gh skill repair Community-Access/accessibility-agents.

See the Hooks Guide for detailed testing commands and manual debugging steps.

Updating

# Marketplace installs
claude plugin update accessibility-agents@community-access

# Skill-based installs
gh extension upgrade gh-skill
gh skill setup Community-Access/accessibility-agents

Uninstalling

gh skill uninstall Community-Access/accessibility-agents

License

MIT