Reduce CLS by Measuring Shifts Before Fixing Them

1. Capture layout-shift entries with their sources in the console.

// paste in DevTools console, then reload and interact
new PerformanceObserver((list) => {
  for (const e of list.getEntries()) {
    console.log(
      'shift', e.value.toFixed(4),
      'at', Math.round(e.startTime), 'ms',
      'sources:', e.sources.map((s) => s.node?.nodeName + '.' + (s.node?.className || '')).join(', ')
    );
  }
}).observe({ type: 'layout-shift', buffered: true });

Expected output: Lines print like shift 0.1140 at 820ms sources: IMG.hero, DIV.article-meta, naming both the mover and the moment.

2. Rank the shifts by contribution and cluster them by start time.

echo "paste the console lines into shifts.txt"; sort -k2 -rn shifts.txt 2>/dev/null | head -8 || echo "record with DevTools > Performance > Layout Shift regions"

Expected output: Sorted entries show the top contributors; start times cluster around image load, font swap, or data fetch, identifying the trigger class.

3. Reserve exact space for the late-arriving content.

<!-- before: image arrives, pushes everything down 312px -->
<img src="/hero.webp" alt="dashboard">

<!-- after: aspect-ratio box holds the space from first paint -->
<img src="/hero.webp" alt="dashboard"
     width="1200" height="628" style="aspect-ratio: 1200 / 628">

<!-- skeleton with the FINAL height, not a guess -->
<div class="chart-slot" style="height: 420px">
  <div class="skeleton" data-testid="chart-skeleton"></div>
</div>

Expected output: The hero image no longer displaces content when bytes arrive, and the chart skeleton occupies the exact final height, removing the two largest shift sources.

4. Stabilize the font swap that moves text after paint.

/* before: fallback metrics differ -> headings jump on swap */

/* after: match fallback metrics to the webfont */
@font-face {
  font-family: 'Inter';
  src: url('/inter-var.woff2') format('woff2-variations');
  font-display: swap;
  ascent-override: 96.37%; descent-override: 24.21%;
  line-gap-override: 0%;
  size-adjust: 100.06%;
}

/* plus a fallback stack with matched x-height */
font-family: 'Inter', 'Helvetica Neue', Arial, sans-serif;

Expected output: Re-running the observer shows the 60-200ms text jumps shrink to near zero after the swap metrics match.

5. Re-measure until the total is under threshold.

node -e "const s=[0.114,0.062,0.031,0.004];console.log('CLS',s.reduce((a,b)=>a+b).toFixed(3))" && echo "target <= 0.05; re-run the PerformanceObserver to confirm"

Expected output: The recomputed session CLS prints; iterating per source until the sum is at or under 0.05 turns a vague metric into a completed checklist.

Problem

PerformanceObserver logs nothing

Solution

The observer must be registered before the shifts happen; use buffered: true on a fresh reload, and check the page is not served in an iframe where the metric is reported to the parent frame.

Problem

Sources list is empty or null nodes

Solution

Elements were removed before the shift entry was read; capture a trace instead, and use the Layout Shift regions overlay in the Performance panel to see the moved rectangles.

Problem

Dynamic content genuinely needs to grow

Solution

Insert new content only below the fold, or animate it in with fixed height: growing downward below the viewport contributes nothing to CLS, while moving existing text does.