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

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.)
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)
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-align for body paragraphs

Category E: Internationalization Readiness (I18N)

Check ID	Check	Standard	Method
I18N-01	No hardcoded strings in components	i18n best practice	Scan source code for string literals in JSX/templates
I18N-02	Layout handles text expansion (+30%)	i18n design	Inject longer text strings, check for overflow
I18N-03	RTL layout support (if applicable)	i18n	Toggle `dir="rtl"` , check layout adaptation
I18N-04	Date/number formatting uses locale	i18n	Check for hardcoded date/number formats
I18N-05	Font stack includes CJK/Unicode fallbacks	i18n typography	Check font-family declarations
I18N-06	Icons/images don't contain text	i18n	Visual inspection of image content

Browser validation: Use JavaScript to modify

dir

attribute, inject longer text, change locale settings. Screenshot at each state.

Phase 4: Report

Generate a structured report saved to

shiplight/reports/design-review-{date}.md

markdown

# Design Review Report
**Date:** {date}
**URL:** {url}
**Pages reviewed:** {list}
**Breakpoints tested:** {list}

## Overall Score: {X}/10 | Confidence: {X}%

## Score Breakdown
| Category | Score | Findings |
|----------|-------|----------|
| Responsive (RES) | 7/10 | 2 high, 1 medium |
| Accessibility (A11Y) | 5/10 | 1 critical, 3 high |
| Visual Consistency (VIS) | 8/10 | 1 medium |
| Typography (TYP) | 9/10 | 1 low |
| i18n Readiness (I18N) | 6/10 | 2 medium |

## Findings

### CRITICAL

#### A11Y-01: Insufficient color contrast on primary buttons
- **Standard:** WCAG 1.4.3 AA (minimum 4.5:1)
- **Finding:** Primary button (#4A90D2 on #FFFFFF) has contrast ratio 3.1:1
- **Evidence:** [screenshot with annotation]
- **Pages affected:** All pages with primary CTA
- **Confidence:** 97%

### HIGH
...

### MEDIUM
...

### LOW / INFO
...

Confidence Scoring

90-100%: Browser-validated, measured programmatically (contrast ratio calculated, element size measured)
70-89%: Strong evidence from DOM inspection, screenshot supports finding
50-69%: Heuristic-based, may vary by context (e.g., "spacing looks inconsistent")
Below 50%: Don't report

Phase 5: Remediate

For each finding, provide:

1. Fix guidance