Documentation/Sections need headings

Sections need headings

ZMD001

Each <section> should contain a heading (<h1>-<h6>) or an accessible label via aria-label/aria-labelledby so the section is named for users and tools.

✅ Good

<section>
  <h2>FAQ</h2>
  <p>Welcome to our FAQ...</p>
</section>

<section aria-label="FAQ">
  <p>Welcome to our FAQ...</p>
</section>

<h2 id="faq-heading">FAQ</h2>
<section aria-labelledby="faq-heading">
  <p>Welcome to our FAQ...</p>
</section>

❌ Bad

<section>
  <p>Welcome to our FAQ…</p>
</section>

When: A <section> element does not contain any <h1>-<h6> heading or ARIA label

Warning: <section> missing heading (<h1>-<h6>) or accessible label (aria-label / aria-labelledby)

Solution: Add an <h1>-<h6> inside each section or label it with aria-label/aria-labelledby

Why it matters

Accessibility: Breaks screen-reader navigation and comprehension—users rely on headings to orient and skip between sections.

SEO: Search engines may struggle to identify section context, reducing content understandability.

In brief

  • Goal: Users understand how content is organized into named sections.
  • What to do: Provide a heading (<h1>-<h6>) or an ARIA label for each section.
  • Why: People with cognitive or visual disabilities can orient themselves; screen-reader users can jump between headings; keyboard users can skip to updated content.

Intent

Provide headings or accessible labels for every logical section so that the page's organization is explicit. Labels act as 'handles' for navigation and comprehension.

Benefits

  • Blind users know when they move to a new section and what its purpose is.
  • People with learning disabilities grasp page structure more easily.
  • Keyboard users can jump focus between headings to find content quickly.
  • Dynamic pages remain navigable by heading even when content updates.

Techniques

  • G141: Each <section> should contain a heading (<h1>-<h6>) or an accessible label via aria-label/aria-labelledby so the section is named for users and tools.
  • H69: Each <section> should contain a heading (<h1>-<h6>) or an accessible label via aria-label/aria-labelledby so the section is named for users and tools.

HTML Semantics

A <section> is sectioning content whose purpose is grouping related elements under a title. Only use when no more specific element (article, nav, aside) applies, and ensure it has a heading or ARIA label.

References

Tips & edge cases

  • Use true <h1>–<h6> elements, not styled <div>s or <span>s — assistive tech relies on semantic markup.
  • Maintain a logical heading hierarchy; avoid skipping levels (e.g. h2 → h4).
  • Keep headings concise and descriptive, like mini-summaries of each section.

See also