| name | review-design |
| description | Perform 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). This skill should be used when a user wants to review design quality, audit UX/UI, check visual hierarchy, typography, color, accessibility, components, or interaction design. Analysis only - identifies issues without modifying code. |
| metadata | {"author":"mgiovani","version":"1.0.0","source":"https://github.com/mgiovani/cc-arsenal"} |
| 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, AskUserQuestion |
| context | fork |
| agent | general-purpose |
Review Design
Cross-Platform AI Agent Skill
This skill works with any AI agent platform that supports the skills.sh standard.
Design Review
Comprehensive UX/UI/design quality analysis across 8 audit dimensions, each mapped to
authoritative standards. This skill performs analysis only - 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;
dimensions 5–8 are in references/criteria-interaction.md.
Anti-Hallucination Guidelines
CRITICAL: Design reviews must be based on ACTUAL evidence, never assumptions:
- Observe before claiming - Never report an issue without reading the code (static) or viewing the screenshot/snapshot (live)
- Evidence-based findings - Every finding cites a file path + line number (static) OR a screenshot region + DOM ref (live)
- Cite a criterion - Every finding maps to a criterion ID and an authoritative citation (WCAG SC, MD3 spec, etc.)
- Measure, don't estimate - Report actual values (contrast ratio, px size, ms duration), not guesses
- Applicable-only scoring - Only score dimensions that apply to the target; never penalize what cannot be observed
- State what was NOT checked - Every report ends with an explicit coverage gap section
- 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:
gh pr view <pr_number> --json files --jq '.files[].path'
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"
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.
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
agent-browser screenshot /tmp/review-design/page.png --full
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.
Agent assignments:
- 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:
- Read the relevant criteria reference for its dimensions (criteria-foundations.md or criteria-interaction.md)
- 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
- Record the measured value (contrast ratio, px, ms, dp) as evidence
- Map each finding to a criterion ID + citation (WCAG SC / MD3 / HIG / NN/g)
- Classify severity (Critical/High/Medium/Low)
- Provide a concrete fix (2-3 approaches with the target value)
Phase 4: Consolidate & Analyze Findings
After all agents complete:
- Collect findings from the 6 agents
- Deduplicate across agents (same element/criterion = one finding)
- Prioritize by severity:
- 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
- Map to dimension: Group findings under the 8 dimensions
- Applicable-only score: For each dimension that applies, score = passed criteria / applicable criteria. Skip dimensions that cannot be observed and say so.
- 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:
- Evidence —
file:line (static) or screenshot region + DOM ref (live)
- A measured value where one applies (ratio / px / ms / dp)
- A criterion ID + authoritative citation
- A concrete fix with the target value
- A justified severity
- No duplicates, no placeholder text ("TODO", "[example]", "lorem")
- An explicit "What Was NOT Checked" section
- Applicable-only scoring (no penalty for unobservable dimensions)
Usage
review-design --url https://example.com
review-design https://example.com
review-design --all --mode static
review-design 123
review-design abc123def
review-design https://staging.example.com --all --mode both
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
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
- 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 is 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
