Design Review Skill | Agent Skills

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

Agent Skills: Design Review

Install this agent skill to your local

Skill Files