Documentation/No skipped heading levels

No skipped heading levels

ZMD002

ZemDomu reports a skipped heading level when a heading moves more than one level deeper, such as an <h4> after an <h2>. Project-aware scans can catch the same skip when the headings live in parent and child components.

What this rule catches

  • Static <h1> through <h6> elements that jump more than one level deeper than the preceding heading.
  • Heading-order problems created when supported React or Vue components are composed across files.

What static analysis cannot prove

  • A static scan cannot confirm the final heading sequence when runtime conditions, slots, or dynamic element names change what renders.
  • Passing this rule does not prove that headings are descriptive or that the rendered page is easy to navigate with assistive technology.

Standards classification and detection confidence

Classification
advisory — Sequential heading levels are a robust authoring convention, but a skipped numeric level is not automatically a WCAG failure.
Detection confidence
context dependent — Local headings are deterministic. Cross-component results depend on the imports and composition paths that Core can resolve statically.

Applicable WCAG 2.2 criteria

Criterion 2.4.6 requires headings to describe topic or purpose; it is relevant context rather than a mechanical heading-level sequence requirement.

Normative means the rule checks a machine-testable part of a cited standards requirement. Advisory means it enforces a documented authoring convention or supporting technique. Neither classification makes a ZemDomu result proof of WCAG conformance.

Examples

✅ Good

<h2>Main section</h2>
<h3>Subpoint</h3>
<p>Details…</p>

❌ Bad

<h2>Main section</h2>
<h4>Subpoint</h4>
<p>Details…</p>

React and Vue notes

React/TSX
Run a workspace or CLI scan when headings are split across JSX or TSX components; checking one component alone may not reveal the composed order.
Vue
Run a project-aware scan when a parent template and imported single-file components contribute headings to the same page outline.

Quick summary

When: A heading level is more than one step deeper than the previous heading

Warning: Heading level skipped: <hX> after <hY>

Solution: Follow sequential heading order

Why it matters

Accessibility: Skipping levels disrupts screen-reader users’ mental model of document structure and impairs navigation.

SEO: Misordered headings can confuse search engine crawlers about content hierarchy.

Rule details

In brief

  • Goal: Maintain a nested document structure via proper heading nesting.
  • What to do: Do not jump more than one level (e.g. `<h2>` → `<h4>`).
  • Why: Screen readers and sighted users rely on heading order to understand hierarchy and navigate content.

Intent

Prevent confusion in document structure by enforcing sequential heading levels without skips.

Benefits

  • Consistent outline improves comprehension for users with cognitive disabilities.
  • Screen-reader users can predict content flow and navigate headings linearly.
  • Search engines better understand content hierarchy, aiding SEO.

Techniques

  • H42: Using h2–h6 to create subheadings in sequence.
  • H65: Validating heading order programmatically.

HTML Semantics

Each heading tag defines a section in the outline; skipping levels breaks the implicit tree structure.

References

Tips & edge cases

  • Use linter rules or automated tests to catch skips early.
  • In long documents, consider an outline to plan heading levels before writing.

See also

Related guides

Last verified: