Heading hierarchy.

Heading hierarchy is the ordering of a page’s h1–h6 elements so they correctly reflect the document structure — it is the screen reader user’s table of contents.

For a sighted user, headings are a typographic signal: whatever is big and bold starts a section. For a screen reader user, headings are a navigation tool — one key jumps from heading to heading, and the page’s structure emerges by listening. A heading level is therefore not a visual decision but a structural one.

The problem usually starts here: a heading is wanted visually smaller, so its level is lowered. Text that should be a section heading becomes an h4 because the h2 looks too big. The visual result is what was wanted; the structural result is a broken document tree.

The rules

The rules of heading hierarchy are few, and all are testable. What is complex is not the rules but following them on an existing site.

1. One h1 per page — it says what the page is about. Usually the page’s main title.
2. No skipping on the way down — no h4 after an h2. One step at a time when descending.
3. Skipping upward is fine — an h2 can follow an h4; a new top-level section has begun.
4. Visual size is independent of level — an h3 can look as small as you like; the size is set with CSS.
5. A heading must really be a heading — a bolded paragraph is not a heading; a section without a heading element is not a section to the screen reader.
6. No empty headings — a heading carrying an icon but no text produces an empty row in the navigation list.

The second rule is the most often broken, and it is almost always broken for visual reasons. The fix is simple: choose the level correctly and set the size with CSS. There is nothing wrong with an h2 at 18 pixels; there is with an h4 standing in for an h2.

What happens in the screen reader

To understand why the rules matter, see what a broken hierarchy produces in the listening experience. When a screen reader user lands on a page, one of their first moves is opening the heading list — the page’s table of contents.

With a correct hierarchy, that list shows the page’s structure: the main title, sections beneath it, subsections beneath those. The user jumps straight to the section they care about. With a broken hierarchy, the list turns meaningless — indents in the wrong places, sections that look like subsections, subsections that look like main sections.

Worse are the sections that use no heading element at all. Text set big and bold but marked up as a paragraph is a heading to the sighted user and not to the screen reader. That section never appears in the navigation list and cannot be jumped to — for someone navigating by ear, that part of the page effectively disappears.

A bolded paragraph is not a heading to the screen reader; that section of the page simply is not in the list.

The h1 debate

“How many h1s should a page have” has been debated for years, with two answers in circulation: per the HTML5 outline algorithm every section may carry its own h1, or per the classic approach a page should have a single h1.

The practical answer is clear: use a single h1. The HTML5 outline algorithm was never actually implemented by any browser or any screen reader, and it was removed from the specification. A page using several h1s produces a flat list in assistive technology, and the hierarchy is lost.

On this site the rule is protected by code: the measurement tool counts the h1s and the hierarchy skips on EVERY generated page. In the latest measurement there is no page with an h1 count other than one, and no hierarchy skip — both zero. The rule lives in a test, not in a style guide.

How to audit

Auditing the heading hierarchy is the easiest, fastest-paying part of an accessibility audit. There are three methods, and each takes a few minutes.

1. Extract an outline with a browser extension — extensions listing the page’s headings with their levels show the skips instantly.
2. Sweep with a short script — collecting headings in source order and reporting consecutive level gaps greater than 1 is a few lines of work, and it sweeps the whole site.
3. Open the screen reader’s heading list — this is the real verification. Does the list tell the page’s story, or is it scrambled?

The second method, being automatable, is the most durable. A hierarchy fixed by hand once breaks again with the next content entries — especially in systems where content editors choose heading levels themselves. With the sweep running on every deployment, the breakage shows immediately.

One last note: heading hierarchy is not a gain limited to accessibility. Search engines derive the document structure from headings too, and answer engines take the sections under headings as the unit when citing passages from a page. A correct hierarchy serves three readers at once: the human, the crawler and the model.

Decay in content systems

The place where heading hierarchy breaks most often is not the code but the content entry interface. Most rich text editors let the content editor choose heading levels freely, and the choice is made by looking at the visual preview — “this looks too big, let’s shrink it.” The result is a broken document tree on a page the technical team never touched.

The lasting fix is constraining the choice. If the content area already provides the page’s h1, the editor should not offer h1 at all. Likewise, jumping two steps below the current deepest level can be blocked in the interface. Giving the editor fewer options here is a convenience, not a restriction — because the right choice is a single option anyway.

Where constraining is impossible, the second line of defense is measurement. A check that sweeps published pages for hierarchy and warns on skips feeds the problem back to the editor. On this site that check lives inside the measurement tool and sweeps all generated pages on every run.

Separating visual size from level

At the heart of the heading debate sits a practical tension: the designer wants a visual scale, the developer wants a structural level, and HTML expresses both with the same element. The tension resolves by separating scale from level.

The method: heading elements define only STRUCTURE and carry no default look. Visual size comes from a separate class. An h2 can then look large or small as needed, and the designer never has to change the level. This separation is a standard pattern in design systems and solves most hierarchy problems at the source.

On this site the typographic scale is defined at token level and applied independently of heading level. Stage headings carry their own scales, body headings theirs — but the HTML level of both is chosen by document structure, not by the size they appear at.

The level tells the structure, the size tells the look. They are not the same thing and must not come from the same place.