SiteLint documentation and guidelines

Headings must not skip levels

Description

This rule checks that heading levels (from <h1> through <h6>) increase by only one level at a time and never skip a level. For example, an <h2> must not be followed directly by an <h4> without an intervening <h3>. This rule applies to the logical document outline, meaning that when a heading level is skipped, assistive technologies may incorrectly interpret the document structure, potentially causing users to think they have missed content.

Disabilities impacted

  • Visual impairments: screen reader users rely heavily on heading structures to navigate documents. When heading levels are skipped, screen readers may announce an incorrect hierarchy, making it difficult for users to understand the relationship between sections or to jump efficiently between content areas.
  • Cognitive disabilities: users with cognitive disabilities benefit from predictable, logical document structures. Skipped heading levels create an inconsistent outline that can be disorienting and make it harder to follow the document’s flow and organization.
  • Motor impairments: users who navigate via keyboard shortcuts (such as using the H and Shift+H keys to move between headings in screen readers) expect headings to follow a logical progression. Skipped levels can cause unexpected jumps or make certain sections unreachable via standard heading navigation commands.

Why it matters

Headings provide the structural backbone of web content, creating an outline that helps all users understand document organization. For assistive technology users, headings are often the primary means of navigating and comprehending page content. When heading levels are skipped, the implied document outline becomes broken or misleading. A user might encounter an <h4> and assume it belongs to the preceding <h3>, but if there is no <h3>, they may be confused about where they are in the document hierarchy. Maintaining proper heading level progression ensures that every user can perceive the intended structure and navigate content efficiently.

Coding problems and solutions

Common coding problems

  • Skipped heading levels: an <h1> is followed by an <h3> or <h4> without an <h2> in between.
  • Inconsistent level resetting: after a deeper heading like <h4>, the next heading is an <h2> without a closing <h3> to properly step back up.
  • Using headings for visual styling: developers sometimes use an <h4> because it “looks right” visually, skipping the appropriate intermediate heading levels.

How to Fix It

Restructure heading levels sequentially

Ensure that heading levels increase by exactly one at each step. You can increase by more than one level only if the lower level heading has been properly closed (i.e., the section has ended). In practice, this means a heading level should never increase by more than one from the immediately preceding heading at the same or higher level.

Correct example
<h1>Main Title</h1>
  <h2>Section 1</h2>
    <h3>Subsection 1.1</h3>
    <h3>Subsection 1.2</h3>
  <h2>Section 2</h2>
    <h3>Subsection 2.1</h3>
      <h4>Detail 2.1.1</h4>
  <h2>Section 3</h2>
Incorrect example
<h1>Main Title</h1>
  <h3>Section 1</h3>      <!-- SKIP: h1 directly to h3 -->
    <h4>Subsection 1.1</h4> <!-- SKIP: h3 to h4 is fine, but missing h2 -->
  <h2>Section 2</h2>      <!-- INCONSISTENT: h4 back to h2 is allowed if section ends, but the h1->h3 skip is still a problem -->

Use multiple h1 elements correctly (or avoid them)

While HTML5 allows multiple <h1> elements when using sectioning elements (<section>, <article>, etc.), this can create complex outlines. The safest approach is to use a single <h1> per page and maintain a clear hierarchy from there.

Correct example (using sectioning elements)
<h1>Page Title</h1>
<section>
  <h2>Section Title</h2>
  <section>
    <h3>Subsection Title</h3>
  </section>
</section>
Incorrect example (confusing outline)
<h1>Main Title</h1>
<section>
  <h1>Another Main Title</h1> <!-- This creates ambiguity in the outline -->
  <h3>Subsection</h3>        <!-- Skip from h1 to h3 -->
</section>

Use CSS for visual styling instead of heading levels

If a heading looks too large or too small, use CSS to adjust its appearance rather than changing its heading level. The heading level should reflect its structural importance, not its visual size.

Correct example
<style>
  .compact-h3 {
    font-size: 1rem;  /* Visually smaller but semantically still an h3 */
  }
</style>

<h3 class="compact-h3">Smaller but still a proper level 3 heading</h3>

Known Limitations

  • Sectioning elements and HTML5 outline: HTML5 introduced a document outline algorithm that uses <section>, <article>, <nav>, and <aside> to create implicit heading levels. However, browser and assistive technology support for this algorithm is poor. This rule checks explicit heading level hierarchy and does not rely on the HTML5 outline algorithm.
  • Dynamic content: This rule checks the DOM at analysis time. If headings are added or removed dynamically (e.g. via JavaScript frameworks), the check must be re-run after each content update.
  • Hidden headings: Headings that are visually hidden but remain in the DOM (e.g. for screen readers) are still evaluated by this rule, as they affect the document outline for assistive technologies.
  • Page fragments: This rule evaluates the entire document. If you are embedding a content fragment that starts with an <h3> (e.g. a widget), that may be flagged as a skip from the page’s previous heading. In such cases, ensure the embedding context provides the proper heading level continuity.

Resources

Rule

  • Audit: Accessibility
  • Standard: WCAG 2.1 / WCAG 2.2
  • Level: A
  • Success Criteria: 1.3.1 Info and Relationships
  • ID: headings-hierarchy