Search engines parse heading tags to build a content outline for your page — a skipped level (H1 → H3) tells crawlers the structure is broken, which can depress keyword relevance signals for the skipped content. WCAG 2.2 SC 1.3.1 (Info and Relationships) and SC 2.4.6 (Headings and Labels) require heading levels to convey actual document structure, not just visual styling. A heading hierarchy violation in a screen reader context causes users to jump unexpectedly between content levels, breaking navigation for keyboard-only and assistive technology users. This also flags on automated accessibility audits, which matters increasingly for enterprise and government procurement.
High because heading hierarchy violations degrade both crawler content parsing and assistive technology navigation simultaneously, compounding SEO and accessibility impact across every page that has the defect.
Audit every route page for heading level skips. Fix violations by inserting the missing level or demoting the offending heading:
// app/docs/page.tsx — fix a skip from H1 → H3
// Before (broken):
<h1>Documentation</h1>
<h3>Installation</h3> {/* skip! */}
// After (correct):
<h1>Documentation</h1>
<h2>Getting Started</h2>
<h3>Installation</h3>
For UI component headings from libraries like shadcn/ui (e.g., CardTitle rendering as <h3>): check whether the rendered tag level skips relative to surrounding page headings. If it does, override the rendered element via the component's asChild prop or wrap with an explicit heading at the correct level.
ID: seo-fundamentals.content-structure.heading-hierarchy
Severity: high
What to look for: Check heading tag usage across page components. The hierarchy should go H1 → H2 → H3 without skipping levels (e.g., jumping from H1 to H3, or from H2 to H4). Examine all route pages, not just the index page — heading violations commonly appear on secondary pages like /docs, /blog, /pricing.
Note on component library headings: UI libraries such as shadcn/ui render component elements (e.g., CardTitle, AlertTitle) as heading-level tags or <div> elements depending on the component. These component-internal elements may appear in the DOM as heading tags but are used for visual styling, not document structure. Focus on headings that represent the page's actual content hierarchy — section titles, article headings, and page structural divisions. If a component renders an <h3> or <h4> inside a card that is not part of the document's section hierarchy, check whether it creates a level skip relative to the surrounding document headings. If it does, that is a genuine violation regardless of whether the heading comes from a component.
Pass criteria: Enumerate all heading elements (<h1> through <h6>) across all route pages. For each page, list all headings in document order and verify levels are sequential — no level is skipped. An H3 only appears after an H2, an H4 only after an H3, etc. At least 1 heading element must exist across the project.
Fail criteria: Any page has a heading level that skips (e.g., H1 followed directly by H3 with no H2 in between, or H2 followed directly by H4 with no H3 in between). If no heading elements (<h1> through <h6>) are found at all on any page, this is a fail — do NOT pass vacuously when headings are absent. Detail must read: "No heading elements found — cannot assess hierarchy. Use semantic heading elements instead of styled divs." This prevents false passes on bare-minimum or stub codebases that use only <div> and <p> elements.
Skip (N/A) when: Never — heading hierarchy applies to all pages with content.
Detail on fail: Identify the specific hierarchy violation and the page it occurs on. Example: "On /docs, <h2> ('Understanding Your Results') is followed by <h4> ('Grade Scale') with no <h3> in between" or "On /blog, <h1> is followed by <h3> with no <h2> in between"
Remediation: Search engines use heading hierarchy to understand your content structure. Skipped levels suggest content organization problems. Review your heading levels and ensure they follow a logical sequence:
// app/docs/page.tsx — correct hierarchy
<h1>Documentation</h1>
<h2>Getting Started</h2>
<h3>Installation</h3>
<h3>Configuration</h3>
<h2>API Reference</h2>
<h3>Endpoints</h3>
If a UI component renders heading elements for visual purposes (card titles, alert headings), consider whether the rendered tag level creates a hierarchy violation and adjust either the component's rendered element or the surrounding heading structure accordingly.