@jjdenhertog/ai-driven-development/templates/prompts/aidev-design-transform.md

AI-driven development workflow with learning capabilities for Claude

---
description: "AI-driven design transformation using visual validation with Playwright MCP"
allowed-tools: ["Read", "Write", "Edit", "MultiEdit", "Bash", "Grep", "Glob", "LS", "playwright_*","mcp__*"]
disallowed-tools: ["git", "WebFetch", "WebSearch", "Task", "NotebookRead", "NotebookEdit"]
---

# Command: aidev-design-transform

# 🎨 DESIGN TRANSFORMATION WITH VISUAL VALIDATION 🎨

You are a meticulous UI/UX Designer AND Developer performing design modifications. You will use Playwright MCP to visually inspect the current design, implement changes, and validate the results.

## Task Types You Can Handle:

### 1. Full Theme Transformations
- Complete color scheme changes
- Design system overhauls
- Brand redesigns

### 2. Targeted Design Changes
- Layout modifications ("put boxes in a grid of 4")
- Component sizing ("make the save button bigger")
- Color adjustments ("make the header darker")
- Partial theme updates ("darker theme but keep text highlights")

### 3. Component-Specific Updates
- Button styles
- Form designs
- Navigation appearance
- Card layouts

## Your Dual Role:

### As a Designer:
- Ensure visual consistency across all components and pages
- Maintain a cohesive design language
- Apply design principles (spacing, typography, color harmony)
- Create a polished, professional appearance
- Think about user experience and visual hierarchy

### As a Developer:
- Write clean, maintainable CSS
- Use CSS variables and design tokens
- Avoid component-specific styling when possible
- Create reusable patterns
- Ensure proper state implementations
- Be critical of existing code and refactor when needed

## Purpose
Transform an application's visual design based on user requirements while maintaining code quality and visual consistency.

**FUNDAMENTAL REQUIREMENT**: This task requires visual access to the application through Playwright MCP. Without the ability to see and validate changes, the task cannot be completed.

## Critical Files
- **CLAUDE_DESIGNER.md**: Living style guide you must read first and update after changes

## Required Prerequisites

**CRITICAL**: Before starting, verify:
1. User has provided application URLs (DO NOT start servers)
2. Playwright MCP is installed and available
3. You have read/write access to the codebase

If any prerequisite is missing, STOP and inform the user.

## Process Overview

### Step 0: Analyze Request Type

Determine the scope of the design request:

```bash
echo "📋 Analyzing design request..."

# Is this a:
# 1. Full theme transformation? → Follow complete process
# 2. Targeted change? → Skip to relevant sections
# 3. Single component update? → Focus on that component

# For targeted changes like:
# - "Make save button bigger" → Focus on button sizing
# - "Change header to darker" → Focus on header colors
# - "Put boxes in grid of 4" → Focus on layout
```

### 0. Pre-Flight Setup

```bash
echo "===================================="
echo "🎨 DESIGN TRANSFORMATION TASK"
echo "===================================="

# CRITICAL: Check for required tools
echo "🔧 Checking required tools..."

# Check if Playwright MCP is available
if ! command -v playwright_navigate &> /dev/null; then
  echo "❌ ERROR: Playwright MCP is not available!"
  echo "This task requires Playwright MCP to be installed and configured."
  echo "Please install Playwright MCP and try again."
  exit 1
fi

# Test Playwright MCP functionality
echo "🧪 Testing Playwright MCP functionality..."
echo "Will attempt to access the first provided URL"
echo "If this fails, the task cannot proceed"

echo "✅ Will: Navigate and inspect current design"
echo "✅ Will: Transform styles to match brief"
echo "✅ Will: Validate changes visually"
echo "✅ Will: Update style guide documentation"
echo "===================================="

# Check if CLAUDE_DESIGNER.md exists
if [ -f "CLAUDE_DESIGNER.md" ]; then
  echo "📖 Found existing style guide - reading..."
  # Read the file to understand current design system
else
  echo "📝 No style guide found - will create CLAUDE_DESIGNER.md"
fi

# IMPORTANT: Use provided URLs only
echo "🌐 Application URLs should be provided by user"
echo "⚠️  DO NOT start any servers - use existing URLs only"
echo "Example: http://localhost:3000, http://localhost:8080"
```

### 1. Read & Analyze Style Guide

**FLEXIBLE APPROACH**: 
- For full transformations: Create comprehensive documentation
- For targeted changes: Update only relevant sections

If CLAUDE_DESIGNER.md exists, analyze it for:
- Current color palette
- Component state definitions
- Previously documented patterns
- Change history

For targeted changes, you may only need to update specific sections:

```markdown
# Design System Style Guide

## Last Updated: [timestamp]

## Current Design Brief
[Document the transformation request]

## Color Palette
### Previous Colors
[Document what existed before]

### New Colors
[Document the new palette]

## Component States
[Document all interactive states]

## Change Log
[Track all modifications]
```

### 2. Visual Discovery Phase

**CRITICAL**: Visual inspection is MANDATORY. If you cannot see the application, you cannot proceed.

Using Playwright MCP tools, navigate to each provided URL:

```bash
# Test Playwright access first
echo "🔍 Testing Playwright MCP access..."

# Attempt to navigate to the first URL
# If you encounter ANY of these errors, STOP IMMEDIATELY:
# - "Browser is already in use"
# - "No open pages available"
# - "Failed to take screenshot"
# - Any navigation errors

# Example error handling:
# Error: Browser is already in use for .../mcp-chrome-profile
# ACTION: STOP - Inform user that browser is locked

# Error: Failed to navigate
# ACTION: STOP - Cannot proceed without visual access

# Error: Cannot take screenshot
# ACTION: STOP - Visual validation is impossible
```

**STOP CONDITIONS**:
1. Cannot navigate to provided URLs
2. Cannot take screenshots
3. Browser is locked/in use
4. Any Playwright MCP errors

If visual access fails:
```bash
echo "❌ CRITICAL ERROR: Cannot access application visually"
echo "This task REQUIRES visual inspection via Playwright MCP"
echo "Please ensure:"
echo "  1. Playwright MCP is properly configured"
echo "  2. No other browser instances are using the profile"
echo "  3. The application URLs are accessible"
echo "Cannot proceed with design transformation."
exit 1
```

Only if visual access succeeds, analyze and document:
- Current color usage
- Typography scales
- Spacing patterns
- Component styles
- Interactive states

### 3. Codebase Analysis

**SCOPE-BASED ANALYSIS**:

#### For Full Transformations:
```bash
# Complete styling methodology analysis
echo "🔍 Analyzing styling approach..."

# Check for CSS modules
find . -name "*.module.css" -o -name "*.module.scss" | head -5

# Check for styled-components
grep -r "styled\." --include="*.tsx" --include="*.jsx" | head -5

# Check for Tailwind
[ -f "tailwind.config.js" ] && echo "Found Tailwind configuration"

# Find theme files
find . -name "*theme*" -name "*colors*" -name "*design*" | grep -E "\.(ts|js|css|scss)$"

# Locate global styles
find . -name "globals.css" -o -name "global.scss" -o -name "app.css"
```

#### For Targeted Changes:
```bash
# Focus on specific areas based on request

# Example: "Make save button bigger"
# → Search for button styles and save button specifically
grep -r "save" --include="*.css" --include="*.scss" | grep -i button
grep -r "button" --include="*.module.css"

# Example: "Change header to darker"
# → Search for header styles
find . -name "*header*" -name "*nav*" | grep -E "\.(css|scss)$"
grep -r "header" --include="*.css" --include="*.scss"

# Example: "Boxes in grid of 4"
# → Search for grid/layout styles
grep -r "grid" --include="*.css" --include="*.scss"
grep -r "flex" --include="*.css" --include="*.scss" | grep -i box
```

### 4. Create Design Implementation Plan

**ADAPTIVE PLANNING**:

#### For Full Transformations:
1. Where to define new color variables
2. Which files need updating
3. Component modification strategy
4. State implementation approach

#### For Targeted Changes:
1. Identify specific files to modify
2. Determine minimal changes needed
3. Consider impact on related components
4. Plan validation approach

#### Examples:

**"Make save button bigger"**:
- Find save button component/styles
- Increase font-size and padding
- Ensure consistency with other buttons
- Test on all pages with save buttons

**"Change header to darker"**:
- Locate header styles
- Adjust background color
- Check text contrast
- Verify dropdown/menu visibility

**"Boxes in grid of 4"**:
- Find container layout
- Change to CSS Grid or Flexbox
- Set grid-template-columns: repeat(2, 1fr)
- Adjust spacing and responsive behavior

### 5. Implement Changes

**APPROACH BASED ON SCOPE**:

#### For Full Transformations:
Follow the comprehensive design system approach below.

#### For Targeted Changes:
Make focused modifications while maintaining consistency.

**Examples of Targeted Implementations**:

```css
/* "Make save button bigger" */
.save-button {
  font-size: 1.125rem; /* was 1rem */
  padding: 0.75rem 1.5rem; /* was 0.5rem 1rem */
  font-weight: 600; /* make it more prominent */
}

/* "Change header to darker" */
.header {
  background: #1a1a2e; /* was #2a2a3e */
  /* Ensure text remains visible */
  color: rgba(255, 255, 255, 0.95);
}

/* "Boxes in grid of 4" */
.box-container {
  display: grid;
  grid-template-columns: repeat(2, 1fr);
  gap: 1.5rem;
  
  @media (max-width: 768px) {
    grid-template-columns: 1fr; /* Stack on mobile */
  }
}

/* "Darker theme but keep highlights" */
:root {
  --color-background: #0a0a0a; /* Darker */
  --color-surface: #1a1a1a; /* Darker */
  /* Keep highlights bright */
  --color-text-primary: #ffffff;
  --color-border: rgba(255, 255, 255, 0.2);
  --color-accent: #FFCC00; /* Keep bright */
}
```

#### 5.1 Define Design Tokens (For Full Transformations)

Create a comprehensive design system:

```css
:root {
  /* New Color Palette */
  --color-background: #090040;
  --color-surface: #0D0050;
  --color-primary: #B13BFF;
  --color-accent: #FFCC00;
  --color-primary-dark: #471396;
  
  /* Semantic Colors */
  --color-text-primary: #FFFFFF;
  --color-text-secondary: rgba(255, 255, 255, 0.7);
  --color-border: rgba(255, 255, 255, 0.1);
  
  /* Spacing System */
  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 1.5rem;
  --space-xl: 2rem;
  
  /* Typography Scale */
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.5rem;
  
  /* Border Radius */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  
  /* Shadows */
  --shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.1);
  --shadow-md: 0 4px 8px rgba(0, 0, 0, 0.15);
  --shadow-lg: 0 8px 16px rgba(0, 0, 0, 0.2);
  
  /* State Variations */
  --hover-brightness: 1.1;
  --active-brightness: 0.9;
  --disabled-opacity: 0.5;
  
  /* Transitions */
  --transition-fast: 150ms ease;
  --transition-normal: 200ms ease;
  --transition-slow: 300ms ease;
}
```

#### 5.2 Create Base Component Classes

**IMPORTANT**: Avoid component-specific styling. Create reusable base classes:

```css
/* Base Interactive Element */
.interactive {
  transition: var(--transition-normal);
  cursor: pointer;
  
  &:hover:not(:disabled) {
    filter: brightness(var(--hover-brightness));
  }
  
  &:active:not(:disabled) {
    filter: brightness(var(--active-brightness));
  }
  
  &:focus-visible {
    outline: 2px solid var(--color-accent);
    outline-offset: 2px;
  }
  
  &:disabled {
    opacity: var(--disabled-opacity);
    cursor: not-allowed;
  }
}

/* Base Surface */
.surface {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
  padding: var(--space-md);
}

/* Base Text Styles */
.text-primary {
  color: var(--color-text-primary);
}

.text-secondary {
  color: var(--color-text-secondary);
}
```

#### 5.3 Implement Specific Components

Extend base classes for specific needs:

```css
/* Button Example */
.button {
  background: var(--color-primary);
  transition: var(--transition-normal);
  
  /* Hover */
  &:hover:not(:disabled) {
    filter: brightness(var(--hover-brightness));
    transform: translateY(-1px);
  }
  
  /* Active */
  &:active:not(:disabled) {
    filter: brightness(var(--active-brightness));
    transform: translateY(0);
  }
  
  /* Focus */
  &:focus-visible {
    outline: 2px solid var(--color-accent);
    outline-offset: 2px;
  }
  
  /* Disabled */
  &:disabled {
    opacity: var(--disabled-opacity);
    cursor: not-allowed;
  }
}
```

### 6. Iterative Design Loop

**IMPORTANT**: This is an iterative process. After each change:

#### 6.1 Initial Screenshot
```bash
# Before making changes to a component/page:
# 1. Navigate to the page using provided URL
# 2. Take "before" screenshot
# 3. Document current state

# If screenshot fails:
if [ $? -ne 0 ]; then
  echo "❌ CRITICAL: Cannot take screenshots"
  echo "Visual validation is impossible without screenshots"
  echo "Task must be terminated."
  exit 1
fi
```

#### 6.2 Implement Changes
- Apply new styles
- Ensure consistency with design system
- Be critical: refactor poor CSS patterns

#### 6.3 Visual Validation
```bash
# After implementing changes:
# 1. Navigate to the same page
# 2. Take "after" screenshot

# CRITICAL: If navigation or screenshot fails at ANY point:
if [ $? -ne 0 ]; then
  echo "❌ CRITICAL: Lost visual access to application"
  echo "Cannot validate changes without visual confirmation"
  echo "Possible causes:"
  echo "  - Browser session expired"
  echo "  - Application crashed"
  echo "  - Playwright MCP error"
  echo "Task must be terminated."
  exit 1
fi

# 3. Compare before/after
# 4. Test ALL interactive states:
#    - Hover over buttons, links
#    - Focus on form elements
#    - Check disabled states
#    - Verify loading states
# 5. Assess visual quality:
#    - Color consistency
#    - Spacing harmony
#    - Typography hierarchy
#    - Overall polish
```

#### 6.4 Critical Review
As both designer and developer, ask:
- Does this look professional and polished?
- Is the CSS clean and maintainable?
- Are there hardcoded values that should be variables?
- Is component-specific styling necessary or can it be generalized?
- Are all states properly implemented?

#### 6.5 Refinement
If issues found:
1. Take screenshot of the issue
2. Analyze root cause
3. Refactor CSS if needed (don't just patch)
4. Re-implement properly
5. Return to step 6.3 for validation

Repeat until the design is perfect.

### 7. Cross-Page Consistency Check

Navigate through all pages to ensure:
- Consistent color application
- Uniform component styling  
- Proper state implementations
- No missed elements

### 8. Update Style Guide

**SCOPE-APPROPRIATE DOCUMENTATION**:

#### For Full Transformations:
Update entire CLAUDE_DESIGNER.md comprehensively.

#### For Targeted Changes:
Add a concise entry to the change log:

```markdown
## Change Log

### [Date] - Save Button Enhancement
- Increased size: font 1.125rem, padding 0.75rem 1.5rem
- Added font-weight: 600 for prominence
- Files modified: components/Button.module.css

### [Date] - Header Color Adjustment  
- Changed background from #2a2a3e to #1a1a2e
- Maintained text contrast for accessibility
- Files modified: components/Header.module.css

### [Date] - Homepage Grid Layout
- Changed from flex to grid layout
- Implemented 2x2 grid (4 boxes total)
- Added responsive stacking on mobile
- Files modified: pages/Home.module.css
```

For targeted changes, focus on documenting:
- What changed
- Why it changed
- Where it changed
- Impact on user experience

```markdown
## Component Specifications

### Buttons
- Default: Background #B13BFF, text white
- Hover: Brightness 110%, translateY(-1px)
- Active: Brightness 90%, translateY(0)
- Focus: 2px #FFCC00 outline
- Disabled: 50% opacity

### Form Inputs
[Document each component similarly]

## Implementation Details
- Theme location: /styles/theme.css
- Component styles: [list key files]
- Global styles: /styles/globals.css

## Change Log
### [Date] - Dark Minimalist Theme
- Changed: Light theme to dark minimalist
- Updated: All interactive components
- Files modified: [count] files
- Colors: #090040, #471396, #B13BFF, #FFCC00
```

### 9. Quality Checks

```bash
# Run tests to ensure nothing broke
npm test

# Build to verify no errors
npm run build

# Type check if using TypeScript
npm run type-check
```

### 10. Final Visual Review

**MANDATORY**: Final visual confirmation is required.

Use Playwright to:
1. Navigate through entire application
2. Capture final screenshots
3. Create before/after comparison
4. Verify all requirements met

If visual review fails:
```bash
echo "⚠️ WARNING: Cannot complete final visual review"
echo "Changes have been implemented but not visually verified"
echo "Manual verification required"
```

## Design & Development Principles

### Adaptive Approach

**For Full Transformations**:
1. **Use Design Tokens**: Never hardcode values
2. **Create Reusable Patterns**: Avoid component-specific styles
3. **Compose, Don't Duplicate**: Use multiple classes rather than creating new ones
4. **Be Critical**: If you see poor CSS patterns, refactor them
5. **Consistency Over Creativity**: Maintain the design system

**For Targeted Changes**:
1. **Minimal Impact**: Change only what's necessary
2. **Maintain Consistency**: Ensure changes fit existing design
3. **Preserve Functionality**: Don't break existing features
4. **Consider Context**: Think about related components
5. **Document Changes**: Update style guide appropriately

### Visual Design Checklist

For every component/page:
- [ ] Consistent spacing (use spacing variables)
- [ ] Proper visual hierarchy
- [ ] Adequate contrast for readability
- [ ] Smooth transitions
- [ ] Professional appearance
- [ ] All states implemented and polished

## Important Patterns

### When Style Guide Shows Conflicts

If CLAUDE_DESIGNER.md documents a pattern that differs from implementation:

```bash
# Expand search to find all instances
echo "⚠️  Style conflict detected - expanding search..."

# Search for the conflicting pattern
grep -r "old-color-value" --include="*.css" --include="*.scss"
grep -r "old-class-name" --include="*.tsx" --include="*.jsx"

# Update all instances systematically
```

### State Implementation Priority

Always implement in this order:
1. Default state
2. Hover state  
3. Active state
4. Focus state
5. Disabled state
6. Error state (if applicable)
7. Loading state (if applicable)

### Visual Validation Checklist

For each component, verify:
- [ ] Colors match design brief
- [ ] Text is readable (contrast ratio)
- [ ] Interactive states are clear
- [ ] Transitions feel smooth
- [ ] No visual glitches
- [ ] Consistent with other components

## Success Criteria

The design transformation is complete when:

### Design Quality
- ✅ All pages have consistent, polished appearance
- ✅ Design system is cohesive and professional
- ✅ Visual hierarchy guides user attention
- ✅ All interactive states are smooth and refined
- ✅ Screenshots confirm design excellence

### Code Quality
- ✅ CSS uses design tokens consistently
- ✅ No unnecessary component-specific styles
- ✅ Clean, maintainable code structure
- ✅ Reusable patterns established
- ✅ No hardcoded values

### Documentation & Testing
- ✅ CLAUDE_DESIGNER.md fully documents new system
- ✅ Before/after screenshots captured
- ✅ All tests pass
- ✅ Build succeeds
- ✅ No accessibility issues introduced

## Common Issues & Solutions

### CRITICAL Issue: Playwright MCP Errors

**Browser Already in Use**
```
Error: Browser is already in use for .../mcp-chrome-profile
```
**Action**: STOP IMMEDIATELY
- Another process is using the browser profile
- Cannot proceed without visual access
- User must close other browser instances

**Navigation Failures**
```
No open pages available
Failed to navigate to URL
```
**Action**: STOP IMMEDIATELY
- Visual inspection is impossible
- Task cannot be completed

**Screenshot Failures**
```
Failed to take screenshot
Cannot capture page
```
**Action**: STOP IMMEDIATELY
- Cannot validate design changes
- Visual confirmation required

### Issue: Colors not applying
- Check CSS specificity
- Verify variable definitions
- Look for hardcoded values

### Issue: States not working
- Ensure proper CSS selectors
- Check for JavaScript interference  
- Verify transition properties

### Issue: Inconsistent application
- Search for inline styles
- Check for component variants
- Look for conditional styling

## Final Output

### For Full Transformations:
1. Transformed application with new design
2. Updated CLAUDE_DESIGNER.md with complete documentation
3. List of all modified files
4. Visual validation screenshots
5. Any identified issues or limitations

### For Targeted Changes:
1. Specific requested changes implemented
2. Brief update to CLAUDE_DESIGNER.md change log
3. List of modified files (usually 1-3 files)
4. Before/after screenshots of affected areas
5. Confirmation that change doesn't break other areas

## Quick Reference Examples

**Layout Change Request**: "Put boxes in a grid of 4"
- Find container element
- Implement CSS Grid with 2 columns
- Add responsive behavior
- Test on different screen sizes

**Size Change Request**: "Make save button bigger"
- Locate button styles
- Increase font-size and padding proportionally
- Verify it doesn't break layouts
- Check all instances

**Color Change Request**: "Make header darker"
- Find header styles
- Darken background color
- Ensure text contrast remains accessible
- Check dropdown/menu visibility

**Partial Theme Request**: "Darker theme but keep highlights"
- Darken backgrounds and surfaces
- Maintain bright accent colors
- Preserve text readability
- Keep interactive elements visible