AddThisFeature

Layout Shift Guard

Stop content jumping as a page loads, and catch it when it starts happening again.

involved Front-End Performance

What it adds

Reserved space for everything that arrives late, plus measurement that reports unexpected movement on the app's main screens.

What your agent is told to do

5
  1. 1

    Walk the app's main screens with the network throttled and note everything that moves after first paint. Images, avatars, embeds, banners, ad slots, and asynchronously loaded panels are the usual sources.

  2. 2

    Give every image, video, iframe, and embed explicit dimensions or a fixed aspect ratio so its box exists before its content arrives, including the ones whose size comes from data.

  3. 3

    Control the swap from fallback to web font so the two have compatible metrics, and accept a slightly imperfect fallback over a page that reflows once the real font lands.

  4. 4

    Reserve space for anything conditional that appears above or beside existing content — validation messages, incident banners, trial notices, unsaved indicators — rather than letting it push the layout down when it arrives.

  5. 5

    Do not count movement the user asked for. Expanding a row, opening a drawer, or loading the next page on a click is intended motion, and a guard that flags it will be turned off within a week.

Edge cases it handles

7
  • Media and embeds without declared dimensions collapse to nothing and then snap to full size; every one needs a reserved box, including those sized from record data.
  • A fallback font with different metrics to the real one reflows every paragraph when the swap happens, so the two must be matched or the swap must be suppressed until the real font is ready.
  • Banners, toasts, and validation messages are the most common late arrivals in an app that has otherwise been optimised, and each needs its space held open in advance.
  • Movement caused directly by a user action must be excluded from measurement, or the signal is drowned in noise and stops being actionable.
  • Sticky headers and action bars that change height on scroll will register as shifts unless their reserved height is fixed; this overlaps Sticky Action Bar, which owns the pinning behaviour while this entry owns the space reservation.
  • A skeleton placeholder must match the real content's dimensions. A skeleton that is the wrong height causes the shift it was meant to prevent.
  • Measurement must run on the devices and connections real users have, not only on a fast machine where everything arrives before first paint.

Definition of done

8
  • Every image, video, iframe, and embed on the main screens has reserved dimensions before its content loads.
  • Font swapping produces no visible reflow of surrounding text.
  • Conditional banners and validation messages appear in space already held for them.
  • Layout movement is measured on the app's main screens and reported.
  • Movement resulting from a direct user action is excluded from the measurement.
  • Skeleton placeholders match the dimensions of the content that replaces them.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.