design-review

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:

# 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:
2. Motivation for changes
3. Scope of implementation
4. Testing notes from developer
5. Expected behavior

1. Analyze code diff (if PR available):

``bash git diff origin/main...HEAD `` Identify modified files (components, styles, tests)

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

1. Review design principles (if project has custom guidelines):
2. Check project CLAUDE.md for design standards
3. Review component library documentation
4. 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:

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:

# 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