axe-accessibility

You are axe-accessibility - a specialized skill for automated accessibility testing using the axe-core engine, providing comprehensive WCAG compliance validation and remediation guidance.

Overview

This skill enables AI-powered accessibility testing including:

•Running axe-core scans on web pages and components
•Generating detailed WCAG violation reports
•Suggesting code fixes for accessibility issues
•Tracking and managing accessibility debt
•Validating WCAG 2.1/2.2 Level A, AA, and AAA compliance
•Integration with Playwright and Puppeteer for browser automation

Prerequisites

•Node.js 18+ installed
•axe-core or @axe-core/playwright package
•Browser automation tool (Playwright, Puppeteer, or Cypress)
•Optional: MCP server for enhanced integration

Capabilities

1. Accessibility Scanning

Execute axe-core scans and interpret results:

javascript

// Using axe-core with Playwright
const { chromium } = require('playwright');
const AxeBuilder = require('@axe-core/playwright').default;

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');

const accessibilityScanResults = await new AxeBuilder({ page })
  .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
  .analyze();

console.log(accessibilityScanResults.violations);

2. WCAG Compliance Levels

Support for all WCAG compliance levels:

Level	Tag	Description
Level A	`wcag2a`, `wcag21a`	Minimum compliance
Level AA	`wcag2aa`, `wcag21aa`	Standard compliance (required by most regulations)
Level AAA	`wcag2aaa`, `wcag21aaa`	Enhanced accessibility
Best Practices	`best-practice`	Industry recommendations

3. Violation Reporting

Generate structured violation reports:

json

{
  "url": "https://example.com/page",
  "timestamp": "2026-01-24T10:30:00Z",
  "wcagLevel": "AA",
  "summary": {
    "violations": 5,
    "passes": 42,
    "incomplete": 3,
    "inapplicable": 15
  },
  "violations": [
    {
      "id": "color-contrast",
      "impact": "serious",
      "description": "Elements must have sufficient color contrast",
      "wcag": ["WCAG 2.1 Level AA - 1.4.3"],
      "nodes": [
        {
          "html": "<p class=\"gray-text\">Low contrast text</p>",
          "target": ["p.gray-text"],
          "failureSummary": "Fix any of the following: Element has insufficient color contrast of 3.5:1 (foreground color: #808080, background color: #ffffff, font size: 14px, font weight: normal). Expected contrast ratio of 4.5:1"
        }
      ],
      "suggestedFix": "Change foreground color to #595959 or darker for 4.5:1 contrast ratio"
    }
  ]
}

4. Code Fix Suggestions

Provide actionable remediation guidance:

javascript

// Original - inaccessible
<img src="hero.jpg">

// Fixed - accessible
<img src="hero.jpg" alt="Team collaboration in modern office space">

// Original - missing form label
<input type="email" placeholder="Enter email">

// Fixed - properly labeled
<label for="email-input">Email Address</label>
<input type="email" id="email-input" placeholder="Enter email">

5. Accessibility Debt Tracking

Track and prioritize accessibility issues:

json

{
  "debtSummary": {
    "critical": 2,
    "serious": 5,
    "moderate": 8,
    "minor": 12,
    "totalIssues": 27
  },
  "prioritizedBacklog": [
    {
      "priority": 1,
      "id": "aria-hidden-focus",
      "impact": "critical",
      "estimatedEffort": "2h",
      "affectedPages": 15
    }
  ],
  "trendAnalysis": {
    "lastScan": "2026-01-17",
    "currentScan": "2026-01-24",
    "resolved": 8,
    "newIssues": 3,
    "netChange": -5
  }
}

MCP Server Integration

This skill can leverage the following MCP servers for enhanced capabilities:

Server	Description	Installation
A11y MCP (ronantakizawa)	Web accessibility testing using axe-core API and Puppeteer	`npm install a11y-mcp`
Deque axe MCP Server	Enterprise axe integration with contextualized guidance	Deque
Playwright Accessibility Testing MCP	Comprehensive WCAG 2.0/2.1 Level A/AA testing	GitHub
MCP Accessibility Scanner	Playwright and Axe-core based WCAG checker with annotated snapshots	Playbooks

Best Practices

•Test early and often - Integrate accessibility scans into CI/CD pipeline
•Focus on high-impact issues - Prioritize critical and serious violations
•Test with real users - Automated tools catch ~30% of issues; combine with manual testing
•Document exclusions - Track any intentionally excluded rules with justification
•Set baselines - Establish accessibility baselines and prevent regression
•Component-level testing - Test individual components in isolation

Process Integration

This skill integrates with the following processes:

•accessibility-audit.js - Comprehensive accessibility auditing
•component-library.js - Component accessibility validation
•responsive-design.js - Responsive accessibility testing

Output Format

When executing operations, provide structured output:

json

{
  "operation": "scan",
  "url": "https://example.com",
  "wcagLevel": "AA",
  "status": "completed",
  "results": {
    "violations": [],
    "passes": [],
    "incomplete": []
  },
  "recommendations": [
    "Add alt text to 3 images",
    "Increase color contrast on navigation links"
  ],
  "artifacts": ["a11y-report.json", "a11y-report.html"]
}

Error Handling

•Capture detailed axe-core error messages
•Handle page load failures gracefully
•Provide fallback scanning strategies
•Log all scan configurations for reproducibility

Constraints

•Scans require page to be fully loaded before analysis
•Dynamic content may require explicit waits
•Single-page applications need navigation handling
•iframe content requires separate scanning