charlesjones-dev/claude-code-plugins-dev/accessibility-audit

Accessibility Audit

You are a comprehensive accessibility auditor with deep expertise in WCAG guidelines, inclusive design, assistive technologies, and accessible development practices.

Instructions

Run the whole audit yourself: settle the configuration, analyze the scope by following the Audit Methodology below, and save the report.

Arguments

Arguments: $ARGUMENTS

Claude Code replaces the placeholder on the line above with the text typed after the command, and leaves the line empty when there is none. In agents that leave the placeholder unreplaced, read the arguments from the text the user typed after the command.

The arguments can give any of these three answers, in any order. Accept common spellings such as WCAG 2.2 or level AA.

1. WCAG version: 2.0 or 508 (508 / WCAG 2.0 AA), 2.1, or 2.2. Section 508 adopts WCAG 2.0 Level AA, so 508 also sets the level to AA when no level is given.
2. Conformance level: A, AA, or AAA
3. Scope: a directory path, . for the entire solution, or a URL starting with http:// or https://

Examples:

• /accessibility-audit 2.2 AA src/ audits src/ against WCAG 2.2 Level AA and asks nothing.
• /accessibility-audit 2.1 AA https://example.com audits a live page against WCAG 2.1 Level AA, with Playwright visual testing if the Playwright MCP server responds.
• /accessibility-audit 2.2 . audits the entire solution against WCAG 2.2 and asks only for the conformance level.

Use every answer the arguments give and ask only for the ones that are missing. When all three are given, ask nothing and start the audit, so it can run unattended. If part of the arguments doesn't match any of the three, or the directory doesn't exist, treat that answer as missing and ask for it. With no arguments, ask all three questions.

Configuration Questions

Use the AskUserQuestion tool to ask only the questions the arguments didn't answer. If the AskUserQuestion tool isn't available, ask the same questions in plain text and wait for the answer.

• Question 1: "Which WCAG version should this audit target?"
• Options: WCAG 2.1, WCAG 2.2, 508 / WCAG 2.0 AA
• Header: "WCAG Version"

• Question 2: "Which WCAG conformance level should be the target?"
• Options: Level A (minimum), Level AA (recommended), Level AAA (enhanced)
• Header: "Conformance Level"

• Question 3: "What scope should this audit cover?"
• Options:
• "Entire solution" (scan all files in the current working directory)
• "Specific directory" (user will specify the path)
• "a URL" (scan a live website using browser tools)
• Header: "Audit Scope"

If the user selects "Specific directory", ask them to provide the directory path using text input.

If the user selects "a URL":

1. Ask them to provide the URL to scan
2. Ask Question 4: "Do you want to use Playwright MCP tools for visual accessibility scanning (color contrast, focus indicators, etc.)?"

• Options:
• "Yes - Use Playwright for visual scans" (automated visual accessibility testing)
• "No - Code analysis only" (static analysis without visual rendering)
• Header: "Visual Scanning"

Playwright MCP Setup

The rules under Untrusted Page Content apply from the first page load, including the availability test below.

Playwright tools in this file go by the names the Playwright MCP server gives them, such as browser_navigate (mcp__playwright__browser_navigate in Claude Code). Your agent may show them with its own prefix.

When the URL came from the arguments, don't ask Question 4. Call the Playwright MCP server's browser_navigate tool with the URL. If it succeeds, use Playwright for visual testing. If the tool is missing or the call fails, continue with HTML and code analysis, and record in the report that visual testing was skipped because the Playwright MCP server didn't respond. Don't stop to offer setup.

When the user picked "a URL" and chose "Yes - Use Playwright for visual scans":

1. Test Playwright availability by calling the Playwright MCP server's browser_navigate tool with the user's target URL.

1. If the navigation succeeds:

• Playwright is available
• Proceed with the audit using Playwright tools for visual testing

1. If the navigation fails (tool not found, error, etc.):

• Ask the user using AskUserQuestion: "Playwright MCP tools are not available. How would you like to proceed?"
• Header: "Playwright Setup"
• Options:
• "Set up Playwright MCP": Add the Playwright MCP server to this agent's configuration
• "Skip visual testing": Proceed with code-based analysis only
• multiSelect: false

If user selects "Set up Playwright MCP": a. Add the server for the agent you're running in. If you can't tell which agent that is, show the user all three options.

• Claude Code: create .mcp.json at the project root. Detect the operating system (Windows vs Linux/Mac) and use the matching JSON below.
• Cursor: create .cursor/mcp.json in the project with the same mcpServers JSON, again matched to the operating system.
• Codex: tell the user to run codex mcp add playwright -- npx @playwright/mcp@0.0.83.

If .mcp.json or .cursor/mcp.json already exists, add the playwright entry to its mcpServers object instead of replacing the file.

Keep the version pinned. With @latest, every new session would run whatever release npm serves that day, including a compromised one. To move to a newer version, pick a release that has been out at least 3 days, so a bad release has time to be found and pulled.

For Linux/Mac: ``json { "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@0.0.83"] } } } ``

For Windows: ``json { "mcpServers": { "playwright": { "command": "cmd", "args": ["/c", "npx", "@playwright/mcp@0.0.83"] } } } ``

b. Tell the user to restart the agent or start a new session so it loads the Playwright MCP server, then run /accessibility-audit again c. End the command session

If user selects "Skip visual testing":

• Proceed with code-based analysis only
• Record in the report that visual testing was skipped

Running the Audit

Once the configuration is settled, perform the audit yourself by following the Audit Methodology below. Identify accessibility barriers, WCAG compliance issues, and opportunities for inclusive design improvement in the chosen scope, then write the report described under Output Requirements.

Analysis Scope

The audit covers all 8 core expertise areas below (semantic HTML, ARIA, keyboard navigation, color contrast, forms, alternative text, interactive components, and responsive/mobile accessibility). For URL audits with Playwright MCP, the audit additionally performs visual contrast measurement, live keyboard navigation testing, and touch target verification on the rendered page.

Output Requirements

• Create comprehensive audit report with findings
• Save the report to docs/accessibility/YYYY-MM-DD-HHMMSS-accessibility-audit.md, relative to the repository root (the current working directory when there is no repository). Create the folder if it doesn't exist.
• Example: docs/accessibility/2025-10-29-143022-accessibility-audit.md
• Include audit configuration header specifying:
• WCAG version being audited against
• Target conformance level (A, AA, or AAA)
• Audit scope (entire solution, specific directory path, or URL)
• For URL audits: whether Playwright MCP visual testing was used, and if it was skipped, why
• For codebase audits: Include actual findings with exact file paths and line numbers
• For URL audits with Playwright: Include visual testing findings with screenshots when relevant
• Provide before/after code examples for remediation
• Prioritize findings by severity: Critical, High, Medium, Low
• Include WCAG compliance matrix for selected version and level

Accessibility Audit Skill

This skill provides comprehensive accessibility expertise for identifying WCAG compliance issues, assistive technology barriers, and inclusive design opportunities. Analyze codebases, rendered pages, or both to produce structured audit reports with actionable remediation guidance.

When to Use This Skill

Invoke this skill when:

• Auditing applications for WCAG 2.1 or 2.2 compliance (codebase or URL)
• Reviewing new features for accessibility requirements
• Investigating accessibility issues reported by users
• Evaluating keyboard navigation and focus management
• Assessing color contrast and visual accessibility
• Reviewing ARIA implementation in custom components
• Conducting form accessibility audits
• Performing visual accessibility testing on live websites (with Playwright MCP)

Core Accessibility Expertise

1. Semantic HTML & Document Structure

Examine for document structure issues:

• Heading hierarchy (h1-h6) for proper nesting without level skipping
• Semantic elements (nav, main, footer, article, section, aside) vs generic divs/spans
• Landmark regions for screen reader navigation
• Logical reading order in DOM matching visual order

Key Rules:

• Every page must have exactly one h1; headings must not skip levels
• Use semantic HTML elements for their intended purpose, not just styling
• Landmark regions should be unique and properly labeled
• DOM order should match visual/logical reading order

2. ARIA Implementation

Validate ARIA usage by checking for:

• Valid ARIA roles matching the element's purpose
• Appropriate states and properties (aria-expanded, aria-checked, aria-selected)
• Landmark roles (banner, navigation, main, complementary, contentinfo, search)
• Live regions for dynamic content (aria-live, aria-atomic, aria-relevant)
• ARIA labels and descriptions (aria-label, aria-labelledby, aria-describedby)

Key Rules:

• First rule of ARIA: Don't use ARIA if a native HTML semantic element exists
• All interactive ARIA widgets must be keyboard accessible
• Required ARIA attributes must be present for each role
• ARIA states must accurately reflect the current UI state

3. Keyboard Navigation & Focus Management

Verify keyboard accessibility:

• All interactive elements reachable via keyboard (tab, enter, space, arrows)
• Tab order follows logical/visual flow; no keyboard traps
• Visible focus indicators with sufficient contrast (3:1 against adjacent colors, SC 1.4.11)
• Skip navigation links for bypassing repetitive content
• Focus management in modals/dialogs (trap focus, return on close)
• ESC key closes modals and cancels operations

Key Rules:

• All functionality must be available via keyboard alone
• Focus indicators must be clearly visible (SC 2.4.7 Level AA)
• Opening modals should trap focus; closing should return focus
• Interactive elements should respond to appropriate keys (enter/space for buttons)

WCAG 2.2 Additions:

• SC 2.4.11 Focus Not Obscured (Minimum) (AA): Focused component not entirely hidden by author-created content
• SC 2.4.13 Focus Appearance (AAA): Focus indicator meets minimum area, contrast, and change of contrast requirements

4. Color Contrast & Visual Accessibility

Evaluate color accessibility:

• Normal text contrast: minimum 4.5:1 (AA), 7:1 (AAA)
• Large text contrast: minimum 3:1 (AA), 4.5:1 (AAA); large text is 18pt+ or 14pt+ bold
• UI component and graphical object contrast: minimum 3:1 (AA)
• Information not conveyed by color alone (SC 1.4.1)
• Sufficient differentiation for color blindness (especially red-green)