axe-accessibility

# axe Accessibility Skill

Test web pages for accessibility violations and get AI-powered remediation guidance using the axe DevTools MCP Server.

## Prerequisites

- Docker running locally
- `AXE_API_KEY` environment variable set
- Docker image pulled: `dequesystems/axe-mcp-server:latest`

## Tools

The wrapper script at `scripts/axe-mcp.js` (Node.js — no extra dependencies) provides two tools:

### analyze

Scan a live web page for accessibility violations. Requires a URL (works with localhost).

```bash
node scripts/axe-mcp.js analyze <url>
```

Returns JSON-RPC response. The violations are in `result.content[0].text` (JSON string) under the `data` array. Each violation has: `rule`, `impact`, `description`, `selector`, `source`, `helpUrl`.

### remediate

Get AI-powered fix guidance for a specific violation. Handles HTML with quotes/brackets safely.

```bash
node scripts/axe-mcp.js remediate <ruleId> <elementHtml> <issueRemediation> [pageUrl]
```

Returns `general_description`, `remediation`, and `code_fix` in `result.content[0].text`.

### tools-list

List available MCP tools.

```bash
node scripts/axe-mcp.js tools-list
```

## Workflow

When modifying UI code and a live page is available:

1. **Analyze** — `node scripts/axe-mcp.js analyze <url>`
2. **Parse** — extract violations from the JSON response
3. **Remediate** — for each unique rule violation, call remediate with ruleId, element HTML, and issue description
4. **Apply** — implement the recommended code fixes in source
5. **Verify** — re-run analyze to confirm zero violations

When no live page is available (static code review), apply accessibility best practices directly:
- Images: `alt` text (or `alt=""` for decorative)
- Forms: inputs need associated `<label>` elements
- Interactive elements: keyboard accessible, visible focus
- Color contrast: WCAG AA (4.5:1 normal text, 3:1 large text)
- ARIA: valid, complete, not redundant with native semantics
- Headings: proper hierarchy (h1 → h2 → h3)
- Dynamic c...