Design Review

Design Review

World-class design review following standards of top Silicon Valley companies (Stripe, Airbnb, Linear).

Parse Arguments

Output Path Configuration:

• If $ARGUMENTS is provided and non-empty: Use $ARGUMENTS as the output directory
• Otherwise: Use default ./reviews/design/

Git Analysis

GIT STATUS:

!`git status`

FILES MODIFIED:

!`git diff --name-only origin/HEAD...`

COMMITS:

!`git log --no-decorate origin/HEAD...`

DIFF CONTENT:

!`git diff --merge-base origin/HEAD`

Review the complete diff above to understand the scope of UI/UX changes.

Core Methodology

"Live Environment First" — Always assess the interactive experience before diving into static analysis or code. Prioritize the actual user experience over theoretical perfection.

Prerequisites

• A live preview environment (local dev server or staging URL)
• Playwright CLI for automated browser testing (refer to the playwright:playwright-cli skill for full command reference)

Review Phases

Execute each phase systematically. See WORKFLOW.md for detailed checklists.

Confidence & Signal Quality

Before reporting any finding, score confidence 1-10:

Finding caps: Max 8 meaningful findings (Blocker + High-Priority + Medium-Priority) and max 2 Nits per review. If more exist, keep the highest-confidence items and note "additional observations available on request."

Self-reflection: After generating all candidate findings, re-evaluate each in context of the full set. Remove redundant, low-signal, or opinion-only items. Apply false positive filtering from WORKFLOW.md.

Triage Matrix

Categorize every finding using confidence thresholds:

• [Blocker]: Measurable failure requiring immediate fix — broken layout, keyboard trap, contrast <4.5:1, element inaccessible, content overflow (confidence >=8)
• [High-Priority]: Documented system violation — wrong design token, WCAG AA violation, responsive breakage (confidence >=7)
• [Medium-Priority]: Inconsistency with evidence — spacing/alignment with comparison screenshot (confidence >=6)
• [Nit]: Minor aesthetic detail, optional — max 2 per review
• [Praise]: Acknowledge a good design decision — max 1 per review

Communication Principles

1. Problems Over Prescriptions: Describe problems and their impact, not technical solutions. Example: Instead of "Change margin to 16px", say "The spacing feels inconsistent with adjacent elements." 2. Evidence-Based: Provide screenshots for visual issues. Reference specific design tokens or WCAG criteria. 3. Start Positive: Begin with acknowledgment of what works well.

Output Instructions

1. Create output directory using Bash: mkdir -p {output-directory} 2. Save the report to: {output-directory}/{YYYY-MM-DD}_{HH-MM-SS}_design-review.md

Include this header:

# Design Review Report

**Date**: {ISO 8601 date}
**Branch**: {current branch name}
**Commit**: {short commit hash}
**Reviewer**: Claude Code (design-review)

---

3. Display the full report to the user in the chat 4. Confirm the save: Report saved to: {output-directory}/{filename}

Resources

• WORKFLOW.md - Detailed phase-by-phase checklists, false positive filtering, confidence scoring guide, and report template
• EXAMPLES.md - Sample design review reports
• TROUBLESHOOTING.md - Common issues with environment, viewports, accessibility, and output

Design Review Examples

Invocation

# Default output path
/review:design-review

# Custom output path
/review:design-review custom/reviews/

Sample Report — Mixed Findings

# Design Review Report

**Date**: 2025-08-05T11:00:00Z
**Branch**: feat/settings-page
**Commit**: n4o5p6q
**Reviewer**: Claude Code (design-review)

---

## Summary

The new settings page is well-structured with clean visual hierarchy and intuitive grouping of related options. The form interactions are responsive and the success state feedback is clear. However, there are accessibility issues with keyboard navigation and a responsive layout break on tablet viewports that should be addressed before merge.

## Findings

### Blockers

None.

### High-Priority

- **[High-Priority]** The settings form sections are not keyboard-accessible — Tab key skips from the navigation sidebar directly to the footer, bypassing all form controls. (Confidence: 10/10)
  - **Impact**: Users relying on keyboard navigation cannot access any settings. Violates WCAG 2.1 AA Success Criterion 2.1.1 (Keyboard).
  - **Evidence**: focus-1.png → focus-2.png shows Tab jumping from sidebar to footer

- **[High-Priority]** On tablet portrait viewport (768px), the two-column layout for "Notification Preferences" overlaps with the sidebar, causing form labels to be cut off. (Confidence: 9/10)
  - **Impact**: Users on tablet devices cannot read option labels, making the form unusable at this breakpoint.
  - **Reference**: Layout breakpoint rule at `@media (min-width: 768px)` does not account for sidebar width.
  - **Evidence**: settings-tablet-overlap.png

### Medium-Priority / Suggestions

- **[Medium]** The "Delete Account" button has the same visual weight as the "Save Changes" button. Both are solid blue buttons at the same size. (Confidence: 7/10)
  - **Context**: Destructive actions should be visually differentiated from primary actions to prevent accidental clicks. The design system uses `--color-danger` for destructive actions.

### Praise

- **[Praise]** Clean use of `fieldset`/`legend` for form grouping — correct semantic HTML that makes the form structure clear to assistive technology.

### Nitpicks

- **Nit:** The spacing between the "Profile" and "Security" section headers (32px) is different from the spacing between "Security" and "Notifications" (24px). Design system specifies `--spacing-xl` (32px) for section gaps.

## Responsive Summary

| Viewport | Status | Notes |
|----------|--------|-------|
| Small mobile (375px) | Pass | Single column, good touch targets |
| Standard mobile (390px) | Pass | Consistent with 375px |
| Tablet portrait (768px) | Issues | Two-column overlap with sidebar |
| Tablet landscape (1024px) | Pass | Three-column layout works |
| Laptop (1280px) | Pass | Clean layout, proper spacing |
| Desktop (1440px) | Pass | Clean layout, proper spacing |
| Large monitor (1920px) | Pass | Content centered, max-width applied |
| Zoom reflow (400%) | Pass | Single column, no horizontal scroll |

## Accessibility Summary

### Automated (axe-core)

| Check | Status | Notes |
|-------|--------|-------|
| Color contrast | Pass | All text meets 4.5:1 ratio |
| Image alt text | Pass | No images in settings page |
| Form labels | Pass | All inputs have associated labels |
| ARIA validity | Pass | No ARIA errors detected |
| Heading hierarchy | Pass | h1 → h2 → h3 hierarchy correct |
| Document landmarks | Pass | main, nav, footer present |

### Manual (Keyboard)

| Check | Status | Notes |
|-------|--------|-------|
| Skip link | Pass | Skip-to-content link present |
| Tab order | Issues | Tab skips form controls entirely |
| Focus visibility | Pass | Visible focus rings on all interactive elements |
| Modal focus trap | N/A | No modals on this page |
| Button activation | Pass | Enter and Space work on all buttons |
| Keyboard traps | Pass | No keyboard traps detected |

## Verdict

- **Recommendation**: Request Changes
- **Blockers**: 0
- **High-Priority**: 2
- **Medium-Priority**: 1
- **Nits**: 1

Sample Report — Clean Review

# Design Review Report

**Date**: 2025-08-08T15:30:00Z
**Branch**: fix/button-states
**Commit**: r7s8t9u
**Reviewer**: Claude Code (design-review)

---

## Summary

Excellent fix for the button hover and disabled states. The visual feedback is now consistent across all button variants (primary, secondary, ghost) and matches the design system specifications. Keyboard focus states are properly implemented and the disabled state correctly prevents interaction while maintaining sufficient color contrast.

## Findings

### Blockers

None.

### High-Priority

None.

### Medium-Priority / Suggestions

None.

### Praise

- **[Praise]** Consistent transition timing across all button variants — 200ms ease-in-out matches the design system's `--transition-fast` token.

### Nitpicks

- **Nit:** The transition duration for the hover state on ghost buttons (300ms) is slightly longer than primary and secondary buttons (200ms). The design system specifies `--transition-fast` (200ms) for all button transitions.

## Responsive Summary

| Viewport | Status | Notes |
|----------|--------|-------|
| Small mobile (375px) | Pass | Full-width buttons display correctly |
| Standard mobile (390px) | Pass | Consistent with 375px |
| Tablet portrait (768px) | Pass | Touch targets meet 44px minimum |
| Tablet landscape (1024px) | Pass | Inline buttons space correctly |
| Laptop (1280px) | Pass | All states work correctly |
| Desktop (1440px) | Pass | All states work correctly |
| Large monitor (1920px) | Pass | No stretch or overflow |
| Zoom reflow (400%) | Pass | Buttons stack vertically at zoom |

## Accessibility Summary

### Automated (axe-core)

| Check | Status | Notes |
|-------|--------|-------|
| Color contrast | Pass | Disabled state maintains 3:1 ratio (decorative) |
| Form labels | N/A | No form inputs in this change |
| ARIA validity | Pass | Button roles correct |

### Manual (Keyboard)

| Check | Status | Notes |
|-------|--------|-------|
| Tab order | Pass | Tab order correct |
| Focus visibility | Pass | Visible focus rings on all button variants |
| Button activation | Pass | Enter and Space work on all variants |
| Keyboard traps | Pass | No keyboard traps |

## Verdict

- **Recommendation**: Approve
- **Blockers**: 0
- **High-Priority**: 0
- **Medium-Priority**: 0
- **Nits**: 1

Sample Report — Accessibility-Focused Review

# Design Review Report

**Date**: 2025-09-12T09:45:00Z
**Branch**: feat/search-modal
**Commit**: k3m4n5p
**Reviewer**: Claude Code (design-review)

---

## Summary

The new search modal implements a clean, keyboard-driven interface with a well-structured results list. The visual design is polished and consistent with the design system. However, axe-core detected critical accessibility violations (missing form label, low contrast on placeholder text) and manual keyboard testing revealed a focus trap issue when the modal closes.

## Findings

### Blockers

- **[Blocker]** The search input has no accessible label — axe-core violation `label` (critical). Screen readers announce this as "edit text" with no context. (Confidence: 10/10)
  - **Impact**: Screen reader users cannot identify the purpose of the input field.
  - **Reference**: WCAG 1.3.1 (Info and Relationships), WCAG 4.1.2 (Name, Role, Value)
  - **Evidence**: axe-core output: `{ id: "label", impact: "critical", nodes: 1 }`

- **[Blocker]** When closing the search modal with Escape, focus is sent to `<body>` instead of returning to the trigger button. User loses their place in the page. (Confidence: 10/10)
  - **Impact**: Keyboard users must Tab from the beginning of the page after closing the modal.
  - **Reference**: WCAG 2.4.3 (Focus Order) — focus must return to the triggering element.
  - **Evidence**: after-escape.png shows focus indicator at top of page

### High-Priority

- **[High-Priority]** Placeholder text "Search docs, APIs, guides..." has contrast ratio 2.8:1 against the white background — axe-core violation `color-contrast` (serious). (Confidence: 9/10)
  - **Impact**: Users with low vision cannot read the placeholder text.
  - **Reference**: WCAG 1.4.3 (Contrast Minimum) — 4.5:1 for normal text. Placeholder is not exempt.
  - **Evidence**: axe-core output: `{ id: "color-contrast", impact: "serious", nodes: 1 }`

- **[High-Priority]** Search results list items are not keyboard-navigable. Arrow keys do nothing; Tab skips from input to close button, bypassing all results. (Confidence: 9/10)
  - **Impact**: Keyboard users cannot select a search result.
  - **Reference**: ARIA Authoring Practices — Combobox pattern requires arrow key navigation through results.
  - **Evidence**: focus-3.png shows focus jumping from input to close button

### Medium-Priority / Suggestions

- **[Medium]** No empty state message when search returns zero results. The results area is simply blank. (Confidence: 7/10)
  - **Context**: Users may think the search is still loading. A "No results found" message with suggestion to refine the query improves UX.

### Praise

- **[Praise]** The `aria-live="polite"` region announcing result count ("5 results found") is excellent — screen reader users get immediate feedback as they type.

### Nitpicks

- **Nit:** The modal backdrop uses `opacity: 0.4` while the design system standard is `--overlay-opacity: 0.5`.

## Responsive Summary

| Viewport | Status | Notes |
|----------|--------|-------|
| Small mobile (375px) | Pass | Modal fills viewport, input auto-focused |
| Standard mobile (390px) | Pass | Consistent with 375px |
| Tablet portrait (768px) | Pass | Centered modal, appropriate width |
| Tablet landscape (1024px) | Pass | Consistent with portrait |
| Laptop (1280px) | Pass | Centered, max-width 640px |
| Desktop (1440px) | Pass | Clean centered layout |
| Large monitor (1920px) | Pass | No stretch |
| Zoom reflow (400%) | Pass | Modal adapts to single column |

## Accessibility Summary

### Automated (axe-core)

| Check | Status | Notes |
|-------|--------|-------|
| Color contrast | Issues | Placeholder text 2.8:1 (needs 4.5:1) |
| Image alt text | N/A | No images |
| Form labels | Issues | Search input missing accessible label |
| ARIA validity | Pass | aria-live region correctly implemented |
| Heading hierarchy | Pass | Modal heading is h2 |
| Document landmarks | Pass | dialog role present |

### Manual (Keyboard)

| Check | Status | Notes |
|-------|--------|-------|
| Skip link | N/A | Modal context |
| Tab order | Issues | Results not navigable via keyboard |
| Focus visibility | Pass | Focus ring visible on input and close button |
| Modal focus trap | Pass | Tab cycles within modal |
| Button activation | Pass | Close button responds to Enter/Space |
| Keyboard traps | Pass | Escape closes modal |
| Focus return | Issues | Focus sent to body, not trigger |

## Verdict

- **Recommendation**: Request Changes
- **Blockers**: 2
- **High-Priority**: 2
- **Medium-Priority**: 1
- **Nits**: 1

Sample Report — Responsive Edge Case

# Design Review Report

**Date**: 2025-10-01T14:20:00Z
**Branch**: feat/pricing-cards
**Commit**: w8x9y0z
**Reviewer**: Claude Code (design-review)

---

## Summary

The pricing cards component is visually polished at standard breakpoints with good typography hierarchy and clear CTA placement. However, between-breakpoint testing revealed a layout failure at widths between 768px and 1024px where the three-column card grid doesn't gracefully transition to two columns, causing cards to overflow. The 400% zoom reflow also has issues.

## Findings

### Blockers

- **[Blocker]** At viewport widths 769px–1023px, the three-column pricing grid overflows its container. Cards are clipped on the right edge, and the "Enterprise" card's CTA button is partially hidden. (Confidence: 10/10)
  - **Impact**: Users on small tablets or resized browser windows cannot see or interact with the rightmost pricing option.
  - **Reference**: CSS grid uses `grid-template-columns: repeat(3, 1fr)` at `≥768px` but the combined card min-widths (280px × 3 = 840px) exceed available width at 769px–1023px.
  - **Evidence**: pricing-900px.png shows right card clipped

### High-Priority

- **[High-Priority]** At 400% browser zoom, pricing cards stack vertically but the "Most Popular" badge on the middle card overflows its container and overlaps the adjacent card's title. (Confidence: 8/10)
  - **Impact**: Zoomed-in users see overlapping content that obscures pricing information.
  - **Reference**: WCAG 1.4.4 (Resize Text) — content must reflow without loss of information at 400% zoom.
  - **Evidence**: zoom-400-pricing.png shows badge overlap

### Medium-Priority / Suggestions

- **[Medium]** On landscape mobile (812×375), the pricing toggle (Monthly/Annual) wraps to two lines, pushing the cards below the fold. (Confidence: 7/10)
  - **Context**: Toggle text "Billed Monthly" / "Billed Annually" could be shortened to "Monthly" / "Annual" at narrow viewports using a responsive variant.

### Praise

- **[Praise]** The card hover state with subtle elevation change and border color transition creates a polished interactive feel. The `--shadow-md` to `--shadow-lg` progression matches the design system perfectly.

### Nitpicks

- **Nit:** The "per month" text under pricing uses `font-size: 13px` — the design system's smallest text token is `--text-xs` (12px). Consider aligning to the token.

## Responsive Summary

| Viewport | Status | Notes |
|----------|--------|-------|
| Small mobile (375px) | Pass | Single column, cards stack well |
| Standard mobile (390px) | Pass | Consistent with 375px |
| Tablet portrait (768px) | Issues | 3-col grid too tight at exactly 768px |
| Between (769–1023px) | Issues | Cards overflow container |
| Tablet landscape (1024px) | Pass | 3-col grid has enough space |
| Laptop (1280px) | Pass | Clean 3-col layout |
| Desktop (1440px) | Pass | Generous spacing |
| Large monitor (1920px) | Pass | Max-width constrains cards |
| Zoom reflow (400%) | Issues | Badge overflow on stacked cards |

## Accessibility Summary

### Automated (axe-core)

| Check | Status | Notes |
|-------|--------|-------|
| Color contrast | Pass | All text meets 4.5:1 |
| Image alt text | N/A | Decorative icons use aria-hidden |
| Form labels | N/A | Toggle uses proper radio group |
| ARIA validity | Pass | No errors |
| Heading hierarchy | Pass | Card titles are h3 under page h2 |
| Document landmarks | Pass | Section role with aria-label |

### Manual (Keyboard)

| Check | Status | Notes |
|-------|--------|-------|
| Tab order | Pass | Toggle → Card 1 CTA → Card 2 CTA → Card 3 CTA |
| Focus visibility | Pass | Focus ring on toggle and CTA buttons |
| Button activation | Pass | Enter/Space work on toggle and CTAs |
| Keyboard traps | Pass | No traps |

## Verdict

- **Recommendation**: Request Changes
- **Blockers**: 1
- **High-Priority**: 1
- **Medium-Priority**: 1
- **Nits**: 1

Design Review Troubleshooting

Common issues when using the design-review skill.

---

Environment Issues

No live preview available

Symptoms: Cannot execute interaction or responsiveness phases.

Cause: No local dev server or staging URL is running.

Fix:

• Start the local dev server before running the review
• Provide a staging URL if available
• The skill can still perform code-only review (Phases 6-7) without a live environment, but Phases 1-5 require browser access

Playwright CLI not installed

Symptoms: Browser automation commands fail.

Fix:

npm install -g @playwright/cli@latest
playwright-cli --help

Or run /playwright-setup to configure interactively.

---

Viewport Testing Issues

Responsive issues not detected

Symptoms: Report misses layout breakage at certain screen sizes.

Cause: Only standard breakpoints were tested, missing between-breakpoint issues.

Fix: The skill tests 7 viewport tiers (375-1920px). If you suspect issues at specific sizes, mention the target viewport in your review request.

Screenshots not captured

Symptoms: Report references screenshots but none are attached.

Cause: Playwright output directory not configured or not writable.

Fix: Run /playwright-setup to configure the output directory, or check that .playwright/cli.config.json has a valid outputDir.

---

Finding Quality Issues

Too many aesthetic opinions

Symptoms: Report includes subjective design preferences rather than measurable issues.

Fix:

• Findings below confidence 7 should be suppressed
• Only measurable failures (contrast ratios, WCAG violations, broken layouts) qualify as Blockers
• Design system violations need a specific token or rule reference

Accessibility findings seem wrong

Symptoms: WCAG violations flagged that the code actually handles.

Fix:

• Verify against the actual rendered DOM, not just source code
• Check if ARIA attributes or semantic HTML resolve the flagged issue
• Run axe-core directly for a second opinion: the skill uses automated + manual checks

---

Output Issues

Report directory creation fails

Cause: Permission denied or invalid path.

Fix: Ensure the output directory is writable. Default is ./reviews/design/ relative to the project root.

Design Review Workflow

Detailed phase-by-phase review checklists, false positive filtering, and confidence scoring guide.

---

Phase 0: Preparation

• Analyze the PR description to understand motivation, changes, and testing notes
• Review the code diff to understand implementation scope
• Set up the live preview environment using Playwright CLI (via Bash)
• Configure initial viewport (1440x900 for desktop)

Phase 1: Interaction and User Flow

• Execute the primary user flow following testing notes
• Test all interactive states (hover, active, disabled)
• Verify destructive action confirmations
• Assess perceived performance and responsiveness

Phase 2: Responsiveness Testing

Viewport Tiers

Test across 7 viewport tiers, capturing screenshots at each:

Priority: Always test 375px, 768px, and 1440px. Test additional tiers when the diff touches layout, grid, or responsive code.

Between-Breakpoint Testing

Testing only at standard breakpoints misses failures between them. After fixed-viewport tests:

1. Identify the app's CSS breakpoints from the codebase (e.g., @media (min-width: 768px)) 2. Test at widths just below each breakpoint (e.g., 767px, 1023px, 1279px) 3. Look for: overlapping elements, text truncation, missing layout transitions

Modern CSS Checks

• Container queries (@container): Verify components adapt to container width, not just viewport
• Fluid typography (clamp()): Verify body text stays ≥16px at minimum viewport and doesn't become excessively large
• Viewport units: Check for vh vs dvh/svh/lvh — mobile browser chrome collapse creates layout issues with full-height components

Zoom Reflow (WCAG 1.4.4)

Content must reflow at 400% browser zoom without horizontal scrolling:

playwright-cli eval "document.documentElement.style.zoom = '4'"
playwright-cli screenshot --filename=.playwright-cli/zoom-400.png

Verify: single-column reflow, no horizontal scroll, all content visible.

Orientation Testing

Test landscape mode on mobile viewports — modals and fixed-position elements often break:

playwright-cli resize 812 375
playwright-cli screenshot --filename=.playwright-cli/mobile-landscape.png

Phase 3: Visual Polish

• Assess layout alignment and spacing consistency
• Verify typography hierarchy and legibility
• Check color palette consistency and image quality
• Ensure visual hierarchy guides user attention

Phase 4: Accessibility (WCAG 2.1 AA)

Split into automated checks (axe-core) and manual checks (keyboard testing). Both are required — axe-core catches ~30% of WCAG issues; the rest require human verification.

Automated: axe-core Scan

Run axe-core via Playwright to detect machine-verifiable violations:

playwright-cli eval "
  const script = document.createElement('script');
  script.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js';
  document.head.appendChild(script);
  await new Promise(r => script.onload = r);
  const results = await axe.run();
  return JSON.stringify({
    violations: results.violations.map(v => ({
      id: v.id,
      impact: v.impact,
      description: v.description,
      nodes: v.nodes.length
    })),
    passes: results.passes.length,
    incomplete: results.incomplete.length
  }, null, 2);
"

What axe-core reliably catches:

• Color contrast ratios below 4.5:1 (normal text) / 3:1 (large text / UI components)
• Images missing alt attributes (presence only — not quality)
• Form inputs without associated labels
• Missing <html lang> attribute
• Duplicate element IDs
• Empty/nameless buttons and links
• Invalid ARIA roles, attributes, and values
• Skipped heading levels
• Missing document landmarks (<main>, <nav>)

Severity-to-triage mapping:

Manual: Keyboard Navigation Sequence

axe-core cannot verify these — execute manually using Playwright CLI:

1. Skip link: Press Tab once → verify skip-to-content link appears as first focusable element 2. Tab order: Press Tab through all interactive elements → verify logical order matches visual layout 3. Modal focus trap: Open a modal → Tab → verify focus stays inside modal; cannot Tab to elements behind it 4. Modal dismiss: Press Escape → verify modal closes and focus returns to the trigger element 5. Button activation: Press Enter and Space on all buttons → verify both activate the button 6. Dropdown/menu navigation: Press Arrow keys in dropdowns → verify items are navigable 7. No keyboard traps: Verify you can always Tab away from any element (no element captures focus permanently)

# Example keyboard testing sequence
playwright-cli press Tab
playwright-cli screenshot --filename=.playwright-cli/focus-1.png
playwright-cli press Tab
playwright-cli screenshot --filename=.playwright-cli/focus-2.png
playwright-cli press Enter
playwright-cli screenshot --filename=.playwright-cli/after-enter.png
playwright-cli press Escape
playwright-cli screenshot --filename=.playwright-cli/after-escape.png

Additional Checks

• Verify all images have alt text (axe checks presence; manually verify quality for key images)
• Test color contrast on dynamic elements (hover states, active states, disabled states)
• Verify focus indicators are visible on all interactive elements (minimum 2px outline or equivalent)
• Check that touch targets meet 44x44px minimum on mobile viewports

What NOT to Flag (Requires Specialized Tools)

Do not flag these as findings — they require screen reader testing or subjective judgment beyond automated review scope:

• Alt text quality (axe verifies presence; quality requires human context)
• Screen reader announcement phrasing
• Reading order preferences that differ from DOM order without clear usability impact

Phase 5: Robustness Testing

• Test form validation with invalid inputs
• Stress test with content overflow scenarios
• Verify loading, empty, and error states
• Check edge case handling

Phase 6: Code Health

• Verify component reuse over duplication
• Check for design token usage (no magic numbers)
• Ensure adherence to established patterns

Phase 7: Content and Console

• Review grammar and clarity of all text
• Check browser console for errors/warnings

---

Signal Quality & False Positive Filtering

Apply these rules before finalizing findings. Discard any finding that matches a hard exclusion.

Hard Exclusions

1. Aesthetic preferences — do not flag without referencing a specific design token, WCAG criterion, or system rule 2. Code-level issues invisible in the live environment — defer to code review 3. Third-party widget styling — maps, embeds, social buttons, ad units are out of scope 4. Cross-browser font rendering — antialiasing differences between macOS/Windows/Linux are expected 5. Dynamic content variability — timestamps, user avatars, live data change between screenshots 6. Animation mid-transition — always wait for animations to settle before capturing evidence 7. Pixel rounding differences — sub-pixel variations between viewports are not findings 8. Vague suggestions — discard any finding that says "could look better" without citing a design token or WCAG rule 9. Consistent patterns — do not flag code or design patterns used elsewhere in the codebase 10. Changes outside the diff — do not report on unchanged UI unless directly impacted by the change

Signal Quality Criteria

For each remaining finding, verify all four: 1. Is there a concrete, demonstrable impact (broken layout, inaccessible content, visual inconsistency)? 2. Can you reference a specific design token, WCAG criterion, or system rule being violated? 3. Is the finding backed by evidence (screenshot, axe output, contrast ratio measurement)? 4. Would a senior designer confidently raise this in a design review?

If any answer is "no," suppress the finding.

Confidence Scoring Guide

Self-Reflection Pass

After generating all candidate findings:

1. Review all findings together as a set — are there redundant or overlapping items? 2. Re-score each finding with full context of the others 3. Apply hard exclusion rules — remove any matches 4. Enforce caps: keep top 8 meaningful findings + top 2 Nits by confidence 5. If exceeding caps, drop the lowest-confidence items and note: "Additional observations available on request"

---

Playwright CLI Integration

Use the Playwright CLI skill (playwright:playwright-cli) for all browser automation:

Core Commands

Viewport Configurations

Accessibility Testing Commands

# Accessibility tree inspection
playwright-cli snapshot

# Keyboard navigation testing
playwright-cli press Tab
playwright-cli press Enter
playwright-cli press Space
playwright-cli press Escape

# Focus state verification (screenshot after each Tab)
playwright-cli press Tab
playwright-cli screenshot --filename=.playwright-cli/focus-state.png

# axe-core scan (see Phase 4 for full script)
playwright-cli eval "<axe-core injection script>"

---

Report Template

# Design Review Report

**Date**: {ISO 8601 date}
**Branch**: {current branch name}
**Commit**: {short commit hash}
**Reviewer**: Claude Code (design-review)

---

## Summary

[Positive opening acknowledging what works well, followed by overall assessment]

## Findings

### Blockers

- **[Blocker]** {Problem description} (Confidence: {N}/10)
  - **Impact**: {How this affects users}
  - **Evidence**: {Screenshot or axe output}

### High-Priority

- **[High-Priority]** {Problem description} (Confidence: {N}/10)
  - **Impact**: {How this affects users}
  - **Reference**: {Design token, WCAG criterion, or system rule violated}
  - **Evidence**: {Screenshot or measurement}

### Medium-Priority / Suggestions

- **[Medium]** {Problem description} (Confidence: {N}/10)
  - **Context**: {Why this matters, with evidence}

### Praise

- **[Praise]** {What was done well and why it matters}

### Nitpicks

- **Nit:** {Minor aesthetic detail}

## Responsive Summary

| Viewport | Status | Notes |
|----------|--------|-------|
| Small mobile (375px) | {Pass/Issues} | {Details} |
| Standard mobile (390px) | {Pass/Issues} | {Details} |
| Tablet portrait (768px) | {Pass/Issues} | {Details} |
| Tablet landscape (1024px) | {Pass/Issues} | {Details} |
| Laptop (1280px) | {Pass/Issues} | {Details} |
| Desktop (1440px) | {Pass/Issues} | {Details} |
| Large monitor (1920px) | {Pass/Issues} | {Details} |
| Zoom reflow (400%) | {Pass/Issues} | {Details} |

## Accessibility Summary

### Automated (axe-core)

| Check | Status | Notes |
|-------|--------|-------|
| Color contrast | {Pass/Issues} | {Details} |
| Image alt text | {Pass/Issues} | {Details} |
| Form labels | {Pass/Issues} | {Details} |
| ARIA validity | {Pass/Issues} | {Details} |
| Heading hierarchy | {Pass/Issues} | {Details} |
| Document landmarks | {Pass/Issues} | {Details} |

### Manual (Keyboard)

| Check | Status | Notes |
|-------|--------|-------|
| Skip link | {Pass/Issues/N/A} | {Details} |
| Tab order | {Pass/Issues} | {Details} |
| Focus visibility | {Pass/Issues} | {Details} |
| Modal focus trap | {Pass/Issues/N/A} | {Details} |
| Button activation | {Pass/Issues} | {Details} |
| Keyboard traps | {Pass/Issues} | {Details} |

## Verdict

- **Recommendation**: {Approve / Request Changes / Approve with Notes}
- **Blockers**: {count}
- **High-Priority**: {count}
- **Medium-Priority**: {count}
- **Nits**: {count}