vibecheck0.3.0
Performancelayout-thrashingwarning

Cumulative layout shift (CLS)

Layout shift is when content jumps after it has already rendered — an image loads and pushes the text down, a banner injects itself above the fold, a web font swaps and reflows everything. It is a Core Web Vitals metric Google ranks on, and it makes users tap the wrong thing. AI-built pages shift constantly because generated markup omits width/height on images and drops late content in without reserving space.

Framework fixes
GeneralReactNext.jsVanilla JS

Symptoms

  • Text and buttons jump down as images or ads load in
  • You tap one thing and hit another because it moved
  • A visible reflow when the web font swaps in
  • PageSpeed Insights reports a poor CLS score (> 0.1)

How VibeCheck catches it

In your widget · Problems

warninglayout-thrashingLayout shift cluster detected (3 shifts)

To your coding agent · MCP

agent › get_detected_issues
→ { detector: "layout-thrashing", issue: "Layout shift cluster detected (3 shifts)", threshold: "≥ 3 layout shifts within a 500ms window, with no recent user input" }

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

Root causes

  • Images and videos without width/height (or an aspect-ratio box) reserving space
  • Content injected above existing content (banners, cookie bars, ads) after load
  • Web fonts swapping and reflowing text (FOUT) without a matched fallback
  • Dynamically sized containers that resize once data arrives

The fix

Reserve the final space before the content arrives. Give every image and embed explicit dimensions or a CSS aspect-ratio box, insert late content into a pre-sized container (never above existing content), and size fallback fonts to match the web font so the swap doesn’t reflow.

  1. Add width and height (or aspect-ratio) to every image, video, and iframe
  2. Reserve a fixed-size slot for anything injected after load (ads, banners, embeds)
  3. Use font-display: optional or a size-adjusted fallback to avoid font-swap reflow
Reserve space with aspect-ratiocss
.media {
  aspect-ratio: 16 / 9;
  width: 100%;
}
/* size the fallback to the web font so the swap doesn't reflow */
@font-face {
  font-family: 'Inter Fallback';
  src: local('Arial');
  size-adjust: 107%;
}

FAQ

What CLS score do I need?
Google considers CLS good at 0.1 or below, and poor above 0.25, for 75% of page loads. It is one of the three Core Web Vitals used in ranking.
Why does the layout-thrashing detector flag this?
VibeCheck observes the browser’s layout-shift entries. When three or more fire within 500ms without user input, it flags a cluster — that burst is exactly what a jumpy load feels like.
My image is responsive — do I still set width and height?
Yes. Set the intrinsic width/height attributes so the browser knows the aspect ratio, then use CSS (width:100%; height:auto) to scale it. That gives you responsiveness with zero shift.