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)

Measurable criteria for dimensions 1–4 are in references/criteria-foundations.md; dimensions 5–8 are in 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 contrast ratio from the two hex/rgb values found in the CSS/tokens with the sibling product-design-tokens skill's scripts/contrast.py --pair FG BG (otherwise a python3 one-liner of the WCAG relative-luminance formula, given in references/agent-prompts.md); 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:

# 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:

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):

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. 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:

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.

• 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

# 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: measurable criteria for dimensions 1-4 (hierarchy, layout, typography, color, depth)
• references/criteria-interaction.md: measurable criteria for dimensions 5-8 (components, feedback, motion, accessibility)
• references/agent-prompts.md: per-agent prompts (live + static) and grep patterns
• 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

Standards References

• WCAG 2.2
• Material Design 3
• Apple Human Interface Guidelines
• Nielsen Norman Group
• Refactoring UI
• Laws of UX