/design-review - Frontend & Design Audit

Audit frontend code for design consistency, accessibility compliance, responsive behavior, and UX patterns - producing actionable findings with severity levels and file:line references.

Target: $ARGUMENTS

When to Use

• Before deploying UI changes to production
• After design system updates or theme changes
• When accessibility compliance is required (WCAG AA)
• After new contributor frontend PRs
• When UI inconsistencies are reported by users
• When migrating or updating component libraries
• NOT for: backend-only changes (use /codereview)
• NOT for: performance-only audits (use @perf directly)
• NOT for: creating new designs (use @designer)

Workflow

Step 1: Scope & Stack Detection

1. Identify target - Component, page, module, or full frontend
2. Detect CSS framework:

# Detect styling approach
grep -rl "tailwind\|@apply" . --include="*.css" --include="*.config.*" 2>/dev/null | head -5
grep -rl "styled-components\|@emotion\|css-in-js" . --include="*.ts" --include="*.tsx" 2>/dev/null | head -5
grep -rl "\.module\.css\|\.module\.scss" $TARGET 2>/dev/null | head -5

3. Detect component library:

# Check for UI libraries
grep -rn "shadcn\|radix\|headlessui\|chakra\|mantine\|vuetify\|primevue" package.json 2>/dev/null

4. Read design tokens if they exist (theme files, CSS variables, Tailwind config)

Step 2: Design Consistency Audit

Check for consistent use of design system:

# Find hardcoded colors (potential token violations)
grep -rn "#[0-9a-fA-F]\{3,8\}\|rgb(\|rgba(\|hsl(" $TARGET --include="*.tsx" --include="*.vue" --include="*.svelte" --include="*.css" 2>/dev/null | grep -v "node_modules\|\.config\." | head -30

# Find hardcoded pixel values (potential spacing violations)
grep -rn "margin:\|padding:\|gap:" $TARGET --include="*.tsx" --include="*.vue" --include="*.css" 2>/dev/null | grep "[0-9]px" | head -20

# Find hardcoded z-index
grep -rn "z-index:" $TARGET --include="*.tsx" --include="*.vue" --include="*.css" 2>/dev/null | head -10

Step 3: Accessibility Audit (WCAG AA)

Check for accessibility compliance:

# Missing alt text
grep -rn "<img" $TARGET --include="*.tsx" --include="*.vue" --include="*.svelte" 2>/dev/null | grep -v "alt=" | head -10

# Missing form labels
grep -rn "<input\|<select\|<textarea" $TARGET --include="*.tsx" --include="*.vue" 2>/dev/null | grep -v "aria-label\|aria-labelledby\|id=" | head -10

# onClick without keyboard handler
grep -rn "onClick=" $TARGET --include="*.tsx" 2>/dev/null | grep -v "button\|Button\|<a " | head -10

# Check for prefers-reduced-motion
grep -rn "prefers-reduced-motion" $TARGET --include="*.css" --include="*.tsx" --include="*.vue" 2>/dev/null | wc -l

Step 4: Responsive Review

Check responsive behavior:

# Find fixed widths (potential responsive issues)
grep -rn "width: [0-9]\+px" $TARGET --include="*.css" --include="*.tsx" --include="*.vue" 2>/dev/null | grep -v "max-width\|min-width" | head -15

# Check for responsive image usage
grep -rn "<img" $TARGET --include="*.tsx" --include="*.vue" 2>/dev/null | grep -v "srcset\|sizes\|next/image\|nuxt-img" | head -10

Step 5: UX Pattern Review

Check for complete UX states:

For each component/page in scope, verify that all applicable states are handled.

Step 6: Report & Findings

1. Classify every finding with severity (CRITICAL/HIGH/MEDIUM/LOW)
2. Include file:line references for every finding
3. Provide concrete fix for every finding
4. Calculate scores per category (0-100)

Severity Levels

Verification Protocol

Before claiming the review is complete:

1. All 4 audit dimensions were checked (consistency, accessibility, responsive, UX)
2. Every finding has a severity level and file:line reference
3. Every CRITICAL/HIGH finding has a concrete fix suggestion
4. Automated checks were run (grep for hardcoded values, missing alt text, etc.)
5. Design token/theme files were read before flagging consistency issues
6. At least one component was traced through all UX states (loading, empty, error, success)

Anti-Rationalization

Rules

1. Read-only - Never modify files during a review
2. Evidence required - Every finding needs a file:line reference
3. Token-first - Check if design tokens exist before flagging hardcoded values
4. Accessibility is non-negotiable - WCAG AA violations are always HIGH or CRITICAL
5. Framework-aware - Check for framework-specific patterns (next/image, NuxtImg, etc.)
6. State completeness - Every interactive component must handle loading, error, and empty states
7. No false positives - Verify that a "hardcoded value" isn't actually a CSS variable or token

Output

──── /design-review ────
Target: $ARGUMENTS
Stack: [framework] + [CSS approach] + [component library]

Consistency:   [score]/100 - [N findings]
Accessibility: [score]/100 - [N findings]
Responsive:    [score]/100 - [N findings]
UX Patterns:   [score]/100 - [N findings]

Severity:
  CRITICAL: N
  HIGH: N
  MEDIUM: N
  LOW: N

Top Findings:
1. [CRITICAL] [description] - [file:line]
2. [HIGH] [description] - [file:line]
3. [HIGH] [description] - [file:line]

Overall Score: [N]/100
Verdict: [PASS | PASS WITH NOTES | NEEDS WORK | FAIL]