review-design v1.1.1A

Immutable. This exact content never changes and is served at /api/v1/blob/ec2570754a5efeac.

---
name: review-design
description: Performs a comprehensive UX/UI/design quality audit of a live URL or a
  static codebase, mapped to authoritative standards (WCAG 2.2 AA, Material Design 3,
  Apple HIG, Nielsen Norman Group, Refactoring UI, Laws of UX). Use when a user wants
  to review design quality, audit UX/UI, or check visual hierarchy, typography, color,
  dark mode, shadows/elevation, buttons/icons, feedback states, motion, or accessibility
  contrast. Triggers on "design review", "UX audit", "accessibility audit", "check
  contrast", "review this against WCAG". Analysis only, cites evidence and a criterion
  for every finding, never modifies code. Not for correctness, security, dependency, or
  performance review (use review-code, review-security, review-deps, or review-perf).
  Not for pixel-diff visual regression testing against a baseline (use vrt-check).
metadata:
  summary: "UX/UI/design quality audit mapped to WCAG 2.2 AA plus the Material Design 3 and Apple HIG guidelines"
  author: mgiovani
  version: 1.1.1
disable-model-invocation: true
argument-hint: '[url|pr_number|commit_sha|--all] [--scope dimension] [--mode live|static|both]'
allowed-tools: Read, Grep, Glob, Bash(git *), Bash(gh *), Bash(agent-browser *), Task, TodoWrite
context: fork
agent: general-purpose
---

# Design Review

Comprehensive UX/UI/design quality analysis across 8 audit dimensions, each mapped to
authoritative standards. This skill only analyzes: it identifies design
issues, explains findings against a cited criterion, and suggests fix approaches without
making code changes.

It supports two input modes:

- Live mode: audits a running URL via the `agent-browser` CLI (screenshots + DOM/accessibility snapshot).
- Static mode: audits a codebase (CSS/components/design tokens) via Grep.

When both a URL and a codebase target are supplied, it runs both and emits two separate reports.

## Audit Taxonomy (8 Dimensions)

| # | Dimension | Key Standards |
|---|-----------|---------------|
| 1 | Visual Hierarchy & Layout | NN/g, Refactoring UI, Laws of UX, MD3 8pt grid |
| 2 | Typography | Butterick, Refactoring UI, MD3, Apple HIG |
| 3 | Color & Theming (incl. Dark Mode) | MD3 color roles, 60-30-10, WCAG 1.4.1/1.4.3 |
| 4 | Depth & Elevation (Shadows) | MD3 elevation, Refactoring UI, Josh Comeau |
| 5 | Components & Affordance (Buttons/Icons) | MD3 buttons/icons, Apple HIG, NN/g |
| 6 | Feedback & States | NN/g visibility-of-status, MD3 state layers |
| 7 | Motion & Microinteractions | NN/g animation, Laws of UX (Doherty), MD3 motion |
| 8 | Accessibility (cross-cutting) | WCAG 2.2 AA |

Measurable criteria for dimensions 1–4 are in [references/criteria-foundations.md](references/criteria-foundations.md);
dimensions 5–8 are in [references/criteria-interaction.md](references/criteria-interaction.md).

## Anti-hallucination guidelines

Design reviews must be based on actual evidence, never assumptions. This is critical:

1. Observe before claiming: never report an issue without reading the code (static) or viewing the screenshot/snapshot (live)
2. Evidence-based findings: every finding cites a file path + line number (static) OR a screenshot region + DOM ref (live)
3. Cite a criterion: every finding maps to a criterion ID and an authoritative citation (WCAG SC, MD3 spec, etc.)
4. Measure, don't estimate: report actual values (contrast ratio, px size, ms duration), not guesses. In static mode there is no rendered page to sample from, so compute the WCAG relative-luminance contrast ratio directly from the two hex/rgb values found in the CSS/tokens (formula in [references/agent-prompts.md](references/agent-prompts.md#computing-contrast-ratio-from-hexrgb-no-browser-needed)); never eyeball a ratio
5. Applicable-only scoring: only score dimensions that apply to the target; never penalize what cannot be observed
6. State what was NOT checked: every report ends with an explicit coverage gap section
7. No invented standards: only reference real WCAG SCs, MD3 specs, and HIG guidance

## Review Workflow

### Phase 0: Parse Arguments & Resolve Mode

Parse arguments to determine target and mode:

```
Arguments:
- <url>: A live URL to audit (http/https) → live mode
- <pr_number>: Files changed in a PR (e.g., "123", "#123") → static mode
- <commit_sha>: Files changed in a commit (e.g., "abc123") → static mode
- "--all" or a path or no args: Entire codebase → static mode
- "--mode [live|static|both]": Force a mode
- "--scope [dimension]": Focus on one dimension (e.g., typography, color, accessibility)
```

Mode resolution:
- A URL argument (or `--mode live`) → live audit.
- A PR / commit / `--all` / path (or `--mode static`) → static audit.
- Both a URL and a codebase target present (or `--mode both`) → run both, emit two reports.

For static PR/commit scope, get changed files:
```bash
# For PR
gh pr view <pr_number> --json files --jq '.files[].path'
# For commit
git diff-tree --no-commit-id --name-only -r <commit_sha>
```

### Phase 1: Discovery

Use an Explore agent (model: `haiku`) to detect the design system and tooling:

```
Use Task tool with Explore agent (model: haiku):
- prompt: "Discover the project's design system and front-end stack:
    1. Detect CSS approach: Tailwind, CSS Modules, styled-components, vanilla CSS, Sass
    2. Detect component/design system: Material UI, Chakra, Radix, shadcn/ui, Ant Design, custom
    3. Find design tokens: tailwind.config.*, theme files, CSS custom properties (:root { --* }), tokens.json
    4. Find existing a11y tooling: eslint-plugin-jsx-a11y, axe, pa11y, Storybook a11y addon
    5. Detect dark-mode support: prefers-color-scheme, .dark class, data-theme
    6. List the key UI directories (components/, styles/, app/, pages/)
    Return: a stack + design-system summary with the token source of truth."
- subagent_type: "Explore"
```

Without a Task tool, run this discovery yourself inline using the same 6 steps before proceeding.

**For live mode**, confirm the URL is reachable and `agent-browser` is installed:
```bash
agent-browser --version || echo "agent-browser not installed (npm install -g agent-browser)"
```
If `agent-browser` is missing, tell the user how to install it (`npm install -g agent-browser && agent-browser install`) and offer to fall back to static mode.

### Phase 2: Initialize Progress Tracking

Use TodoWrite to track progress across the 8 dimensions plus capture, consolidation, and report generation. One todo per dimension. Without TodoWrite, narrate phase/dimension transitions in your responses instead.

### Phase 3: Capture, then Spawn Parallel Audit Agents

**Live mode, capture first** (the agents analyze these artifacts):
```bash
mkdir -p /tmp/review-design
agent-browser open <url>
agent-browser snapshot -i > /tmp/review-design/snapshot.txt   # interactive elements + a11y tree
agent-browser screenshot /tmp/review-design/page.png --full     # full-page screenshot
# Optional, for inspected elements:
# agent-browser get styles @<ref>   # computed CSS
# agent-browser get box @<ref>      # bounding box (for touch-target size)
```
Capture additional viewports/pages if the user names them. Always `agent-browser close` when done.

**Then spawn 6 parallel Explore agents** (model: `sonnet`) covering the 8 dimensions. For the full per-agent prompts (live screenshot/snapshot analysis AND static grep patterns), see [references/agent-prompts.md](references/agent-prompts.md). Without a Task tool, run the 6 dimension analyses sequentially inline yourself, one after another, using the same per-agent prompts and criteria references.

Agent assignments:

| Agent | Covers |
| --- | --- |
| Agent 1 | Visual Hierarchy + Layout & Spacing (Dimension 1) |
| Agent 2 | Typography (Dimension 2) |
| Agent 3 | Color + Dark Mode (Dimension 3) |
| Agent 4 | Depth/Shadows + Components/Affordance (Dimensions 4, 5) |
| Agent 5 | Feedback & States + Motion/Microinteractions (Dimensions 6, 7) |
| Agent 6 | Accessibility, WCAG 2.2 AA (Dimension 8, cross-cutting) |

Each agent must:
1. Read the relevant criteria reference for its dimensions (criteria-foundations.md or criteria-interaction.md)
2. Live: visually analyze the screenshot and cross-reference the DOM/a11y snapshot. Static: grep CSS/components/tokens for measurable failures, then read each match to verify
3. Record the measured value (contrast ratio, px, ms, dp) as evidence
4. Map each finding to a criterion ID + citation (WCAG SC / MD3 / HIG / NN/g)
5. Classify severity (Critical/High/Medium/Low)
6. Provide a concrete fix (2-3 approaches with the target value)

### Phase 4: Consolidate & Analyze Findings

After all agents complete:

1. Collect findings from the 6 agents.
2. Deduplicate across agents (same element/criterion = one finding).
3. Prioritize by severity, using this table:

   | Severity | Criteria |
   | --- | --- |
   | Critical | WCAG AA failure blocking use (contrast < 3:1 on text, no keyboard focus, missing form labels), unusable touch targets |
   | High | WCAG AA contrast failures (< 4.5:1 body text), missing focus-visible, no reduced-motion support, broken hierarchy |
   | Medium | Off-grid spacing, un-tinted shadows, weak typographic scale, missing hover/active states |
   | Low | Polish: minor inconsistency, sub-optimal line length, icon-label spacing |

4. Map to dimension: group findings under the 8 dimensions.
5. Applicable-only score: for each dimension that applies, score = passed criteria / applicable criteria. Skip dimensions that cannot be observed and say so.
6. Statistics: total findings, by severity, by dimension; elements/files reviewed vs. those with issues.

### Phase 5: Generate Report(s)

Generate a markdown report per the template in [references/report-template.md](references/report-template.md).

- Live audit → `design-report-live.md`
- Static audit → `design-report-static.md`
- Both modes → produce **both** files.

### Phase 6: Verification & Quality Gate

Before presenting, verify every finding has:
1. Evidence: `file:line` (static) or screenshot region + DOM ref (live)
2. A measured value where one applies (ratio / px / ms / dp)
3. A criterion ID + authoritative citation
4. A concrete fix with the target value
5. A justified severity
6. No duplicates, no placeholder text ("TODO", "[example]", "lorem")
7. An explicit "What Was NOT Checked" section
8. Applicable-only scoring (no penalty for unobservable dimensions)

## Usage

```bash
# Live audit of a running site
review-design --url https://example.com
review-design https://example.com

# Static audit of the codebase
review-design --all --mode static
review-design 123                  # PR #123 changed files
review-design abc123def            # a commit

# Both: live + static (two reports)
review-design https://staging.example.com --all --mode both

# Focus a single dimension
review-design --url https://example.com --scope accessibility
review-design --all --scope typography
```

## Scope Options

`--scope` focuses the audit on one dimension: `hierarchy`, `layout`, `typography`,
`color`, `dark-mode`, `depth`, `components`, `feedback`, `motion`, `accessibility`.
If omitted, all 8 dimensions are audited.

## Additional Resources

- [references/criteria-foundations.md](references/criteria-foundations.md): measurable criteria for dimensions 1-4 (hierarchy, layout, typography, color, depth)
- [references/criteria-interaction.md](references/criteria-interaction.md): measurable criteria for dimensions 5-8 (components, feedback, motion, accessibility)
- [references/agent-prompts.md](references/agent-prompts.md): per-agent prompts (live + static) and grep patterns
- [references/report-template.md](references/report-template.md): live and static report templates

## What This Skill Does

- Audits UX/UI/design quality across 8 standards-mapped dimensions
- Works against a live URL (agent-browser) or a static codebase (grep)
- Measures real values (contrast, sizes, durations) as evidence
- Maps every finding to a criterion ID + authoritative citation
- Produces severity-ranked, fix-oriented report(s)

## What This Skill Does NOT Do

- Does not modify any code or design files
- Does not auto-fix issues or commit changes
- Does not run a full automated a11y scanner (axe/pa11y), it reasons from evidence
- Does not evaluate native mobile (SwiftUI/Compose/Flutter) static patterns (web-first; future extension)
- Does not guarantee 100% issue detection

## Limitations

| Limitation | Detail |
| --- | --- |
| Heuristic + measured | Combines tool measurements with expert heuristics; some judgment calls remain |
| Live mode | Needs a reachable URL and the `agent-browser` CLI installed |
| Static mode | Pattern-based; dynamic/runtime states may be missed |
| Screenshot analysis | Depends on render fidelity at the captured viewport |
| Expert review | Recommended for high-stakes or regulated interfaces |

## Standards References

- [WCAG 2.2](https://www.w3.org/TR/WCAG22/)
- [Material Design 3](https://m3.material.io/)
- [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines)
- [Nielsen Norman Group](https://www.nngroup.com/articles/)
- [Refactoring UI](https://www.refactoringui.com/)
- [Laws of UX](https://lawsofux.com/)