aiskillstore/ux-waiting-audit

UX Waiting States Audit

Evaluate how applications handle long-running operations (30+ seconds) using browser automation.

Core Principle

Screenshot First, DOM Second — always take a screenshot when navigating or stuck. Visual inspection beats DOM probing.

📸 Screenshot → 👀 Analyze visually → 🎯 Click coordinates → 📸 Verify → Repeat

---

Critical: Screenshot-First Automation

When to Screenshot

ALWAYS screenshot:

• After opening any URL (initial state)
• Before trying to interact with elements
• When ANY JavaScript returns "missing value" or fails
• After clicking/submitting (verify success)
• At timed intervals during long operations

Why Screenshots Beat DOM Probing

| DOM Approach | Screenshot Approach | |--------------|---------------------| | Complex selectors fail silently | Visual shows exact UI state | | "missing value" gives no info | Image reveals button locations | | 10+ attempts to find element | 1 screenshot → click coordinates | | Can't see actual user experience | See exactly what user sees |

Screenshot Workflow Pattern

# 1. Navigate
Control Chrome:open_url(TARGET_URL)
sleep(2)

# 2. ALWAYS screenshot first
# Use browser screenshot or html2canvas
# Analyze the image before ANY interaction

# 3. If interaction needed, prefer coordinates over selectors
# After seeing screenshot: "The submit button is at ~(1200, 650)"
Control Chrome:execute_javascript("document.elementFromPoint(1200, 650).click()")

# 4. Screenshot again to verify

---

Quick Start Workflow

Phase 1: Setup & Navigate

# 1. Navigate to target URL
Control Chrome:open_url(TARGET_URL)
sleep(3)

# 2. SCREENSHOT - See what loaded
# Analyze: What's visible? Where are interactive elements?

# 3. Ask user to help identify:
#    - Which operation to test
#    - How to trigger it (button location, input needed)

Phase 2: Trigger Operation (The Hard Part)

This is often where audits get stuck. Modern SPAs have complex UIs.

# Strategy 1: Ask user for guidance
# "I see the page. Can you describe where the button is or what to click?"

# Strategy 2: Use simple, targeted JS
Control Chrome:execute_javascript("document.querySelector('button[type=submit]').click()")

# Strategy 3: Coordinate-based clicking (after screenshot)
Control Chrome:execute_javascript("document.elementFromPoint(X, Y).click()")

# Strategy 4: Let user trigger manually
# "Please click the button to start the operation, then tell me when it's processing"

Phase 3: Capture Waiting States

Once operation is running:

# T+0s: Screenshot immediately when operation starts
# T+10s: Screenshot after 10 seconds
sleep(10)
# Screenshot + capture_state.js

# T+30s: Screenshot after 30 seconds  
sleep(20)
# Screenshot + capture_state.js

# T+Complete: Screenshot when done
# Watch for UI changes indicating completion

Phase 4: Evaluate & Report

# 1. Evaluate screenshots against checklist (see references/checklist.md)
# 2. Generate report with annotated screenshots
# 3. Prioritize recommendations

---

Troubleshooting: When Stuck

Problem: Can't find/click element

❌ WRONG: Keep trying different selectors
   → Wastes time, silent failures

✅ RIGHT: Take screenshot, analyze visually
   → Ask user for help if needed
   → Use coordinate-based clicking

Problem: JavaScript returns "missing value"

This usually means:

1. The script is too complex (simplify it)
2. The element doesn't exist (screenshot to verify)
3. Timing issue (add sleep, retry)

Fix: Use simple one-liner JS, not complex functions.

// ❌ Complex (fails silently)
(function() { const elements = []; ... return JSON.stringify(elements); })()

// ✅ Simple (clear result)
document.body.innerText.substring(0, 500)
document.querySelectorAll('button').length
document.querySelector('.loading') !== null

Problem: Form won't submit

Try in order:

1. Screenshot to see submit button location
2. document.forms[0].submit()
3. Click submit button by coordinates
4. Ask user to submit manually

---

Audit Instructions

Step 1: Understand the Target

Ask user for:

1. URL to audit
2. Operation to test (search, report generation, AI task, etc.)
3. How to trigger — button name, location, or steps
4. Expected duration (helps calibrate screenshot intervals)
5. Any auth requirements (login credentials if needed)

If user is available: Ask them to trigger the operation manually while you capture screenshots. This avoids navigation complexity.

Step 2: Capture Sequence

Always screenshot first. Then run simple state checks:

// Simple one-liners that won't fail silently:

// Check for spinner
!!document.querySelector('[class*="spin"], [class*="load"], .spinner')

// Check for progress bar
!!document.querySelector('progress, [role="progressbar"]')

// Get visible text (look for status messages)
document.body.innerText.substring(0, 1000)

// Count results appearing
document.querySelectorAll('[class*="result"], [class*="item"]').length

Capture Timeline: | Time | Action | |------|--------| | T+0s | Screenshot + note what triggered | | T+10s | Screenshot + simple state checks | | T+30s | Screenshot + simple state checks | | T+Complete | Screenshot + final state |

Step 3: Evaluate Against Checklist

Load and evaluate against references/checklist.md. Score each category:

• ✅ Present and well-implemented
• ⚠️ Partially implemented / needs improvement
• ❌ Missing
• N/A Not applicable to this operation

Step 4: Generate Report

Use template from references/report-template.md.

---

Key Evaluation Patterns

Progressive Value Detection

Look for:

// Partial results appearing
document.querySelectorAll('[class*="result"], [class*="item"], li, tr').length

// Streaming content
document.querySelector('[class*="stream"], [class*="typing"], [class*="cursor"]')

Heartbeat Indicators

Look for:

// Counters
document.body.innerText.match(/\d+\s*(found|processed|complete|%)/gi)

// Animations (CSS or JS)
document.querySelectorAll('[class*="animate"], [class*="pulse"], [class*="spin"]')

Time Estimation

Look for:

// Time remaining text
document.body.innerText.match(/(\d+\s*(sec|min|second|minute)|remaining|left|ETA)/gi)

// Progress percentage
document.querySelector('[role="progressbar"]')?.getAttribute('aria-valuenow')

---

Screenshot Comparison Strategy

For each interval, note:

1. What changed from previous screenshot
2. Activity signals (counters, animations, partial results)
3. User anxiety factors (frozen UI, no feedback)

Compare: | Element | T+0s | T+10s | T+30s | Complete | |---------|------|-------|-------|----------| | Results visible | | | | | | Counter/progress | | | | | | Status message | | | | | | Animation active | | | | |

---

Report Output Structure

Generate markdown report with:

1. Summary Score: X/10 categories addressed
2. Screenshots Gallery: With timestamps and annotations
3. Strengths: What works well
4. Critical Gaps: Missing elements hurting UX most
5. Quick Wins: Low-effort, high-impact improvements
6. Detailed Findings Table: See references/report-template.md
7. Priority Matrix: P1/P2/P3 recommendations

---

Best-in-Class Comparisons

Reference these examples of excellent waiting UX:

• Figma exports: Progress bar + percentage + file count
• Notion AI: Streaming text + cursor animation
• ChatGPT: Token-by-token streaming + stop button
• Linear search: Instant partial results + refinement
• Vercel deployments: Step-by-step progress + logs

---

Error Scenarios to Test

If possible, test:

1. Partial failure: Does UI degrade gracefully?
2. Network interruption: Is progress preserved?
3. Timeout: Is there clear feedback?

// Simulate slow network (if DevTools available)
// Or disconnect briefly and observe behavior

---

Common Issues to Flag

| Issue | User Impact | Quick Fix | |-------|-------------|-----------| | Spinner only | Anxiety, abandon | Add status text | | No progress | "Is it stuck?" | Add heartbeat counter | | No cancellation | Trapped feeling | Add cancel button | | Silent completion | Missed results | Add completion animation | | Full-page block | Can't multitask | Move to background |