/loading-states-and-perceived-performance

name: loading-states-and-perceived-performance
description: Manage user expectations during wait times with appropriate loading states — from simple spinners to complex skeleton screens and staggered animations. Perceived performance is often more important than actual load time. Use when designing data-heavy components, handling API calls, building hero sections, or improving the feel of a slow interface.
metadata:
  priority: 7
  pathPatterns:
    - "components/**"
    - "src/components/**"
    - "**/*.tsx"
    - "**/*.jsx"
    - "**/*.css"
    - "**/*.scss"
    - "design-system/**"
  promptSignals:
    phrases:
      - "loading state"
      - "spinner"
      - "skeleton screen"
      - "skeleton loader"
      - "perceived performance"
      - "loading animation"
      - "shimmer effect"
      - "staggered loading"
      - "prefetch"
      - "prioritise loading"
      - "progressive loading"
      - "lazy load data"
retrieval:
  aliases:
    - loading states
    - skeleton loaders
    - spinners
    - perceived performance
    - shimmy
    - glimmer
    - prefetching
    - priority loading
    - progressive data loading
  intents:
    - design a loading state
    - add a skeleton screen
    - improve perceived performance
    - choose between spinner and skeleton
    - handle slow data loading
    - adding delight to the wait
    - load the most important content first
    - prefetch the likely next step
  examples:
    - what loading state should this card use
    - add a skeleton loader for this list
    - make the page feel faster while loading
    - design a spinner for this button
    - load the key content first then stream the rest
    - prefetch the next page so it feels instant

Loading States and Perceived Performance

Users don't mind waiting as much if they understand *what* they are waiting for and *how much* progress is being made. Perceived performance is the design work of making a system feel faster than it actually is.

---

Choosing the Right Loading State

| Wait Duration | Best Pattern | Use for | |---|---|---| | **Short (< 1s)** | **Inline Spinner / Loader** | Button actions, small updates, quick data fetches | | **Medium (1s – 3s)** | **Skeleton Screen** | Cards, lists, dashboards, profile pages | | **Long (> 3s)** | **Determinate Progress Bar** | File uploads, complex exports, heavy processing | | **Full Page** | **Staggered Entry / Animated Sections** | Initial app load, hero sections, immersive transitions |

---

Simple Cases: Spinners and Loaders

Use spinners for small, contained actions where the layout doesn't change significantly.

• **Button Spinners:** Replace button text or sit alongside it. The button should enter a `disabled` state to prevent double-submissions.
• **Micro-Loaders:** A small 16–24px circle for inline updates (e.g., saving a single field).
• **Animation Tip:** A "spring-loaded" rotation (easing in and out) feels more premium than a constant linear rotation.

@keyframes spin {
  0%   { transform: rotate(0deg); }
  100% { transform: rotate(360deg); }
}
.spinner {
  animation: spin 800ms cubic-bezier(0.4, 0, 0.2, 1) infinite;
}

---

Skeleton Screens (Glimmer/Shimmer)

Skeleton screens provide a visual placeholder that mimics the layout of the final content. This reduces "layout shift" (CLS) and signals to the user exactly where the content will appear.

The Shimmer Effect

A subtle, moving gradient that travels across the skeleton elements.

.skeleton {
  background: var(--color-grey-100);
  background-image: linear-gradient(
    90deg,
    rgba(255, 255, 255, 0) 0%,
    rgba(255, 255, 255, 0.5) 50%,
    rgba(255, 255, 255, 0) 100%
  );
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
}

@keyframes shimmer {
  0%   { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}

Rules for Skeletons

• **Match the shape:** If the final content is a round avatar, use a round skeleton. If it's a 2-line heading, use two bars of varying widths.
• **Stay Recessive:** Skeletons should use your most subtle grey (`--color-grey-100` or `grey-50`). They should not draw focus.
• **Fade into Reality:** When data arrives, fade the actual content in over the skeleton (150–200ms) rather than snapping.

---

Fully Animated Sections

For major page transitions or initial loads, use a coordinated animation strategy.

Staggered Entry (Cascading)

Instead of the whole page appearing at once, animate sections in a sequence. This guides the user's eye from the most important content (hero) down to secondary areas.

.section {
  opacity: 0;
  transform: translateY(10px);
  animation: slide-up 400ms ease-out forwards;
}
/* Stagger by index */
.section:nth-child(1) { animation-delay: 100ms; }
.section:nth-child(2) { animation-delay: 200ms; }
.section:nth-child(3) { animation-delay: 300ms; }

@keyframes slide-up {
  to { opacity: 1; transform: translateY(0); }
}

Hero Section "Bloom"

For hero sections, you might use a more complex animation: 1. **Background image** fades in slowly. 2. **Heading** slides in with a slight overshoot (spring). 3. **CTA button** appears last with a crisp fade-in or subtle color transition.

---

Load in Priority Order — and Prefetch What's Next

Don't wait for everything before showing anything. Load in the order of **value to the user**, so the thing they came for appears first and the rest fills in around it. This is both a perceived-performance win and a code-efficiency one: you fetch and render less up front.

• **First, the highest-value content** — the key figure, the primary record, the above-the-fold answer. Render it the moment it's ready.
• **Then the next tier, then the next** — secondary panels, related lists, and below-the-fold sections stream in behind it (skeletons hold their space so nothing shifts — see the skeleton section above).
• **Fetch only what the current view needs.** Defer data for tabs, drawers, and off-scree