Heading Hierarchy: Fixing Heading Structure

How people use headings to get around a page

A sighted visitor glances down a page and sees the sections at once. Someone using a screen reader cannot do that, so headings take on that job. The common ways they are used:

• Jumping. In NVDA and JAWS, pressing H moves to the next heading and Shift+H to the previous one. The number keys 1 to 6 jump to the next heading of that level, so pressing 2 skims the main sections.
• Listing. NVDA's elements list (Insert+F7) and the VoiceOver rotor on Mac and iPhone show every heading as a list. People read the list, choose a heading and land on that section.
• Understanding. The level of each heading tells the listener how sections relate: an h3 after an h2 is part of it, while the next h2 starts something new.

So the heading list should read like a sensible contents page on its own. If you can read only the headings of your page and still understand what is on it and where, the structure is working.

Headings help other visitors too. People with reading or attention difficulties rely on clear headings to find their place, and search engines and AI tools use them to understand which text belongs to which topic.

What WCAG actually requires, and what is best practice

Heading findings are a mix of genuine WCAG failures and widely agreed best practice. It helps to know which is which when deciding what to fix first.

The Accessibility Audit reports both kinds. Fix the failures first, then tidy the best-practice issues, which are usually quick once the templates are right.

Printing the heading outline of a page

Before editing anything, get the real heading structure, not the one the design suggests. Paste this into the browser console (F12, then Console) on any page. It lists every heading in order, indented by level, and flags empty headings and skipped levels:

(() => {
  let last = 0;
  document.querySelectorAll('h1,h2,h3,h4,h5,h6,[role="heading"]').forEach(h => {
    const level = h.getAttribute('aria-level') ? +h.getAttribute('aria-level') : +h.tagName.slice(1) || 2;
    const text = h.textContent.replace(/\s+/g, ' ').trim();
    const flags = [];
    if (!text) flags.push('EMPTY');
    if (last && level > last + 1) flags.push('SKIPS FROM H' + last);
    console.log('  '.repeat(level - 1) + 'H' + level + ' ' + (text || '(no text)') + (flags.length ? '   <-- ' + flags.join(', ') : ''));
    last = level;
  });
})();

Run it on one page of each template: home, a standard page, a blog post, a category or collection page, a product page and the contact page. Look for three things in the output:

1. Does the first heading describe this particular page, or is it the site name or a "Menu" label repeated everywhere?
2. Do the levels step down one at a time as you go into a section, and back up when a new section starts?
3. Are there headings with no text, or text that is plainly not a heading, such as a price, a phone number or a promotional line?

Then compare the output with what you see. Any bold line, large text or coloured band that looks like a section title but does not appear in the list is a fake heading.

Common structural mistakes and their fixes

The logo or site name as the h1

Many themes wrap the logo in an h1 on every page, so every page starts with the same heading and the real title appears as a second one. On inner pages, make the logo a plain link with an image whose alt text names the business, and let the page title be the main heading.

Bold paragraphs pretending to be headings

<!-- Looks like a heading, is not one -->
<p><strong>Opening hours</strong></p>

<!-- A real heading -->
<h2>Opening hours</h2>

This is especially common in text pasted from word processors and in older content where editors used bold to mark sections. It is a genuine failure, because sighted readers get structure that listeners do not.

Levels chosen for size

<!-- A small heading was wanted, so h5 was used -->
<h2>Delivery</h2>
<h5>Next-day delivery</h5>

<!-- Correct level, smaller style -->
<h2>Delivery</h2>
<h3 class="heading-small">Next-day delivery</h3>

The level describes position in the structure; the class describes appearance. Keeping them separate means designers can make any heading any size without breaking navigation.

Headings used for decoration

Taglines, prices, "Free delivery over £50" banners and testimonial quotes are often put in heading tags because they are meant to stand out. They then appear in the heading list as if they were sections. Change them to paragraphs or span elements with a class that gives the same look.

Sidebars, footers and cards

Repeated regions need levels that fit around the main content. A common and sensible pattern is: the page title as h1, main content sections as h2, sidebar and footer blocks as h2 as well, since they are separate areas of the page. Product and article cards in a listing usually sit one level below the heading of the list they belong to. Footer column titles such as "Quick links" can also simply be styled text if they do not introduce anything a listener would jump to.

Headings in the HTML5 outline myth

Older advice said you could start every section or article with an h1 and browsers would work out the levels. That outline algorithm was never implemented by browsers or screen readers and has been removed from the HTML standard. Every h1 is announced as level 1, wherever it sits, so use explicit levels.

Where to fix headings on each platform

For reusable components, let the page decide the level. A simple approach is a prop or setting such as headingLevel that defaults to a sensible value and renders the matching tag, so the same card can sit under an h2 on one page and an h3 on another.

The fix, step by step

Edge cases

• Headings in accordions and tabs. It is fine for a heading to wrap the button that opens an accordion panel, for example an h3 containing a button. The heading gives structure and the button gives the control. Do not put the heading inside the button, because the heading role would be lost.
• Visually hidden headings. A heading hidden with a visually hidden class, such as "Main navigation" or "Related products", can help screen reader users find regions that have no visible title. Use them sparingly and keep them at a level that fits the outline.
• role="heading". If you cannot change the tag, role="heading" with aria-level creates a heading for assistive technology. A real heading tag is better and should be used wherever you control the markup.
• Headings containing links. A heading that is also a link, such as an article title in a list, is fine. Make sure the link text is the heading text, not "Read more".
• Very long headings. A heading that runs to several lines is tiring to hear in a list. Keep headings short and put the detail in the paragraph below.
• Dialogs and pop-ups. A modal usually starts with its own heading, often an h2, which the dialog can reference with aria-labelledby as its name.

Keeping the structure right

• Limit heading choices in the editor. Many editors let you remove h1 from the options available in content, since the template already provides it, and some let you restrict levels further.
• Give editors a rule of thumb. "Choose the level by what the heading belongs to, choose the size in the style settings" prevents most content problems.
• Clean pasted content. Text pasted from word processors often brings bold lines instead of headings. Paste as plain text, then apply heading blocks.
• Review new components. When a new card, banner or widget is designed, decide its heading level, or whether it needs one, before it is built.
• Recheck after redesigns. A new theme or design system is the most common moment for heading structure to break across the whole site.