ui-design-review

# UI Design Review Skill

## Overview

This skill provides prompting patterns, checklists, and templates for conducting UI design reviews using Gemini's multimodal vision capabilities.

## When to Use

- Reviewing screenshots, wireframes, or mockups
- Conducting accessibility audits
- Validating design system consistency
- Comparing implementation to design reference
- Analyzing UI patterns and usability

## Model Routing

### Gemini API Key Detection

```bash
# Check API key availability and select model
determine_gemini_model() {
  if [[ -n "$GEMINI_API_KEY" ]]; then
    echo "g/gemini-3-pro-preview"  # Direct Gemini API
  elif [[ -n "$OPENROUTER_API_KEY" ]]; then
    echo "google/gemini-3-pro-preview"  # OpenRouter
  else
    echo "ERROR: No API key available (need GEMINI_API_KEY or OPENROUTER_API_KEY)"
    return 1
  fi
}

GEMINI_MODEL=$(determine_gemini_model)
```

### Why `or/` Prefix for OpenRouter

The model ID `google/gemini-3-pro-preview` collides with Claudish's automatic routing:

| Model ID | Routes To | Requires |
|----------|-----------|----------|
| `google/gemini-*` | Gemini Direct | GEMINI_API_KEY |
| `google/gemini-*` | OpenRouter | OPENROUTER_API_KEY |
| `g/gemini-*` | Gemini Direct (explicit) | GEMINI_API_KEY |

**Rule**: Always use `or/` prefix when routing Google models through OpenRouter.

## Passing Images to Claudish

### Method 1: Image File Path (Recommended)

```bash
# Pass image file directly with --image flag
npx claudish --model "$GEMINI_MODEL" --image "$IMAGE_PATH" --quiet --auto-approve <<< "$ANALYSIS_PROMPT"

# Example
npx claudish --model "g/gemini-3-pro-preview" --image "screenshots/dashboard.png" --quiet --auto-approve <<< "Analyze this UI for usability issues."
```

### Method 2: Base64 Encoded (For Inline Images)

```bash
# Encode image to base64
IMAGE_B64=$(base64 -i "$IMAGE_PATH")

# Include in prompt with data URI
printf '%s' "[Image: data:image/png;base64,$IMAGE_B64]

Analyze this UI for usability issues." | npx claudish --stdin --model "$GEMINI_MODEL" --quiet --auto-approve
```

### Method 3: URL Reference (For Remote Images)

```bash
# Reference image by URL
printf '%s' "[Image: https://example.com/screenshot.png]

Analyze this UI for usability issues." | npx claudish --stdin --model "$GEMINI_MODEL" --quiet --auto-approve
```

## Prompting Patterns

### Pattern 1: General Usability Review

```markdown
Analyze this UI screenshot for usability issues.

**Image**: [attached or path]

**Focus Areas**:
1. Visual hierarchy - Is the most important content prominent?
2. Affordances - Do interactive elements look clickable/tappable?
3. Feedback - Is system status clearly communicated?
4. Consistency - Do similar elements behave similarly?
5. Error prevention - Are destructive actions guarded?

**Output Format**:
For each issue found:
- **Location**: Where in the UI
- **Issue**: What the problem is
- **Principle**: Which design principle it violates
- **Severity**: CRITICAL/HIGH/MEDIUM/LOW
- **Recommendation**: Specific fix
```

### Pattern 2: WCAG Accessibility Audit

```markdown
Audit this UI for WCAG 2.1 AA compliance.

**Image**: [attached or path]

**Checklist**:
1. **Perceivable**
   - [ ] Text contrast >= 4.5:1 (WCAG 1.4.3)
   - [ ] Non-text contrast >= 3:1 (WCAG 1.4.11)
   - [ ] Information not conveyed by color alone (WCAG 1.4.1)
   - [ ] Text resizable to 200% (WCAG 1.4.4)

2. **Operable**
   - [ ] Keyboard accessible (WCAG 2.1.1)
   - [ ] No keyboard traps (WCAG 2.1.2)
   - [ ] Focus visible (WCAG 2.4.7)
   - [ ] Touch targets >= 44x44px (WCAG 2.5.5)

3. **Understandable**
   - [ ] Labels present for inputs (WCAG 3.3.2)
   - [ ] Error identification clear (WCAG 3.3.1)
   - [ ] Instructions available (WCAG 3.3.2)

4. **Robust**
   - [ ] Valid structure implied (headings, regions)

**Output Format**:
| Criterion | Status | Notes | Fix |
|-----------|--------|-------|-----|
| 1.4.3 | PASS/FAIL | Details | Recommendation |
```

### Pattern 3: Design System Consistency Check

```markdown
Compare this implementation against the design system.

**Implementation Image**: [attached or path]
**Design System Reference**: [tokens, components, patterns]

**Validation Points**:
1. **Colors**
   - Primary, secondary, accent colors
   - Semantic colors (success, warning, error)
   - Background and surface colors

2. **Typography**
   - Font family usage
   - Size scale adherence
   - Weight usage (regular, medium, bold)
   - Line height consistency

3. **Spacing**
   - Margin scale (4, 8, 16, 24, 32, 48...)
   - Padding consistency
   - Gap between elements

4. **Components**
   - Button variants (primary, secondary, ghost)
   - Input styles (default, focus, error, disabled)
   - Card patterns

5. **Elevation**
   - Shadow levels
   - Border usage
   - Layer hierarchy

**Output Format**:
| Element | Expected | Actual | Deviation |
|---------|----------|--------|-----------|
| Button BG | #2563EB | #3B82F6 | Wrong shade |
```

### Pattern 4: Comparative Design Review

```markdown
Compare the implementation screenshot to the original design.

**Design Reference**: [Figma export or mockup]
**Implementation**: [Screenshot of built UI]

**Comparison Points**:
1. Layout and positioning accuracy
2. Color fidelity
3. Typography matching
4. Spacing precision
5. Component rendering
6. Responsive behavior (if multiple sizes)

**Output Format**:
## Match Analysis

**Overall Fidelity**: X/10

### Exact Matches
- [List elements that match perfectly]

### Deviations
| Element | Design | Implementation | Impact | Fix |
|---------|--------|----------------|--------|-----|
| CTA Button | #2563EB | #3B82F6 | Visual | Change to design color |

### Missing Elements
- [Elements in design but not in implementation]

### Extra Elements
- [Elements in implementation but not in design]
```

## Review Templates

### Quick Review (5 minutes)

Focus on critical issues only:
1. Can users complete the primary task?
2. Are there any major accessibility barriers?
3. Is the visual hierarchy clear?
4. Are interactive elements obviously interactive?

### Standard Review (15 minutes)

Full heuristic evaluation:
1. All Nielsen's 10 heuristics
2. WCAG AA key criteria
3. Visual design quality
4. Interaction design

### Comprehensive Review (30+ minutes)

Deep analysis including:
1. Full heuristic evaluation
2. Complete WCAG AA audit
3. Design system consistency
4. Competitive analysis context
5. User flow mapping

## Severity Guidelines

| Severity | User Impact | Examples | Action |
|----------|-------------|----------|--------|
| **CRITICAL** | Blocks task completion | Invisible submit button, broken flow | Fix immediately |
| **HIGH** | Major barrier | Fails WCAG AA, confusing navigation | Fix before release |
| **MEDIUM** | Noticeable friction | Inconsistent spacing, unclear labels | Fix in next sprint |
| **LOW** | Polish opportunity | Minor alignment, shade variance | Backlog |

## Integration with Multi-Model Validation

Use claudish CLI for multi-model design reviews:

```bash
claudish --model google/gemini-3-pro-preview --stdin --quiet <<EOF > ${SESSION_PATH}/reviews/design-review/gemini.md
Review the dashboard screenshot at screenshots/dashboard.png

Focus on usability and accessibility.
EOF
```

This enables:
- Running multiple design reviewers in parallel
- Consensus analysis on design issues
- Different model perspectives (Gemini vision, Claude reasoning)

## Best Practices

### DO
- Always validate image inputs exist before analysis
- Cite specific design principles for every issue
- Provide actionable, specific recommendations
- Prioritize by severity (CRITICAL first)
- Use Gemini for visual analysis (not guessing)

### DON'T
- Give vague aesthetic opinions ("looks bad")
- Overwhelm with LOW severity items
- Forget accessibility considerations
- Skip the principle citation
- Assume implementation details without seeing