Agent skill

axe-accessibility

Automated accessibility testing using axe-core API for WCAG compliance validation. Run accessibility scans, generate violation reports, suggest code fixes, and track accessibility debt.

View SKILL.md on GitHub Repository
Stars 514
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/ux-ui-design/skills/axe-accessibility

Metadata

Additional technical details for this skill

author
babysitter-sdk
version
1.0.0
category
accessibility-testing
backlog id
SK-UX-001

SKILL.md

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

  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:

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

Didn't find tool you were looking for?

Be as detailed as possible for better results