Rule ID: ace-struct-heading-order

Check that heading levels follow a logical hierarchical sequence without skipping levels

Blind Deafblind Mobility Best Practice

What This Rule Checks

Headings on a webpage should be structured logically, with proper use of heading tags (h1 through h6) in a hierarchical order. This ensures that users, especially those using assistive technologies like screen readers, can easily understand the structure and contents of the page.

Who Is Affected

This issue primarily affects: Blind users, who rely entirely on screen readers or braille displays to navigate and interact with content; Deafblind users, who rely on braille displays and cannot access visual or auditory content; Mobility users, who navigate using keyboards, switches, voice control, or other assistive input devices.

Why This Matters

Screen reader users rely on heading hierarchy to understand page structure and navigate efficiently. Skipping levels creates confusion about content relationships. Studies show that heading navigation is the most-used screen reader feature for finding content.

How to Fix

Use Sequential Heading Levels: Start with <h1> for the main title, then use <h2>, <h3>, and so on to structure the content. Avoid skipping heading levels (e.g., jumping from <h2> to <h4>).

Use Only One <h1>: Limit each page to a single <h1> element for the main title. Additional sections should use <h2> or lower heading levels.

Do Not Use Headings for Visual Styling: If text needs to appear larger or bolder without acting as a heading, use CSS styling rather than heading tags.

Code Examples

Incorrect Markup Solutions:
Code example
<!-- Skipped heading levels --> <h1>Page Title</h1> <h4>Subsection</h4> <!-- Skipped h2 and h3 --> <!-- Multiple h1 elements --> <h1>Site Name</h1> <h1>Page Title</h1> Copy
Correct Markup Solutions:
Code example
<!-- Sequential heading hierarchy --> <h1>Page Title</h1> <h2>Main Section</h2> <h3>Subsection</h3> <h3>Another Subsection</h3> <h2>Second Section</h2> Copy

Common Mistakes to Avoid

  • Skipping heading levels (e.g., h1 to h4) for visual styling instead of using CSS.
  • Using multiple <h1> elements on a single page.
  • Choosing heading levels based on font size rather than document hierarchy.
  • Nesting headings out of order within components or sections.

Tip: Proper document structure enables assistive technologies to present content meaningfully. Headings, lists, and semantic HTML elements create a navigable outline of the page that screen reader users depend on.