axe-core heading-order error skipped heading level bug

axe-core heading-order error skipped heading level bug - how to fix it

TL;DR

Fix the heading outline so levels only increase by one: h1 then h2, then h3, never h1 straight to h3. Restyle with CSS classes instead of picking a heading level for its looks. One line of why: screen reader users navigate by heading level, and a skipped level makes the outline lie about the page structure.

The error, verbatim

{
  "id": "heading-order",
  "impact": "moderate",
  "help": "Heading levels should only increase by one",
  "nodes": [
    { "target": ["h4.section-title"], "failureSummary": "Fix any of the following: Heading order invalid" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules heading-order --save axe-head.json

Expected: Violations array contains heading-order with the offending heading selectors.

Step 2: Dump the heading outline

node -e "console.log('use the headingsMap check in axe DevTools or:')"; curl -s https://example.com | rg -o 'h1|h2|h3|h4|h5|h6' | sort | uniq -c | head -10

Expected: Shows the heading sequence so you can spot the skipped level.

Step 3: Find the skipped headings in source

rg -n --glob '*.{jsx,tsx,vue,html}' 'h4|h5|h6' src | head -20

Expected: Shows heading usages to renumber.

Step 4: Fix the levels and re-scan

npx @axe-core/cli https://example.com --rules heading-order

Expected: Exit code 0, 0 violations. The outline now descends one level at a time.

Step 5: Gate the rule in CI

npx @axe-core/cli https://example.com --exit | tail -3

Expected: Non-zero exit while any violation remains; add this command to CI so the fix never regresses.

When to use this skill

• Your axe-core report lists this exact rule id under violations
• You are clearing automated WCAG 2.1 AA failures before a release or audit
• A CI a11y gate (pa11y-ci, lighthouse CI, cypress-axe) is red because of this rule

When NOT to use this skill

• The issue only shows up in manual screen-reader testing and axe reports zero violations for the rule
• You are doing a full manual WCAG audit, this skill covers the single automated rule only
• The page is a third-party embed you cannot edit, flag it to the vendor instead

Compatibility

axe-core 4.8+ (rule heading-order, WCAG 1.3.1). Pair with page-has-heading-one for a valid outline. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

heading order invalid axe

The failureSummary wording, same fix.

skipped heading level h1 to h3

The classic instance: authors pick h3 because it looks right.

axe DevTools flags the same rule

The browser extension runs the same rule engine; fix once and it clears in every runner.

Why it happens

Authors choose heading levels by visual size, so an h4 gets used for a subsection that should be an h3, skipping a level. Component libraries hardcode heading levels inside cards and widgets, which then land at the wrong depth on different pages. Axe only checks that increases are by one, decreases can jump freely, so the fix is always about renumbering the too-deep headings. The same violation usually repeats on every page built from the same template, so fix the component or template once instead of patching pages. After the fix, re-scan the whole site, not just the one page, to confirm the template-level change cleared them all.

Edge cases

• Decreasing levels can skip freely (h3 back to h1 is fine), only increases must step by one.
• Style with classes, not heading levels: an h3 styled to look like an h4 is correct, an h4 used as a subsection is not.
• Reusable components should accept a heading level prop or use the lowest sensible level.
• Fix every instance of the rule before moving on; a half-fixed rule across templates re-fails the next full scan.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_o6K7wR2LqmTrbuqC3a65xw