skeleton-loaders

name	skeleton-loaders
description	Use when designing loading states for async content. Covers skeleton loader anatomy, when to use vs spinner, the shimmer animation, and the rules to avoid loader fatigue.

Skeleton Loaders

Skeletons feel faster than spinners. Used right, they preview the content shape and reduce perceived wait.

When to use skeleton vs spinner

Load time	Pattern
< 200ms	None (avoid flash)
200-500ms	Spinner
500ms - 3s	Skeleton
3s+	Skeleton + progress indicator

Skeleton anatomy

A skeleton is a low-fidelity placeholder that matches the final content:

• Rectangles for text (vary height to match font-size)
• Circles for avatars
• Match approximate widths (don't make all rectangles 100% wide)
• Use the surface-elevated color, not a different color

Shimmer animation

Subtle moving gradient that signals "loading":

.skeleton {
  background: linear-gradient(90deg,
    rgba(255,255,255,0.03) 0%,
    rgba(255,255,255,0.08) 50%,
    rgba(255,255,255,0.03) 100%);
  background-size: 200% 100%;
  animation: shimmer 1.5s ease-in-out infinite;
}
@keyframes shimmer {
  0% { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}

How many skeleton items

For lists: 3-5 skeleton rows. More creates noise. For cards: 3-6 skeleton cards in a grid. For tables: 5-8 skeleton rows with cell-matched widths.

Skeleton vs blurred preview

For images: blurred low-res preview (BlurHash) is better than a skeleton rectangle. Shows the content shape while it loads.

When NOT to skeleton

• < 200ms loads (flashes in/out, feels broken)
• Initial app shell (use spinner; user expects it)
• Static content (no async; just show it)
• Error / empty states (skeleton implies "coming" — wrong if it's not)

Common mistakes

• Skeleton that doesn't match content shape (all rectangles 100% wide for paragraphs of varying length)
• Shimmer animation too fast (jittery) or too slow (3s+, ignored)
• Skeleton for sub-200ms loads (flash)
• Skeleton stays after content loads (forgot to remove)
• Different color than the actual surface (looks broken)

Where this fits in X3 Compass

X3 Compass uses skeleton on dashboard tile fetches (200-1000ms typical), skeleton table rows on drivers page, spinner-only for AI response wait (>200ms).