Agent skill

loading-states

Design effective loading states, skeleton screens, and empty states that maintain user confidence. Use when content takes time to load, when showing progress, or handling empty data scenarios. Triggers on "loading state", "skeleton screen", "empty state", "spinner", "progress bar", "loading animation", "zero state".

View SKILL.md on GitHub Repository
Stars 20
Forks 4

Install this agent skill to your Project

npx add-skill https://github.com/sanky369/vibe-building-skills/tree/main/skills/frontend-design/loading-states

SKILL.md

Loading & Empty States

Maintain user confidence when content isn't immediately available.

Loading State Types

Choose by Duration

Duration Recommendation
< 100ms No indicator needed
100ms - 1s Subtle indicator (opacity change)
1s - 10s Skeleton screen or spinner
> 10s Progress bar with estimate

Skeleton Screens

When to Use

  • Page or section content loading
  • Lists, cards, tables
  • Better than spinners for known layouts

Basic Skeleton

css
.skeleton {
  background: #e5e7eb;
  border-radius: 4px;
}

/* Animated shimmer */
.skeleton-animated {
  background: linear-gradient(
    90deg,
    #f3f4f6 25%,
    #e5e7eb 50%,
    #f3f4f6 75%
  );
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
}

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

Skeleton Components

html
<!-- Text skeleton -->
<div class="skeleton skeleton-text" style="width: 80%"></div>
<div class="skeleton skeleton-text" style="width: 60%"></div>

<!-- Avatar skeleton -->
<div class="skeleton skeleton-avatar"></div>

<!-- Image skeleton -->
<div class="skeleton skeleton-image"></div>
css
.skeleton-text {
  height: 16px;
  margin-bottom: 8px;
}

.skeleton-avatar {
  width: 40px;
  height: 40px;
  border-radius: 50%;
}

.skeleton-image {
  width: 100%;
  aspect-ratio: 16/9;
}

Card Skeleton Example

html
<article class="card card-skeleton">
  <div class="skeleton skeleton-image"></div>
  <div class="card-content">
    <div class="skeleton skeleton-text" style="width: 70%"></div>
    <div class="skeleton skeleton-text" style="width: 90%"></div>
    <div class="skeleton skeleton-text" style="width: 50%"></div>
  </div>
</article>

What NOT to Skeleton

  • Modals (should be instant or loading indicator inside)
  • Toasts/notifications
  • Dropdown menus
  • The skeleton itself shouldn't have a skeleton

Spinners

When to Use

  • Unknown content structure
  • Short operations (1-3 seconds)
  • Small areas (buttons, inputs)

Simple Spinner

css
.spinner {
  width: 24px;
  height: 24px;
  border: 3px solid #e5e7eb;
  border-top-color: var(--primary);
  border-radius: 50%;
  animation: spin 0.8s linear infinite;
}

@keyframes spin {
  to { transform: rotate(360deg); }
}

Button Loading State

css
.button-loading {
  position: relative;
  color: transparent; /* Hide text */
  pointer-events: none;
}

.button-loading::after {
  content: '';
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  width: 20px;
  height: 20px;
  border: 2px solid currentColor;
  border-top-color: transparent;
  border-radius: 50%;
  animation: spin 0.6s linear infinite;
}

Inline Loading Text

html
<span class="loading-text">
  Loading
  <span class="loading-dots">
    <span>.</span><span>.</span><span>.</span>
  </span>
</span>

Progress Bars

When to Use

  • Operations > 10 seconds
  • File uploads/downloads
  • Multi-step processes

Basic Progress Bar

html
<div class="progress">
  <div
    class="progress-bar"
    role="progressbar"
    style="width: 65%"
    aria-valuenow="65"
    aria-valuemin="0"
    aria-valuemax="100"
  >
    65%
  </div>
</div>
css
.progress {
  height: 8px;
  background: #e5e7eb;
  border-radius: 4px;
  overflow: hidden;
}

.progress-bar {
  height: 100%;
  background: var(--primary);
  transition: width 0.3s ease-out;
}

Indeterminate Progress

css
.progress-indeterminate .progress-bar {
  width: 30%;
  animation: indeterminate 1.5s infinite ease-in-out;
}

@keyframes indeterminate {
  0% { transform: translateX(-100%); }
  100% { transform: translateX(400%); }
}

Empty States

Types of Empty States

  1. First Use: User hasn't added data yet
  2. No Results: Search/filter returned nothing
  3. Error State: Something went wrong
  4. Success Empty: Completed all tasks (inbox zero)

First Use Empty State

html
<div class="empty-state">
  <img src="illustration.svg" alt="" class="empty-illustration">
  <h3 class="empty-title">No projects yet</h3>
  <p class="empty-description">
    Create your first project to get started
  </p>
  <button class="button-primary">
    Create Project
  </button>
</div>

No Results Empty State

html
<div class="empty-state">
  <span class="empty-icon">🔍</span>
  <h3 class="empty-title">No results found</h3>
  <p class="empty-description">
    Try adjusting your search or filters
  </p>
  <button class="button-secondary">
    Clear Filters
  </button>
</div>

Empty State Styles

css
.empty-state {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  padding: 48px 24px;
  text-align: center;
}

.empty-illustration {
  width: 200px;
  max-width: 100%;
  margin-bottom: 24px;
}

.empty-icon {
  font-size: 48px;
  margin-bottom: 16px;
}

.empty-title {
  font-size: 20px;
  font-weight: 600;
  margin-bottom: 8px;
  color: var(--text-primary);
}

.empty-description {
  font-size: 14px;
  color: var(--text-secondary);
  max-width: 300px;
  margin-bottom: 24px;
}

Error States

html
<div class="empty-state error-state">
  <span class="empty-icon">⚠️</span>
  <h3 class="empty-title">Something went wrong</h3>
  <p class="empty-description">
    We couldn't load your data. Please try again.
  </p>
  <button class="button-primary">
    Retry
  </button>
</div>

Best Practices

Do

  • Match skeleton layout to actual content
  • Show loading state immediately (don't wait)
  • Use animations to indicate activity
  • Provide progress info when possible
  • Include helpful actions in empty states
  • Keep messaging friendly and helpful

Don't

  • Show spinners for everything
  • Use loading states for instant operations
  • Leave users without feedback
  • Make empty states feel like dead ends
  • Animate aggressively (respect motion preferences)

Accessibility

css
/* Announce loading to screen readers */
.loading-region[aria-busy="true"]::before {
  content: "Loading...";
  position: absolute;
  clip: rect(0, 0, 0, 0);
}

/* Respect reduced motion */
@media (prefers-reduced-motion: reduce) {
  .skeleton-animated {
    animation: none;
  }

  .spinner {
    animation-duration: 1.5s;
  }
}

Checklist

  • Loading appears within 100ms of action
  • Skeleton matches content structure
  • Progress shown for long operations (>10s)
  • Empty states have helpful actions
  • Error states include retry option
  • Animations respect prefers-reduced-motion
  • Screen readers announce loading state
  • Loading doesn't block entire page unnecessarily

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

sanky369/vibe-building-skills

tweet-writer

Write viral, persuasive, engaging tweets and threads. Uses web research to find viral examples in your niche, then models writing based on proven formulas and X algorithm optimization. Use when creating tweets, threads, or X content strategy.

20 4
Explore
sanky369/vibe-building-skills

direct-response-copy

Write persuasive sales copy that converts using proven direct response principles. Use when writing landing pages, sales emails, ads, or any copy designed to drive action.

20 4
Explore
sanky369/vibe-building-skills

brand-voice

Define and establish your unique brand voice with personality dimensions, voice guidelines, and consistency frameworks. Use when creating brand guidelines, ensuring messaging consistency, or developing voice standards for your organization.

20 4
Explore
sanky369/vibe-building-skills

seo-content

Create articles that rank in search engines and engage readers. Use when building organic traffic, establishing authority, or creating content that attracts your ideal customers through search.

20 4
Explore
sanky369/vibe-building-skills

newsletter

Build recurring audience touchpoints with compelling newsletters. Use when building audience loyalty, establishing authority, or creating regular engagement with your subscribers.

20 4
Explore
sanky369/vibe-building-skills

positioning-angles

Find your unique market positioning using 8 proven frameworks. Use when developing marketing strategy, creating differentiation, or clarifying why customers should choose you over competitors.

20 4
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results