Loading State Design Template for PMs

Use skeleton screens when the layout of the loaded content is predictable. Dashboards, lists, cards, and tables all have stable structures that can be represented as placeholder shapes. Use spinners only when the layout is unpredictable (e.g., search results with varying heights) or for inline, brief operations (a button that takes 500ms to complete). The [design system documentation template](/templates/design-system-documentation-template) is where you codify which loading pattern each component uses.

Reserve the exact space the content will occupy. Skeleton shapes should match the dimensions of the real content. If a card is 120px tall when loaded, its skeleton should be 120px tall. For text, use multiple line skeletons at the expected text height. For images, use a placeholder at the image's aspect ratio. This prevents cumulative layout shift (CLS), a Core Web Vital that affects SEO ranking.

Both are valid. `loading.tsx` applies to the entire route segment and shows while the page component's async data fetches resolve. Suspense boundaries are more granular: you can wrap individual components so the rest of the page renders immediately while one section shows a skeleton. For dashboards with multiple independent data sources, Suspense boundaries per section provide the best experience.

200ms is the standard threshold. Below 200ms, the human visual system does not register the delay as a "wait." Showing a skeleton for 50ms and removing it creates a distracting flash. Use a timeout: only render the loading UI if the data has not arrived after 200ms. ---