vibecheck0.3.0
Search visibilityseoh1-missingwarning

No H1 heading

The <h1> is the strongest on-page signal of what a page is about, for both search engines and screen-reader users navigating by heading. AI-built pages often style a big <div> or <p> to look like a heading, so it looks right but carries zero semantic weight. Others start the document at <h2> because the <h1> “felt too big”.

Framework fixes
GeneralReactVueSvelteVanilla JS

Symptoms

  • The visually-largest text is a styled <div> or <span>, not an <h1>
  • The document heading outline starts at <h2>
  • Screen-reader heading navigation skips the main topic

How VibeCheck catches it

In your widget · Problems

warningseoNo <h1> heading

To your coding agent · MCP

agent › get_detected_issues
→ { detector: "seo", issue: "No <h1> heading", threshold: "zero <h1> elements on the page" }

The same string in your widget and in your agent’s context — no screenshot, no copy-paste.

Root causes

  • A heading was faked with a styled div/span instead of a real <h1>
  • The page starts its heading hierarchy at <h2>
  • A shared layout owns the <h1> on some routes but not this one

The fix

Add exactly one <h1> per page that describes its main topic, and style it however you like — semantics and visual size are independent. Keep the rest of the outline logical (<h2> for sections, <h3> for subsections).

  1. Identify the page’s single main topic
  2. Mark it up as one <h1> (restyle with CSS, not by changing the tag)
  3. Ensure sub-sections use <h2>/<h3> in order
html
<!-- fake heading -->
<div class="text-4xl font-bold">Pricing</div>

<!-- real heading -->
<h1 class="text-4xl font-bold">Pricing</h1>

FAQ

Can I have more than one H1?
HTML5 technically allows it, but for SEO clarity ship exactly one <h1> per page and use <h2>+ for the rest. Multiple <h1>s dilute the topic signal.
Does the H1 have to be the biggest text?
No. Semantics and styling are separate — style your <h1> however you like. What matters is that the tag is an <h1>.
Should the H1 match the <title>?
They should be closely related but need not be identical. The <title> is tuned for search results; the <h1> is the on-page headline.