design-review

What this skill does

# Design Review Skill

**Status**: Production Ready ✅
**Last Updated**: 2025-11-20
**Dependencies**: Playwright MCP or Chrome DevTools
**Methodology**: 7-phase systematic review (inspired by Stripe, Airbnb, Linear)

---

## Quick Start

### 1. Prerequisites Check

Before starting a design review, verify browser automation tools are available:

**Option A: Playwright MCP** (recommended for interactive testing)
- See the `playwright-testing` skill for Playwright setup
- Provides browser automation, screenshots, viewport testing, console monitoring

**Option B: Chrome DevTools CLI** (alternative for screenshots and performance)
- See the `chrome-devtools` skill for Puppeteer CLI setup
- Provides screenshot capture, performance analysis, network monitoring

For complete browser tools reference, see [references/browser-tools-reference.md](references/browser-tools-reference.md).

### 2. Understand the Review Scope

**For PR reviews:**
```bash
# Analyze git diff to understand scope
git diff --name-only origin/main...HEAD

# Read PR description for context
```

**For general UI reviews:**
Simply provide the preview URL and component/page description.

### 3. Execute 7-Phase Review

Follow the systematic checklist below. Each phase has specific objectives and testing procedures.

---

## The 7-Phase Review Methodology

### Phase 0: Preparation

**Objective:** Understand context and set up testing environment.

**Steps:**
1. **Read PR description** or review request to understand:
   - Motivation for changes
   - Scope of implementation
   - Testing notes from developer
   - Expected behavior

2. **Analyze code diff** (if PR available):
   ```bash
   git diff origin/main...HEAD
   ```
   Identify modified files (components, styles, tests)

3. **Set up live preview environment:**
   - Navigate to preview URL using browser tools
   - Set initial viewport: 1440x900 (desktop)
   - Take baseline screenshot for reference

4. **Review design principles** (if project has custom guidelines):
   - Check project CLAUDE.md for design standards
   - Review component library documentation
   - Note design system tokens and patterns

**When to skip:** For quick component reviews without git context.

---

### Phase 1: Interaction & User Flow

**Objective:** Verify the interactive experience works as expected.

**For complete interaction guide**: Load `references/interaction-patterns.md` when testing interactive states, forms, buttons, navigation flows, micro-interactions, modals, or keyboard navigation.

**Quick checklist:**
- Test 5 interactive states (default, hover, active, focus, disabled) for all elements
- Execute primary user flow (form submission, navigation, key actions)
- Verify destructive actions have confirmation dialogs
- Assess perceived performance (loading states, optimistic UI)

**Triage:** [Blocker] Critical flow broken | [High] Poor UX/missing focus states | [Medium] Missing polish | [Nitpick] Minor timing issues

---

### Phase 2: Responsiveness Testing

**Objective:** Ensure design works across all viewport sizes.

**For complete responsive guide**: Load `references/responsive-testing.md` when testing viewports, touch targets, mobile navigation, image responsiveness, or debugging horizontal scrolling.

**Test 3 viewports:**
- **Desktop (1440px)**: Optimal layout, full feature set
- **Tablet (768px)**: Graceful adaptation, 44×44px touch targets, collapsing nav
- **Mobile (375px)**: No horizontal scroll, 16px min text, mobile-friendly navigation

**Quick testing:**
```bash
mcp__playwright__browser_resize(width: 1440, height: 900)  # Desktop
mcp__playwright__browser_resize(width: 768, height: 1024)  # Tablet
mcp__playwright__browser_resize(width: 375, height: 667)   # Mobile
mcp__playwright__browser_take_screenshot(fullPage: true)
```

**Triage:** [Blocker] Layout broken | [High] Horizontal scroll/overlapping | [Medium] Suboptimal spacing | [Nitpick] Minor inconsistencies

---

### Phase 3: Visual Polish

**Objective:** Assess aesthetic quality and visual consistency.

**For design principles guide**: Load `references/visual-polish.md` when evaluating typography hierarchy, spacing/layout, color palette, alignment/grid, visual hierarchy, image quality, or S-Tier design standards.

**Quick evaluation (5 criteria):**
1. **Layout & spacing**: Grid alignment, 8px scale, design tokens (no magic numbers like 17px)
2. **Typography**: Clear H1>H2>H3 hierarchy, 1.5-1.7 line height, limited font weights
3. **Color**: Design system tokens, semantic usage (red=error, green=success), consistent brand
4. **Images**: High-res (no pixelation), correct aspect ratios, optimized sizes, alt text
5. **Visual hierarchy**: Primary actions stand out, eye flows naturally, strategic whitespace

**Triage:** [Blocker] Illegible text/broken images | [High] Obvious inconsistencies | [Medium] Spacing/alignment issues | [Nitpick] Aesthetic preferences

---

### Phase 4: Accessibility (WCAG 2.1 AA)

**Objective:** Ensure inclusive design for all users.

**For complete WCAG 2.1 AA checklist**: Load `references/accessibility-wcag.md` when verifying WCAG compliance, testing keyboard navigation, checking color contrast, auditing semantic HTML, or using accessibility testing tools (Lighthouse, axe, WAVE).

**Quick WCAG tests (4 principles):**

1. **Perceivable**: Alt text on images, color contrast (4.5:1 text, 3:1 UI components), semantic HTML
2. **Operable**: Keyboard navigation (Tab order logical, visible focus on ALL interactive elements, Enter/Space activation, Escape closes modals, no keyboard traps)
3. **Understandable**: Clear labels, helpful error messages, consistent navigation/terminology
4. **Robust**: Valid HTML, proper ARIA attributes (roles, states, properties)

**Critical tests:**
- Tab through entire page (verify focus states visible, logical order, no traps)
- Test with WebAIM Contrast Checker (all text/UI ≥4.5:1 or 3:1)
- Verify form labels associated with inputs (`<label for="id">` or `aria-label`)
- Check semantic HTML (h1→h2→h3 no skipping, `<button>` not `<div onClick>`)

**Triage:** [Blocker] No keyboard access to core features | [High] WCAG AA violations | [Medium] Semantic HTML issues | [Nitpick] Enhanced accessibility

---

### Phase 5: Robustness Testing

**Objective:** Verify handling of edge cases and error conditions.

**Test scenarios:**

#### 5.1 Form Validation

- Submit form with empty required fields
- Enter invalid data (wrong email format, out-of-range numbers)
- Test field-level validation (real-time feedback)
- Verify clear error messages with guidance
- Test successful submission flow (confirmation message)

#### 5.2 Content Overflow

- **Long text strings**: Very long names, emails, titles
- **Many items**: Large lists, tables with hundreds of rows
- **Deeply nested content**: Comments with many replies
- **Empty states**: No data to display (show helpful message)

**Common overflow issues:**
- Text breaking layout (overflowing containers)
- Truncation without ellipsis or tooltip
- Performance issues with large lists
- Missing empty state designs

#### 5.3 Loading & Error States

- **Loading states**: Skeleton screens, spinners, progress indicators
- **Error messages**: Clear, actionable error descriptions
- **Retry mechanisms**: Allow user to retry failed operations
- **Timeout handling**: Graceful handling of slow/failed requests
- **Optimistic updates**: Immediate feedback, rollback on failure

**Test procedure:**
```bash
# Simulate slow network
# Check browser DevTools Network tab → throttling

# Force error states
# Test with invalid API responses or network failures
```

**Common problems:**
- No loading indicators (appears frozen)
- Vague error messages ("Error occurred")
- No retry mechanism after failures
- Layout jumps when content loads

**Triage priorities:**
- **[Blocker]** Crashes or complete failures under edge cases
- **[High]** Poor error handling or confusing states
- **[Medium]** Missing edge case handling or minor issues
- **[Nitpic