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: A clear primary heading can help users orient to a page; multiple H1 elements are not automatically an accessibility failure.
Semantic context: One descriptive primary heading is a useful page convention for readers; Google does not require exactly one H1.
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: A single primary heading is ZemDomu's recommended page convention; other heading patterns can still be valid when the headings describe the content.
Intent
Encourage one clearly identified primary page heading without treating the H1 count as a WCAG or ranking requirement.
Benefits
- Screen-reader users hear a clear entry point to the main content.
- Users with cognitive disabilities grasp page structure more quickly.
- A clear primary heading helps readers identify the 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
Heading levels describe sections and subsections. A single H1 can identify the primary page topic, but HTML does not require exactly one H1.
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.