Claude Code Visual Development Guide for UIs, explaining to Claude Code how to use Chromium and Playwright MCP to iteratively create, LOOK and refine the UI it is creating.

Claude Code Visual Development Guide for UIs

# 🎨 Complete Visual UI Development Guide for Claude Code

## 🚀 The Game-Changing Discovery

**Claude Code can SEE screenshots!** This completely transforms UI development from blind coding to visual design with real-time feedback.

### The Transform
- **Old Way**: Write code → Hope it looks good → Fix bugs when reported
- **New Way**: Build → **SEE** → Judge → Refine → Repeat until beautiful

---

## 📋 Quick Start (5 Minutes)

### Step 1: Initial Setup Prompt
Copy and paste this to Claude:
```
I want to build a [describe your UI] using the visual development workflow.

After creating each component:
1. Take screenshots with: npm run screenshot
2. LOOK at them with: Read screenshots/desktop-*.png
3. Tell me what you see visually
4. Improve based on visual observations
5. Repeat until it looks professional

Start by setting up the environment with npm run setup.
```

### Step 2: Essential Commands
```bash
# Initial Setup (smart - only installs if needed)
npm install
npm run setup    # Checks for Chromium, installs if missing
npm run dev      # Start development server

# The Visual Loop (THE CORE WORKFLOW)
npm run screenshot                    # Capture all viewports
Read screenshots/desktop-*.png       # SEE what you built! 
Read screenshots/mobile-*.png        # Check mobile view
Read screenshots/tablet-*.png        # Check tablet view
```

### Step 3: The "Aha!" Moment
When Claude says **"Looking at the screenshot, I can see..."** and describes visual elements (not code), the workflow is working!

---

## 🔄 The Core Visual Development Loop

### The 5-Step Process
```
1. BUILD  → Create initial UI (don't aim for perfect)
2. SHOOT  → npm run screenshot (capture all viewports)
3. LOOK   → Read screenshots/*.png ← THE MAGIC STEP
4. JUDGE  → "The header feels cramped, colors clash..."
5. FIX    → Make visual improvements
↩️ REPEAT until beautiful
```

### Visual Analysis Template
When looking at screenshots, structure observations like this:
```markdown
## Visual Analysis

### First Impression
"The page feels [balanced/cluttered/empty/professional]..."

### What's Working
- ✅ Clean card layout with good shadows
- ✅ Clear visual hierarchy in navigation

### Issues to Fix
1. **Spacing**: Cards too close together, need breathing room
2. **Typography**: Heading doesn't stand out from body text
3. **Mobile**: Text wrapping awkwardly at 375px

### Priority Fixes
1. Increase card gap from 16px to 24px
2. Make h1 larger and bolder
3. Adjust mobile font sizes
```

---

## 💡 Recommended Tech Stack

### Quick Start Stack (Optimal for Visual Development)
```
Framework: React (component isolation)
Build Tool: Vite (instant HMR)
Styling: TailwindCSS (rapid visual adjustments)
```

**Why this combo?**
- Vite's HMR = see changes instantly
- Tailwind utilities = trivial visual tweaks
- React components = isolated iterations

But the workflow works with **any** stack - Vue, Svelte, vanilla HTML. The key is being able to see and iterate.

---

## 📸 Practical Visual Development Examples

### Example 1: Building a Feature
```
User: "Create a pricing page with three tiers"

Claude: I'll build this using visual development.
[Creates initial version]
[Takes screenshot]

Looking at the desktop screenshot, I can see:
- ❌ Cards are too close together
- ❌ No visual hierarchy between tiers
- ❌ "Recommended" tier doesn't stand out
- ✅ Clean layout structure

Let me fix these issues...
[Makes improvements]
[Takes new screenshot]

Much better! The cards now have breathing room and the 
recommended tier has a colored border that makes it pop.
```

### Example 2: Visual Debugging
```
User: "The mobile layout looks broken"

Claude: Let me capture screenshots and investigate.
[Takes screenshots at all viewports]

Looking at mobile-*.png, I can see:
- Horizontal scroll at 375px width
- Navigation menu overlapping logo
- Cards too narrow, text cramped

[Fixes each issue]
[Verifies with new screenshots]
```

### Example 3: Design Polish
```
User: "Make it look more professional"

Claude: I'll analyze the current design and elevate it.
[Takes screenshots]

Visually, the design feels flat and generic. I'll add:
- Subtle shadows for depth
- Better color hierarchy
- More intentional spacing
- Refined typography scale

[Iterates with screenshots until polished]
```

---

## 🎯 Visual Language Guide

### Describe What You SEE, Not Code

| ❌ Wrong (Technical) | ✅ Right (Visual) |
|---------------------|-------------------|
| "Added mb-4 class" | "Gave it breathing room" |
| "Changed to flexbox" | "Aligned elements horizontally" |
| "Set color to #3B82F6" | "Made it a vibrant blue" |
| "Applied border-radius" | "Softened the corners" |
| "Increased z-index" | "Brought it to the front" |
| "Used grid-cols-3" | "Arranged in three columns" |

### Visual Problem → Solution Reference

| Visual Problem | Likely Fix |
|---------------|------------|
| "Feels cramped" | Increase padding/margins |
| "No hierarchy" | Vary font sizes/weights |
| "Looks flat" | Add shadows, borders, depth |
| "Feels chaotic" | Align to consistent grid |
| "Hard to read" | Increase contrast/font size |
| "Not modern" | Simplify, add white space |
| "Unbalanced" | Adjust visual weight distribution |

---

## ⚠️ Common Pitfalls & How to Avoid Them

### Pitfall 1: Taking Screenshots But Not Looking
```
❌ WRONG: "I took screenshots. Moving on."
✅ RIGHT: "Let me look at the screenshots... I can see the header 
is cramped and the mobile view has text cutoff..."
```

### Pitfall 2: Describing Code Instead of Visuals
```
❌ WRONG: "I added Tailwind classes for spacing"
✅ RIGHT: "Looking at the screenshot, the cards now have better 
separation and the layout feels more balanced"
```

### Pitfall 3: Not Comparing Before/After
```
❌ WRONG: "I made changes. Here's the new version."
✅ RIGHT: "Comparing before/after screenshots: The spacing 
improvement is dramatic - much easier to scan now"
```

### Pitfall 4: Ignoring Mobile
```
❌ WRONG: "Desktop looks perfect, ship it"
✅ RIGHT: "Let me check all viewports... Mobile needs work"
```

---

## ✅ Project Setup Checklist

Copy this checklist for every new visual UI project:

```markdown
### Initial Setup
- [ ] Run `npm install` to install dependencies
- [ ] Run `npm run setup` to check/install Chromium
- [ ] Verify dev server with `npm run dev`
- [ ] Test screenshots with `npm run screenshot`
- [ ] Confirm you can READ screenshots: `Read screenshots/desktop-*.png`

### Development Phase
- [ ] Build initial component (rough is fine)
- [ ] Take first screenshots
- [ ] **LOOK at screenshots** (crucial step!)
- [ ] Document 3-5 visual observations
- [ ] Fix most obvious issue first
- [ ] Take new screenshots
- [ ] Compare before/after
- [ ] Repeat until satisfied

### Validation Phase
- [ ] Check desktop (1440px)
- [ ] Check tablet (768px)
- [ ] Check mobile (375px)
- [ ] Verify no horizontal scroll
- [ ] Confirm text readability
- [ ] Test interactive states
```

---

## 🔧 Advanced Techniques

### The "Squint Test"
Look at the screenshot with unfocused eyes. You should see clear visual hierarchy. If everything blurs together, you need stronger contrast.

### The "First Glance Test"
What draws your eye first? This should be the most important element. If not, adjust visual weight.

### The "Emotion Check"
How does the design *feel*? Professional? Playful? Trustworthy? Chaotic? Ensure it matches intended brand emotion.

### A/B Visual Testing
Create two versions, screenshot both, compare visually:
```
"Create two hero section designs. Take screenshots of both, 
look at them, and explain which works better visually and why."
```

### Visual Consistency Audit
```
"Screenshot all major components. Look at them as a collection. 
Identify any inconsistencies in spacing, colors, or style."
```

---

## 📝 Iteration Tracking Template

Document your visual improvements:
```markdown
### Iteration 1
- **Screenshot**: desktop-[timestamp].png
- **Observation**: Header too small, no visual impact
- **Change**: Increased h1 to 48px, added gradient
- **Result**: Much stronger visual hierarchy

### Iteration 2
- **Screenshot**: mobile-[timestamp].png  
- **Observation**: Cards stacking poorly on mobile
- **Change**: Full width on mobile, larger tap targets
- **Result**: Much more usable on phones
```

---

## 🚨 Quick Command Reference

### Essential Commands
```bash
npm run setup      # Smart Chromium setup (checks first)
npm run dev        # Start dev server
npm run screenshot # Capture all viewports
npm run validate   # Check against design specs
npm run iterate    # Automated refinement loop
```

### Viewing Screenshots (Most Important!)
```bash
Read screenshots/desktop-*.png   # View desktop
Read screenshots/mobile-*.png    # View mobile  
Read screenshots/tablet-*.png    # View tablet
Read screenshots/final-*.png     # View final versions
```

### Emergency Fixes
```bash
# Screenshots not working?
npm run setup

# Manual Chromium install
npx playwright install chromium

# Can't see images?
ls screenshots/

# Dev server issues?
Ctrl+C then npm run dev
```

---

## 🎬 Magic Prompts for Different Scenarios

### Full Visual Development
```
"Build a [component] using visual development. Create it, 
screenshot it, look at it, describe what you see, and iterate 
based on visual observations until it looks professional."
```

### Visual Debugging
```
"Something looks wrong. Take screenshots at all viewports, 
look carefully, identify specific visual problems, then fix 
them one by one with verification screenshots."
```

### Design Polish
```
"The functionality works but needs visual polish. Screenshot 
the current state, analyze aesthetics, and elevate the design. 
Focus on spacing, typography, and visual hierarchy."
```

### Responsive Audit
```
"Check the responsive design. Take screenshots at mobile (375px), 
tablet (768px), and desktop (1440px). Look at each and identify 
where the design breaks. Fix issues based on what you SEE."
```

---

## 🏆 Success Criteria

You're doing visual development RIGHT when:

1. **Claude describes what it SEES** not what the code does
2. **Iterations are based on visual observations** not assumptions  
3. **Before/after comparisons** guide improvements
4. **All viewports are checked** not just desktop
5. **Aesthetic judgments** drive decisions
6. **The UI looks polished** not just functional

---

## 💭 The Mindset Shift

### From Blind Coder to Visual Designer

**Old Thought Process:**
1. Read requirements
2. Write semantic HTML
3. Add CSS classes
4. Hope it looks good
5. Debug when someone complains

**New Thought Process:**
1. Build rough version
2. **LOOK at what I built**
3. **SEE what needs improvement**
4. Make it visually better
5. **Verify improvements visually**
6. Iterate until beautiful

---

## 🐍 Building UIs for Existing Programs

### Perfect Use Case: Wrapping Backend Logic with Beautiful UIs

The visual workflow is **ideal** for building UIs around existing programs (Python, Node.js, etc.) because:
- Your backend logic already works
- You can focus purely on UI/UX
- Clear separation of concerns
- Visual polish transforms scripts into products

### Common Architecture Patterns

#### Web UI with API Backend (Recommended)
```
┌─────────────┐     API      ┌──────────────┐
│  Beautiful  │◄──────────►  │   Your       │
│   React UI  │    JSON      │   Program    │
└─────────────┘              └──────────────┘
   (Visual Dev)              (Python/Node/etc)
```

**Python Example:**
```python
# backend.py
from flask import Flask, jsonify, request
from flask_cors import CORS
import your_existing_module

app = Flask(__name__)
CORS(app)

@app.route('/api/process', methods=['POST'])
def process():
    data = request.json
    result = your_existing_module.run(data['input'])
    return jsonify({'result': result})
```

**Frontend Connection:**
```javascript
// React component
const callBackend = async (input) => {
  const response = await fetch('http://localhost:5000/api/process', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ input })
  });
  return response.json();
};
```

### UI Patterns by Program Type

| Program Type | UI Components | Visual Focus |
|-------------|---------------|--------------|
| **Data Analyzer** | File upload, charts, export | Clear data flow, beautiful visualizations |
| **File Processor** | Drag-drop, progress, preview | Before/after comparison, status indicators |
| **Automation Tool** | Config forms, logs, controls | Real-time status, readable output |
| **ML Model** | Input forms, predictions, confidence | Trust-building visualizations |
| **Web Scraper** | URL input, filters, results table | Progress tracking, data presentation |

### Adapted Prompt for Existing Programs
```
"I have a [Python/Node/etc] program that [describes functionality].
Create a beautiful web UI wrapper for it:

1. Set up API endpoints to expose the functions
2. Build a React frontend using visual development
3. Focus on making the program's purpose immediately clear
4. Use screenshots to refine until it looks professional

The program:
- Takes: [input description]
- Does: [process description]  
- Returns: [output description]
"
```

### Special Considerations

#### Long-Running Operations
```javascript
// Beautiful progress tracking
const [progress, setProgress] = useState(0);
const [status, setStatus] = useState('Initializing...');

// Visual feedback is crucial for Python scripts
<div className="space-y-2">
  <div className="flex justify-between text-sm">
    <span>{status}</span>
    <span>{progress}%</span>
  </div>
  <div className="w-full bg-gray-200 rounded-full h-2">
    <div 
      className="bg-primary h-2 rounded-full transition-all"
      style={{ width: `${progress}%` }}
    />
  </div>
</div>
```

#### Error Handling
Instead of showing raw stack traces, create friendly error displays:
```javascript
<div className="bg-red-50 border border-red-200 rounded-lg p-4">
  <h3 className="text-red-800 font-medium">Unable to Process</h3>
  <p className="text-red-600 mt-1">{error.userMessage}</p>
  <details className="mt-2">
    <summary className="text-sm text-red-500 cursor-pointer">
      Technical Details
    </summary>
    <pre className="mt-2 text-xs bg-red-100 p-2 rounded">
      {error.stackTrace}
    </pre>
  </details>
</div>
```

### Success Metrics for Program Wrappers
Your UI wrapper succeeds when:
- Non-technical users can use your program
- The UI makes the program's purpose obvious
- Complex inputs are simplified visually
- Results are clearer than terminal output
- It feels like professional software, not a script

---

## 🎯 Final Challenge

Test if you've mastered visual development:

```
"Build a simple card component. Take a screenshot and look at it. 
Describe three specific visual improvements. Implement them and 
show me before/after screenshots with visual analysis of why 
the changes improved the design."
```

If Claude:
- ✅ Views the screenshot
- ✅ Describes visual elements
- ✅ Makes aesthetic judgments
- ✅ Implements improvements
- ✅ Compares results visually

**Congratulations! You've unlocked visual development!** 🎉

---

## 🔑 The Core Revelation (Never Forget)

**You can SEE screenshots with the Read tool.**

This isn't just about debugging. It's about designing with eyes. Every screenshot is an opportunity to make it better. Every iteration brings you closer to beautiful.

You're not coding blind anymore. You're a designer who can see.

**Now go build something beautiful!** ✨

---

*Remember: The magic command is `Read screenshots/[filename].png` - Use it constantly!*