design-review — quality + safety report

---
name: design-review
description: "7-phase frontend design review with accessibility (WCAG 2.1 AA), responsive testing, visual polish. Use for PR reviews, UI audits, or encountering contrast issues, broken layouts, accessibility violations, inconsistent spacing, missing focus states."

metadata:
  keywords:
    - design review
    - UI audit
    - frontend review
    - accessibility audit
    - WCAG compliance
    - responsive design
    - visual QA
    - UX review
    - component review
    - PR design check
    - layout issues
    - accessibility violations
    - contrast problems
    - broken responsive
    - interaction bugs
    - keyboard navigation
    - focus states
    - design system compliance
    - visual consistency
    - user experience

license: MIT
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
---
# 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
- **[Nitpick]** Loading state aesthetics or minor polish

---

### Phase 6: Code Health

**Objective:** Ensure maintainable, consistent implementation.

**For code patterns guide**: Load `references/code-health-patterns.md` when evaluating component reuse (DRY principle), design token usage (colors, spacing, typography), pattern consistency (naming, file structure, API patterns), or identifying red flags (duplication, magic numbers, broken abstractions).

**Quick review (3 criteria):**
1. **Component reuse**: No copy-paste, shared components extracted, composition over duplication
2. **Design tokens**: CSS variables for colors/spacing/typography (no magic numbers like `margin: 17px`), border radii consistent
3. **Pattern consistency**: Follows codebase patterns, naming conventions match, file structure organized

**Triage:** [High] Introduces tech debt/breaks patterns | [Medium] Missed reuse opportunities | [Nitpick] Code style preferences

---

### Phase 7: Content & Console

**Objective:** Verify polished details and technical correctness.

#### 7.1 Content Review

**Check for:**
- **Grammar and spelling**: No typos or grammatical errors
- **Clarity**: Labels and instructions are unambiguous
- **Tone consistency**: Matches brand voice (formal/casual)
- **Placeholder text**: Replaced with real content (no "Lorem ipsum")
- **Microcopy quality**: Helpful error messages, button labels, tooltips

**Common content issues:**
- Typos in UI text
- Placeholder text left in production
- Vague labels ("Submit" vs "Save Changes")
- Inconsistent terminology
- Unhelpful error messages ("Error" vs "Email format invalid")

#### 7.2 Console Check

**Test procedure:**
```bash
# Using Playwright MCP
mcp__playwright__browser_console_messages()

# Using Chrome DevTools
# Open DevTools → Console tab
```

**Look for:**
- **JavaScript errors**: Uncaught exceptions, null references
- **React warnings**: Key prop warnings, lifecycle issues
- **Network failures**: Failed API requests, 404s
- **Deprecation warnings**: Old API usage warnings
- **Performance warnings**: Slow renders, memory leaks

**Triage priorities:**
- **[Blocker]** Console errors breaking functionality
- **[High]** Grammar errors or confusing content in user-facing text
- **[Medium]** Console warnings or minor content issues
- **[Nitpick]** Content polish, minor console noise

---

## Communication Principles

### 1. Problems Over Prescriptions

Describe the **problem and its impact**, not the solution. Let the developer decide implementation.

**❌ Prescriptive (avoid):**
"Change the margin to 16px"

**✅ Problem-focused (preferred):**
"The spacing feels inconsistent with adjacent elements, creating visual clutter that distracts from the primary CTA. The current spacing breaks the established rhythm of the design system."

### 2. Triage Matrix

Categorize **every issue** with clear priority:

| Priority | Criteria | Action Required |
|----------|----------|----------------|
| **[Blocker]** | Critical failures, core functionality broken, critical accessibility violations | Must fix before merge |
| **[High-Priority]** | Significant UX issues, obvious design inconsistencies, WCAG vi

… (truncated)