网页设计审查员

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

适用范围

• 静态网站（HTML/CSS/JS）
• 单页应用程序框架，如 React / Vue / Angular / Svelte
• 全栈框架，如 Next.js / Nuxt / SvelteKit
• 内容管理系统平台，如 WordPress / Drupal
• 任何其他网络应用

前提条件

必需

1. 目标网站必须正在运行
   • 本地开发服务器（例如 http：//localhost：3000）
   • 预发布环境
   • 生产环境（用于只读审查）
2. 必须提供浏览器自动化功能
   • 截图捕获
   • 页面导航
   • 文档对象模型信息检索
3. 访问源代码（进行修复时）
   • 项目必须位于工作区内

工作流程概览

flowchart TD
    A[步骤 1：信息收集] --> B[步骤 2：视觉检查]
    B --> C[步骤 3：问题修复]
    C --> D[步骤 4：重新验证]
    D --> E{还有问题吗？}
    E -->|是| B
    E -->|否| F[完成报告]

步骤 1：信息收集阶段

1.1 确认网址

如果未提供网址，询问用户：

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

1.2 了解项目结构

在进行修复时，收集以下信息：

1.3 自动项目检测

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

检测目标：
├── package.json     → 框架和依赖项
├── tsconfig.json    → TypeScript 使用情况
├── tailwind.config  → Tailwind CSS
├── next.config      → Next.js
├── vite.config      → Vite
├── nuxt.config      → Nuxt
└── src/ 或 app/     → 源代码目录

1.4 识别样式方法

步骤 2：视觉检查阶段

2.1 页面遍历

1. 导航到指定的网址
2. 捕获截图
3. 检索文档对象模型结构/快照（如可能）
4. 如果存在其他页面，通过导航进行遍历

2.2 检查项目

布局问题

响应式问题

可访问性问题

视觉一致性

2.3 视口测试（响应式）

在以下视口进行测试：

步骤 3：问题修复阶段

3.1 问题优先级排序

block-beta
    columns 1
    block:priority["优先级矩阵"]
        P1["P1：立即修复\n（影响功能性的布局问题）"]
        P2["P2：接下来修复\n（降低用户体验的视觉问题）"]
        P3["P3：尽可能修复\n（轻微视觉不一致）"]
    end

3.2 识别源文件

从有问题的元素识别源文件：

1. 基于选择器的搜索
   • 通过类名或 ID 搜索代码库
   • 使用 grep_search 探索样式定义
2. 基于组件的搜索
   • 从元素文本或结构识别组件
   • 使用 semantic_search 探索相关文件
3. 文件模式过滤

   样式文件： src/**/*.css, styles/**/*
   组件： src/components/**/*
   页面： src/pages/**, app/**
   

3.3 应用修复

特定框架的修复指南

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

修复原则

1. 最小更改：只做解决问题所需的最小更改
2. 尊重现有模式：遵循项目中现有的代码风格
3. 避免破坏性更改：注意不要影响其他区域
4. 添加注释：在适当位置添加注释说明修复原因

步骤 4：重新验证阶段

4.1 修复后确认

1. 重新加载浏览器（或等待开发服务器热模块替换）
2. 捕获修复区域的截图
3. 对比修复前后

4.2 回归测试

• 验证修复没有影响其他区域
• 确认响应式显示未被破坏

4.3 迭代决策

flowchart TD
    A{还有问题吗？}
    A -->|是| B[返回步骤 2]
    A -->|否| C[进入完成报告]

迭代限制：如果针对特定问题需要超过 3 次修复尝试，请咨询用户

输出格式

审查结果报告

# 网页设计审查结果

## 摘要

| 项目 | 值 |
|------|-------|
| 目标网址 | {网址} |
| 框架 | {检测到的框架} |
| 样式方法 | {CSS / Tailwind / 等} |
| 测试的视口 | 桌面端、移动端 |
| 检测到的问题 | {N} |
| 已修复的问题 | {M} |

## 检测到的问题

### [P1] {问题标题}

- **页面**： {页面路径}
- **元素**： {选择器或描述}
- **问题**： {问题的详细描述}
- **已修复文件**： `{文件路径}`
- **修复详情**： {更改描述}
- **截图**： 修复前后

### [P2] {问题标题}
...

## 未修复的问题（如有）

### {问题标题}
- **原因**： {为何未修复/无法修复}
- **建议操作**： {给用户的建议}

## 建议

- {对未来改进的建议}

必需能力

参考实现

使用 Playwright 模型上下文协议实现

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

配置示例（模型上下文协议服务器）

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

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

同样的工作流程可以使用这些工具实现。只要它们提供必要的能力（导航、截图、文档对象模型检索），工具的选择是灵活的。

最佳实践

要做的（推荐）

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

不要做的（不推荐）

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

故障排除

问题：找不到样式文件

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

问题：修复未生效

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

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

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