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