UX Improver

Recursive workflow that transforms frustrating user experiences into intuitive, efficient interactions through iterative screenshot analysis and targeted fixes.

Screenshot → Grade (6 UX dimensions) → Fix Top 3 → Repeat until score >= 8.0

Focus: Usability, Not Aesthetics

This skill evaluates user experience (can users accomplish tasks efficiently?) rather than visual design (does it look pretty?).

Prerequisites

• Chrome integration (claude --chrome) - PREFERRED
• Playwright - Fallback for CI/headless scenarios
• Web application running (default: localhost:3000)

Browser Decision Tree

Is Chrome MCP available? (claude --chrome)
├── Yes → Use Chrome tools
│   ├── tabs_context_mcp → get tab IDs
│   ├── tabs_create_mcp → new tab
│   ├── navigate → go to URL
│   ├── computer action:"screenshot" → capture
│   └── read_page → get accessibility tree (CRITICAL for UX)
│
└── No → Fall back to Playwright
    ├── Use sync_playwright API
    ├── page.screenshot(full_page=True)
    └── Save to /tmp/ for analysis

Workflow

Phase 1: Screenshot & Analyze

1. Setup browser context

   Chrome: tabs_context_mcp → tabs_create_mcp → navigate
   Playwright: browser.new_page() → page.goto()
   

2. Capture full-page screenshot

   Chrome: computer(action: "screenshot", tabId: X)
   Playwright: page.screenshot(path="/tmp/ux_audit.png", full_page=True)
   

3. Get accessibility tree (essential for UX evaluation)

   read_page(tabId, filter: "all") → element roles, labels, states
   read_page(tabId, filter: "interactive") → buttons, links, inputs
   

4. Analyze against 6 UX dimensions using vision + accessibility data

5. Output structured UX report

Phase 2: Fix Top 3 Issues

1. Rank issues by: severity × user_impact × fix_complexity

   • Prioritize: Blocking issues > Friction issues > Polish issues

2. For each issue (top 3 only):

   a. Use read_page to identify element refs and roles
   b. Grep codebase for component files
   c. Apply UX fix:
      - Add missing labels/aria-labels
      - Add loading/disabled states
      - Improve button text
      - Add error messages
      - Add progress indicators
   d. Preserve existing functionality
   

3. Wait for hot reload (2-3 seconds for HMR)

Phase 3: Re-evaluate

1. Take new screenshot
2. Re-check accessibility tree
3. Re-grade against same 6 dimensions
4. Decision:
   • score < 8.0 AND iteration < 5 → goto Phase 2
   • score >= 8.0 → auto-stop, generate final report
   • iteration >= 5 → stop, generate final report with recommendations

UX Grading Dimensions

Scoring Scale

Pass threshold: 8.0 (configurable)

UX Anti-Patterns to Detect & Fix

Usability (Critical)

Information Architecture (Major)

User Flows (Critical)

Affordances & Signifiers (Major)

Feedback & Status (Major)

Error Handling (Critical)

Output Format

Per-Iteration Report

## UX Grade: X.X/10 - [Status]

**Iteration**: N of 5

| Dimension | Score | Status | Key Issue |
|-----------|-------|--------|-----------|
| Usability | X/10 | PASS/FAIL | [specific issue] |
| Info Architecture | X/10 | PASS/FAIL | [specific issue] |
| User Flows | X/10 | PASS/FAIL | [specific issue] |
| Affordances | X/10 | PASS/FAIL | [specific issue] |
| Feedback | X/10 | PASS/FAIL | [specific issue] |
| Error Handling | X/10 | PASS/FAIL | [specific issue] |

## Top 3 UX Issues to Fix

### Issue #1: [Title] (Critical/Major/Minor)
- **Location**: [element/page area]
- **Problem**: [UX issue description]
- **User Impact**: [how this hurts users]
- **Root Cause**: [missing component/prop/state]
- **Files Found**:
  - `src/components/Button.tsx:42`
  - `src/pages/checkout.tsx:15`
- **Fix**:
  ```tsx
  // Change this
  <button>Submit</button>
  // To this
  <button disabled={isLoading}>
    {isLoading ? 'Processing...' : 'Complete Purchase'}
  </button>

Issue #2: ...

Issue #3: ...

Applying fixes...

### Final Report

```markdown
## UX Improvement Summary

| Metric | Before | After | Change |
|--------|--------|-------|--------|
| **Overall** | X.X | X.X | +X.X |
| Usability | X | X | +X |
| Info Architecture | X | X | +X |
| User Flows | X | X | +X |
| Affordances | X | X | +X |
| Feedback | X | X | +X |
| Error Handling | X | X | +X |

## Files Modified
- `src/components/Button.tsx` - Added loading state
- `src/components/Form.tsx` - Added inline validation
- `src/pages/checkout.tsx` - Added progress indicator

## Iterations Completed: X

## Final Status: PASSING / NEEDS_MORE_WORK

## Remaining Recommendations
[If score < 8, list remaining UX issues]

File Discovery Patterns

From Screenshot to Source File

1. Get accessibility tree

   read_page(tabId, filter: "interactive") → buttons, links, inputs with roles
   find(query: "submit button", tabId) → specific element refs
   

2. Extract identifying info

   • Element text content
   • ARIA labels/roles
   • Class names
   • Test IDs (data-testid)

3. Search codebase

   # Find by button text
   grep -r "Submit" --include="*.tsx" --include="*.jsx"
   
   # Find by component name
   grep -r "CheckoutButton" --include="*.tsx"
   
   # Find by test ID
   grep -r "data-testid=\"checkout" --include="*.tsx"
   

4. Common UX-related locations

   src/components/           # UI components
   src/components/forms/     # Form components
   src/components/feedback/  # Toast, loading, error components
   src/hooks/               # State hooks (useLoading, useError)
   src/pages/               # Page-level UX
   

Chrome Tool Reference

Iteration Control

• max_iterations: 5 (prevents infinite loops)
• pass_threshold: 8.0 (UX is "good enough")
• auto_continue: When score < 8.0
• auto_stop: When score >= 8.0 OR iterations >= 5

Integration Notes

This skill integrates with:

• webapp-testing: Shares Chrome/Playwright decision patterns
• ux-designer: Uses WCAG accessibility principles
• design-improver: Complementary (design-improver for aesthetics, this for UX)

Example Session

User: /uximprove the checkout flow

Claude: [Takes screenshot of localhost:3000/checkout]

## UX Grade: 4.8/10 - Significant Issues

| Dimension | Score | Status | Key Issue |
|-----------|-------|--------|-----------|
| Usability | 4/10 | FAIL | Vague "Submit" button |
| Info Architecture | 6/10 | PASS | Sections organized |
| User Flows | 3/10 | FAIL | No progress indicator |
| Affordances | 5/10 | FAIL | Payment fields look disabled |
| Feedback | 4/10 | FAIL | No loading state on submit |
| Error Handling | 5/10 | FAIL | Generic error messages |

## Top 3 UX Issues to Fix

### Issue #1: No Loading State (Critical)
- **Location**: Submit button
- **Problem**: Button doesn't indicate processing
- **User Impact**: Users click multiple times, think app is broken
- **Fix**: Add isLoading state and spinner

### Issue #2: Vague Button Text (Major)
- **Location**: Submit button
- **Problem**: "Submit" doesn't describe action
- **User Impact**: Users unsure what clicking will do
- **Fix**: Change to "Complete Purchase"

### Issue #3: No Progress Indicator (Major)
- **Location**: Checkout flow
- **Problem**: Users don't know how many steps remain
- **User Impact**: Abandonment due to uncertainty
- **Fix**: Add step indicator (Step 2 of 3)

[Applies fixes]
[Takes new screenshot]

## UX Grade: 7.1/10 - Good (+2.3)

[Continues until score >= 8.0]

## Final Report
UX improved from 4.8 to 8.2 in 3 iterations.

Complementary Usage

For complete UI improvement, run both:

/designimprove the checkout page  # Fix visual aesthetics
/uximprove the checkout flow      # Fix user experience

The skills don't overlap - they address different aspects of quality.