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:
!`git status`
FILES MODIFIED:
!`git diff --name-only origin/HEAD...`
COMMITS:
!`git log --no-decorate origin/HEAD...`
DIFF CONTENT:
!`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:
# 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
1---2name: design-review-113description: Comprehensive UI/UX design review with live environment testing, responsive validation, accessibility compliance (WCAG 2.1 AA), and visual consistency analysis using Playwright. Use when user runs /design-review, /review:design-review, requests a "design review", "UI review", "UX audit", or mentions "review the design", "check accessibility", "responsive testing".4---5
6# Design Review
7
8World-class design review following standards of top Silicon Valley companies (Stripe, Airbnb, Linear).
9
10## Parse Arguments
11
12**Output Path Configuration**:
13- If `$ARGUMENTS` is provided and non-empty: Use `$ARGUMENTS` as the output directory
14- Otherwise: Use default `./reviews/design/`
15
16## Git Analysis
17
18GIT STATUS:
19
20```
21!`git status`
22```
23
24FILES MODIFIED:
25
26```
27!`git diff --name-only origin/HEAD...`
28```
29
30COMMITS:
31
32```
33!`git log --no-decorate origin/HEAD...`
34```
35
36DIFF CONTENT:
37
38```
39!`git diff --merge-base origin/HEAD`
40```
41
42Review the complete diff above to understand the scope of UI/UX changes.
43
44## Core Methodology
45
46**"Live Environment First"** — Always assess the interactive experience before diving into static analysis or code. Prioritize the actual user experience over theoretical perfection.
47
48## Prerequisites
49
50- A live preview environment (local dev server or staging URL)
51- Playwright CLI for automated browser testing (refer to the `playwright:playwright-cli` skill for full command reference)
52
53## Review Phases
54
55Execute each phase systematically. See [WORKFLOW.md](WORKFLOW.md) for detailed checklists.
56
57| Phase | Focus | Key Actions |
58|-------|-------|-------------|
59| 0 | Preparation | Analyze PR/description, review code diff, set up preview, configure viewport (1440x900) |
60| 1 | Interaction | Execute user flows, test interactive states (hover/active/disabled), verify confirmations |
61| 2 | Responsiveness | 7 viewport tiers (375–1920px), between-breakpoint sweeps, zoom reflow (400%), container queries |
62| 3 | Visual Polish | Layout alignment, typography hierarchy, color consistency, image quality |
63| 4 | Accessibility | Automated axe-core scan + manual keyboard sequence (Tab order, focus traps, Enter/Space) |
64| 5 | Robustness | Form validation, content overflow, loading/empty/error states, edge cases |
65| 6 | Code Health | Component reuse, design tokens (no magic numbers), pattern adherence |
66| 7 | Content & Console | Grammar, text clarity, browser console errors/warnings |
67
68## Confidence & Signal Quality
69
70Before reporting any finding, score confidence 1-10:
71
72| Confidence | Action | Requirement |
73|------------|--------|-------------|
74| 9-10 | Report | Measurable failure with concrete evidence (screenshot, axe output, contrast ratio) |
75| 7-8 | Report | Design system violation with specific token/rule reference |
76| 5-6 | Suppress | Plausible but speculative — no system rule to cite |
77| Below 5 | Discard | Aesthetic preference or subjective opinion |
78
79**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."
80
81**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](WORKFLOW.md).
82
83## Triage Matrix
84
85Categorize every finding using confidence thresholds:
86
87- **[Blocker]**: Measurable failure requiring immediate fix — broken layout, keyboard trap, contrast <4.5:1, element inaccessible, content overflow (confidence >=8)
88- **[High-Priority]**: Documented system violation — wrong design token, WCAG AA violation, responsive breakage (confidence >=7)
89- **[Medium-Priority]**: Inconsistency with evidence — spacing/alignment with comparison screenshot (confidence >=6)
90- **[Nit]**: Minor aesthetic detail, optional — max 2 per review
91- **[Praise]**: Acknowledge a good design decision — max 1 per review
92
93## Communication Principles
94
951. **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."
962. **Evidence-Based**: Provide screenshots for visual issues. Reference specific design tokens or WCAG criteria.
973. **Start Positive**: Begin with acknowledgment of what works well.
98
99## Output Instructions
100
1011. **Create output directory** using Bash: `mkdir -p {output-directory}`
1022. **Save the report** to: `{output-directory}/{YYYY-MM-DD}_{HH-MM-SS}_design-review.md`
103
104Include this header:
105
106```markdown
107# Design Review Report
108
109**Date**: {ISO 8601 date}
110**Branch**: {current branch name}
111**Commit**: {short commit hash}
112**Reviewer**: Claude Code (design-review)
113
114---
115```
116
1173. **Display the full report** to the user in the chat
1184. **Confirm the save**: Report saved to: {output-directory}/{filename}
119
120## Resources
121
122- [WORKFLOW.md](WORKFLOW.md) - Detailed phase-by-phase checklists, false positive filtering, confidence scoring guide, and report template
123- [EXAMPLES.md](EXAMPLES.md) - Sample design review reports
124- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues with environment, viewports, accessibility, and output
majiayu000