Web Design Reviewer

Visual inspection workflow using chrome-devtools MCP to identify and fix design issues.

Prerequisites

1. •Website running (localhost or remote)
2. •chrome-devtools MCP available
3. •Access to source code (for fixes)

Workflow

1. Information Gathering → 2. Visual Inspection → 3. Issue Fixing → 4. Verification
                                    ↑__________________________|

Step 1: Information Gathering

Get URL

If not provided, ask:

"What URL should I review? (e.g., http://localhost:3000)"

Detect Project

Check for:

• •package.json → Framework (React, Vue, Next.js)
• •tailwind.config.* → Tailwind CSS
• •*.module.css → CSS Modules
• •styled.* in code → styled-components

Step 2: Visual Inspection

Viewport Testing

Test at 4 breakpoints using mcp__chrome-devtools__resize_page:

For Each Viewport:

1. •Resize: mcp__chrome-devtools__resize_page
2. •Screenshot: mcp__chrome-devtools__take_screenshot
3. •Snapshot: mcp__chrome-devtools__take_snapshot (DOM structure)
4. •Analyze for issues

Issue Categories

P1 - Critical (Fix Immediately)

• •Element overflow causing horizontal scroll
• •Element overlap blocking content
• •Content completely hidden
• •Buttons/links unusable

P2 - Important (Fix Next)

• •Alignment inconsistencies
• •Spacing irregularities
• •Text clipping/truncation
• •Contrast issues (< 4.5:1)

P3 - Minor (Fix If Time)

• •Slight positioning differences
• •Minor spacing variations
• •Non-critical visual polish

Visual Checklist

Layout:

• • No horizontal scrollbar
• • Content fits viewport
• • Elements don't overlap unintentionally
• • Grid/flex alignment correct

Typography:

• • Text readable size (min 16px body)
• • Line height appropriate (1.5-1.8)
• • No text clipping
• • Long words wrap properly

Responsive:

• • Mobile: Touch targets 44x44px+
• • Tablet: Layout optimized
• • Desktop: Max-width set
• • Smooth breakpoint transitions

Accessibility:

• • Contrast ratio 4.5:1+
• • Focus states visible
• • Images have alt text

Step 3: Issue Fixing

Identify Source File

1. •Get selector from screenshot/snapshot
2. •Search codebase:
   code

   Glob: src/**/*.{css,scss,tsx,jsx,vue}
   Grep: ".selector-name"
   

Apply Minimal Fix

Principle: Smallest change that resolves the issue.

Common fixes:

/* Overflow */
.container { max-width: 100%; overflow-x: hidden; }

/* Flex item overflow */
.flex-item { min-width: 0; }

/* Grid item overflow */
.grid-item { min-width: 0; word-wrap: break-word; }

/* Text clipping */
.text { overflow: hidden; text-overflow: ellipsis; }

/* Contrast */
.text { color: #374151; } /* Increase from light gray */

Step 4: Verification

1. •Wait for HMR or refresh
2. •Re-screenshot fixed viewport
3. •Compare before/after
4. •Check for regressions in other viewports

Iteration limit: If 3+ attempts fail, consult user.

Output Format

# Design Review: [URL]

## Summary
| Item | Value |
|------|-------|
| Framework | Next.js |
| Styling | Tailwind CSS |
| Viewports Tested | 4 |
| Issues Found | 3 |
| Issues Fixed | 2 |

## Issues

### [P1] Horizontal overflow on mobile
- **Page**: /dashboard
- **Element**: `.data-table`
- **Issue**: Table exceeds viewport width
- **Fix**: Added `overflow-x: auto` to table container
- **File**: `src/components/DataTable.tsx:45`

### [P2] Low contrast text
- **Element**: `.description`
- **Issue**: Gray text (#9ca3af) on white fails WCAG AA
- **Fix**: Changed to #6b7280 (4.8:1 ratio)
- **File**: `src/styles/globals.css:120`

## Unfixed Issues

### [P3] Minor alignment at 1920px
- **Reason**: Would require significant refactor
- **Recommendation**: Consider for next sprint

## Recommendations
- Add `max-width: 100%` to all images globally
- Consider container queries for card component

Chrome DevTools MCP Tools

Useful Scripts

// Detect overflow elements
document.querySelectorAll('*').forEach(el => {
  if (el.scrollWidth > el.clientWidth) console.log('Overflow:', el);
});

// Outline all elements
document.querySelectorAll('*').forEach(el => {
  el.style.outline = '1px solid red';
});

Best Practices

DO:

• •Screenshot before any fix
• •Fix one issue at a time
• •Verify each fix before moving on
• •Follow existing code patterns

DON'T:

• •Large refactors without confirmation
• •Fix multiple issues at once
• •Ignore design system/brand guidelines
• •Skip regression testing