---

name: design-improver description: Recursively improve web UI design via vision-based screenshot analysis. Use when asked to "improve design", "audit UI", "fix styling", "grade the interface", or "/designimprove". Triggers on design review, UI improvement, screenshot analysis, design grade.

Design Improver

Recursive workflow that transforms mediocre UI into world-class design through iterative screenshot analysis and targeted fixes.

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

Prerequisites

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

Browser Decision Tree

CopyIs 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 element tree
│
└── No → Fall back to Playwright
    ├── Use sync_playwright API
    ├── page.screenshot(full_page=True)
    └── Save to /tmp/ for analysis

Workflow

Phase 1: Screenshot & Grade

1. Setup browser context

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

2. Capture full-page screenshot

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

3. Analyze screenshot against 6 dimensions using vision capabilities

4. Output structured grade report

Phase 2: Fix Top 3 Issues

1. Rank issues by: severity × visual_impact × fix_complexity

   • Prioritize: High Impact + Low Effort fixes first

2. For each issue (top 3 only):

   Copya. Use read_page to get element refs and class names
   b. Grep codebase for matching selectors:
      - grep "\.classname" **/*.css
      - grep "className.*classname" **/*.tsx
   c. Apply MINIMAL targeted fix (single property when possible)
   d. Preserve existing structure
   

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

Phase 3: Re-evaluate

1. Take new screenshot
2. Re-grade against same 6 dimensions
3. 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

Grading Dimensions

Scoring Scale

Pass threshold: 8.0 (configurable via max score parameter)

Anti-Patterns to Detect & Fix

Typography (Critical)

Color (Major)

Layout (Major)

Visual Polish (Minor-Major)

Output Format

Per-Iteration Report

Copy## Design Grade: X.X/10 - [Status]

**Iteration**: N of 5

| Dimension | Score | Status | Key Issue |
|-----------|-------|--------|-----------|
| Typography | X/10 | PASS/FAIL | [specific issue] |
| Color | X/10 | PASS/FAIL | [specific issue] |
| Layout | X/10 | PASS/FAIL | [specific issue] |
| Motion | X/10 | PASS/FAIL | [specific issue] |
| Polish | X/10 | PASS/FAIL | [specific issue] |
| Accessibility | X/10 | PASS/FAIL | [specific issue] |

## Top 3 Issues to Fix

### Issue #1: [Title] (Critical/Major/Minor)
- **Location**: [element description, area of page]
- **Problem**: [what's wrong]
- **Root Cause**: [CSS property, missing style, etc.]
- **Files Found**:
  - `src/styles/globals.css:42`
  - `src/components/Hero.tsx:15`
- **Fix**:
  ```css
  /* Change this */
  font-family: Inter, sans-serif;
  /* To this */
  font-family: 'Playfair Display', serif;

Issue #2: ...

Issue #3: ...

---

Applying fixes...

Copy
### Final Report

```markdown
## Design Improvement Summary

| Metric | Before | After | Change |
|--------|--------|-------|--------|
| **Overall** | X.X | X.X | +X.X |
| Typography | X | X | +X |
| Color | X | X | +X |
| Layout | X | X | +X |
| Motion | X | X | +X |
| Polish | X | X | +X |
| Accessibility | X | X | +X |

## Files Modified
- `src/styles/globals.css` - Font family, shadows
- `src/styles/variables.css` - Color tokens
- `src/components/Hero/Hero.tsx` - Layout adjustments

## Iterations Completed: X

## Final Status: PASSING / NEEDS_MORE_WORK

## Remaining Recommendations
[If score < 8, list what else could be improved]

File Discovery Patterns

From Screenshot to Source File

1. Extract element info from page

   Copyread_page(tabId, filter: "all") → accessibility tree with refs
   find(query: "hero section", tabId) → specific element refs
   

2. Get class names from elements

   • Look for className, class attributes in tree
   • Note component names from React DevTools patterns

3. Search codebase

   Copy# CSS/SCSS files
   grep -r "\.hero-section" --include="*.css" --include="*.scss"
   
   # React/Vue components
   grep -r "className.*hero" --include="*.tsx" --include="*.jsx"
   
   # Tailwind classes
   grep -r "bg-gradient" --include="*.tsx"
   

4. Common locations to check

   Copysrc/styles/          # Global CSS
   src/app/globals.css  # Next.js global styles
   src/theme/           # Theme tokens
   src/components/      # Component styles
   tailwind.config.js   # Tailwind customization
   

Chrome Tool Reference

Iteration Control

• max_iterations: 5 (prevents infinite loops)
• pass_threshold: 8.0 (design 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
• frontend-design: Uses design anti-pattern definitions
• ux-designer: Uses WCAG accessibility checklist

Example Session

CopyUser: /designimprove the dashboard

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

## Design Grade: 5.4/10 - Needs Work

| Dimension | Score | Status | Key Issue |
|-----------|-------|--------|-----------|
| Typography | 4/10 | FAIL | Default Inter font |
| Color | 6/10 | PASS | Acceptable palette |
| Layout | 5/10 | FAIL | Standard grid layout |
| Motion | 3/10 | FAIL | No transitions |
| Polish | 5/10 | FAIL | Flat backgrounds |
| Accessibility | 8/10 | PASS | Good contrast |

## Top 3 Issues to Fix

### Issue #1: Generic Typography (Critical)
...

[Applies fixes]
[Takes new screenshot]

## Design Grade: 7.2/10 - Good (+1.8)

[Continues until score >= 8.0]

## Final Report
Overall improved from 5.4 to 8.1 in 3 iterations.