Repository navigation
docs: add Designing loading UI guide - #98068
Draft
aurorascharff wants to merge 15 commits into
Draft
aurorascharff wants to merge 15 commits into
aurorascharff wants to merge 15 commits into
Conversation
Contributor
Tests PassedCommit: f7be810 |
aurorascharff
changed the title
Add a guide for designing loading states: choosing between a fallback and a pending indicator, sizing skeletons to keep CLS at zero, holding previous results during updates with transitions, revealing variable-height sections top-down with nested Suspense, and crossfading reveals with ViewTransition. Cross-links the profiling guide for finding boundaries that gate too much, and adds CLS cross-links to the interactive apps guide.
An aria-hidden skeleton gains nothing from ul/li semantics (screen readers skip the subtree); the geometry that prevents layout shift comes from the classes. Switch to plain divs and note why.
The profiling guide is not on canary yet, so the loading UI guide cannot link to it. Restore the related entry, the Popcorn loading note, and the Next steps bullet once that guide lands.
aurorascharff
force-pushed
the
aurorascharff/loading-ui-guide
branch
from
August 29, 2026 21:42
39b996a to
6e75cea
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Loading UI is where App Router apps most often feel broken, and the failures are consistent enough to name: a route-level
loading.tsxcompeting with a page skeleton and a per-query spinner, a coarse boundary hiding a header that could have painted immediately, sections revealing in network order and pushing each other down, a skeleton that reserves the wrong height, and an empty state rendered from data that hasn't arrived. None of this was documented in one place, and Streaming covers how the HTML arrives rather than how the result should look.What
Adds
docs/01-app/02-guides/loading-ui.mdx, a guide organized around those failures so each one is findable by symptom. Sections cover shell painting (top-level awaits, coarse boundaries, competing signals, client-effect fetching), fallback design (geometry, false empty states, fallbacks that never resolve), reveal order (popcorn loading, stable labels, crossfading the swap), updates (holding results during search, delaying pending indicators, pagination that remounts), and verification.Also adds
evals/evals/agent-052-design-loading-ui, a broken team directory that reproduces the failures for an agent to fix, and cross-links the guide from Streaming, Instant navigation, View transitions, Interactive apps, Linking and navigating, Fetching data,loading.js,layout.js,useLinkStatus, Public pages, and the Production checklist.How
Every pattern comes from a companion demo (loading-ui-demo), so the snippets are code that runs rather than illustrations. Layout stability is measured with a
layout-shiftPerformanceObserver across each journey rather than judged by eye, which is how the fallback geometry numbers in the guide were arrived at.Note on scope: this targets
canary, which does not yet contain the React performance profiling guide, soprofiling-performance.mdxandskills/next-performance-profilingappear as additions in this diff. #95859 is the same head commit stacked onworktree-next-react-perf-track-dev-tools, where those are already present.