/ui-review

name: ui-review
description: >
  Review UI designs and implementations for accessibility, consistency, usability, and visual quality.
  Use when asked to review a design, audit accessibility, check UI consistency, compare implementation
  against mockups, or evaluate a user interface.

UI Review

Systematic UI/UX review methodology for designs (in Penpot) and implementations (in code).

Process

1. **Understand context** — what product, who are the users, what's the goal of this screen? 2. **Gather materials** — pull the Penpot designs and/or the live implementation 3. **Run the checklist** — score each category 4. **Report** — use the structured output format

Review Checklist

1. Accessibility (WCAG 2.1 AA)

Color & Contrast

• [ ] Text contrast ≥ 4.5:1 against background (normal text)
• [ ] Text contrast ≥ 3:1 against background (large text ≥ 24px or 18.67px bold, equivalent to WCAG 18pt/14pt)
• [ ] UI component contrast ≥ 3:1 against adjacent colors (borders, icons, controls)
• [ ] Information not conveyed by color alone (use icons, patterns, labels too)
• [ ] Tested with color blindness simulation (protanopia, deuteranopia, tritanopia)

Keyboard Navigation

• [ ] All interactive elements reachable via Tab key
• [ ] Logical tab order (left-to-right, top-to-bottom, follows visual flow)
• [ ] Visible focus indicator on all focusable elements (no outline:none without replacement)
• [ ] Escape closes modals/dropdowns
• [ ] Enter/Space activates buttons and links
• [ ] Arrow keys navigate within composite widgets (tabs, menus, radio groups)

Screen Reader

• [ ] All images have meaningful alt text (or aria-hidden if decorative)
• [ ] Form inputs have associated labels (not just placeholder text)
• [ ] ARIA landmarks used (main, nav, aside, footer)
• [ ] Dynamic content changes announced (aria-live regions for toasts, errors)
• [ ] Headings follow a logical hierarchy (h1 → h2 → h3, no skipping)

Motion & Interaction

• [ ] Animations respect `prefers-reduced-motion`
• [ ] No content that flashes more than 3 times per second
• [ ] Touch targets ≥ 44x44px on mobile (WCAG 2.1 AAA — optional but recommended)
• [ ] Adequate time for timed interactions (or ability to extend)

2. Design System Compliance

• [ ] All colors from the token palette (no hex codes outside the system)
• [ ] Typography uses defined scale (no arbitrary font sizes)
• [ ] Spacing uses the 4px grid (no magic numbers)
• [ ] Components match design system variants (no custom one-offs)
• [ ] Icons from the approved set (Lucide)
• [ ] Border radius from token scale
• [ ] Shadows from token scale

3. Layout & Responsiveness

• [ ] Works at all breakpoints: 375px, 768px, 1280px, 1536px
• [ ] No horizontal scroll on mobile
• [ ] Text remains readable at all sizes (no text smaller than 12px)
• [ ] Touch-friendly spacing on mobile (no cramped click targets)
• [ ] Images and media scale properly
• [ ] Content hierarchy maintained across breakpoints

4. Interaction Design

• [ ] Clear affordances (buttons look clickable, links look linkable)
• [ ] Hover states on all interactive elements (desktop)
• [ ] Loading states for async operations (skeleton screens or spinners)
• [ ] Empty states designed (no blank pages — always guide the user)
• [ ] Error states with clear recovery actions
• [ ] Success feedback for completed actions
• [ ] Confirmation for destructive actions (delete, discard)
• [ ] Undo available where possible

5. Visual Quality

• [ ] Consistent alignment (nothing looks "off" by a pixel)
• [ ] Visual hierarchy clear (primary action stands out, secondary is quieter)
• [ ] Whitespace used effectively (not cramped, not wastefully sparse)
• [ ] Typography hierarchy clear (heading → subheading → body → caption)
• [ ] Icon sizes consistent and proportional to surrounding text
• [ ] No orphaned words in headings (line breaks make sense)

6. Content & Copy

• [ ] Labels are clear and concise (no jargon)
• [ ] Error messages explain what went wrong AND how to fix it
• [ ] Button text describes the action ("Save changes" not "Submit")
• [ ] Placeholder text is a hint, not a label
• [ ] Consistent terminology throughout (don't mix "delete"/"remove"/"trash")

Output Format

## UI Review — [Screen/Component Name]

**Reviewed:** [date]
**Context:** [product, screen, purpose]
**Overall:** 🟢 Good | 🟡 Needs Work | 🔴 Significant Issues

### Accessibility
Score: X/10
[Specific findings with severity]

### Design System Compliance
Score: X/10
[Specific findings]

### Layout & Responsiveness
Score: X/10
[Specific findings]

### Interaction Design
Score: X/10
[Specific findings]

### Visual Quality
Score: X/10
[Specific findings]

### Content & Copy
Score: X/10
[Specific findings]

### 🔴 Must Fix
1. [Critical issues — accessibility violations, broken layouts]

### 🟡 Should Fix
1. [Important issues — inconsistencies, missing states]

### 🔵 Nice to Have
1. [Polish items — minor alignment, copy tweaks]

### ✅ What's Working Well
1. [Call out good patterns — reinforces what to keep doing]

Quick Review (for smaller changes)

For minor changes or single components, use a shortened format:

1. **Accessibility** — contrast OK? Keyboard accessible? Screen reader friendly? 2. **Consistency** — matches the design system? 3. **States** — all states present? (hover, focus, disabled, error, loading) 4. **Responsive** — works on mobile? 5. **Copy** — labels clear and actionable?

Report as: ✅ Pass | 🟡 Minor issues | 🔴 Blocking issues