web-design-reviewer

SKILL.md

Web Design Reviewer

This skill enables visual inspection and validation of website design quality, identifying and fixing issues at the source code level.

Scope of Application

Static sites (HTML/CSS/JS)

SPA frameworks such as React / Vue / Angular / Svelte

Full-stack frameworks such as Next.js / Nuxt / SvelteKit

CMS platforms such as WordPress / Drupal

Any other web application

Prerequisites

Required

Target website must be running

Local development server (e.g., http://localhost:3000)

Staging environment

Production environment (for read-only reviews)

Browser automation must be available

Screenshot capture

Page navigation

DOM information retrieval

Access to source code (when making fixes)

Project must exist within the workspace

Workflow Overview

flowchart TD
    A[Step 1: Information Gathering] --> B[Step 2: Visual Inspection]
    B --> C[Step 3: Issue Fixing]
    C --> D[Step 4: Re-verification]
    D --> E{Issues Remaining?}
    E -->|Yes| B
    E -->|No| F[Completion Report]

Step 1: Information Gathering Phase

1.1 URL Confirmation

If the URL is not provided, ask the user:

Please provide the URL of the website to review (e.g., http://localhost:3000)

1.2 Understanding Project Structure

When making fixes, gather the following information:

Item
Example Question

Framework
Are you using React / Vue / Next.js, etc.?

Styling Method
CSS / SCSS / Tailwind / CSS-in-JS, etc.

Source Location
Where are style files and components located?

Review Scope
Specific pages only or entire site?

1.3 Automatic Project Detection

Attempt automatic detection from files in the workspace:

Detection targets:
├── package.json     → Framework and dependencies
├── tsconfig.json    → TypeScript usage
├── tailwind.config  → Tailwind CSS
├── next.config      → Next.js
├── vite.config      → Vite
├── nuxt.config      → Nuxt
└── src/ or app/     → Source directory

1.4 Identifying Styling Method

Method
Detection
Edit Target

Pure CSS
*.css files
Global CSS or component CSS

SCSS/Sass
*.scss, *.sass
SCSS files

CSS Modules
*.module.css
Module CSS files

Tailwind CSS
tailwind.config.*
className in components

styled-components
styled. in code
JS/TS files

Emotion
@emotion/ imports
JS/TS files

CSS-in-JS (other)
Inline styles
JS/TS files

Step 2: Visual Inspection Phase

2.1 Page Traversal

Navigate to the specified URL

Capture screenshots

Retrieve DOM structure/snapshot (if possible)

If additional pages exist, traverse through navigation

2.2 Inspection Items

Layout Issues

Issue
Description
Severity

Element Overflow
Content overflows from parent element or viewport
High

Element Overlap
Unintended overlapping of elements
High

Alignment Issues
Grid or flex alignment problems
Medium

Inconsistent Spacing
Padding/margin inconsistencies
Medium

Text Clipping
Long text not handled properly
Medium

Responsive Issues

Issue
Description
Severity

Non-mobile Friendly
Layout breaks on small screens
High

Breakpoint Issues
Unnatural transitions when screen size changes
Medium

Touch Targets
Buttons too small on mobile
Medium

Accessibility Issues

Issue
Description
Severity

Insufficient Contrast
Low contrast ratio between text and background
High

No Focus State
Cannot determine state during keyboard navigation
High

Missing alt Text
No alternative text for images
Medium

Visual Consistency

Issue
Description
Severity

Font Inconsistency
Mixed font families
Medium

Color Inconsistency
Non-unified brand colors
Medium

Spacing Inconsistency
Non-uniform spacing between similar elements
Low

2.3 Viewport Testing (Responsive)

Test at the following viewports:

Name
Width
Representative Device

Mobile
375px
iPhone SE/12 mini

Tablet
768px
iPad

Desktop
1280px
Standard PC

Wide
1920px
Large display

Step 3: Issue Fixing Phase

3.1 Issue Prioritization

block-beta
    columns 1
    block:priority["Priority Matrix"]
        P1["P1: Fix Immediately\n(Layout issues affecting functionality)"]
        P2["P2: Fix Next\n(Visual issues degrading UX)"]
        P3["P3: Fix If Possible\n(Minor visual inconsistencies)"]
    end

3.2 Identifying Source Files

Identify source files from problematic elements:

Selector-based Search

Search codebase by class name or ID

Explore style definitions with grep_search

Component-based Search

Identify components from element text or structure

Explore related files with semantic_search

File Pattern Filtering

Style files: src/**/*.css, styles/**/*
Components: src/components/**/*
Pages: src/pages/**, app/**

3.3 Applying Fixes

Framework-specific Fix Guidelines

See references/framework-fixes.md for details.

Fix Principles

Minimal Changes: Only make the minimum changes necessary to resolve the issue

Respect Existing Patterns: Follow existing code style in the project

Avoid Breaking Changes: Be careful not to affect other areas

Add Comments: Add comments to explain the reason for fixes where appropriate

Step 4: Re-verification Phase

4.1 Post-fix Confirmation

Reload browser (or wait for development server HMR)

Capture screenshots of fixed areas

Compare before and after

4.2 Regression Testing

Verify that fixes haven't affected other areas

Confirm responsive display is not broken

4.3 Iteration Decision

flowchart TD
    A{Issues Remaining?}
    A -->|Yes| B[Return to Step 2]
    A -->|No| C[Proceed to Completion Report]

Iteration Limit: If more than 3 fix attempts are needed for a specific issue, consult the user

Output Format

Review Results Report

# Web Design Review Results

## Summary

| Item | Value |
|------|-------|
| Target URL | {URL} |
| Framework | {Detected framework} |
| Styling | {CSS / Tailwind / etc.} |
| Tested Viewports | Desktop, Mobile |
| Issues Detected | {N} |
| Issues Fixed | {M} |

## Detected Issues

### [P1] {Issue Title}

- **Page**: {Page path}
- **Element**: {Selector or description}
- **Issue**: {Detailed description of the issue}
- **Fixed File**: `{File path}`
- **Fix Details**: {Description of changes}
- **Screenshot**: Before/After

### [P2] {Issue Title}
...

## Unfixed Issues (if any)

### {Issue Title}
- **Reason**: {Why it was not fixed/could not be fixed}
- **Recommended Action**: {Recommendations for user}

## Recommendations

- {Suggestions for future improvements}

Required Capabilities

Capability
Description
Required

Web Page Navigation
Access URLs, page transitions
✅

Screenshot Capture
Page image capture
✅

Image Analysis
Visual issue detection
✅

DOM Retrieval
Page structure retrieval
Recommended

File Read/Write
Source code reading and editing
Required for fixes

Code Search
Code search within project
Required for fixes

Reference Implementation

Implementation with Playwright MCP

Playwright MCP is recommended as the reference implementation for this skill.

Capability
Playwright MCP Tool
Purpose

Navigation
browser_navigate
Access URLs

Snapshot
browser_snapshot
Retrieve DOM structure

Screenshot
browser_take_screenshot
Images for visual inspection

Click
browser_click
Interact with interactive elements

Resize
browser_resize
Responsive testing

Console
browser_console_messages
Detect JS errors

Configuration Example (MCP Server)

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--caps=vision"]
    }
  }
}

Other Compatible Browser Automation Tools

Tool
Features

Selenium
Broad browser support, multi-language support

Puppeteer
Chrome/Chromium focused, Node.js

Cypress
Easy integration with E2E testing

WebDriver BiDi
Standardized next-generation protocol

The same workflow can be implemented with these tools. As long as they provide the necessary capabilities (navigation, screenshot, DOM retrieval), the choice of tool is flexible.

Best Practices

DO (Recommended)

✅ Always save screenshots before making fixes

✅ Fix one issue at a time and verify each

✅ Follow the project's existing code style

✅ Confirm with user before major changes

✅ Document fix details thoroughly

DON'T (Not Recommended)

❌ Large-scale refactoring without confirmation

❌ Ignoring design systems or brand guidelines

❌ Fixes that ignore performance

❌ Fixing multiple issues at once (difficult to verify)

Troubleshooting

Problem: Style files not found

Check dependencies in package.json

Consider the possibility of CSS-in-JS

Consider CSS generated at build time

Ask user about styling method

Problem: Fixes not reflected

Check if development server HMR is working

Clear browser cache

Rebuild if project requires build

Check CSS specificity issues

Problem: Fixes affecting other areas

Rollback changes

Use more specific selectors

Consider using CSS Modules or scoped styles

Consult user to confirm impact scope