Web Design Reviewer

Web design reviewer

Inspect local or remote websites visually, identify layout, responsive, accessibility, and consistency defects, then make source-level fixes when the workspace contains the code.

When to invoke

• "Review this website design."
• "Check the UI for layout problems."
• "Fix the responsive layout."
• "Find design problems on this page."
• "Validate the web design after my changes."

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 and context

Required

1. Target website must be running

   • Local development server (e.g., http://localhost:3000)
   • Staging environment
   • Production environment (for read-only reviews)

2. Browser automation must be available

   • Screenshot capture
   • Page navigation
   • DOM information retrieval

3. Access to source code (when making fixes)

   • Project must exist within the workspace

Procedure

---
config:
  theme: base
  look: classic
  themeVariables:
    darkMode: false
    background: "#ffffff"
    primaryColor: "#f5f5f5"
    primaryTextColor: "#111111"
    primaryBorderColor: "#555555"
    secondaryColor: "#e0e0e0"
    secondaryTextColor: "#111111"
    secondaryBorderColor: "#666666"
    tertiaryColor: "#bdbdbd"
    tertiaryTextColor: "#111111"
    tertiaryBorderColor: "#444444"
    lineColor: "#444444"
    textColor: "#111111"
    mainBkg: "#f5f5f5"
    nodeBorder: "#555555"
    clusterBkg: "#ffffff"
    clusterBorder: "#999999"
    edgeLabelBackground: "#ffffff"
    actorBkg: "#e0e0e0"
    actorBorder: "#555555"
    actorTextColor: "#111111"
    actorLineColor: "#777777"
    signalColor: "#333333"
    signalTextColor: "#111111"
    labelBoxBkgColor: "#f5f5f5"
    labelBoxBorderColor: "#777777"
    labelTextColor: "#111111"
    loopTextColor: "#111111"
    activationBkgColor: "#bdbdbd"
    activationBorderColor: "#555555"
    noteBkgColor: "#f5f5f5"
    noteTextColor: "#111111"
    noteBorderColor: "#777777"
    attributeBackgroundColorOdd: "#f5f5f5"
    attributeBackgroundColorEven: "#e0e0e0"
---
flowchart TD
    accTitle: Web design review procedure
    accDescr: Information gathering leads to visual inspection, issue fixing and re-verification; remaining issues return to inspection, otherwise the review ends in a completion report.
    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"]

Legend. Rectangles are review steps; the diamond is the decision after re-verification. Solid arrows show the normal order; the labeled branches show the two outcomes.

Explanation. Inspection and fixing repeat until re-verification finds nothing left. The report is written from the verified state, not from the first pass.

Information gathering

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:

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

Visual inspection criteria

2.1 Page Traversal

1. Navigate to the specified URL
2. Capture screenshots
3. Retrieve DOM structure/snapshot (if possible)
4. If additional pages exist, traverse through navigation

2.2 Inspection Items

Work through references/visual-checklist.md during inspection and again during post-fix verification.

Layout Issues

Responsive Issues

Accessibility Issues

Visual Consistency

2.3 Viewport Testing (Responsive)

Test at the following viewports:

Source-level fixing

3.1 Issue Prioritization

---
config:
  theme: base
  look: classic
  themeVariables:
    darkMode: false
    background: "#ffffff"
    primaryColor: "#f5f5f5"
    primaryTextColor: "#111111"
    primaryBorderColor: "#555555"
    secondaryColor: "#e0e0e0"
    secondaryTextColor: "#111111"
    secondaryBorderColor: "#666666"
    tertiaryColor: "#bdbdbd"
    tertiaryTextColor: "#111111"
    tertiaryBorderColor: "#444444"
    lineColor: "#444444"
    textColor: "#111111"
    mainBkg: "#f5f5f5"
    nodeBorder: "#555555"
    clusterBkg: "#ffffff"
    clusterBorder: "#999999"
    edgeLabelBackground: "#ffffff"
    actorBkg: "#e0e0e0"
    actorBorder: "#555555"
    actorTextColor: "#111111"
    actorLineColor: "#777777"
    signalColor: "#333333"
    signalTextColor: "#111111"
    labelBoxBkgColor: "#f5f5f5"
    labelBoxBorderColor: "#777777"
    labelTextColor: "#111111"
    loopTextColor: "#111111"
    activationBkgColor: "#bdbdbd"
    activationBorderColor: "#555555"
    noteBkgColor: "#f5f5f5"
    noteTextColor: "#111111"
    noteBorderColor: "#777777"
    attributeBackgroundColorOdd: "#f5f5f5"
    attributeBackgroundColorEven: "#e0e0e0"
---
flowchart TD
    accTitle: Fix priority order
    accDescr: Layout defects that affect functionality are fixed first, then visual defects that degrade the experience, then minor inconsistencies.
    P1["P1 · fix immediately<br/>layout defects affecting functionality"] --> P2["P2 · fix next<br/>visual defects degrading the experience"]
    P2 --> P3["P3 · fix if possible<br/>minor visual inconsistencies"]

Legend. Each rectangle is a priority band; the arrows show the order in which the bands are addressed.

Explanation. A defect that blocks a task outranks one that only looks wrong. Work down the bands so a long tail of cosmetic issues never delays a functional fix.

3.2 Identifying Source Files

Identify source files from problematic elements:

1. Selector-based Search

   • Search codebase by class name or ID
   • Explore style definitions with grep_search

2. Component-based Search

   • Identify components from element text or structure
   • Explore related files with semantic_search

3. 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

1. Minimal Changes: Only make the minimum changes necessary to resolve the issue
2. Respect Existing Patterns: Follow existing code style in the project
3. Avoid Breaking Changes: Be careful not to affect other areas
4. Add Comments: Add comments to explain the reason for fixes where appropriate

Re-verification

4.1 Post-fix Confirmation

1. Reload browser (or wait for development server HMR)
2. Capture screenshots of fixed areas
3. 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

---
config:
  theme: base
  look: classic
  themeVariables:
    darkMode: false
    background: "#ffffff"
    primaryColor: "#f5f5f5"
    primaryTextColor: "#111111"
    primaryBorderColor: "#555555"
    secondaryColor: "#e0e0e0"
    secondaryTextColor: "#111111"
    secondaryBorderColor: "#666666"
    tertiaryColor: "#bdbdbd"
    tertiaryTextColor: "#111111"
    tertiaryBorderColor: "#444444"
    lineColor: "#444444"
    textColor: "#111111"
    mainBkg: "#f5f5f5"
    nodeBorder: "#555555"
    clusterBkg: "#ffffff"
    clusterBorder: "#999999"
    edgeLabelBackground: "#ffffff"
    actorBkg: "#e0e0e0"
    actorBorder: "#555555"
    actorTextColor: "#111111"
    actorLineColor: "#777777"
    signalColor: "#333333"
    signalTextColor: "#111111"
    labelBoxBkgColor: "#f5f5f5"
    labelBoxBorderColor: "#777777"
    labelTextColor: "#111111"
    loopTextColor: "#111111"
    activationBkgColor: "#bdbdbd"
    activationBorderColor: "#555555"
    noteBkgColor: "#f5f5f5"
    noteTextColor: "#111111"
    noteBorderColor: "#777777"
    attributeBackgroundColorOdd: "#f5f5f5"
    attributeBackgroundColorEven: "#e0e0e0"
---
flowchart TD
    accTitle: Iteration decision after re-verification
    accDescr: If issues remain the review returns to visual inspection; otherwise it proceeds to the completion report.
    A{"Issues remaining?"} -->|Yes| B["Return to step 2"]
    A -->|No| C["Proceed to the completion report"]

Legend. The diamond is the decision after re-verification; the two labeled branches are its outcomes.

Explanation. Re-verification decides whether the loop continues. Stopping before it passes leaves the defect in the product with a report that says it was reviewed.

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

Report format

## Web design review result

## 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

Browser automation options

Implementation with Playwright MCP

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

Configuration Example (MCP Server)

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

Other Compatible Browser Automation Tools

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.

Gotchas

Do

• 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

Do not

• 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

1. Check dependencies in package.json
2. Consider the possibility of CSS-in-JS
3. Consider CSS generated at build time
4. Ask user about styling method

Problem: Fixes not reflected

1. Check if development server HMR is working
2. Clear browser cache
3. Rebuild if project requires build
4. Check CSS specificity issues

Problem: Fixes affecting other areas

1. Rollback changes
2. Use more specific selectors
3. Consider using CSS Modules or scoped styles
4. Consult user to confirm impact scope

Progressive disclosure and bundled resources

Read bundled references only when the task needs that depth.

• references/visual-checklist.md: detailed inspection checklist for layout, responsive, accessibility, and visual consistency passes.
• references/framework-fixes.md: framework-specific source fix guidance for React, Vue, Angular, Svelte, Next.js, Nuxt, SvelteKit, Tailwind CSS, CSS Modules, and CSS-in-JS.

Output template

## Web design review result

**Status:** complete | needs fixes | blocked
**Target URL:** `<http://localhost:3000 or remote URL>`
**Framework:** `<React/Vue/Angular/Svelte/Next.js/Nuxt/SvelteKit/CMS/unknown>`
**Styling:** `<CSS/SCSS/Sass/Tailwind CSS/CSS Modules/styled-components/Emotion/unknown>`
**Tested viewports:** `375px`, `768px`, `1280px`, `1920px`

| Priority | Page | Element | Issue | Evidence | Fixed file | Verification |
| --- | --- | --- | --- | --- | --- | --- |
| P1 | `<path>` | `<selector or description>` | `<overflow/overlap/contrast/focus/etc.>` | `<screenshot or DOM evidence>` | `{File path}` | `<Before/After result>` |

**Unfixed issues**
- `<issue>`: `<reason and recommended action>`

Quality gate

• name is web-design-reviewer and matches the parent directory.
• The target URL is reachable, including http://localhost:3000 when the local server is running.
• Screenshots or DOM snapshots were inspected before any edit.
• references/visual-checklist.md is used for inspection and post-fix verification when detailed review is requested.
• references/framework-fixes.md is used before framework-specific edits.
• Mobile 375px, tablet 768px, desktop 1280px, and wide 1920px viewports are tested when responsive behavior is in scope.
• Fixes are minimal, source-level, and verified with screenshots or DOM evidence after reload/HMR/rebuild.
• More than three failed fix attempts on one issue are reported instead of continuing blindly.

References

• Playwright MCP