---

name: ui-review description: "UI/UX audit skill for reviewing existing interfaces. Invoke when user asks to review UI, audit the frontend, check design quality, or review UX. Analyzes code structure, accessibility, visual consistency, responsiveness, and UX patterns. Outputs structured findings with severity and fix suggestions. Supports optional persona (e.g., 'as a senior designer')." allowed-tools:

• Bash
• Read
• Grep
• Glob metadata: token-cost-tier: instruction token-cost-estimate: 3000

---

/ui-review — UI/UX Audit

Usage

/ui-review [--target <path|url>] [--as <persona>] [--mode quick|standard|deep]

• --target — directory, file, or URL to review (default: current working directory)
• --as <persona> — load reviewer persona from .claude/personas/<persona>.md
• quick — layout + accessibility + obvious issues only
• standard — full audit across all 7 categories (default)
• deep — standard + component-level analysis + refactor suggestions

---

Step 0 — Preflight

Identify the UI stack:

# Check package.json for frameworks
grep -l "react\|vue\|svelte\|angular\|next\|nuxt" "${TARGET:-.}/package.json" 2>/dev/null | head -5

# Count UI files
find "${TARGET:-.}" -type f \( -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.html" \) 2>/dev/null | wc -l

Load persona if --as specified:

• Read .claude/personas/<persona>.md
• Apply that reviewer's lens to all findings below

---

Step 1 — Component Structure Analysis

find "${TARGET:-.}" -type f \( -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" \) 2>/dev/null | head -30

Check for:

• Component files > 200 lines (split concern smell)
• Missing prop validation / TypeScript types on UI components
• Inline styles (> 3 occurrences is a smell)
• God components (single file doing layout + state + data fetch)

grep -rn "style={{" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | wc -l
grep -rn "useState\|useEffect\|fetch\|axios" "${TARGET:-.}/src" --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10

---

Step 2 — Accessibility Audit (a11y)

grep -rn "<img " "${TARGET:-.}" --include="*.tsx" --include="*.jsx" --include="*.vue" --include="*.html" 2>/dev/null | grep -v 'alt=' | head -20

grep -rn "<button\|<a " "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | grep -v "aria-label\|aria-describedby\|title=" | head -20

grep -rn "onClick.*div\|onClick.*span" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10

grep -rn "tabIndex\|role=" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10

Flags:

• <img> without alt → HIGH (WCAG 1.1.1)
• Click handlers on div/span → MEDIUM (keyboard inaccessible)
• Missing aria-label on icon buttons → MEDIUM
• tabIndex="-1" on focusable elements → check intent

---

Step 3 — Responsiveness & Layout

grep -rn "px-\|width:\|height:" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" --include="*.css" 2>/dev/null | grep -v "min-\|max-\|%" | head -20

grep -rn "overflow:\s*hidden\|overflow-hidden\|truncate" "${TARGET:-.}" 2>/dev/null | head -10

grep -rn "@media\|sm:\|md:\|lg:\|xl:" "${TARGET:-.}" 2>/dev/null | wc -l

Flags:

• Fixed pixel widths on containers (not max-width) → MEDIUM
• No responsive breakpoints in layout components → MEDIUM
• Content overflow hidden without visible affordance → LOW

---

Step 4 — Visual Consistency

# Check for color/spacing values hardcoded outside design tokens
grep -rn "#[0-9a-fA-F]\{3,6\}\|rgb(\|rgba(" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" --include="*.css" 2>/dev/null | grep -v "theme\|token\|var(--\|tailwind" | head -20

# Check for magic spacing numbers
grep -rn "margin:\s*[0-9]\|padding:\s*[0-9]\|gap:\s*[0-9]" "${TARGET:-.}" --include="*.css" 2>/dev/null | head -20

Flags:

• Hardcoded color values outside design tokens → MEDIUM (consistency drift risk)
• Magic spacing numbers outside scale → LOW
• Multiple font sizes not from a defined scale → MEDIUM

---

Step 5 — UX Pattern Check

grep -rn "loading\|isLoading\|skeleton\|spinner" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10

grep -rn "error\|catch\|onError\|fallback" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10

grep -rn "empty\|isEmpty\|noData\|no.*result" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10

grep -rn "toast\|notification\|alert\|feedback" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10

Check coverage of UI states:

• [ ] Loading state
• [ ] Error state
• [ ] Empty state
• [ ] Success feedback

Missing states → MEDIUM (user confusion in edge cases).

---

Step 6 — Performance Red Flags

# Re-renders: anonymous functions in JSX
grep -rn "onClick={() =>" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | wc -l

# Missing keys in lists
grep -rn "\.map(" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | grep -v "key=" | head -20

# Large image without lazy loading
grep -rn "<img " "${TARGET:-.}" --include="*.tsx" --include="*.jsx" --include="*.html" 2>/dev/null | grep -v "loading=\|lazy" | head -10

Flags:

• .map() without key prop → HIGH (React reconciliation issues)
• Anonymous arrow functions in render at scale (> 20 occurrences) → LOW
• Images without loading="lazy" in long lists → LOW

---

Step 7 — Security in UI

grep -rn "dangerouslySetInnerHTML\|innerHTML\|document\.write\|v-html" "${TARGET:-.}" --include="*.tsx" --include="*.jsx" --include="*.vue" 2>/dev/null | head -10

grep -rn "localStorage\.\|sessionStorage\." "${TARGET:-.}" --include="*.tsx" --include="*.jsx" 2>/dev/null | grep -v "test\|spec" | head -10

• dangerouslySetInnerHTML without sanitization → CRITICAL (XSS)
• Sensitive data (tokens, keys) in localStorage → HIGH

---

Report Format

UI REVIEW REPORT
================
Target  : <path>
Stack   : <detected framework>
Files   : <N scanned>
Persona : <name if --as used>

## Findings (severity-ordered)

[FINDING] <CATEGORY>/<ID>: <issue name>
  Location : <file>:<line or component>
  Severity : CRITICAL | HIGH | MEDIUM | LOW
  Issue    : <what's wrong>
  Impact   : <user or dev impact>
  Fix      : <concrete suggestion>

## State Coverage
  Loading  : ✓ / ✗
  Error    : ✓ / ✗
  Empty    : ✓ / ✗
  Success  : ✓ / ✗

## Verdict
PASS | PASS_WITH_WARNINGS | NEEDS_WORK | CRITICAL_ISSUES

## Fix Plan (top 3 priority fixes)
1. [CRITICAL/HIGH finding] — specific change needed
2. ...
3. ...