design-review

What this skill does

# Design Review

Evaluate your application's visual quality and usability against established design standards. This review catches issues that typically require a trained designer's eye — responsive breakpoints, accessibility compliance, visual hierarchy, spacing consistency, and internationalization readiness.

## When to use

Use `/design-review` when:
- Shipping UI without a designer reviewing it
- Before a launch or demo
- After significant UI changes or redesigns
- Checking accessibility compliance (WCAG 2.1 AA)
- Validating responsive behavior across devices

## Standards Referenced

- **WCAG 2.1 Level AA** — Web Content Accessibility Guidelines
- **Material Design** / **Human Interface Guidelines** — spacing, touch targets, typography scales
- **ISO 9241-110** — Interaction principles (suitability, self-descriptiveness, conformity)
- **APCA** — Advanced Perceptual Contrast Algorithm (next-gen contrast)

## Phase Overview

```
Phase 1: EDUCATE   → Brief context on what we check and why
Phase 2: SCOPE     → Identify pages, breakpoints, and focus areas
Phase 3: ANALYZE   → Browser-based checks with evidence capture
Phase 4: REPORT    → Findings with screenshots, scores, confidence
Phase 5: REMEDIATE → Fix guidance + YAML regression tests
```

---

## Phase 1: Educate

> **Why this matters:** 94% of first impressions are design-related. Poor visual quality erodes trust even when functionality is correct. Accessibility issues affect 15-20% of users and carry legal risk (ADA lawsuits increased 300% since 2018).

This review checks your app against objective, measurable design criteria — not subjective taste. Every finding references a specific standard.

---

## Phase 2: Scope

### Gather context

1. **Auto-detect** — scan the project for:
   - Framework (React, Vue, Next.js, etc.)
   - CSS approach (Tailwind, CSS modules, styled-components, etc.)
   - Design system in use (if any)
   - Route structure → list of pages
   - Existing a11y tooling (eslint-plugin-jsx-a11y, axe-core, etc.)

2. **Ask the user** (one at a time, with auto-detected defaults):
   - **Target URL**: Where is the app running? (auto-detect dev server)
   - **Key pages**: Which pages matter most? (recommend top 3-5 from routes)
   - **Target devices**: Desktop only? Mobile-first? Both? (default: both)
   - **Brand guidelines**: Any specific colors, fonts, or design system? (default: evaluate against general best practices)
   - **Focus areas**: Any known concerns? (optional)

3. **Define breakpoints** to test:
   - Mobile: 375px (iPhone SE), 390px (iPhone 14)
   - Tablet: 768px (iPad)
   - Desktop: 1280px, 1920px
   - (Adjust based on user's target audience)

---

## Phase 3: Analyze

Open a browser session with `new_session` using `record_evidence: true`. For each page in scope, run the following check categories.

### Category A: Responsive Design (RES)

| Check ID | Check | Standard | Method |
|----------|-------|----------|--------|
| RES-01 | Viewport meta tag present | Mobile best practice | Inspect `<meta name="viewport">` |
| RES-02 | No horizontal overflow at any breakpoint | Responsive design | Resize viewport, check for horizontal scrollbar |
| RES-03 | Touch targets ≥ 48x48px on mobile | WCAG 2.5.8 / Material Design | Measure interactive element sizes at mobile breakpoint |
| RES-04 | Text remains readable without zoom at 375px | WCAG 1.4.4 | Check font sizes ≥ 16px for body text on mobile |
| RES-05 | Navigation is accessible at all breakpoints | Usability | Verify nav collapses/adapts, hamburger menu works |
| RES-06 | Images scale appropriately | Responsive images | Check for `srcset`/`sizes` or CSS containment |
| RES-07 | No content truncation without indication | Usability | Check text overflow, ellipsis with tooltip or expand |
| RES-08 | Form inputs are usable on mobile | Usability | Check input sizes, proper input types (tel, email) |

**Browser validation:** For each breakpoint, use `act` to resize the viewport, then `inspect_page` to capture DOM and screenshot. Check for overflow elements, measure sizes via JavaScript.

### Category B: Accessibility (A11Y)

| Check ID | Check | Standard | Method |
|----------|-------|----------|--------|
| A11Y-01 | Color contrast ratio ≥ 4.5:1 (normal text) | WCAG 1.4.3 AA | Extract computed colors, calculate ratio |
| A11Y-02 | Color contrast ratio ≥ 3:1 (large text ≥ 18pt) | WCAG 1.4.3 AA | Same as above for large text |
| A11Y-03 | All images have alt text | WCAG 1.1.1 | Check `<img>` elements for `alt` attribute |
| A11Y-04 | Form inputs have associated labels | WCAG 1.3.1 | Check `<label for="">` or `aria-label` |
| A11Y-05 | Heading hierarchy is logical (h1→h2→h3) | WCAG 1.3.1 | Extract heading levels, check sequence |
| A11Y-06 | Focus is visible on all interactive elements | WCAG 2.4.7 | Tab through elements, check focus ring visibility |
| A11Y-07 | Keyboard navigation works (Tab, Enter, Escape) | WCAG 2.1.1 | Navigate entire page via keyboard |
| A11Y-08 | Skip navigation link present | WCAG 2.4.1 | Check for skip-to-content link |
| A11Y-09 | ARIA roles used correctly | WCAG 4.1.2 | Check for misused/redundant ARIA |
| A11Y-10 | Page has lang attribute | WCAG 3.1.1 | Check `<html lang="">` |
| A11Y-11 | Modal focus trapping works | WCAG 2.4.3 | Open modal, verify Tab stays within |
| A11Y-12 | Error messages are associated with inputs | WCAG 3.3.1 | Check `aria-describedby` or `aria-errormessage` |
| A11Y-13 | Reduced motion respected | WCAG 2.3.3 | Check for `prefers-reduced-motion` media query |
| A11Y-14 | No seizure-inducing content (>3 flashes/sec) | WCAG 2.3.1 | Visual inspection of animations |

**Browser validation:** Use `inspect_page` to extract the DOM. Run JavaScript via `act` to compute contrast ratios, check ARIA attributes, extract heading hierarchy. Use keyboard navigation (Tab, Enter, Escape) to test focus management.

### Category C: Visual Consistency (VIS)

| Check ID | Check | Standard | Method |
|----------|-------|----------|--------|
| VIS-01 | Consistent spacing scale | Design systems | Extract margins/paddings, check for consistent scale (4px/8px grid) |
| VIS-02 | Typography scale is consistent | Typographic hierarchy | Extract font sizes, check for consistent ratio/scale |
| VIS-03 | Color palette is limited and intentional | Design best practice | Extract all used colors, flag if >10 unique non-gray colors |
| VIS-04 | Interactive elements have consistent styling | Consistency | Compare button styles, link styles across pages |
| VIS-05 | Alignment grid is consistent | Layout | Check for misaligned elements that break the visual grid |
| VIS-06 | Loading states exist for async operations | UX best practice | Trigger async actions, verify loading indicators |
| VIS-07 | Empty states are handled | UX best practice | Navigate to pages with no data, check for meaningful empty states |
| VIS-08 | Error states are styled consistently | UX best practice | Trigger validation errors, check styling |
| VIS-09 | Dark mode consistency (if applicable) | Design systems | Toggle dark mode, check for un-themed elements |

**Browser validation:** Use JavaScript to extract computed styles, compare across elements and pages. Screenshot comparison between pages for visual consistency.

### Category D: Typography & Readability (TYP)

| Check ID | Check | Standard | Method |
|----------|-------|----------|--------|
| TYP-01 | Body text 16-20px | Readability research | Extract computed font-size |
| TYP-02 | Line height 1.4-1.6 for body text | Readability | Extract computed line-height |
| TYP-03 | Line length 45-75 characters | Readability (Bringhurst) | Measure character count per line |
| TYP-04 | Font loading strategy (FOUT/FOIT prevention) | Web performance | Check font-display CSS, preload hints |
| TYP-05 | Sufficient hierarchy levels (≥3 distinct sizes) | Typography | Extract and count distinct heading sizes |
| TYP-06 | Text is left-aligned (not justified) for body | Readability | Check text-al