ui-review

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