All rules

Sheath rule

a11y-no-skip-heading-levels

Heading levels should only increase by one level at a time.
Package
Core
Category
Accessibility
Default severity
warning by default
Auto-fix
Manual fix

#Why

Heading levels should increase by one level at a time (h1 -> h2 -> h3). Skipping levels (e.g., h1 -> h3) makes content harder to navigate for screen reader users who use headings to understand document structure. It also suggests a broken document outline.

#Examples

#Bad

<!-- Skipping from h1 to h3 -->

<h1>Main Title</h1>

<h3>Subsection</h3>



<!-- Skipping multiple levels -->

<h1>Page Title</h1>

<h2>Section</h2>

<h5>Deep subsection</h5>



<!-- Skipping from h2 to h4 -->

<h2>Chapter</h2>

<h4>Topic</h4>

#Good

<!-- Sequential heading levels -->

<h1>Main Title</h1>

<h2>Section</h2>

<h3>Subsection</h3>

<h4>Sub-subsection</h4>



<!-- Going back up is allowed -->

<h1>Page Title</h1>

<h2>First Section</h2>

<h3>Details</h3>

<h2>Second Section</h2>

<h3>More Details</h3>



<!-- Proper document outline -->

<h1>Site Name</h1>

<h2>About Us</h2>

<h3>Our Team</h3>

<h3>Our Mission</h3>

<h2>Services</h2>

<h3>Consulting</h3>

<h3>Support</h3>

#Heading Level Rules

  1. Start with <h1> for the main page title
  2. Increase by only one level at a time (h1 -> h2 -> h3)
  3. You can decrease by any amount (h4 -> h2 is fine)
  4. Don't skip levels when going deeper (h2 -> h4 is bad)

#Notes

  • Think of headings like a book outline
  • Screen readers provide navigation by heading level
  • CSS can make any heading look like any size - choose level by meaning, not appearance
  • For multiple <h1> elements, see seo-no-multiple-h1

#References

#Related Rules