Suspense Boundary Strategy

Place loading boundaries so the page fills in usefully rather than all at once.

involved Developer Experience

What it adds

A decision about where the interface is allowed to wait, so slow regions never hold up the parts that are ready.

What your agent is told to do

1
Map each screen into the regions that can be shown independently — the shell and navigation, the primary content, then secondary panels and counts — and let each one arrive on its own rather than waiting for the slowest.
2
Draw a boundary wherever a slow region would otherwise delay a fast one, and only there. A boundary per component fragments the page into a dozen separately twitching rectangles.
3
Start every request a region needs as early as the parameters are known, so the requests overlap instead of queueing behind whichever component happens to render first.
4
Give each boundary a placeholder with the same dimensions as its eventual content, so regions resolving in an unpredictable order do not push each other around the page.
5
This entry decides where the boundaries go and what the placement is trying to achieve; the appearance of the pending, empty, and refreshing states inside them belongs to Async Boundary Component. Do not define a second set of skeletons here.

Edge cases it handles

Content already on screen must stay on screen during a refetch. Falling back to a placeholder for data the user is currently reading is a regression, not a loading state.
Server-rendered markup and the client's first render must agree about which regions were pending, or the page will visibly reshuffle the moment it becomes interactive.
Requests must not chain. A region that fetches a record, renders, then fetches that record's related items turns two round trips into a sequence, and the boundary hides the delay rather than removing it.
Every boundary needs a matching failure containment from Error Boundary Pattern. A region that can be pending can also fail, and without a fallback the failure escapes to the nearest ancestor and takes healthy regions with it.
Streaming a page in fragments changes when the document title, the metadata, and the response status can be decided. Settle those before the parts that stream, or a not-found record will be delivered inside a successful page.
Keyboard focus and scroll restoration must account for content that arrives after the initial paint, or a user who tabs immediately will land somewhere that then moves.
Boundaries around content above the fold should be few. The user is judging the page by how quickly the top of it settles, not by how many pieces it was split into.

Definition of done

Each screen resolves in named stages, with the shell and primary content never waiting on secondary regions.
The number of boundaries is deliberate and documented per screen, not one per component.
Requests for a screen's regions are issued in parallel, with no region waiting on another's response to begin.
Refetching data leaves the currently visible content in place.
Server and client agree on the pending regions, with no visible reshuffle on hydration.
Every boundary is paired with failure containment from Error Boundary Pattern.
Placeholders match the dimensions of their content, and regions resolving out of order cause no layout shift.
The feature matches the existing design system.
No existing functionality is broken.

Related features

Prompt Versioning

Retrieval Debugger

AI Cost Budgets

How it works

1

Copy the link

Grab the Markdown instruction URL for this feature.
2

Give it to your AI

Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
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.