Design Review

World-class design review following standards of top Silicon Valley companies (Stripe, Airbnb, Linear).

Parse Arguments

Output Path Configuration:

•If $ARGUMENTS is provided and non-empty: Use $ARGUMENTS as the output directory
•Otherwise: Use default ./reviews/design/

Git Analysis

GIT STATUS:

code

!`git status`

FILES MODIFIED:

code

!`git diff --name-only origin/HEAD...`

COMMITS:

code

!`git log --no-decorate origin/HEAD...`

DIFF CONTENT:

code

!`git diff --merge-base origin/HEAD`

Review the complete diff above to understand the scope of UI/UX changes.

Core Methodology

"Live Environment First" — Always assess the interactive experience before diving into static analysis or code. Prioritize the actual user experience over theoretical perfection.

Prerequisites

•A live preview environment (local dev server or staging URL)
•Playwright CLI for automated browser testing (refer to the playwright:playwright-cli skill for full command reference)

Review Phases

Execute each phase systematically. See WORKFLOW.md for detailed checklists.

Phase	Focus	Key Actions
0	Preparation	Analyze PR/description, review code diff, set up preview, configure viewport (1440x900)
1	Interaction	Execute user flows, test interactive states (hover/active/disabled), verify confirmations
2	Responsiveness	7 viewport tiers (375–1920px), between-breakpoint sweeps, zoom reflow (400%), container queries
3	Visual Polish	Layout alignment, typography hierarchy, color consistency, image quality
4	Accessibility	Automated axe-core scan + manual keyboard sequence (Tab order, focus traps, Enter/Space)
5	Robustness	Form validation, content overflow, loading/empty/error states, edge cases
6	Code Health	Component reuse, design tokens (no magic numbers), pattern adherence
7	Content & Console	Grammar, text clarity, browser console errors/warnings

Confidence & Signal Quality

Before reporting any finding, score confidence 1-10:

Confidence	Action	Requirement
9-10	Report	Measurable failure with concrete evidence (screenshot, axe output, contrast ratio)
7-8	Report	Design system violation with specific token/rule reference
5-6	Suppress	Plausible but speculative — no system rule to cite
Below 5	Discard	Aesthetic preference or subjective opinion

Finding caps: Max 8 meaningful findings (Blocker + High-Priority + Medium-Priority) and max 2 Nits per review. If more exist, keep the highest-confidence items and note "additional observations available on request."

Self-reflection: After generating all candidate findings, re-evaluate each in context of the full set. Remove redundant, low-signal, or opinion-only items. Apply false positive filtering from WORKFLOW.md.

Triage Matrix

Categorize every finding using confidence thresholds:

•[Blocker]: Measurable failure requiring immediate fix — broken layout, keyboard trap, contrast <4.5:1, element inaccessible, content overflow (confidence >=8)
•[High-Priority]: Documented system violation — wrong design token, WCAG AA violation, responsive breakage (confidence >=7)
•[Medium-Priority]: Inconsistency with evidence — spacing/alignment with comparison screenshot (confidence >=6)
•[Nit]: Minor aesthetic detail, optional — max 2 per review
•[Praise]: Acknowledge a good design decision — max 1 per review

Communication Principles

•Problems Over Prescriptions: Describe problems and their impact, not technical solutions. Example: Instead of "Change margin to 16px", say "The spacing feels inconsistent with adjacent elements."
•Evidence-Based: Provide screenshots for visual issues. Reference specific design tokens or WCAG criteria.
•Start Positive: Begin with acknowledgment of what works well.

Output Instructions

•Create output directory using Bash: mkdir -p {output-directory}
•Save the report to: {output-directory}/{YYYY-MM-DD}_{HH-MM-SS}_design-review.md

Include this header:

markdown

# Design Review Report

**Date**: {ISO 8601 date}
**Branch**: {current branch name}
**Commit**: {short commit hash}
**Reviewer**: Claude Code (design-review)

---

•Display the full report to the user in the chat
•Confirm the save: Report saved to: {output-directory}/{filename}

Resources

•WORKFLOW.md - Detailed phase-by-phase checklists, false positive filtering, confidence scoring guide, and report template
•EXAMPLES.md - Sample design review reports
•TROUBLESHOOTING.md - Common issues with environment, viewports, accessibility, and output