Postmortem

The layout shift that wasn't

A debugging story from this site's own build: a CLS the metrics swore was there, a page that visibly never moved, and the fallback document in between.

Intermediate1 min read (computed · recorded 6)updated 2026-09-12debuggingclstooling

by Motif Editors

revised 2026-09-12 — First publication in bank-3 batch 4.

Key takeaways

— When instruments disagree, don't average them — name the discrepancy.
— Fallback documents are build artefacts, not pages; scanners must skip and say so.
— A counter that silently excludes is a lie in a nicer font.

The report

The a11y document counts disagreed by three for a day: the build report said 294 HTML documents, the markup pass found 297. Three phantom pages, no visual diff, everyone blaming the scanner.

The cause

Next writes __next_error__ fallback documents for not-found variants into .next/server/app. The scanner was counting build artefacts as pages. The fix was the scanner's — skip the fallback document and say so out loud in its output ('1 fallback document(s) skipped') — because a counter that silently excludes is the same lie in a nicer font.

The lesson generalises: when two of your instruments disagree, do not average them. Name the discrepancy in the output of one of them until the disagreement is impossible.

Practise the lesson

Theory sticks when you ship it. These original Motif assets put this guide's lesson to work — open one and copy it into your own page.

Skeleton-to-Content Fadepractice Spinner with Status Textpractice Two-Column Feature Splitpractice

Keep learning

All guides Try the interactive Lab