When Skeletons Beat Spinners (Product)

The rule: skeletons work for known-shape content. A user profile always has an avatar, a name, and a bio — three elements, same every time. A skeleton for that is an accurate prediction. A feed with variable item counts, search with variable results, or any list that might return empty are unknown-shape content. Use a spinner.

// ❌ Skeleton for unknown-count results
function SearchResults({ query }) {
  if (isLoading) return <SkeletonCards count={4} />; // wrong if results ≠ 4
  if (results.length === 0) return <EmptyState />;
  return results.map(r => <ResultCard key={r.id} {...r} />);
}

// ✅ Spinner for unknown-count results
function SearchResults({ query }) {
  if (isLoading) return <Spinner label="Searching…" />;
  if (results.length === 0) return <EmptyState />;
  return results.map(r => <ResultCard key={r.id} {...r} />);
}

// ✅ Skeleton for known-shape profile
function UserProfile({ userId }) {
  if (isLoading) return <ProfileSkeleton />; // always: avatar + name + bio
  return <Profile user={user} />;
}

The 200ms delay rule applies to both: don't flash any indicator for loads under 200ms. A short flash is more distracting than no indicator at all.

The skeleton was the wrong tool because the content shape was not known in advance. Five-column shimmer suggested five columns of content; three radio options produced one compact row. Any skeleton that does not precisely match the actual rendered content causes a layout prediction violation — which the brain perceives as a visual jolt more disruptive than a spinner, whose resolution shape is unpredictable by design. A spinner carries no shape prediction; a skeleton carries an explicit one. Wrong predictions are worse than no predictions.

The discipline required is to categorise loading states before choosing an indicator. User profile: known shape (avatar, name, bio), predictable count (1), likely over 600ms on first load — skeleton is correct. Search results: unknown count, may be empty, shape depends on result type — spinner is correct. Form submit: immediate feedback needed, no content shape to predict — button loading state (spinner within the button) is correct. Applying these categories consistently prevents the settings-panel failure mode from recurring.

Now click the "Empty results" variant. The skeleton mode shows four cards, then collapses to an empty state — the prediction is wrong. The spinner mode goes directly from spinning to empty state. Which feels more correct?

The skeleton shimmer animation should use background: linear-gradient animated with a CSS @keyframes that shifts the gradient position. The shimmer direction should match reading direction (left to right in LTR). Use animation-timing-function: ease-in-out and a 1.4–1.8s duration — faster shimmer feels erratic; slower feels static.

/* Skeleton shimmer — accessible, performant */
@keyframes shimmer {
  from { background-position: -200px 0; }
  to   { background-position: calc(200px + 100%) 0; }
}

.skeleton {
  background: linear-gradient(
    90deg,
    var(--color-surface-2) 25%,
    var(--color-surface-3) 50%,
    var(--color-surface-2) 75%
  );
  background-size: 400px 100%;
  border-radius: 4px;
}

@media (prefers-reduced-motion: no-preference) {
  .skeleton { animation: shimmer 1.6s ease-in-out infinite; }
}
/* No animation in reduced-motion mode — static skeleton is fine */