Efficient Web Design Reviewer

Perform automated visual inspection and design quality validation of web applications with actionable fix recommendations.

When to Use This Command

Run this command when you need to:

• Audit a website for layout issues, accessibility violations, and responsive design problems
• Generate a prioritized list of visual defects with their source file locations
• Validate design consistency across multiple viewports and browser environments

Consider alternatives when:

• You need a full accessibility audit with WCAG compliance certification
• You are designing from scratch and need creative direction rather than defect detection

Quick Start

Configuration

Copy
name: efficient-web-design-reviewer
type: command
category: design

Example Invocation

Copy
claude command:run efficient-web-design-reviewer --url http://localhost:3000 --viewports all

Example Output

Target: http://localhost:3000
Framework: Next.js (detected)
Styling: Tailwind CSS (detected)
Viewports tested: mobile (375px), tablet (768px), desktop (1280px), wide (1920px)

Issues Found: 7

[P1] Element Overflow on Mobile
  Page: /pricing
  Element: .pricing-table
  Issue: Table overflows viewport at 375px width
  File: src/components/PricingTable.tsx:42
  Fix: Add overflow-x-auto wrapper or stack columns on mobile

[P1] Insufficient Color Contrast
  Page: /about
  Element: .subtitle text
  Issue: Contrast ratio 3.2:1 (minimum 4.5:1 required)
  File: src/styles/globals.css:89
  Fix: Darken text color from #999 to #767676 or darker

[P2] Inconsistent Spacing
  Page: /features
  Element: .feature-card
  Issue: Cards use mix of gap-4 and gap-6
  File: src/components/Features.tsx:28
  Fix: Standardize to gap-6 across all card grids

Summary: 2 critical, 3 medium, 2 low severity issues

Core Concepts

Design Review Overview

Aspect	Details
Layout Validation	Overflow detection, alignment checks, spacing consistency
Responsive Testing	Mobile, tablet, desktop, and wide viewport validation
Accessibility	Color contrast ratios, focus states, alt text, and ARIA labels
Visual Consistency	Font families, color palette, spacing scale adherence
Source Mapping	Maps visual issues to specific source files and line numbers

Review Process Workflow

  Target URL
       |
       v
  +------------------+
  | Detect Framework |---> React / Vue / Next.js
  +------------------+
       |
       v
  +------------------+
  | Capture Screens  |---> 4 viewport sizes
  +------------------+
       |
       v
  +------------------+
  | Analyze Layout   |---> Overflow, alignment, spacing
  +------------------+
       |
       v
  +------------------+
  | Check A11y       |---> Contrast, focus, semantics
  +------------------+
       |
       v
  +------------------+
  | Map to Source    |---> File paths and line numbers
  +------------------+
       |
       v
  +------------------+
  | Generate Report  |---> Prioritized issue list
  +------------------+

Configuration

Parameter	Type	Default	Description
url	string	required	URL of the website to review (local or remote)
viewports	string	all	Viewports to test: mobile, tablet, desktop, wide, or all
severity	string	all	Minimum severity to report: p1, p2, p3, or all
fix	boolean	false	Automatically apply fixes to source files after review
pages	string	/	Comma-separated page paths to review

Best Practices

1. Review One Page at a Time - Fix issues on a single page before moving to the next. Fixing multiple pages simultaneously makes it difficult to verify each change and increases the risk of regressions.

2. Prioritize P1 Layout Breaks - Content that overflows the viewport or overlaps other elements is a usability blocker. Fix these before addressing spacing inconsistencies or minor visual polish.

3. Test at Real Device Sizes - Use actual device widths (375px for iPhone, 768px for iPad) rather than arbitrary breakpoints. Real device sizes catch issues that round-number breakpoints miss.

4. Follow Existing Design Patterns - When fixing issues, match the project's existing styling conventions. Introducing a new spacing value or color that does not exist in the design system creates new inconsistencies.

5. Capture Before and After Screenshots - Save screenshots before applying fixes so you can visually confirm the improvement. Automated changes can sometimes fix one issue while creating another.

Common Issues

1. Framework Not Detected - The reviewer cannot determine the styling method. Specify the framework explicitly with a flag, or ensure the project root contains the expected configuration files (package.json, tailwind.config.js).

2. Source File Mapping Fails - CSS-in-JS or dynamically generated class names prevent mapping visual elements to source files. In these cases, search for the component text or structure in the codebase rather than relying on class name matching.

3. False Positives on Hidden Elements - Elements hidden by JavaScript state (modals, dropdowns) may be flagged as overlapping. Verify that flagged elements are actually visible in the normal page state before applying fixes.