PixelPilot uiux-loading-storytelling.instructions.md

Loading State Storytelling

Users will wait. Make it worth their while. This file covers progress narratives, skeleton animations, entertaining loaders, and techniques that make loading feel faster — even when it isn't.

---

CRITICAL RULES

1. Always show progress — Unknown waits feel 3x longer than known waits.
2. Be honest — Fake progress bars destroy trust when they stall at 99%.
3. Respect reduced motion — Animated loaders need static alternatives.
4. Performance — Loaders shouldn't be heavier than the content.
5. Accessible — Screen readers should announce loading states.

---

PSYCHOLOGY OF WAITING

Technique	Effect
Show progress	Feels faster
Explain what's happening	Builds trust
Entertain	Distracts from wait
Let users do something	Active waiting feels shorter
Show remaining time	Sets expectations

Rule: An 8-second wait with progress feels shorter than a 4-second wait without.

---

PROGRESS NARRATIVES

Tell users what's happening, step by step:

// ProgressNarrative.tsx
interface NarrativeStep {
  message: string;
  duration: number;  // Estimated ms
  icon?: string;
}

const uploadSteps: NarrativeStep[] = [
  { message: 'Preparing your files...', duration: 1000, icon: '📁' },
  { message: 'Encrypting for security...', duration: 2000, icon: '🔐' },
  { message: 'Uploading to cloud...', duration: 5000, icon: '☁️' },
  { message: 'Verifying integrity...', duration: 1500, icon: '✅' },
  { message: 'Almost there...', duration: 500, icon: '🎉' },
];

export function ProgressNarrative({ 
  steps, 
  onComplete 
}: { 
  steps: NarrativeStep[];
  onComplete: () => void;
}) {
  const [currentStep, setCurrentStep] = useState(0);
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    if (currentStep >= steps.length) {
      onComplete();
      return;
    }

    const step = steps[currentStep];
    const interval = 50; // Update every 50ms
    const increment = 100 / (step.duration / interval);

    let stepProgress = 0;
    const timer = setInterval(() => {
      stepProgress += increment;
      
      // Calculate total progress
      const completedProgress = (currentStep / steps.length) * 100;
      const currentProgress = (stepProgress / 100) * (100 / steps.length);
      setProgress(completedProgress + currentProgress);

      if (stepProgress >= 100) {
        clearInterval(timer);
        setCurrentStep(prev => prev + 1);
      }
    }, interval);

    return () => clearInterval(timer);
  }, [currentStep, steps, onComplete]);

  const step = steps[Math.min(currentStep, steps.length - 1)];

  return (
    <div className="progress-narrative" role="status" aria-live="polite">
      <div className="progress-narrative__icon" aria-hidden="true">
        {step.icon}
      </div>
      
      <p className="progress-narrative__message">
        {step.message}
      </p>
      
      <div className="progress-narrative__bar">
        <div 
          className="progress-narrative__fill"
          style={{ width: `${progress}%` }}
          role="progressbar"
          aria-valuenow={Math.round(progress)}
          aria-valuemin={0}
          aria-valuemax={100}
        />
      </div>
      
      <span className="progress-narrative__percent">
        {Math.round(progress)}%
      </span>
    </div>
  );
}