web-design-reviewer

网页设计审查

此技能可对网站设计质量进行视觉检查与验证，并在源代码层面识别和修复问题。

适用范围

• 静态网站（HTML/CSS/JS）
• SPA 框架，例如 React / Vue / Angular / Svelte
• 全栈框架，例如 Next.js / Nuxt / SvelteKit
• CMS 平台，例如 WordPress / Drupal
• 任何其他 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	Module 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 检查项

检查期间以及修复后验证期间，请逐一对照 references/visual-checklist.md。

布局问题

问题	描述	严重程度
元素溢出	内容从父元素或视口溢出	高
元素重叠	元素发生非预期重叠	高
对齐问题	网格或 flex 对齐问题	中
间距不一致	padding/margin 不一致	中
文本裁剪	长文本未得到正确处理	中

响应式问题

问题	描述	严重程度
不移动友好	布局在小屏幕上断裂	高
断点问题	屏幕尺寸变化时过渡不自然	中
触摸目标	移动端按钮过小	中

无障碍问题

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

视觉一致性

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

2.3 视口测试（响应式）

在以下视口进行测试：

名称	宽度	代表性设备
Mobile	375px	iPhone SE/12 mini
Tablet	768px	iPad
Desktop	1280px	标准 PC
Wide	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 获取），工具的选择是灵活的。

---

最佳实践

DO（推荐）

• ✅ 在进行修复前始终保存截图
• ✅ 一次修复一个问题并逐一验证
• ✅ 遵循项目现有的代码风格
• ✅ 重大更改前与用户确认
• ✅ 详细记录修复细节

DON'T（不推荐）

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

---

故障排除

问题：找不到样式文件

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

问题：修复未生效

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

问题：修复影响了其他区域

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