heading-order

Heading levels must not skip a level

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

Expectation. In document order, each heading's level is no more than one greater than the highest heading level seen so far. 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.

Examples

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

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

View source