playbooks

home / skills / shipshitdev / library / ai-loading-ux

ai-loading-ux skill

/bundles/frontend/skills/ai-loading-ux

This skill designs AI loading UX patterns to reduce perceived wait time and boost user trust during thinking, progress, and streaming states.

This is most likely a fork of the ai-loading-ux skill from rohunvora
npx playbooks add skill shipshitdev/library --skill ai-loading-ux

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
4.5 KB
---
name: ai-loading-ux
description: Design AI loading, thinking, and progress indicator UX. Use when explicitly asked to improve AI waiting states, add thinking indicators, or design loading UX for AI interfaces. Covers reasoning display (chain-of-thought), progress steps, streaming states, and the "elevator mirror effect" for reducing perceived wait time.
---

# AI Loading UX

Design patterns for showing users what's happening while waiting for AI output.

## Decision Framework

First, identify which pattern category applies:

| User is waiting for... | Pattern Category | Key Goal |
|------------------------|------------------|----------|
| AI reasoning/thinking | **Reasoning Display** | Build trust through transparency |
| Multi-step task completion | **Progress Steps** | Show advancement toward goal |
| Content generation/streaming | **Streaming States** | Reduce perceived wait time |
| Background processing | **Status Indicators** | Confirm work is happening |

## Core Principles

### 1. The Elevator Mirror Effect

Users waiting for AI feel time pass slower. Give them something to watch/read—animated indicators reduce *perceived* wait time even when actual time is unchanged.

### 2. Progressive Disclosure

- Show condensed indicator by default ("Thinking...")
- Make details *available* but not forced
- Let curious users expand; don't burden everyone

### 3. More Transparency ≠ Better UX

Balance visibility with cognitive load. Users want answers, not reasoning—but they want to *trust* the answer came from good reasoning.

### 4. Signal Completion Clearly

Users must know when processing ends. Ambiguous end states frustrate users.

## Pattern Quick Reference

### Reasoning Display (Chain-of-Thought)

When AI is "thinking" through a problem. See [references/reasoning-patterns.md](references/reasoning-patterns.md).

**Best approach (Claude-style):**

- Hidden by default, expandable on demand
- Structured bullets when expanded
- Time counter or progress indicator
- Clear "done" state

**Anti-patterns:**

- Wall of streaming text (overwhelming)
- Scrolling too fast to read
- No expand option (feels opaque)
- No clear end state

### Progress Steps

When AI completes sequential tasks. See [references/progress-patterns.md](references/progress-patterns.md).

**Best approach:**

- Show current step + total steps
- Mark completed steps visually
- Show what's actively happening
- Allow step-level details on expand

### Streaming States

When content generates token-by-token. See [references/streaming-patterns.md](references/streaming-patterns.md).

**Best approach:**

- Typing cursor or text animation
- Smooth token appearance (not jarring)
- Skeleton for expected content shape
- "Stop generating" escape hatch

### Status Indicators

When background work happens. See [references/status-patterns.md](references/status-patterns.md).

**Best approach:**

- Subtle but visible animation
- Brief description of current action
- Don't block user from other actions
- Notify on completion

## Implementation Checklist

When implementing any AI loading state:

1. [ ] **Identify pattern category** from decision framework above
2. [ ] **Choose visibility level**: always visible, expandable, or minimal
3. [ ] **Add motion**: animation reduces perceived wait (but keep it subtle)
4. [ ] **Show progress**: time elapsed, steps completed, or content streamed
5. [ ] **Signal completion**: clear visual/state change when done
6. [ ] **Provide escape**: stop/cancel for long operations
7. [ ] **Handle errors**: don't leave user in permanent loading state
8. [ ] **Test on slow connections**: ensure graceful degradation

## Product Comparisons (Reference)

| Product | Approach | Strength | Weakness |
|---------|----------|----------|----------|
| Claude | Hidden reasoning, expandable, structured bullets | Low cognitive load | Can feel opaque |
| ChatGPT | Brief labels, auto-collapse | Unobtrusive | Less transparent |
| DeepSeek | Full streaming reasoning | Maximum transparency | Overwhelming |
| Gemini | User-scrolled, numbered steps | Clear structure | Unclear completion |

## Usage

Read the relevant reference file for your pattern category:

- [references/reasoning-patterns.md](references/reasoning-patterns.md) - Chain-of-thought, thinking indicators
- [references/progress-patterns.md](references/progress-patterns.md) - Step sequences, task completion
- [references/streaming-patterns.md](references/streaming-patterns.md) - Token streaming, content generation
- [references/status-patterns.md](references/status-patterns.md) - Background processing, polling states

Overview

This skill designs AI loading, thinking, and progress indicator UX to make waiting states clear, trustworthy, and less frustrating. It provides patterns for reasoning displays, progress steps, streaming states, and subtle status indicators, plus a practical checklist for implementation. Use it to improve perceived wait time, communicate work-in-progress, and signal completion cleanly.

How this skill works

The skill helps you choose the right pattern from a decision framework based on what the user is waiting for (reasoning, multi-step tasks, streaming output, or background processing). It prescribes visibility rules (hidden, minimal, or expandable), motion and progress signals, error and completion handling, and escape controls like cancel or stop. It bundles concrete UI behavior recommendations (e.g., structured bullets for chain-of-thought, step counters, typing cursors, skeletons) and a short implementation checklist.

When to use it

  • When users wait for AI reasoning and you need to build trust without overloading them
  • When an AI task completes multiple sequential steps and progress needs to be visible
  • When large content is generated token-by-token and perceived latency should be reduced
  • When background processing runs and users need confirmation that work is ongoing
  • When you want to provide an expandable view of internal reasoning without forcing it on everyone

Best practices

  • Apply the elevator mirror effect: add subtle animation or readable content to reduce perceived wait time
  • Default to minimal indicators and make reasoning or step details expandable on demand
  • Show clear progress—elapsed time, step counts, or streaming tokens—and mark a distinct done state
  • Provide an explicit escape (cancel/stop) and robust error states to avoid permanent loading
  • Avoid streaming raw chain-of-thought by default; use structured bullets when expanded
  • Test loading UX on slow and unreliable connections to ensure graceful degradation

Example use cases

  • Show a compact "Thinking..." label with an expandable structured reasoning panel for complex answers
  • Display step X of Y with checked completed steps and a detail drawer for long-running workflows
  • Render smooth token-by-token text with a typing cursor and a "Stop generating" control for content creation
  • Use a subtle spinner plus short action text for background syncing that doesn’t block the UI
  • Expose a time counter or progress bar for operations with predictable duration to manage expectations

FAQ

Should I always show chain-of-thought to users?

No. Hide reasoning by default and make it expandable: most users want answers, but some benefit from seeing the reasoning for trust or debugging.

How do I avoid overwhelming users with streamed reasoning?

Smooth token appearance, structured bullets when expanded, and an option to collapse prevent information overload; never auto-scroll fast streams that outpace reading speed.