name: ux-improver description: Recursively improve web application UX via vision-based screenshot analysis. Use when asked to "improve UX", "fix usability", "audit user experience", or "/uximprove". Triggers on UX review, usability improvement, user flow analysis, interaction audit.

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

Git Operations

After each iteration that makes code changes:

1. Commit with iteration context:

   git add <files> && git commit -m "ux: [changes] (iteration N, score X.X)"
   

After the final iteration: 2. Push to trigger CI:

git push

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.