Back to Details

web-design-reviewer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Web Design Reviewer

Web Design Reviewer

This skill enables visual inspection and validation of website design quality, identifying and fixing issues at the source code level.
该Skill可对网站设计质量进行视觉检查与验证，在源代码层面识别并修复问题。

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
  • 静态网站（HTML/CSS/JS）
  • 单页应用框架，如React、Vue、Angular、Svelte
  • 全栈框架，如Next.js、Nuxt、SvelteKit
  • CMS平台，如WordPress、Drupal
  • 其他任何Web应用

Prerequisites

前置条件

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
  1. 目标网站必须处于运行状态
    • 本地开发服务器（例如：
      http://localhost:3000
      ）
    • 预发布环境
    • 生产环境（仅用于只读审查）
  2. 必须具备浏览器自动化能力
    • 截图捕获
    • 页面导航
    • DOM信息获取
  3. 具备源代码访问权限（当需要修复问题时）
    • 项目必须存在于工作区内

Workflow Overview

工作流程概述

mermaid
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]
mermaid
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.1 URL Confirmation

1.1 URL确认

If the URL is not provided, ask the user:
Please provide the URL of the website to review (e.g., 
http://localhost:3000
)
如果未提供URL，请询问用户：
请提供需要审查的网站URL（例如：
http://localhost:3000
）

1.2 Understanding Project Structure

1.2 了解项目结构

When making fixes, gather the following information:
ItemExample Question
FrameworkAre you using React / Vue / Next.js, etc.?
Styling MethodCSS / SCSS / Tailwind / CSS-in-JS, etc.
Source LocationWhere are style files and components located?
Review ScopeSpecific pages only or entire site?
当需要修复问题时，收集以下信息：
项示例问题
框架你是否使用React、Vue、Next.js等框架？
样式方法CSS/SCSS/Tailwind/CSS-in-JS等？
源码位置样式文件和组件位于何处？
审查范围仅特定页面还是整个网站？

1.3 Automatic Project Detection

1.3 自动项目检测

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
尝试从工作区的文件中自动检测：
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

1.4 识别样式方法

MethodDetectionEdit 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 stylesJS/TS files
方法检测方式编辑目标
纯CSS
*.css
文件		全局CSS或组件CSS
SCSS/Sass
*.scss
、
*.sass
文件		SCSS文件
CSS Modules
*.module.css
文件		模块CSS文件
Tailwind CSS
tailwind.config.*
文件		组件中的className
styled-components代码中的
styled.
JS/TS文件
Emotion
@emotion/
导入		JS/TS文件
其他CSS-in-JS内联样式JS/TS文件

Step 2: Visual Inspection Phase

步骤2：视觉检查阶段

2.1 Page Traversal

2.1 页面遍历

  1. Navigate to the specified URL
  2. Capture screenshots
  3. Retrieve DOM structure/snapshot (if possible)
  4. If additional pages exist, traverse through navigation
  1. 导航至指定URL
  2. 捕获截图
  3. 检索DOM结构/快照（如果可能）
  4. 如果存在其他页面，通过导航遍历

2.2 Inspection Items

2.2 检查项

Layout Issues

布局问题

IssueDescriptionSeverity
Element OverflowContent overflows from parent element or viewportHigh
Element OverlapUnintended overlapping of elementsHigh
Alignment IssuesGrid or flex alignment problemsMedium
Inconsistent SpacingPadding/margin inconsistenciesMedium
Text ClippingLong text not handled properlyMedium
问题描述严重程度
元素溢出内容从父元素或视口溢出高
元素重叠元素意外重叠高
对齐问题Grid或Flex布局对齐错误中
间距不一致内边距/外边距不一致中
文本截断长文本未正确处理中

Responsive Issues

响应式问题

IssueDescriptionSeverity
Non-mobile FriendlyLayout breaks on small screensHigh
Breakpoint IssuesUnnatural transitions when screen size changesMedium
Touch TargetsButtons too small on mobileMedium
问题描述严重程度
非移动端友好小屏幕上布局断裂高
断点问题屏幕尺寸变化时过渡不自然中
触摸目标过小移动端按钮尺寸过小中

Accessibility Issues

可访问性问题

IssueDescriptionSeverity
Insufficient ContrastLow contrast ratio between text and backgroundHigh
No Focus StateCannot determine state during keyboard navigationHigh
Missing alt TextNo alternative text for imagesMedium
问题描述严重程度
对比度不足文本与背景的对比度比率过低高
无焦点状态键盘导航时无法确定状态高
缺少替代文本图片无替代文本中

Visual Consistency

视觉一致性

IssueDescriptionSeverity
Font InconsistencyMixed font familiesMedium
Color InconsistencyNon-unified brand colorsMedium
Spacing InconsistencyNon-uniform spacing between similar elementsLow
问题描述严重程度
字体不一致混合使用多种字体中
颜色不一致品牌颜色不统一中
间距不一致相似元素间的间距不统一低

2.3 Viewport Testing (Responsive)

2.3 视口测试（响应式）

Test at the following viewports:
NameWidthRepresentative Device
Mobile375pxiPhone SE/12 mini
Tablet768pxiPad
Desktop1280pxStandard PC
Wide1920pxLarge display
在以下视口尺寸下测试：
名称宽度代表设备
移动端375pxiPhone SE/12 mini
平板768pxiPad
桌面端1280px标准PC
宽屏1920px大型显示器

Step 3: Issue Fixing Phase

步骤3：问题修复阶段

3.1 Issue Prioritization

3.1 问题优先级

mermaid
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
mermaid
block-beta
    columns 1
    block:priority["Priority Matrix"]
        P1["P1: 立即修复\n(影响功能的布局问题)"]
        P2["P2: 下一步修复\n(降低用户体验的视觉问题)"]
        P3["P3: 尽可能修复\n(轻微的视觉不一致)"]
    end

3.2 Identifying Source Files

3.2 识别源文件

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/**
从有问题的元素中识别源文件：
  1. 基于选择器的搜索
    • 通过类名或ID搜索代码库
    • 使用
      grep_search
      探索样式定义
  2. 基于组件的搜索
    • 从元素文本或结构识别组件
    • 使用
      semantic_search
      探索相关文件
  3. 文件模式过滤
    Style files: src/**/*.css, styles/**/*
Components: src/components/**/*
Pages: src/pages/**, app/**

3.3 Applying Fixes

3.3 应用修复

Framework-specific Fix Guidelines

框架特定修复指南

See references/framework-fixes.md for details.
详情请参考references/framework-fixes.md。

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
  1. 最小变更：仅进行解决问题所需的最小变更
  2. 遵循现有模式：遵循项目中的现有代码风格
  3. 避免破坏性变更：注意不要影响其他区域
  4. 添加注释：在适当的地方添加注释说明修复原因

Step 4: Re-verification Phase

步骤4：重新验证阶段

4.1 Post-fix Confirmation

4.1 修复后确认

  1. Reload browser (or wait for development server HMR)
  2. Capture screenshots of fixed areas
  3. Compare before and after
  1. 重新加载浏览器（或等待开发服务器HMR）
  2. 捕获修复区域的截图
  3. 对比修复前后

4.2 Regression Testing

4.2 回归测试

  • Verify that fixes haven't affected other areas
  • Confirm responsive display is not broken
  • 验证修复未影响其他区域
  • 确认响应式显示未被破坏

4.3 Iteration Decision

4.3 迭代决策

mermaid
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
mermaid
flowchart TD
    A{Issues Remaining?}
    A -->|Yes| B[返回步骤2]
    A -->|No| C[生成完成报告]
迭代限制：如果某个问题需要超过3次修复尝试，请咨询用户

Output Format

输出格式

Review Results Report

审查结果报告

markdown
undefined
markdown
undefined

Web Design Review Results

网页设计审查结果

Summary

摘要

ItemValue
Target URL{URL}
Framework{Detected framework}
Styling{CSS / Tailwind / etc.}
Tested ViewportsDesktop, Mobile
Issues Detected{N}
Issues Fixed{M}
项值
目标URL{URL}
框架{检测到的框架}
样式方案{CSS/Tailwind等}
测试视口桌面端、移动端
检测到的问题{N}
已修复问题{M}

Detected Issues

检测到的问题

[P1] {Issue Title}

[P1] {问题标题}

  • 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}

[P2] {问题标题}

...
...

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

所需能力

CapabilityDescriptionRequired
Web Page NavigationAccess URLs, page transitions✅
Screenshot CapturePage image capture✅
Image AnalysisVisual issue detection✅
DOM RetrievalPage structure retrievalRecommended
File Read/WriteSource code reading and editingRequired for fixes
Code SearchCode search within projectRequired for fixes
能力描述是否必需
网页导航访问URL、页面跳转✅
截图捕获页面图像捕获✅
图像分析视觉问题检测✅
DOM检索页面结构检索推荐
文件读写源代码读取和编辑修复时必需
代码搜索项目内代码搜索修复时必需

Reference Implementation

参考实现

Implementation with Playwright MCP

使用Playwright MCP的实现

Playwright MCP is recommended as the reference implementation for this skill.
CapabilityPlaywright MCP ToolPurpose
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
推荐使用Playwright MCP作为该Skill的参考实现。
能力Playwright MCP工具用途
导航
browser_navigate
访问URL
快照
browser_snapshot
检索DOM结构
截图
browser_take_screenshot
视觉检查用图像
点击
browser_click
与交互元素交互
调整尺寸
browser_resize
响应式测试
控制台
browser_console_messages
检测JS错误

Configuration Example (MCP Server)

配置示例（MCP服务器）

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

Other Compatible Browser Automation Tools

其他兼容的浏览器自动化工具

ToolFeatures
SeleniumBroad browser support, multi-language support
PuppeteerChrome/Chromium focused, Node.js
CypressEasy integration with E2E testing
WebDriver BiDiStandardized 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.
工具特性
Selenium广泛的浏览器支持、多语言支持
Puppeteer专注Chrome/Chromium、Node.js
Cypress易于与E2E测试集成
WebDriver BiDi标准化的下一代协议
使用这些工具也可实现相同的工作流程。只要它们提供必要的能力（导航、截图、DOM检索），工具选择灵活。

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

问题：样式文件未找到

  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
  1. 检查
    package.json
    中的依赖
  2. 考虑CSS-in-JS的可能性
  3. 考虑构建时生成的CSS
  4. 询问用户样式方案

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
  1. 检查开发服务器HMR是否工作
  2. 清除浏览器缓存
  3. 如果项目需要构建，重新构建
  4. 检查CSS优先级问题

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
  1. 回滚变更
  2. 使用更具体的选择器
  3. 考虑使用CSS Modules或作用域样式
  4. 咨询用户确认影响范围