Debug CLS in the trace

The tool: the Layout Shifts panel in a Performance trace

Chrome DevTools makes layout shift debugging concrete. When you record a performance trace, the Layout Shifts checkbox in the experience row collects every Layout Shift record, and clicking one in the summary highlights the element that moved it in the DOM, with a red/yellow outline overlay in the frame.

The workflow is always the same order:

1. Open DevTools > Performance.
2. Check the Layout Shifts box in the capture settings.
3. Record, load the page (a hard reload with a slow connection is ideal because late-arriving images and third parties are what trigger shifts).
4. Stop and look in the summary under Layout Shifts: each record is one shift with its score and source.

The trace records the shift even when it is tiny, which is what lets you see the difference between a font swap that moves text a few pixels and a hero that jumps by half the viewport.

Read the record

Each shift record shows the moved element, the affected nodes in the trace, and under Details the shift score the metric will compute. Compare across a few reloads: a consistent element (the same hero, sidebar ad, or cookie banner container) appears in nearly every trace, while a one-off food embed may appear once. The consistent one is the CLS you are shipping, not the noise.

The three sources in the debugger order given by the CLS fix guide:

Turn the trace into a fix

1. Read the records by element: a hero shows Layout Shift on img#hero; an ad shows div.ad-slot.
2. Re-run with network throttling off to see whether the shift also fires when assets are cached; if it disappears on a warm reload, the shift is asset-timing-driven (late image or font), not structural.
3. Apply the reserve fix and re-capture: the shift should disappear from the trace records, because the layout box exists before the asset arrives and the metric no longer counts it.

Diagnosing the special classes

• Hero images with fetchpriority="high": these shift because the browser already reserved nothing; the width/height fix still applies even with a preload.
• CSS variables and style recalcs: a shift that follows a style change on a parent (a sidebar display flip) shows in the trace as a large area moving; check the Layout.changes panel as well.
• Late third-party script injected layout: the trace shows the script frame creating the widget then shifting; the fix moves the injection off the main flow entirely.

The trace is the ground truth. The CLS optimisation article explains the mechanism behind each fix; the layout shift forms article covers the specific interactive-move class; and the audit procedure article places CLS into the field-vs-lab loop so a DevTools trace is not the only proof you keep.