{
    "slug": "heading_hierarchy",
    "term": "Heading Hierarchy (h1-h6)",
    "category": "accessibility",
    "difficulty": "beginner",
    "short": "Headings must form a logical, sequential outline (h1 then h2, no skipped levels) so screen reader users can navigate and grasp page structure.",
    "long": "HTML heading elements h1 through h6 communicate document structure, not visual size. Screen reader users rely heavily on headings to navigate: NVDA, JAWS, and VoiceOver all let users jump from heading to heading and pull up a list of all headings to scan a page like a table of contents. For this to work, headings must form a meaningful outline. There should be exactly one h1 describing the page's primary subject, followed by h2 for major sections, h3 for subsections, and so on. Levels must not be skipped when descending (an h2 followed directly by an h4 implies a missing section), because the gap suggests structure that is not there. You may jump back up freely (an h4 followed by an h2 starts a new major section). The cardinal sin is choosing a heading level for its default font size rather than its semantic rank, or using styled <div>s and <p>s that look like headings but carry no heading role in the accessibility tree. WCAG 2.1 covers this under Success Criterion 1.3.1 (Info and Relationships, Level A) and 2.4.6 (Headings and Labels, Level AA); the practice of a logical heading order is also reflected in SC 2.4.10 (Section Headings, AAA). Tools like axe and Lighthouse flag skipped levels and missing h1, but they cannot judge whether a heading is semantically appropriate, so manual review with a heading-navigation command is essential. Use CSS to control appearance and reserve heading levels for structure; if you need large text that is not a section heading, style a paragraph or span instead.",
    "aliases": [
        "heading levels",
        "document outline",
        "h1-h6 structure",
        "heading structure"
    ],
    "tags": [
        "accessibility",
        "html",
        "wcag",
        "semantic-html",
        "document-structure"
    ],
    "misconception": "Heading levels are about font size, so you pick whichever h tag looks right visually. In reality heading levels convey structural rank for assistive technology; appearance should be controlled with CSS while the level reflects the section's place in the outline.",
    "why_it_matters": "Screen reader users navigate primarily by jumping between headings, so a broken or illogical heading order makes a page disorienting or impossible to scan, and it fails WCAG SC 1.3.1 at Level A.",
    "common_mistakes": [
        "Skipping a level when descending, such as following an h2 directly with an h4.",
        "Choosing a heading level for its default font size instead of its semantic rank.",
        "Using multiple h1 elements or no h1 at all on a page.",
        "Faking headings with styled <div> or <b> elements that have no heading role.",
        "Wrapping non-heading text (like a tagline) in a heading tag just to make it large."
    ],
    "when_to_use": [
        "On every page, to provide a single h1 and a logical, gap-free descending outline of sections and subsections.",
        "When refactoring components that render headings, to verify the assembled page still produces a valid outline across nested components."
    ],
    "avoid_when": [
        "Do not change a heading level purely to match a desired font size when the level is structurally correct; adjust CSS instead.",
        "Do not introduce extra heading elements to create visual separators that carry no structural meaning."
    ],
    "related": [
        "screen_reader_basics",
        "wcag_guidelines",
        "skip_links",
        "accessibility_testing_tools"
    ],
    "prerequisites": [
        "screen_reader_basics",
        "wcag_guidelines"
    ],
    "refs": [
        "https://www.w3.org/TR/WCAG21/#info-and-relationships",
        "https://www.w3.org/TR/WCAG21/#headings-and-labels",
        "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements",
        "https://www.w3.org/WAI/tutorials/page-structure/headings/"
    ],
    "bad_code": "<!-- Levels skipped and sized by appearance -->\n<h1>Acme Store</h1>\n<h4>Featured Products</h4>  <!-- jumps h1 -> h4 -->\n<div class=\"big-text\">Sale Items</div>  <!-- looks like a heading, isn't one -->\n<h2>Customer Reviews</h2>",
    "good_code": "<!-- Logical outline, size controlled in CSS -->\n<h1>Acme Store</h1>\n<h2>Featured Products</h2>\n<h3>Sale Items</h3>\n<h2>Customer Reviews</h2>\n\n<style>\n  /* Style for appearance, not structure */\n  h3 { font-size: 1.75rem; }\n</style>",
    "quick_fix": "Audit headings with a heading-navigation tool, ensure one h1, and renumber tags so levels descend without gaps while controlling size via CSS.",
    "severity": "medium",
    "effort": "low",
    "created": "2026-06-05",
    "updated": "2026-06-05",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/heading_hierarchy",
        "html_url": "https://codeclaritylab.com/glossary/heading_hierarchy",
        "json_url": "https://codeclaritylab.com/glossary/heading_hierarchy.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Heading Hierarchy (h1-h6)](https://codeclaritylab.com/glossary/heading_hierarchy) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/heading_hierarchy"
            }
        }
    }
}