Single H1 per page
ZMD003ZemDomu reports more than one <h1> in the analyzed page structure. Keep one primary page heading and use <h2> through <h6> to organize subsections beneath it.
What this rule catches
- Multiple static <h1> elements in a supported document or composed component structure.
- Duplicate page-level headings introduced across supported parent and child components.
What static analysis cannot prove
- Static analysis cannot prove that the remaining <h1> describes the page clearly.
- Conditional rendering may produce a different number of <h1> elements at runtime, so rendered states still need testing.
Standards classification and detection confidence
- Classification
- advisory — One primary page heading is ZemDomu's documented authoring convention, not a direct WCAG 2.2 success criterion.
- Detection confidence
- context dependent — The count is reliable for the page model Core resolves. Runtime-selected layouts or unresolved component branches can produce a different final document.
Applicable WCAG 2.2 criteria
No direct WCAG 2.2 success criterion.
No WCAG 2.2 success criterion requires exactly one h1. Use the rule to support a predictable page hierarchy, then review the rendered heading structure.
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
<h1>Home</h1>
<section>
<h2>About Us</h2>
<p>…</p>
</section>❌ Bad
<h1>Home</h1>
<section>
<h1>About Us</h1>
<p>…</p>
</section>React and Vue notes
- React/TSX
- A project-aware scan can detect <h1> elements contributed by separate JSX or TSX components; test conditional routes and states after rendering.
- Vue
- A project-aware scan can detect <h1> elements contributed by parent and imported Vue components; test conditional templates after rendering.
Quick summary
When: Multiple <h1> elements are present
Warning: Only one <h1> allowed per document
Solution: Use a single <h1> and lower-level headings thereafter
Why it matters
Accessibility: Multiple H1s dilute the page’s primary topic and confuse assistive-tech navigation.
SEO: Although Google tolerates multiple H1s, a single H1 provides a clearer ranking signal.
Rule details
In brief
- Goal: Ensure the page’s primary topic is communicated unambiguously.
- What to do: Include a single <h1> at the top of the content, then use <h2>–<h6> for subsections.
- Why: Multiple <h1> tags dilute the page’s main focus and confuse assistive technologies.
Intent
Prevent ambiguity in the document outline by enforcing a single top-level heading.
Benefits
- Screen-reader users hear a clear entry point to the main content.
- Users with cognitive disabilities grasp page structure more quickly.
- Search engines receive an unambiguous signal about your page’s topic.
Techniques
H42: Use <h1> for the main page heading and nested <h2>–<h6> for subsections.H65: Validate heading order and count via automated tests or linters.
HTML Semantics
Each <h1>–<h6> element creates an outline; having a single <h1> ensures one root node in that outline tree.
References
Tips & edge cases
- Lint your HTML to catch accidental extra <h1> tags early.
- In multi-topic pages, consider splitting content or using <article> with its own <h1> when contextually appropriate.
- Ensure your page <title> and <h1> match closely for maximum clarity.