design-review

name	design-review
description	UI and design review: evaluate visual quality, responsive behavior, accessibility, color/contrast, typography, layout consistency, and i18n readiness using browser-based validation against industrial standards.

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-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.