axe-core Automated Accessibility Linting

Technical Deep Dive & Specifications

The axe-core Rule Architecture & WCAG Standards

axe-core categorizes rules into standard tag sets based on international standards:

• wcag2a: WCAG 2.0 Level A (Fundamental baseline).
• wcag2aa: WCAG 2.0 Level AA (Legal compliance standard for ADA, Section 508, EAA).
• wcag21a & wcag21aa: WCAG 2.1 additions (Mobile touch targets, reflow, orientation).
• wcag22aa: WCAG 2.2 latest standards (Target size minimums, redundant entry).
• best-practice: Industry-proven accessibility ergonomics beyond baseline legal minima.

The Anatomy of an axe Violation

When an audit fails, axe produces a structured diagnostic object:

{
  "id": "color-contrast",
  "impact": "serious",
  "tags": ["cat.color", "wcag2aa", "wcag143"],
  "description": "Ensures the contrast between foreground and background colors meets WCAG 2 AA minimum thresholds",
  "help": "Elements must have sufficient color contrast",
  "helpUrl": "https://dequeuniversity.com/rules/axe/4.8/color-contrast",
  "nodes": [
    {
      "html": "<button class=\"btn-ghost\">Cancel Subscription</button>",
      "target": [".billing-card > .btn-ghost"],
      "failureSummary": "Fix any of the following:\n  Element has insufficient color contrast of 2.82 (foreground color: #94a3b8, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1"
    }
  ]
}

Dynamic Testing with @axe-core/playwright

Integrating axe-core into Playwright enables automated accessibility regression testing across your test suite:

// tests/accessibility.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test.describe('Accessibility Quality Gates', () => {
  test('Customer Checkout Page must have zero WCAG 2.1 AA violations', async ({ page }) => {
    // 1. Navigate to target URL
    await page.goto('/checkout');
    await page.waitForSelector('#payment-form');

    // 2. Execute AxeBuilder audit scoped to WCAG standards
    const accessibilityScanResults = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
      .exclude('#third-party-chat-widget') // Exclude unmanaged external widgets if necessary
      .analyze();

    // 3. Assert zero violations
    expect(accessibilityScanResults.violations).toEqual([]);
  });
});

Static Linting with eslint-plugin-jsx-a11y

For React and JSX projects, combine dynamic testing with static linting:

// .eslintrc.json
{
  "plugins": ["jsx-a11y"],
  "extends": [
    "eslint:recommended",
    "plugin:jsx-a11y/recommended"
  ],
  "rules": {
    "jsx-a11y/alt-text": "error",
    "jsx-a11y/anchor-is-valid": "error",
    "jsx-a11y/aria-props": "error",
    "jsx-a11y/aria-role": "error",
    "jsx-a11y/no-noninteractive-element-interactions": "error",
    "jsx-a11y/click-events-have-key-events": "error"
  }
}

💻 Interactive Code Playground

Starter Code (Demonstrating Critical A11y Violations)

Line-by-Line Code Breakdown

• Line 21: <p class="muted-caption"> uses color #a0aec0 on a white background (#ffffff). The contrast ratio is 2.36:1, failing WCAG 1.4.3 Level AA (minimum 4.5:1 for standard body text).
• Lines 24–28: <button class="icon-button"> contains only an SVG path without an aria-label, text node, or <title>. Screen readers announce "Button" with no name.
• Lines 31–34: The input <input id="voucher-code"> uses a generic <span>Discount Voucher</span> rather than a <label for="voucher-code"> or aria-label, failing WCAG 1.3.1 (Info and Relationships) and WCAG 4.1.2 (Name, Role, Value).
• Line 37: <button class="btn-warn"> has white text (#ffffff) on a light orange background (#ffb74d), yielding an insufficient contrast ratio of 1.74:1.

Expected axe-core Diagnostic Output

═══════════════════════════════════════════════════════════════════════════════
❌ 3 Accessibility Violations Detected by axe-core:
═══════════════════════════════════════════════════════════════════════════════

1. [color-contrast] (Impact: serious)
   - Elements must have sufficient color contrast
   - Target: .muted-caption (Ratio: 2.36:1, Required: 4.5:1)
   - Target: .btn-warn (Ratio: 1.74:1, Required: 4.5:1)

2. [button-name] (Impact: critical)
   - Buttons must have discernible text
   - Target: button.icon-button (Missing aria-label or accessible text node)

3. [label] (Impact: critical)
   - Form elements must have labels
   - Target: input#voucher-code (No associated <label> or aria-label found)