| name | axe-rules |
| description | Load this skill when configuring axe-core scans, reviewing automated accessibility test results, or writing tests that use @axe-core/playwright, @axe-core/react, or similar integrations. Provides a quick reference to axe 4.x rule IDs, their WCAG mapping, and default severity levels.
|
Axe-Core Rules Reference Skill
Canonical source: examples/AXE_RULES_REFERENCE.md in mgifford/ACCESSIBILITY.md
This skill is derived from that file. When in doubt, the example is authoritative.
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.
Key tags to include in scans:
.withTags(['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'])
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 |
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 |
aria-braille-equivalent | ARIA | Braille label without non-braille equivalent |
aria-command-name | ARIA | Button or link without accessible name |
aria-hidden-focus | ARIA | aria-hidden element contains focusable content |
aria-input-field-name | ARIA | ARIA input field without accessible name |
aria-prohibited-attr | ARIA | Prohibited ARIA attribute used |
color-contrast | Color | Text contrast below 4.5:1 (normal) or 3:1 (large) |
frame-title | Frames | <iframe> without accessible name |
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 |
Moderate Rules — fix in near-term backlog
| Rule ID | Category | Description |
|---|
heading-order | Headings | Heading levels skipped (e.g., h1 → h3) |
th-has-data-cells | Tables | Table headers have no associated data cells |
td-headers-attr | Tables | Table cells reference invalid header IDs |
table-duplicate-name | Tables | <caption> text duplicates summary attribute |
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 |
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 |
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('#known-false-positive')
.include('#component-under-test')
.disableRules(['color-contrast'])
Definition of Done Checklist
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
Standards horizon: These rules target WCAG 2.2 AA.
Monitor: https://www.w3.org/TR/wcag-3.0/
