Scanning Accessibility

Accessibility Test Scanner

Overview

Validate web applications against WCAG 2.1/2.2 accessibility standards covering perceivability, operability, understandability, and robustness. Combines automated scanning with axe-core, Pa11y, and Lighthouse accessibility audits alongside manual validation checklists for keyboard navigation, screen reader compatibility, and color contrast.

Prerequisites

• Accessibility testing library installed (axe-core, @axe-core/playwright, Pa11y, or Lighthouse CI)
• Browser automation tool (Playwright or Puppeteer) for rendering pages
• Application running and accessible at a test URL
• Target WCAG conformance level defined (A, AA, or AAA -- AA is standard)
• Color contrast analyzer (built into axe-core or standalone tool)

Instructions

1. Configure the accessibility scanner with the target WCAG level:
   • Set axe-core rules to WCAG 2.1 AA (or 2.2 AA for latest standard).
   • Include rules for ARIA attributes, color contrast, form labels, and heading structure.
   • Define pages and components to scan (homepage, forms, modals, navigation).
2. Run automated accessibility scans on each page:
   • Use @axe-core/playwright to scan after page load.
   • Run Pa11y for HTML-level validation.
   • Execute Lighthouse accessibility audit for a score and detailed findings.
   • Scan each major interactive state (modal open, dropdown expanded, error state).
3. Validate keyboard navigation:
   • Verify all interactive elements are reachable via Tab key in logical order.
   • Confirm focus indicators are visible on every focusable element.
   • Test Escape key closes modals and dropdowns.
   • Verify skip-to-content link is present and functional.
   • Check that focus is trapped within open modals (no focus escape).
4. Validate ARIA implementation:
   • Check all ARIA roles match the element's purpose (role="button" on clickable divs).
   • Verify aria-label or aria-labelledby on elements without visible text.
   • Confirm aria-live regions announce dynamic content changes.
   • Validate aria-expanded, aria-selected, and aria-checked states toggle correctly.
5. Check color and visual accessibility:
   • Verify text contrast ratio meets WCAG AA (4.5:1 for normal text, 3:1 for large text).
   • Ensure information is not conveyed by color alone (use icons, patterns, or text labels).
   • Test with simulated color blindness filters (protanopia, deuteranopia, tritanopia).
6. Validate form accessibility:
   • Every input has an associated <label> with matching for/id.
   • Error messages are announced via aria-describedby and aria-invalid.
   • Required fields are indicated with aria-required="true" and visual indicators.
7. Generate a compliance report with WCAG success criteria references for each finding.

Output

• Accessibility scan results with violations, passes, and incomplete checks
• WCAG compliance matrix showing pass/fail per success criterion
• Remediation checklist with code fixes for each violation
• Keyboard navigation test results
• Lighthouse accessibility score and improvement recommendations

Error Handling

Examples

Playwright + axe-core accessibility test:

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('homepage meets WCAG AA', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

test('login form is keyboard accessible', async ({ page }) => {
  await page.goto('/login');
  await page.keyboard.press('Tab');
  const focused = await page.evaluate(() => document.activeElement?.getAttribute('data-testid'));
  expect(focused).toBe('email-input');
  await page.keyboard.press('Tab');
  const nextFocused = await page.evaluate(() => document.activeElement?.getAttribute('data-testid'));
  expect(nextFocused).toBe('password-input');
});

Pa11y CI configuration:

{
  "defaults": {
    "standard": "WCAG2AA",
    "timeout": 10000,  # 10000: 10 seconds in ms
    "wait": 1000  # 1000: 1 second in ms
  },
  "urls": [
    "http://localhost:3000/",  # 3000: 3 seconds in ms
    "http://localhost:3000/login",  # 3 seconds in ms
    "http://localhost:3000/dashboard",  # 3 seconds in ms
    { "url": "http://localhost:3000/settings", "actions": ["click element #tab-profile"] }
  ]
}

Resources

• WCAG 2.2 guidelines: https://www.w3.org/TR/WCAG22/
• axe-core: https://github.com/dequelabs/axe-core
• Pa11y: https://pa11y.org/
• WAI-ARIA authoring practices: https://www.w3.org/WAI/ARIA/apg/
• Lighthouse accessibility: https://developer.chrome.com/docs/lighthouse/accessibility/
• WebAIM contrast checker: https://webaim.org/resources/contrastchecker/

Source: jeremylongshore/claude-code-plugins-plus-skills → skills/.curated/scanning-accessibility/SKILL.md

Also appears in: jeremylongshore/claude-code-plugins-plus-skills/plugins/testing/accessibility-test-scanner/skills/scanning-accessibility/SKILL.md