loading-states

Loading & Empty States

Make sure no user ever stares at a blank or frozen-looking screen: inventory every place the app waits or can be empty, choose the correct state for each by expected latency, and implement it. The prime directive: the indicator is chosen by how long the wait is and whether the layout is known — not by taste. Deliver an audit table covering every async surface plus the implemented states, never a lone spinner component.

When to use / when not to

Use for: loading indicators, skeleton screens, progress bars, empty states (first-use, no-results, error-empty, success-empty), "app looks frozen" complaints.

Hand off instead when the real need is:

• Making waits shorter or invisible (optimistic UI, preloading, caching) → skills/frontend-design/performance-optimization — always consider that first; the best loading state is none
• Error messages and recovery flows beyond a simple retry-empty-state → skills/frontend-design/error-handling-recovery
• Shimmer/spinner motion polish, timing tokens → skills/frontend-design/interaction-physics

Step 0 — Inspect the codebase, then ask only what's left

1. Inventory async surfaces: grep for fetch(, axios, useQuery/useSWR/createResource, isLoading/isPending/loading flags, Suspense boundaries, and route-level data loaders. List every view/component that waits on data or mutation.
2. For each, note what currently shows while waiting: nothing (blank), layout jump, spinner, skeleton, or a disabled control. "Nothing" and "layout jump" are the defects to fix first.
3. Check for existing skeleton/spinner/empty-state components — reuse and extend them rather than duplicating.
4. Estimate expected latency per surface from evidence: cached client state (~instant), same-region API reads (usually sub-second), search/aggregation endpoints (seconds), uploads/exports/report generation (long, often measurable). Look for existing timeout configs or telemetry. Where you can't estimate, say so and pick the 1s-class treatment as the safe default.
5. Enumerate empty-capable views: every list, table, grid, search result, and inbox can be empty. Check which ones currently render a bare nothing.