vibecheck0.3.0
Web essentialsweb-essentialsviewporterror

Missing viewport meta tag

Without <meta name="viewport">, mobile browsers assume a ~980px desktop canvas and shrink the whole page to fit, so text is unreadable and tap targets are tiny. AI scaffolds often generate the component tree but leave the base HTML document untouched, so this one line never gets added. It is the single biggest reason an otherwise-fine page looks broken on a phone.

Framework fixes
GeneralReactNext.jsVueSvelteVanilla JS

Symptoms

  • Page looks zoomed-out on mobile — everything is tiny
  • Users have to pinch-to-zoom to read or tap anything
  • CSS media queries never fire because the layout viewport is 980px, not the device width
  • Lighthouse flags "Does not have a <meta name="viewport">"

How VibeCheck catches it

In your widget · Problems

errorweb-essentialsMissing viewport meta tag

To your coding agent · MCP

agent › get_detected_issues
→ { detector: "web-essentials", issue: "Missing viewport meta tag", threshold: "No <meta name="viewport"> present in the document head" }

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

Root causes

  • The framework template (index.html / app.html) was edited to remove it, or a hand-rolled HTML shell never had it
  • Meta tags are managed in a head library but the viewport was never configured
  • A generated single-file export dropped the document <head>

The fix

Add a viewport meta tag to the document head. width=device-width tells the browser to use the physical device width as the layout viewport; initial-scale=1 disables the initial zoom. Do not set maximum-scale or user-scalable=no — that breaks accessibility for users who need to zoom.

  1. Open your document head (index.html, app.html, or your framework’s metadata config)
  2. Add <meta name="viewport" content="width=device-width, initial-scale=1">
  3. Reload on a real phone or device-emulation and confirm the layout uses the full width
The canonical viewport taghtml
<meta name="viewport" content="width=device-width, initial-scale=1" />

FAQ

Should I set user-scalable=no or maximum-scale=1?
No. Disabling zoom is a WCAG accessibility failure — users with low vision rely on pinch-to-zoom. width=device-width, initial-scale=1 is all you need.
Does Next.js add the viewport tag automatically?
Next injects a sensible default, but you should declare the viewport export explicitly so it is intentional and reviewable. Never hard-code the <meta> tag in Next’s App Router.
Why does my media query not work on mobile without this tag?
Without the viewport tag the layout viewport defaults to ~980px, so min-width/max-width breakpoints compare against 980, not the real device width. The tag makes the layout viewport equal the device width.