heading-order

Heading levels must not skip a level

manualconfidence: mediumseverity: minoroperable

Checks that heading levels increase by at most one at a time in document order.

Applies to. Applies whenever the page contains two or more heading elements (native <h1>-<h6>, or explicit role="heading" with aria-level; default level 2 per the ARIA spec when aria-level is absent/invalid). A native <hx> with a valid aria-level (a positive integer) takes that level, as browsers expose it; otherwise it takes its tag level. A native <hx> marked role="none" or "presentation" is still a heading when it can take focus or carries a global ARIA attribute, as WAI-ARIA's presentational roles conflict resolution has browsers ignore that role then. A custom element whose ElementInternals give it the heading role (this.attachInternals().role) counts as role="heading" does, at the level its aria-level attribute or its internals' ariaLevel give.

Expectation. In the order assistive technology reads the page, each heading's level is no more than one greater than the level of the previous heading exposed to assistive technology. Jumping deeper by more than one level (e.g. an <h1> followed directly by an <h3>, skipping <h2>) breaks the document outline assistive technology users rely on when navigating by heading. Going back to a shallower level at any point is always fine.

What a finding reports.

fromLevel: the level of the previous exposed heading (3 for an <h3>).
toLevel: this heading's level, more than one deeper than fromLevel.

These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.

Examples

pass

<h1>Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>

Each heading level increases by at most one at a time.

can't tell

<h1>Title</h1>
<h3>Subsection</h3>

The heading level jumps from 1 to 3, skipping level 2.

How to check

When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.

`HEADING_ORDER_SKIPPED_LEVEL`

Find the heading the report names and note its level and the previous heading's level (from the report or the Accessibility pane).
List the page's headings in order, with a screen reader's headings list or by inspecting them, and look at the section around the skip.
Decide whether the heading belongs one level below the previous heading, or whether a level is missing.

Pass. Each heading is at most one level deeper than the heading before it, so the outline has no gap.

Fail. The heading jumps more than one level deeper than the one before it (an h2 followed by an h4), leaving a gap in the outline, a best-practice miss (G141).

View source