HTML / Element / Partial implementation observation

HTML Heading Elements — `h1`–`h6`, Levels, and Outline

Status: Specification checked; selected Chromium and WPT observations Scope: HTML Living Standard, HTML-AAM, and WPT Checked: 2026-10-31

Technical Summary

h1–h6 are HTML elements for headings and their position in a hierarchy. The number in each element name gives its basic heading level. That level is separate from the text's size and weight.

The HTML Living Standard also defines headingoffset, which adds to the calculated level of the element and descendant headings, and headingreset, which includes the reset element's own offset and then stops before more distant ancestors. These attributes are not needed for ordinary headings. Check support in each browser before relying on them.

Definition and content model

The HTML Standard defines h1–h6 as elements that represent headings for their sections. Each element has a heading level based on its name and, under the current standard, any applicable offset attributes.

Property	Standard definition
Elements	`h1`, `h2`, `h3`, `h4`, `h5`, and `h6`
Categories	Flow content, heading content, and palpable content
Placement	Where flow content is expected; the content model is phrasing content
Tag omission	Neither the start tag nor the end tag may be omitted
DOM interface	`HTMLHeadingElement`
Basic levels	`h1` is level 1, `h2` is level 2, …, `h6` is level 6. The current standard also defines ancestor offsets

Heading levels and document structure

Heading levels describe how topics fit together. Moving one level deeper in the content increases the level by one. When a smaller topic ends and a new, larger topic begins, the next heading can return to a smaller number than the previous one.

Element	Basic level	Example relationship
`h1`	1	The document's main topic
`h2`	2	A topic within the main topic
`h3`	3	A smaller topic within an `h2` topic
`h4`	4	A smaller topic within an `h3` topic
`h5`	5	A smaller topic within an `h4` topic
`h6`	6	A smaller topic within an `h5` topic

HTML conformance says that a document with headings should include at least one level-1 heading. In heading order, a heading cannot jump more than one level deeper than the heading before it. Check whether the heading list still explains the structure when read on its own.

Keep semantic level separate from visual size. Use CSS to change the appearance, and choose concise heading text that identifies the content that follows.

Outline and sectioning elements

The HTML Standard's document outline is the document's headings in tree order: the order in which they appear in the document tree. A table of contents should let users move from each entry to its heading.

Adding a section or article does not by itself reset the level of an h1–h6 element. The historical expectation that an h1 automatically becomes the next level inside a section is not a reliable description of current browser behavior. Mark up and verify the heading elements and levels explicitly.

The current HTML Standard defines separate, explicit mechanisms: headingoffset and headingreset. The calculation adds offsets from the heading and its ancestors. A headingoffset value is a non-negative integer from 0 through 8; a calculated level above 9 is returned as 9. At an element with headingreset, the calculation includes that element's own offset, then stops before more distant ancestors. Across a shadow root, the calculation continues at its host. The standard definition, browser implementation, and HTML-AAM mapping need separate evidence.

hgroup can group a heading with related text such as a subtitle. This Topic focuses on h1–h6; check the standard and each target browser for the related element's outline behavior.

HTML-AAM and the Accessibility Tree

The HTML-AAM 1.0 Working Draft (2026-10-21) maps h1–h6 to the WAI-ARIA heading role. Its element mapping sets the aria-level property to the number in the element name. Browsers expose this role and level through platform accessibility APIs.

The AAM measurement on this page uses Chromium's Accessibility Tree. It is an intermediate representation built by the browser. It is distinct from direct output through Windows UI Automation or IAccessible2, spoken output from NVDA or Narrator, and braille output. The relationship between HTML Standard offset calculation and the element-name wording in the HTML-AAM draft also needs checking in other engines.

The heading role comes from the DOM element and its accessibility mapping, not from appearance. CSS that makes text large does not turn it into an HTML heading.

Fact / Evidence

The standard definition, HTML-AAM mapping, WPT testharness results, and Chromium Accessibility Tree observations are recorded separately. The selected WPT failures show that the tested browser rejects a new selector; they do not show that headingoffset calculations conform to the standard.

Key facts and evidence locations
Type	Fact / Claim	Conditions / Scope	Status	Evidence
SPEC	`h1`–`h6` represent section headings and have basic levels based on their element names.	HTML Living Standard §4.3.6. Element categories, content model, DOM interface, and heading meaning.	Specification checked	HTML Standard: h1–h6
SPEC	The document outline is in heading tree order; `headingoffset` and `headingreset` affect the calculated level.	HTML Living Standard §4.3.11 and §4.3.11.1. This specification claim is separate from browser support.	Specification checked	Headings and outlines · Heading levels & offsets
AAM	HTML-AAM 1.0 WD maps all six elements to `heading` and sets `aria-level` to the number in the element name.	HTML-AAM 1.0 Working Draft 2026-10-21 mapping. This is separate evidence from browser Accessibility Tree measurements.	Mapping checked	HTML-AAM: h1–h6 · WAI-ARIA: heading
WPT	Selected HTML-AAM role and invalid-nesting tests passed. The headingoffset mutation tests hit a selector parse error in the tested Chromium.	WPT commit `5b11a9b4169aba2d11f33d787c88222bf9f017c3`. See the Implementation Evidence row and machine-readable report for counts.	Partial run	roles.html · invalid-nesting.html · headingoffset-mutations.html

Evidence

HTML Living Standard, §4.3.6 The h1, h2, h3, h4, h5, and h6 elements — categories, placement, content model, DOM interface, and meaning.
HTML Living Standard, §4.3.11 Headings and outlines — heading order, document outline, and conformance conditions.
HTML Living Standard, §4.3.11.1 Heading levels & offsets — the headingoffset and headingreset calculation.
HTML Accessibility API Mappings 1.0 Working Draft, 2026-10-21: h1–h6 — heading role and aria-level mapping.
WPT HTML-AAM heading tests at the tested commit, plus the selected role and mutation files linked in the Fact / Evidence table.

Implementation Evidence

The selected WPT files are pinned to one commit and run through the WPT testharness in local Chromium. For HTML-AAM tests, a Playwright / Chromium DevTools Protocol adapter provides computed role and label queries. This is not an official wptrunner / WebDriver run.

Dedicated fixture: heading-v1 records the six native heading elements, level offsets, reset boundaries, browser layout, theme controls, page metadata, and Chromium Accessibility Tree. It passed 16/16 DOM and selector checks. The machine-readable WPT result is in build-config/yugien/research-results/heading-v1/wpt-report.json; final browser conditions and results are recorded in docs/atlas/heading-evidence-2026-10-31.md.

Heading implementation evidence registry
Type	Reproduced scope	Recorded conditions	Status
IMPL	Four Japanese and English Yugien / Atlas pages, shared navigation, search and locale links, responsive layout, theme controls, and heading-v1 DOM/CSS checks	2026-10-31 / Windows 11 Pro build `26300` / Chromium `155.0.8059.85` / Playwright `1.62.1` / DPR `1` / local loopback. All four pages returned HTTP 200; checked canonical and ja/en hreflang, shared stylesheets, global navigation, locale links, and search links. At widths `320`, `390`, `768`, `1280`, and `1920`, document/body did not overflow horizontally. On each page, emulated prefers-color-scheme dark and light, then checked system, explicit light, and explicit dark modes. System-dark / dark background was `#1b201e`; light was `#f5f1e8`. Japanese search for `見出し` and English search for `heading` returned the matching Yugien and Atlas Topics. The fixture at `build-config/yugien/research-results/heading-v1/` passed 16/16 checks. At 320px, Atlas table wrappers were 286px wide, fact table content was 608px, and implementation evidence content was 627px (Japanese) / 658px (English), scrolling inside the wrapper. At 768px, the English implementation evidence table had a 670px wrapper and 690px of content, also scrolling inside the wrapper. These dimensions were measured after the final registry rows were generated.	Partial observation (Chromium 155 / four pages / 320–1920px / three themes)
WPT	Selected WPTs for HTML-AAM heading roles, invalid heading nesting, and headingoffset mutations	2026-10-31 / Chromium `155.0.8059.85` / Playwright `1.62.1`. WPT revision `5b11a9b4169aba2d11f33d787c88222bf9f017c3`. `roles.html`: 60/60 passed (all six `h1`–`h6` role cases passed). `invalid-nesting.html`: 16/16 passed. `headingoffset-mutations.html`: 0/45 passed. All 45 reported an error because Chromium rejected `:heading(1)` as an invalid selector. This WPT run could not determine conformance of the attribute calculation itself. Three files were run through the local testharness; the HTML-AAM role/label helper used CDP Accessibility. This was not the official `wptrunner` / WebDriver launcher. Other tests and browsers were not run. Report: `build-config/yugien/research-results/heading-v1/wpt-report.json`. WPT version used: `5b11a9b4169aba2d11f33d787c88222bf9f017c3`. Test-file links open files from this version.	Selected WPTs only (76 passed / 45 selector errors)
AAM	Chromium Accessibility Tree role, name, and level for heading-v1 `h1`–`h6`, headingoffset and headingreset cases, and the h1 on each of four live topic pages	2026-10-31 / Windows 11 Pro build `26300` / Chromium `155.0.8059.85` / DPR `1`. Measured with CDP `Accessibility.getPartialAXTree`. Each native `h1`–`h6` exposed role `heading`, its text as the name, and levels `1`–`6`. The main heading on all four topic pages exposed role `heading`, localized name, and level `1`. A child `h1` under ancestor `headingoffset=2` remained level `1` (HTML Standard calculation: 3). An `h2` below ancestor `headingoffset=4` and descendant `headingreset` exposed level `2`. `CSS.supports("selector(:heading(2))")` returned `false`. Browser AX Tree only; Windows UIA / IAccessible2, other platform APIs, NVDA/Narrator speech, and braille were not measured.	Partial observation (Chromium AX Tree / one environment)

Coverage / Open Issues

Specification checkedh1–h6 definitions, heading levels, outline, headingoffset, and headingreset
Selected WPTsRan 60 HTML-AAM role checks and 16 invalid-nesting checks, including all six heading role cases
OpenAll 45 headingoffset mutation checks were blocked because Chromium 155 rejected :heading(1) as an invalid selector. In a separate measurement, an h1 under an ancestor with headingoffset=2 still exposed AX level 1 instead of the Standard's calculated level 3.
To investigateCheck how the HTML-AAM draft's element-name-based aria-level mapping and HTML Standard offset calculation relate in other engines and platform APIs.
Not measuredOther browsers, Windows UI Automation / IAccessible2, macOS AX, NVDA or Narrator speech, braille output, and the full WPT suite.

These results cover one Chromium environment and three selected WPT files. They do not establish conformance across browsers, assistive technologies, or accessibility APIs.

HTML Heading Elements — h1–h6, Levels, and Outline