web-design-reviewer

Web 设计审查员

此技能可用于直观检查和验证网站设计质量，并在源代码层面识别和修复问题。

适用范围

• 静态网站（HTML/CSS/JS）
• React / Vue / Angular / Svelte 等 SPA 框架
• Next.js / Nuxt / SvelteKit 等全栈框架
• WordPress / Drupal 等 CMS 平台
• 任何其他 Web 应用

先决条件

必需条件

1. 目标网站必须正在运行

   • 本地开发服务器（例如 http://localhost:3000）
   • 预发布环境
   • 生产环境（用于只读审查）

2. 必须能够使用浏览器自动化

   • 截取屏幕截图
   • 页面导航
   • 获取 DOM 信息

3. 能够访问源代码（需要修复时）

   • 项目必须位于工作区内

工作流概览

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]

---

步骤 1：信息收集阶段

1.1 确认 URL

如果未提供 URL，请询问用户：

请提供要审查的网站 URL（例如：http://localhost:3000）

1.2 了解项目结构

需要进行修复时，请收集以下信息：

项目	示例问题
框架	使用的是 React / Vue / Next.js 等吗？
样式方法	使用 CSS / SCSS / Tailwind / CSS-in-JS 等吗？
源代码位置	样式文件和组件位于何处？
审查范围	仅审查特定页面，还是整个网站？

1.3 自动检测项目

尝试根据工作区中的文件自动检测：

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 识别样式方法

方法	检测方式	编辑目标
纯 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 文件

---

步骤 2：视觉检查阶段

2.1 页面遍历

1. 导航至指定 URL
2. 截取屏幕截图
3. 获取 DOM 结构/快照（如果可行）
4. 如果存在其他页面，通过导航逐一访问

2.2 检查项目

布局问题

问题	描述	严重程度
元素溢出	内容溢出父元素或视口	高
元素重叠	元素意外重叠	高
对齐问题	Grid 或 Flex 对齐问题	中
间距不一致	内边距/外边距不一致	中
文本裁切	未妥善处理过长文本	中

响应式问题

问题	描述	严重程度
移动端适配不佳	小屏幕上的布局错乱	高
断点问题	屏幕尺寸变化时出现不自然的过渡	中
触控目标	按钮在移动端过小	中

无障碍问题

问题	描述	严重程度
对比度不足	文本与背景之间的对比度低	高
无焦点状态	键盘导航时无法确定当前状态	高
缺少 alt 文本	图片没有替代文本	中

视觉一致性

问题	描述	严重程度
字体不一致	混用不同的字体系列	中
颜色不一致	品牌颜色不统一	中
间距不一致	相似元素之间的间距不统一	低

2.3 视口测试（响应式）

在以下视口尺寸下进行测试：

名称	宽度	代表性设备
移动端	375px	iPhone SE/12 mini
平板	768px	iPad
桌面端	1280px	标准 PC
宽屏	1920px	大型显示器

---

步骤 3：问题修复阶段

3.1 问题优先级排序

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 识别源文件

根据存在问题的元素识别源文件：

1. 基于选择器的搜索

   • 按类名或 ID 搜索代码库
   • 使用 grep_search 查找样式定义

2. 基于组件的搜索

   • 根据元素文本或结构识别组件
   • 使用 semantic_search 查找相关文件

3. 文件模式筛选

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

3.3 应用修复

特定框架的修复指南

详情请参阅 references/framework-fixes.md。

修复原则

1. 最小改动：只进行解决问题所需的最小改动
2. 遵循现有模式：遵循项目现有的代码风格
3. 避免破坏性改动：谨慎操作，避免影响其他区域
4. 添加注释：在适当的地方添加注释，说明修复原因

---

第 4 步：重新验证阶段

4.1 修复后确认

1. 重新加载浏览器（或等待开发服务器完成 HMR）
2. 截取修复区域的屏幕截图
3. 对比修复前后

4.2 回归测试

• 确认修复没有影响其他区域
• 确认响应式显示未受影响

4.3 迭代决策

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

迭代次数限制：如果某个问题需要尝试修复超过 3 次，请咨询用户

---

输出格式

审查结果报告

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

---

必备能力

能力	描述	必需
网页导航	访问 URL、页面跳转	✅
屏幕截图	页面图像捕获	✅
图像分析	视觉问题检测	✅
DOM 获取	获取页面结构	建议
文件读写	读取和编辑源代码	修复时必需
代码搜索	在项目中搜索代码	修复时必需

---

参考实现

使用 Playwright MCP 实现

推荐将 Playwright MCP 作为此技能的参考实现。

能力	Playwright MCP 工具	用途
导航	browser_navigate	访问 URL
快照	browser_snapshot	获取 DOM 结构
屏幕截图	browser_take_screenshot	用于视觉检查的图像
点击	browser_click	与交互式元素互动
调整大小	browser_resize	响应式测试
控制台	browser_console_messages	检测 JS 错误

配置示例（MCP 服务）

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

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

工具	特性
Selenium	广泛的浏览器支持，支持多种语言
Puppeteer	专注于 Chrome/Chromium，使用 Node.js
Cypress	易于集成 E2E 测试
WebDriver BiDi	标准化的下一代协议

使用这些工具也可以实现相同的工作流。只要具备所需能力（导航、屏幕截图、DOM 获取），工具的选择就很灵活。

---

最佳实践

应该做（推荐）

• ✅ 修复前务必保存屏幕截图
• ✅ 一次修复一个问题，并逐项验证
• ✅ 遵循项目现有的代码风格
• ✅ 进行重大改动前先征求用户同意
• ✅ 详尽记录修复详情

不应该做（不推荐）

• ❌ 未经确认进行大规模重构
• ❌ 忽视设计系统或品牌指南
• ❌ 忽视性能影响的修复
• ❌ 一次修复多个问题（难以验证）

---

故障排除

问题：未找到样式文件

1. 检查 package.json 中的依赖项
2. 考虑是否使用了 CSS-in-JS
3. 考虑 CSS 是否在构建时生成
4. 询问用户使用的样式方案

问题：修复未生效

1. 检查开发服务器的 HMR 是否正常工作
2. 清除浏览器缓存
3. 如果项目需要构建，请重新构建
4. 检查 CSS 优先级问题

问题：修复影响其他区域

1. 回滚更改
2. 使用更具体的选择器
3. 考虑使用 CSS Modules 或作用域样式
4. 咨询用户以确认影响范围