| name | design-review |
| description | 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".
|
| disable-model-invocation | true |
| argument-hint | [output-directory] |
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
