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 /shiplight: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:

# 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

#### A11Y-01: Insufficient color contrast
**File:** src/components/Button.tsx:23
**Current:** `background: #4A90D2` (contrast 3.1:1 against white)
**Fix:** `background: #2563EB` (contrast 4.8:1 against white) — maintains blue hue, meets AA
**Alternative:** `background: #1D4ED8` (contrast 7.1:1) — meets AAA

2. YAML regression test

- name: a11y-01-button-contrast
  description: Verify primary button meets WCAG AA contrast ratio
  severity: critical
  standard: WCAG-1.4.3-AA
  steps:
    - URL: /
    - VERIFY: Primary action buttons have sufficient color contrast (minimum 4.5:1 ratio for normal text)
      timeout_seconds: 15

Save all YAML tests to shiplight/tests/design-review.test.yaml.

Tips

Use inspect_page to read the DOM first — it's cheaper than screenshots and provides element indices for act.
For contrast checking, use JavaScript via act with window.getComputedStyle() to extract actual rendered colors.
Test keyboard navigation by using act with keyboard actions (Tab, Enter, Escape, Arrow keys).
Run this review at multiple breakpoints — many issues only appear at specific viewport sizes.
For i18n text expansion testing, use act with JavaScript to modify textContent to longer strings.
Close the session with close_session and use generate_html_report for a shareable evidence report.

design-review