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:

.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)

axe severity	Meaning
critical	Blocks access for one or more disability groups
serious	Significantly impairs access
moderate	Creates friction; workaround exists
minor	Best-practice gap; marginal impact

---

Critical Rules — must never appear in production

Rule ID	Category	Description
image-alt	Text alternatives	<img> missing alt attribute
area-alt	Text alternatives	Image map <area> missing alt text
input-image-alt	Text alternatives	<input type="image"> missing alt
video-caption	Text alternatives	<video> without captions
aria-allowed-attr	ARIA	Element has unsupported ARIA attributes for its role
aria-hidden-body	ARIA	aria-hidden applied to <body>
aria-required-attr	ARIA	Required ARIA attribute missing
aria-required-children	ARIA	Required child ARIA roles missing
aria-required-parent	ARIA	Required parent ARIA role missing
aria-roles	ARIA	Invalid ARIA role value
aria-valid-attr	ARIA	Invalid ARIA attribute name
aria-valid-attr-value	ARIA	ARIA attribute has invalid value
label	Forms	Form input without associated <label>
select-name	Forms	<select> without accessible name
button-name	Buttons/Links	Button without discernible text
input-button-name	Buttons/Links	<input type="button"> without text
duplicate-id-aria	Structure	Duplicate id values referenced by ARIA
meta-refresh	Meta	<meta http-equiv="refresh"> causes timed redirect

---

Serious Rules — fix before release

Rule ID	Category	Description
object-alt	Text alternatives	<object> without accessible text
svg-img-alt	Text alternatives	SVG with role="img" and no accessible name
role-img-alt	Text alternatives	Element with role="img" lacks alt text
aria-braille-equivalent	ARIA	Braille label without non-braille equivalent
aria-command-name	ARIA	Button, link, or menu item without accessible name
aria-conditional-attr	ARIA	ARIA attribute used contrary to role spec
aria-hidden-focus	ARIA	aria-hidden element contains focusable content
aria-input-field-name	ARIA	ARIA input field without accessible name
aria-meter-name	ARIA	ARIA meter element without accessible name
aria-progressbar-name	ARIA	ARIA progressbar element without accessible name
aria-prohibited-attr	ARIA	Prohibited ARIA attribute used
aria-toggle-field-name	ARIA	ARIA toggle field without accessible name
aria-tooltip-name	ARIA	ARIA tooltip without accessible name
aria-dialog-name	ARIA	Dialog without accessible name
aria-treeitem-name	ARIA	Tree item without accessible name
color-contrast	Color	Text contrast below 4.5:1 (normal) or 3:1 (large)
frame-title	Frames	<iframe> without accessible name
frame-title-unique	Frames	Frame titles are not unique
frame-focusable-content	Frames	Frame with focusable content is tabindex="-1"
html-has-lang	Language	<html> missing lang attribute
html-lang-valid	Language	lang attribute has invalid BCP 47 value
valid-lang	Language	Inline lang value is invalid
document-title	Language	<title> element missing
list	Structure	<ul>/<ol> contains elements other than <li>
listitem	Structure	<li> outside <ul> or <ol>
definition-list	Structure	<dl> contains elements other than <dt>/<dd>
dlitem	Structure	<dt>/<dd> outside <dl>
bypass	Keyboard	No skip navigation mechanism present
scrollable-region-focusable	Keyboard	Scrollable region not keyboard accessible
link-name	Buttons/Links	Link without discernible text
link-in-text-block	Buttons/Links	Link not distinguishable from surrounding text
avoid-inline-spacing	Content sizing	Text spacing overrides not adjustable
autocomplete-valid	Forms	autocomplete attribute invalid or missing
tabindex	Best practices	tabindex value > 0 used
label-title-only	Best practices	Form field labeled only via title attribute
label-content-name-mismatch	Best practices (experimental)	Visible label text doesn't match accessible name
td-has-header	Tables (experimental)	Large table cells lack associated headers
table-fake-caption	Tables (experimental)	Table caption not marked up with <caption>
p-as-heading	Best practices (experimental)	Paragraph styled to look like a heading

---

Moderate Rules — fix in near-term backlog

Rule ID	Category	Description
heading-order	Headings	Heading levels skipped (e.g., h1 → h3)
empty-heading	Headings	Heading has no discernible text
th-has-data-cells	Tables	Table headers have no associated data cells
td-headers-attr	Tables	Table cells reference invalid header IDs
meta-viewport	Meta	Viewport user-scalable=no disables zoom
html-xml-lang-mismatch	Language	lang and xml:lang attributes disagree
form-field-multiple-labels	Forms	Form field has multiple conflicting labels
landmark-one-main	Best practices	Page has no <main> landmark
landmark-banner-is-top-level	Best practices	banner landmark not at top level
landmark-contentinfo-is-top-level	Best practices	contentinfo landmark not at top level
landmark-main-is-top-level	Best practices	main landmark not at top level
landmark-no-duplicate-banner	Best practices	More than one banner landmark
landmark-no-duplicate-contentinfo	Best practices	More than one contentinfo landmark
landmark-no-duplicate-main	Best practices	More than one main landmark
region	Best practices	Content exists outside landmark regions
page-has-heading-one	Best practices	Page has no <h1>
scope-attr-valid	Best practices	scope attribute has invalid value
accesskeys	Best practices	accesskey values are not unique

---

Minor Rules

Rule ID	Category	Description
table-duplicate-name	Tables	<caption> text duplicates summary attribute
aria-deprecated-role	ARIA	Deprecated ARIA role used
server-side-image-map	Keyboard	Server-side image map used
aria-text	ARIA (best practice)	role="text" on an element with focusable descendants

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)

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:

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