Will It Vibe?Heading levels skip a level
Part of Documentation, UX & Accessibility, which counts for 15% of the overall score. When this check fires it deducts 4 points from that category, once per scan, no matter how many places it turns up.
What it detects
Screen-reader users often navigate by jumping between headings and rely on level (h1, h2, h3...) to understand nesting; a document that jumps from an h2 straight to an h4 with no h3 implies a subsection that does not exist and breaks that mental model. Insert the missing intermediate level instead of choosing a heading tag for its default font size. Heuristic: reports the first skip per file only, and (for JSX) reads heading tags in raw file order, which is not always final render order when headings come from conditional branches.
Why it matters
Heading levels are how screen-reader users understand nesting: jumping from an h2 straight to an h4 with no h3 implies a subsection layer that does not actually exist in the content, which is confusing precisely for the navigation-by-heading workflow this markup is supposed to support. This usually happens when a heading tag was chosen for its default font size rather than its place in the outline.
How to fix it
Insert the missing intermediate heading level, or change the skipped-to heading down to the next level in sequence. If a heading was chosen purely for its visual size, keep the semantically correct level and restyle it with CSS instead of picking a different tag.
The paid report includes a ready-to-paste prompt for your AI coding agent for every check it finds, pointed at the exact findings from your scan. See pricing
Does your repo trip this check?
Paste a GitHub URL or drop a project folder. Scans run in your browser and take seconds.
Scan your repo