Skip to main content

Loading States

Loading states should be subtle and calm, indicating progress without creating anxiety or distraction.

Loading Indicators​

Circular Progress Indicator​

Use for:

  • Full-page loads
  • Modal/overlay loads
  • Button states during async actions

Specifications:

  • Size: 24–32 pt for inline, 40–48 pt for full-page
  • Color: Teal Edge (#4BB4C8) or Amber Star (#FFC857)
  • Style: Indeterminate (spinning) for unknown duration
  • Center in available space

Linear Progress Indicator​

Use for:

  • File uploads
  • Multi-step processes
  • Known progress percentages

Specifications:

  • Height: 4 pt
  • Color: Teal Edge (#4BB4C8)
  • Background: Border color (#E0D7C8)
  • Full width of container

Skeleton Screens​

For content-heavy pages, use skeleton screens instead of spinners:

Card Skeletons​

Mimic the layout of actual cards with placeholder shapes:

  • Container: Same dimensions as real card (white background, 12pt radius)
  • Shapes: Gray rectangles representing text lines and images
  • Color: Light gray (#E8E8E8) with subtle shimmer animation
  • Spacing: Match real card spacing

Book List Skeleton​

  • Book cover placeholder: Rectangle with aspect ratio of book cover
  • Title placeholder: 2 lines of varying widths
  • Author placeholder: 1 line, narrower than title
  • Spacing matches real book list tiles

Feed Skeleton​

  • User avatar placeholder: Circle
  • Name/heading placeholder: 1–2 lines
  • Body text placeholder: 3–4 lines
  • Spacing matches real feed cards

Animation​

Shimmer Effect​

  • Subtle left-to-right shimmer on skeleton shapes
  • Duration: 1.5–2 seconds per cycle
  • Gradient: Light gray to slightly lighter gray
  • Continuous loop

Fade-In​

When real content loads:

  • Fade out skeleton
  • Fade in real content
  • Duration: 200–300ms
  • Smooth transition to avoid jarring changes

Button Loading States​

When a button triggers an async action:

Option 1: Disabled with Spinner​

  • Disable button (reduce opacity to 60%)
  • Replace text with small circular spinner
  • Same size and color as original button

Option 2: Inline Spinner​

  • Keep button text visible
  • Add small spinner to left or right of text
  • Maintain button dimensions

Error States​

If loading fails:

  • Replace loading indicator with error message
  • Use Error color (#C44545) for icon/text
  • Provide retry action when appropriate
  • Keep error messages concise and helpful

Guidelines​

  • Prefer skeleton screens for content-heavy pages (lists, feeds)
  • Use simple spinners for quick operations (under 2 seconds)
  • Avoid multiple simultaneous loading indicators
  • Match skeleton layout to actual content layout
  • Keep animations subtle and calm
  • No emoji in loading or error messages

Implementation Notes​

  • Use platform-native progress indicators when possible
  • Ensure loading states are accessible (announce to screen readers)
  • Consider using shimmer package for skeleton screens in Flutter