a5c-ai/axe-accessibility

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:

// 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:

{
  "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:

// 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:

{
  "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

1. Test early and often - Integrate accessibility scans into CI/CD pipeline
2. Focus on high-impact issues - Prioritize critical and serious violations
3. Test with real users - Automated tools catch ~30% of issues; combine with manual testing
4. Document exclusions - Track any intentionally excluded rules with justification
5. Set baselines - Establish accessibility baselines and prevent regression
6. 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:

{
  "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