Design Review

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

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)

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)

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)

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)

Category E: Internationalization Readiness (I18N)

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.