Axe Rules

Axe-Core Rules Reference Skill

Canonical source: examples/AXE_RULES_REFERENCE.md and examples/AXE_RULES_COVERAGE.md in mgifford/ACCESSIBILITY.md This skill is derived from those files. When in doubt, the example is authoritative. Note: the canonical files are organized around a specific test-fixture scanner project (numbered test pages). This skill re-presents the same rule set and severities as a general-purpose reference, independent of any particular fixture.

Apply these rules when writing, reviewing, or debugging axe-core scans.

Core Principle

Axe-core catches ~30–40% of WCAG issues automatically. It is the baseline, not the ceiling. Always pair automated scanning with manual keyboard and screen reader testing.

An axe-core result is evidence, not a conformance decision. Preserve the rule's raw outcome (violations, incomplete, passes, inapplicable) exactly as axe reports it — do not overwrite or discard it when converting to a project finding. Cite this file, AXE_RULES_REFERENCE.md, or the rule's own dequeuniversity.com/rules/axe/ page as the authority for a WCAG mapping; do not invent a mapping axe-core does not document for that rule. Record an unreviewed violations result as evidence_status: automated-indicator with handling: review — never as a confirmed standards failure — until a human confirms it. See Accessibility Finding Tracking: Policy Classification.

Key tags to include in scans:

typescriptCopy code
.withTags(['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'])

Axe-core 4.11 includes 100+ automated checks across these categories: WCAG 2.0 A/AA (68 rules), WCAG 2.1 A/AA (26 rules), WCAG 2.2 A/AA (1 rule, disabled by default), Best Practices (30+ rules), WCAG AAA (3 rules, disabled by default), Experimental (9 rules, disabled by default), and Deprecated (7 rules, disabled by default).

Severity Scale (axe-core)

Critical Rules — must never appear in production

Serious Rules — fix before release

Moderate Rules — fix in near-term backlog

Minor Rules

Disabled-by-default rules (deprecated marquee/blink/audio-caption) are not listed above — flag them if encountered, but they are not enabled in a default scan.

The three WCAG AAA rules axe-core disables by default report against a level the project's AA target does not require. If enabled and a project has not declared a broader target, classify a confirmed finding from one of these rules as obligation: aspirational, not advisory — it is still a real AAA-level finding, just not part of the AA baseline. Do not report satisfying one of these rules as WCAG AAA conformance.

Running axe-core in CI (Playwright)

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

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

Common configuration options:

typescriptCopy code
// Exclude a specific element (use sparingly — document the reason)
.exclude('#known-false-positive')

// Include only a specific element
.include('#component-under-test')

// Disable a specific rule (document the reason and JIRA/issue link)
.disableRules(['color-contrast'])

Definition of Done Checklist

• axe-core scans run on every PR with wcag2a, wcag2aa, wcag21aa, wcag22aa tags
• Zero critical violations in production code
• Zero serious violations in production code (or explicit waiver with issue link)
• All rule exclusions documented with reason and associated issue
• Light and dark colour schemes both tested
• Mobile viewport tested
• axe results published as CI artifact for reference

Key WCAG Criteria (automation coverage)

• 1.1.1 Non-text Content (A)
• 1.3.1 Info and Relationships (A)
• 1.4.3 Contrast Minimum (AA)
• 2.4.2 Page Titled (A)
• 3.1.1 Language of Page (A)
• 4.1.2 Name, Role, Value (A)
• 4.1.3 Status Messages (AA) — partial coverage

Automation covers ~30–40% of WCAG issues. Always pair with manual testing.

References

• Full axe rules reference
• Axe rules coverage summary
• axe-core rule descriptions
• @axe-core/playwright
• axe-core GitHub

Standards horizon: These rules target WCAG 2.2 AA. Monitor: https://www.w3.org/TR/wcag-3.0/