Skip to content

ericrisco/rsc-harness / skills/ux

Use when an app or SaaS must be easy to use: designing complete user flows, screens and every state, navigation, forms, onboarding, tables, dashboards, search or AI features, or auditing usability and accessibility. Anyone finishes the job without a manual; experts go fast. NOT the visual direction (design), NOT the words (landing-copy).

FileKindSize
SKILL.mdskill md9.3 KB
THIRD_PARTY.mdmarkdown1.6 KB
evals/cases.yamlconfig2.5 KB
references/flows.mdmarkdown7.3 KB
upstream/UPSTREAM.jsonconfig4.7 KB
upstream/ux-designer/GUIDE.mdmarkdown15.2 KB
upstream/ux-designer/LICENSEother1.0 KB
upstream/ux-designer/references/01-core-principles.mdmarkdown7.9 KB
upstream/ux-designer/references/02-laws-of-ux.mdmarkdown8.3 KB
upstream/ux-designer/references/03-accessibility.mdmarkdown10.7 KB
upstream/ux-designer/references/04-visual-design.mdmarkdown8.9 KB
upstream/ux-designer/references/05-information-architecture.mdmarkdown9.1 KB
upstream/ux-designer/references/06-interaction-design.mdmarkdown11.2 KB
upstream/ux-designer/references/07-forms-and-inputs.mdmarkdown11.4 KB
upstream/ux-designer/references/08-mobile-ux.mdmarkdown10.9 KB
upstream/ux-designer/references/09-ux-writing.mdmarkdown9.0 KB
upstream/ux-designer/references/10-user-research.mdmarkdown10.6 KB
upstream/ux-designer/references/11-design-systems.mdmarkdown13.2 KB
upstream/ux-designer/references/12a-presence-awareness.mdmarkdown10.2 KB
upstream/ux-designer/references/12b-conflict-resolution-sync.mdmarkdown15.8 KB
upstream/ux-designer/references/13a-canvas-navigation.mdmarkdown9.5 KB
upstream/ux-designer/references/13b-canvas-objects-performance.mdmarkdown14.2 KB
upstream/ux-designer/references/14-ai-ux-patterns.mdmarkdown20.9 KB
upstream/ux-designer/references/15-ethical-design.mdmarkdown13.9 KB
upstream/ux-designer/references/16-onboarding.mdmarkdown16.5 KB
upstream/ux-designer/references/17-notifications.mdmarkdown17.7 KB
upstream/ux-designer/references/18-data-visualization.mdmarkdown18.8 KB
upstream/ux-designer/references/19-search-ux.mdmarkdown19.0 KB
upstream/ux-designer/references/20-emotional-design.mdmarkdown14.5 KB
upstream/ux-designer/references/21-data-tables.mdmarkdown20.5 KB
upstream/ux-designer/references/22-performance-ux.mdmarkdown17.5 KB
upstream/ux-designer/references/23-internationalization.mdmarkdown15.4 KB
upstream/ux-designer/references/24-voice-and-multimodal.mdmarkdown15.9 KB
upstream/ux-designer/references/25a-barcode-camera-scanning.mdmarkdown21.3 KB
upstream/ux-designer/references/25b-barcode-scanner-workflows.mdmarkdown25.3 KB
upstream/ux-designer/references/25c-barcode-display.mdmarkdown17.3 KB
upstream/ux-usability-foundations/GUIDE.mdmarkdown16.0 KB
upstream/ux-usability-foundations/LICENSEother1.0 KB
upstream/ux-usability-foundations/references/anti-patterns.mdmarkdown8.3 KB
upstream/ux-usability-foundations/references/checklists.mdmarkdown6.2 KB
upstream/ux-usability-foundations/references/decision-prompts.mdmarkdown10.0 KB
upstream/ux-usability-foundations/references/principle-cards.mdmarkdown15.4 KB

upstream/ux-designer/references/22-performance-ux.md

View on GitHub
# Performance & Loading UX

Perceived performance is often more important than actual performance. Users judge an app's speed not by stopwatch measurements but by how fast it *feels*. This reference covers techniques for making interfaces feel instant, responsive, and reliable.

---

## Contents

- Perceived Performance
- Loading Indicator Decision Tree
- Skeleton Screens
- Optimistic Updates
- Progress Indicators
- Image Loading Strategies
- Content Layout Shift Prevention
- Offline-First & Cached State UX
- Prefetching & Preloading
- Key Metrics
- Anti-Patterns
- Sources

---

## Perceived Performance

### Response Time Thresholds

| Duration | Perception | UX Treatment |
|----------|-----------|--------------|
| < 100ms | Instant | No indicator needed |
| 100-300ms | Slight delay | Subtle state change (button press) |
| 300ms-1s | Noticeable | Show spinner or progress hint |
| 1-5s | Waiting | Skeleton screen or progress bar |
| 5-10s | Frustrated | Progress bar with estimate + cancel |
| > 10s | Abandonment risk | Progress steps, background processing option |

### Techniques for Feeling Fast

1. **Optimistic updates** — Apply changes immediately, sync later
2. **Skeleton screens** — Show content shape before data arrives
3. **Progressive loading** — Show most important content first
4. **Prefetching** — Load likely-next content before user requests it
5. **Instant navigation** — Use client-side routing with prefetch
6. **Animation as distraction** — Meaningful transitions mask load time

---

## Loading Indicator Decision Tree

```
How long will the operation take?
├── < 100ms (instant)?
│   └── → No indicator (just update the UI)
├── 100ms - 1s (brief)?
│   ├── User triggered the action?
│   │   └── → Button loading state (spinner replaces label or inline spinner)
│   └── Background/automatic?
│       └── → No indicator (avoid flicker)
├── 1s - 5s (noticeable)?
│   ├── Loading content for a region/page?
│   │   └── → Skeleton screen (matches target layout)
│   ├── Processing user action?
│   │   └── → Inline spinner with status text ("Saving...")
│   └── Unknown duration?
│       └── → Indeterminate progress bar
├── 5s - 30s (long)?
│   ├── Duration is predictable?
│   │   └── → Determinate progress bar with percentage
│   └── Duration is unpredictable?
│       └── → Indeterminate progress with stage labels
└── > 30s (very long)?
    └── → Background task with notification on completion
        ("We'll email you when your export is ready")
```

---

## Skeleton Screens

Skeleton screens show a low-fidelity preview of the content layout before data loads. They reduce perceived wait time and prevent layout shifts.

### Basic Skeleton

```css
.skeleton {
  background: #e5e7eb;
  border-radius: 4px;
  position: relative;
  overflow: hidden;
}

/* Shimmer animation */
.skeleton::after {
  content: '';
  position: absolute;
  inset: 0;
  background: linear-gradient(
    90deg,
    transparent 0%,
    rgba(255, 255, 255, 0.4) 50%,
    transparent 100%
  );
  animation: skeleton-shimmer 1.5s infinite;
}

@keyframes skeleton-shimmer {
  0% { transform: translateX(-100%); }
  100% { transform: translateX(100%); }
}
```

### Skeleton Variants

```html
<!-- Text skeleton -->
<div class="skeleton skeleton--text" style="width: 80%; height: 16px;"></div>
<div class="skeleton skeleton--text" style="width: 60%; height: 16px;"></div>

<!-- Avatar skeleton -->
<div class="skeleton skeleton--circle" style="width: 40px; height: 40px;"></div>

<!-- Image skeleton -->
<div class="skeleton skeleton--image" style="width: 100%; aspect-ratio: 16/9;"></div>

<!-- Card skeleton -->
<div class="skeleton-card">
  <div class="skeleton skeleton--image" style="height: 200px;"></div>
  <div style="padding: 16px;">
    <div class="skeleton skeleton--text" style="width: 70%; height: 20px;"></div>
    <div class="skeleton skeleton--text" style="width: 100%; height: 14px; margin-top: 8px;"></div>
    <div class="skeleton skeleton--text" style="width: 40%; height: 14px; margin-top: 8px;"></div>
  </div>
</div>
```

### Skeleton Best Practices

| Do | Don't |
|----|-------|
| Match the actual content layout | Use generic shapes unrelated to content |
| Use subtle animation (shimmer) | Use pulsing that draws too much attention |
| Show for > 300ms loads | Show for instant loads (causes flicker) |
| Transition smoothly to real content | Pop content in abruptly |
| Keep skeleton visible while data loads | Replace skeleton with spinner |

### Skeleton Transition

```javascript
function showContent(container, data) {
  const skeleton = container.querySelector('.skeleton-wrapper');
  const content = container.querySelector('.content-wrapper');

  // Populate content using safe DOM methods (e.g., textContent,
  // createElement, or a framework's reactive rendering)
  renderDataToDOM(content, data);

  // Cross-fade transition
  skeleton.style.opacity = '0';
  content.style.opacity = '1';

  setTimeout(() => skeleton.remove(), 300);
}
```

```css
.skeleton-wrapper,
.content-wrapper {
  transition: opacity 300ms ease;
}

.content-wrapper {
  opacity: 0;
}
```

---

## Optimistic Updates

Apply changes to the UI immediately before server confirmation, then reconcile.

### Pattern

```javascript
async function toggleFavorite(itemId) {
  // 1. Optimistic: update UI immediately
  const previousState = getItem(itemId).isFavorite;
  updateItemUI(itemId, { isFavorite: !previousState });

  try {
    // 2. Send to server
    await api.toggleFavorite(itemId);
    // Success: UI already correct, nothing to do
  } catch (error) {
    // 3. Rollback on failure
    updateItemUI(itemId, { isFavorite: previousState });
    showToast('Failed to update. Please try again.', { type: 'error' });
  }
}
```

### When to Use Optimistic Updates

| Use Optimistic | Don't Use |
|---------------|-----------|
| Toggles (like, favorite, bookmark) | Financial transactions |
| Status changes (read/unread) | Destructive actions (delete) |
| Form field auto-save | Multi-step workflows |
| Reordering lists | Actions requiring server validation |
| Adding/removing tags | External system integrations |

### Optimistic Update UX Requirements

- Always have a rollback path
- Show subtle "saving" indicator (not blocking)
- On failure: revert UI + show clear error message
- On conflict: show resolution UI (merge dialog)
- Debounce rapid changes (typing, slider adjustments)

---

## Progress Indicators

### Indeterminate Progress

For operations where duration is unknown.

```css
/* Indeterminate progress bar */
.progress-bar--indeterminate {
  height: 4px;
  background: #e5e7eb;
  border-radius: 2px;
  overflow: hidden;
}

.progress-bar--indeterminate::after {
  content: '';
  display: block;
  height: 100%;
  width: 40%;
  background: #3b82f6;
  border-radius: 2px;
  animation: indeterminate 1.5s infinite ease-in-out;
}

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

### Determinate Progress

For operations where progress can be measured.

```html
<div class="progress-container">
  <div class="progress-bar" role="progressbar"
       aria-valuenow="65" aria-valuemin="0" aria-valuemax="100">
    <div class="progress-bar__fill" style="width: 65%"></div>
  </div>
  <span class="progress-label">65% — Uploading 3 of 5 files</span>
</div>
```

### Multi-Step Progress

```
┌──────────────────────────────────────────────────────────────┐
│ Importing data...                                            │
│                                                              │
│ ✓ Validating file format                                     │
│ ✓ Parsing 1,234 records                                      │
│ ⟳ Importing to database (847 of 1,234)                       │
│ ○ Running post-import checks                                 │
│                                                              │
│ ████████████████████░░░░░░░░░░ 68%        [Cancel import]    │
└──────────────────────────────────────────────────────────────┘
```

### Button Loading States

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

.btn--loading::after {
  content: '';
  position: absolute;
  width: 16px;
  height: 16px;
  top: 50%;
  left: 50%;
  margin: -8px 0 0 -8px;
  border: 2px solid rgba(255, 255, 255, 0.3);
  border-top-color: white;
  border-radius: 50%;
  animation: button-spin 0.6s linear infinite;
}

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

**Button loading best practices:**
- Disable the button to prevent double-submit
- Keep button dimensions constant (no layout shift)
- Show spinner inside the button, not replacing it
- Optionally change label: "Save" → "Saving..."

---

## Image Loading Strategies

### Lazy Loading

Only load images when they enter (or approach) the viewport.

```html
<!-- Native lazy loading -->
<img src="photo.jpg" loading="lazy" alt="Description"
     width="800" height="600">
```

### Blur-Up / LQIP (Low Quality Image Placeholder)

Show a tiny, blurred preview that transitions to the full image.

```html
<div class="image-wrapper">
  <img class="image-placeholder" src="photo-20px.jpg"
       style="filter: blur(20px); transform: scale(1.1);"
       aria-hidden="true">
  <img class="image-full" src="photo-800px.jpg" loading="lazy"
       alt="Description"
       onload="this.classList.add('loaded')">
</div>
```

```css
.image-wrapper {
  position: relative;
  overflow: hidden;
}

.image-placeholder {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  object-fit: cover;
}

.image-full {
  opacity: 0;
  transition: opacity 300ms ease;
}

.image-full.loaded {
  opacity: 1;
}
```

### Responsive Images

```html
<img
  srcset="photo-400w.jpg 400w,
          photo-800w.jpg 800w,
          photo-1200w.jpg 1200w"
  sizes="(max-width: 600px) 400px,
         (max-width: 1000px) 800px,
         1200px"
  src="photo-800w.jpg"
  alt="Description"
  loading="lazy"
>
```

### Image Loading Decision Tree

```
What type of image is it?
├── Above the fold (hero, logo, critical UI)?
│   └── → Eager load, preload via <link>, use srcset
├── Below the fold (content images)?
│   └── → loading="lazy", use LQIP/blur-up for large images
├── Thumbnail in a list/grid?
│   └── → loading="lazy", fixed dimensions, skeleton placeholder
├── Background/decorative?
│   └── → CSS background with lazy class, low priority
└── User avatar?
    └── → Eager load if visible, fixed dimensions, fallback initial
```

---

## Content Layout Shift Prevention

Layout shifts are disorienting and frustrating. They happen when content dimensions change after initial render.

### Core Web Vitals: CLS

- **Good:** CLS < 0.1
- **Needs improvement:** 0.1 - 0.25
- **Poor:** CLS > 0.25

### Prevention Techniques

#### Reserve Space for Images

```css
/* Always specify dimensions */
img {
  width: 100%;
  height: auto;
  aspect-ratio: 16 / 9; /* Reserve space before load */
}

/* Container with aspect ratio */
.image-container {
  position: relative;
  width: 100%;
  aspect-ratio: 4 / 3;
  background: #f3f4f6;
}
```

#### Reserve Space for Fonts

```css
/* Use font-display to control FOIT/FOUT */
@font-face {
  font-family: 'CustomFont';
  src: url('font.woff2') format('woff2');
  font-display: swap; /* Show fallback immediately, swap when loaded */
}

/* Match fallback font metrics to reduce shift */
body {
  font-family: 'CustomFont', system-ui, sans-serif;
  font-size-adjust: 0.5; /* Normalize x-height */
}
```

#### Reserve Space for Dynamic Content

```css
/* Fixed-height containers for dynamic content */
.ad-slot {
  min-height: 250px;
  background: #f3f4f6;
}

.notification-area {
  min-height: 0;
  transition: min-height 300ms ease; /* Smooth expansion */
}
```

#### Avoid CLS-Causing Patterns

| Pattern | Problem | Solution |
|---------|---------|----------|
| Images without dimensions | Jump when loaded | Always set width/height or aspect-ratio |
| Injected content above viewport | Pushes content down | Insert below or use overlay |
| Web fonts without fallback | Text reflows | Use font-display: swap + size-adjust |
| Dynamic ads/banners | Layout shift on load | Reserve fixed space |
| Late-loading components | Layout reflowing | Use skeleton placeholders |

---

## Offline-First & Cached State UX

### Connection Status

```css
/* Offline indicator */
.offline-banner {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  padding: 8px 16px;
  background: #fef3c7;
  color: #92400e;
  text-align: center;
  font-size: 14px;
  z-index: 9999;
  transform: translateY(100%);
  transition: transform 300ms ease;
}

.offline-banner--visible {
  transform: translateY(0);
}
```

### Stale Content Indicators

```html
<div class="stale-notice">
  <span>Last updated 5 minutes ago</span>
  <button class="refresh-btn">Refresh</button>
</div>
```

**Stale data guidelines:**
- Show "last updated" timestamp for cached data
- Provide manual refresh option
- Auto-refresh when connection restores
- Differentiate between "cached" and "live" data visually
- Never silently show outdated data as if it were current

### Offline-Capable Actions

| Action Type | Offline Behavior |
|-------------|-----------------|
| Read cached data | Show with "offline" indicator |
| Create new items | Queue locally, sync when online |
| Edit existing items | Queue changes, show "pending sync" |
| Delete items | Mark as "pending delete", hide from view |
| Search | Search local cache only, note limitation |

### Sync Status Indicators

```
┌──────────────────────────────────────────┐
│ ✓ All changes saved                      │  — Everything synced
│ ⟳ Saving...                              │  — Sync in progress
│ ⚠ Offline — changes will sync later      │  — Queued changes
│ ✕ Save failed — click to retry           │  — Error state
└──────────────────────────────────────────┘
```

---

## Prefetching & Preloading

### Link Prefetching

```html
<!-- Prefetch likely next pages -->
<link rel="prefetch" href="/dashboard">
<link rel="prefetch" href="/api/user-data.json">

<!-- Preload critical resources -->
<link rel="preload" href="/fonts/main.woff2" as="font" type="font/woff2" crossorigin>
<link rel="preload" href="/hero.jpg" as="image">
```

### Hover Prefetch

```javascript
// Prefetch on hover (before click)
document.querySelectorAll('a[data-prefetch]').forEach(link => {
  let prefetched = false;

  link.addEventListener('mouseenter', () => {
    if (prefetched) return;
    prefetched = true;

    const prefetchLink = document.createElement('link');
    prefetchLink.rel = 'prefetch';
    prefetchLink.href = link.href;
    document.head.appendChild(prefetchLink);
  });
});
```

### Prefetch Strategy Decision

| Signal | Action |
|--------|--------|
| User hovers over link | Prefetch page |
| User types in search | Prefetch top results |
| User reaches 80% of list | Prefetch next page |
| User is on step 2 of 4 | Prefetch step 3 resources |
| Viewport approaches lazy content | Prefetch images |

---

## Key Metrics

| Metric | Value | Context |
|--------|-------|---------|
| Instant response | < 100ms | No loading indicator needed |
| Skeleton threshold | > 300ms | Show skeleton after this delay |
| Toast error display | >= 5s | Longer than success toasts |
| CLS target | < 0.1 | Core Web Vitals "good" |
| LCP target | < 2.5s | Largest Contentful Paint |
| FID target | < 100ms | First Input Delay |
| INP target | < 200ms | Interaction to Next Paint |
| Optimistic rollback | < 5s | Show error if no confirmation |
| Prefetch hover delay | 65ms | Wait before prefetching |

---

## Anti-Patterns

1. **Spinner for everything** - Use skeletons for content, spinners for actions
2. **Full-page loader** - Block only the region that's loading, not the whole page
3. **No minimum display time** - Skeleton that flashes for 50ms is worse than nothing
4. **Layout shifts on load** - Always reserve space for async content
5. **Silent failures** - User doesn't know their action failed
6. **Optimistic without rollback** - Showing success then silently losing data
7. **Blocking UI during save** - Use background save with status indicator
8. **No offline indication** - Users assume they're connected
9. **Stale data shown as current** - Always indicate data freshness
10. **Retry without feedback** - Show what's happening during retry attempts

---

## Sources

- [web.dev - Core Web Vitals](https://web.dev/vitals/) - Google's performance metrics
- [web.dev - Optimize CLS](https://web.dev/optimize-cls/) - Layout shift prevention
- [Nielsen Norman Group - Response Times](https://www.nngroup.com/articles/response-times-3-important-limits/) - Perception thresholds
- [Smashing Magazine - Skeleton Screens](https://www.smashingmagazine.com/2020/04/skeleton-screens-react/) - Implementation patterns
- [Luke Wroblewski - Mobile Input](https://www.lukew.com/ff/entry.asp?1950) - Perceived performance research
- [Instant.page](https://instant.page/) - Prefetch on hover library
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall