ux-improver

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?).

This Skill Evaluates	NOT This (use /designimprove)
Clear CTAs and labels	Font choices
Navigation efficiency	Color harmony
Loading/feedback states	Visual polish
Error prevention/recovery	Shadows and depth
Affordances (looks clickable)	Typography hierarchy

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

Dimension	Weight	What Makes It Pass
Usability	20%	Users can accomplish tasks with minimal effort. Clear CTAs, obvious actions.
Information Architecture	15%	Content organized logically. Navigation intuitive. Labels clear.
User Flows	20%	Paths to goals are efficient. Progress visible. Next steps obvious.
Affordances & Signifiers	15%	Interactive elements look interactive. Buttons look clickable.
Feedback & Status	15%	System responds to actions. Loading states. Confirmations.
Error Handling	15%	Errors prevented. Messages helpful. Recovery paths clear.

Scoring Scale

Score	Status	Action
9-10	Exceptional	Auto-stop - UX is excellent
7-8	Good	Auto-stop - meets quality bar
5-6	Needs Work	Auto-continue fixing
1-4	Significant Issues	Auto-continue fixing

Pass threshold: 8.0 (configurable)

UX Anti-Patterns to Detect & Fix

Usability (Critical)

Anti-Pattern	Why It's Bad	Fix
Vague CTA text ("Submit", "Click Here")	Users don't know what happens	Use action verbs ("Create Account", "Send Message")
Hidden primary actions	Users can't find main function	Make primary action prominent
Too many options	Choice paralysis	Reduce options, use progressive disclosure
Inconsistent interactions	Confuses users	Standardize patterns across app
No clear starting point	Users don't know where to begin	Add clear onboarding/guidance

Information Architecture (Major)

Anti-Pattern	Why It's Bad	Fix
Deep navigation (> 3 clicks)	Users get lost	Flatten hierarchy
Unclear labels	Users guess meaning	Use user-centric terminology
No visual hierarchy	Can't scan page	Size/weight for importance
Important info below fold	Users miss it	Move critical content up
Inconsistent categorization	Items hard to find	Logical grouping

User Flows (Critical)

Anti-Pattern	Why It's Bad	Fix
Dead ends (no next step)	Users stuck	Always provide next action
Unnecessary steps	Wastes user time	Remove or combine steps
No progress indication	Users feel lost	Add stepper/progress bar
Can't go back	Users trapped	Clear back/cancel buttons
Unclear completion	Users unsure if done	Success confirmation

Affordances & Signifiers (Major)

Anti-Pattern	Why It's Bad	Fix
Flat buttons (no visual cue)	Look like text	Add borders, shadows, background
Clickable text without style	Users don't know it's a link	Underline, color, or button style
Icons without labels	Meaning unclear	Add text labels
No hover/focus states	No feedback on interaction	Add visual state changes
Disabled looks same as enabled	Users try clicking disabled	Dim/gray disabled elements

Feedback & Status (Major)

Anti-Pattern	Why It's Bad	Fix
No loading state	Users think app frozen	Add spinner/skeleton
No action confirmation	Users unsure if worked	Toast/success message
Silent failures	Users don't know error occurred	Error feedback
No undo option	Mistakes permanent	Allow reversal
Stale data displayed	Users see wrong info	Refresh indicators

Error Handling (Critical)

Anti-Pattern	Why It's Bad	Fix
Generic "An error occurred"	No actionable info	Specific error message
No inline validation	Errors found too late	Validate on blur/change
Errors clear form input	User loses work	Preserve input
No recovery suggestion	User stuck	"Try again" or alternatives
Blame the user	Bad experience	Neutral, helpful tone

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

Tool	Purpose	UX-Specific Usage
tabs_context_mcp	Get available tabs	Required first
navigate	Go to URL	Test different pages/flows
computer	Screenshot/click	Capture state, test interactions
read_page	Get accessibility tree	Critical - reveals labels, roles, states
find	Natural language search	Find "submit button", "error message"

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.