web-design-reviewer

Web Design Reviewer

本 Skill 能够对网站设计质量进行视觉检查与校验，并在源码层面识别与修复 UI/UX 问题。

适用范围

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

前置条件

必要条件

1. 目标网站必须处于运行状态

   • 本地开发服务器（例如 http://localhost:3000）
   • 预发布/测试环境（Staging）
   • 线上生产环境（仅限只读检查）

2. 具备浏览器自动化能力

   • 截屏/抓图
   • 页面导航/跳转
   • DOM 信息提取

3. 拥有源码访问权限（在进行修复时）

   • 项目必须存在于当前工作区（Workspace）中

工作流概览

flowchart TD
    A[Step 1: 信息收集] --> B[Step 2: 视觉检查]
    B --> C[Step 3: 问题修复]
    C --> D[Step 4: 重新验证]
    D --> E{是否仍有残留问题？}
    E -->|是| B
    E -->|否| F[输出完成报告]

---

Step 1: 信息收集阶段

1.1 确认 URL

若未提供 URL，向用户询问：

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

1.2 了解项目架构

进行代码修复前，需收集以下项目信息：

检查项	提问示例
前端框架	项目使用的是 React、Vue 还是 Next.js 等？
样式方案	CSS / SCSS / Tailwind / CSS-in-JS 等
源码位置	样式文件与组件存放在哪个目录下？
评审范围	仅评审特定页面还是全站评审？

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

样式方案	识别依据	修改目标
原生 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	行内 style	JS/TS 文件

---

Step 2: 视觉检查阶段

2.1 页面遍历与抓取

1. 跳转至指定 URL
2. 捕获页面截图
3. 获取 DOM 结构/快照（若支持）
4. 若存在其他页面，通过导航链接逐一遍历

2.2 检查项目分类

布局问题（Layout Issues）

问题类型	描述	严重程度
元素溢出（Element Overflow）	内容超出父容器或视口范围	高（High）
元素重叠（Element Overlap）	元素之间发生非预期的遮挡或重叠	高（High）
对齐异常（Alignment Issues）	Grid 或 Flexbox 对齐错位	中（Medium）
间距不一致（Inconsistent Spacing）	Padding/Margin 边距混乱	中（Medium）
文本截断（Text Clipping）	长文本未合理换行或截断处理	中（Medium）

响应式适配问题（Responsive Issues）

问题类型	描述	严重程度
移动端不友好（Non-mobile Friendly）	小屏设备下布局崩溃或无法正常显示	高（High）
断点过渡异常（Breakpoint Issues）	屏幕尺寸切换时布局跳变不自然	中（Medium）
触控区域过小（Touch Targets）	移动端按钮或可点击区域过小	中（Medium）

无障碍访问问题（Accessibility Issues）

问题类型	描述	严重程度
对比度不足（Insufficient Contrast）	文本与背景颜色的对比度过低	高（High）
缺失焦点状态（No Focus State）	键盘导航时无法识别当前焦点位置	高（High）
缺失 alt 属性（Missing alt Text）	图片未配置替代文本	中（Medium）

视觉一致性问题（Visual Consistency）

问题类型	描述	严重程度
字体不统一（Font Inconsistency）	混用未定义的字体系列	中（Medium）
色彩不统一（Color Inconsistency）	未使用统一的主题配色/品牌色	中（Medium）
元素间距不一致（Spacing Inconsistency）	同类元素之间的间距不规则	低（Low）

2.3 视口测试（响应式）

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

名称	宽度	代表设备
Mobile	375px	iPhone SE/12 mini
Tablet	768px	iPad
Desktop	1280px	标准 PC 屏幕
Wide	1920px	大屏显示器

---

Step 3: 问题修复阶段

3.1 修复优先级划分

block-beta
    columns 1
    block:priority["优先级矩阵"]
        P1["P1: 立即修复\n（影响核心功能的布局崩溃与严重缺陷）"]
        P2["P2: 优先修复\n（损害用户体验的视觉问题）"]
        P3["P3: 有空修复\n（次要的视觉微瑕）"]
    end

3.2 定位源码文件

根据出问题的 UI 元素寻找对应的源代码文件：

1. 类名/ID 检索（Selector Search）

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

2. 组件检索（Component Search）

   • 根据元素文本或 DOM 结构判断对应的组件
   • 使用 semantic_search 查找相关组件代码

3. 按文件模式过滤

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

3.3 实施代码修复

框架专属修复指南

详情参见 references/framework-fixes.md。

代码修复原则

1. 最小化改动：仅做出解决问题所需的最小代码变更
2. 遵循既有规范：严格保持与项目现有代码风格一致
3. 避免破坏性变更：切勿引发连锁反应或破坏其他模块
4. 添加必要注释：在关键修复位置注明修复原因

---

Step 4: 重新验证阶段

4.1 修复后确认

1. 刷新浏览器（或等待开发服务器热更新 HMR）
2. 重新截取已修复区域的页面截图
3. 对比修复前后的效果差异

4.2 回归测试

• 确保本次修复没有对页面其他区域产生负面影响
• 确认响应式布局未受到破坏

4.3 迭代决策

flowchart TD
    A{是否仍有残留问题？}
    A -->|是| B[返回 Step 2 重新检查]
    A -->|否| C[进入完成报告]

迭代上限规则：针对同一个特定问题，若尝试修复超过 3 次仍未解决，需主动向用户寻求反馈。

---

输出格式规范

评审结果报告模板

# 网站设计评审报告

## 概览

| 检查项 | 属性值 |
|------|-------|
| 目标 URL | {URL} |
| 技术框架 | {识别出的框架} |
| 样式方案 | {CSS / Tailwind / 其他} |
| 测试视口 | Desktop, Mobile |
| 发现问题数 | {N} |
| 已修复问题数 | {M} |

## 已发现与修复的问题列表

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

- **页面路径**：{Page path}
- **问题元素**：{Selector 或元素描述}
- **详细现象**：{问题具体描述}
- **修复文件**：`{File path}`
- **修改说明**：{具体的代码改动摘要}
- **效果截图**：修复前 / 修复后对比

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

## 未修复问题（如有）

### {问题标题}
- **未修复原因**：{未能修复的具体原因说明}
- **处理建议**：{给用户的建议方案}

## 后续优化建议

- {针对网站 UI/UX 的进一步改进建议}

---

所需能力清单

能力要求	详细描述	必备状态
Web 页面导航	能够访问 URL 并执行页面跳转	✅ 必须
网页截图捕获	能够捕获页面渲染图像	✅ 必须
视觉图像分析	能够识别视觉上的设计缺陷	✅ 必须
DOM 结构获取	能够提取页面 DOM 树信息	推荐配置
文件读写能力	能够读取与编辑源码文件	修复时必须
代码检索能力	能够在项目中快速搜索代码	修复时必须

---

参考实现方案

基于 Playwright MCP 的实现

推荐使用 Playwright MCP 作为本 Skill 的参考实现方案。

能力需求	Playwright MCP 工具	工具用途
页面导航	browser_navigate	访问目标 URL
DOM 快照	browser_snapshot	提取 DOM 结构
截屏分析	browser_take_screenshot	捕获页面截图用于视觉检查
元素交互	browser_click	点击可交互元素
调整视口	browser_resize	测试响应式布局
控制台日志	browser_console_messages	检测 JavaScript 报错

配置示例 (MCP Server)

{
  "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（禁忌做法）

• ❌ 未经用户同意擅自进行大面积代码重构
• ❌ 无视既有的设计系统（Design System）或品牌规范
• ❌ 编写只管视觉不管性能的低效样式代码
• ❌ 一次性批量修复多个问题（会导致难以排查和校验）

---

常见问题排查（Troubleshooting）

问题 1：找不到对应的样式文件

1. 检查 package.json 中的依赖库列表
2. 排查是否采用了 CSS-in-JS 方案
3. 检查样式是否由构建过程动态生成
4. 主动询问用户具体的样式实现方案

问题 2：代码修改后页面无变化/未生效

1. 检查开发服务器的热更新（HMR）机制是否正常运行
2. 清理浏览器缓存
3. 若项目需要手动构建，尝试重新 build
4. 检查是否存在 CSS 优先级（Specificity）覆盖问题

问题 3：修复某个问题后导致其他区域样式崩溃

1. 立即回滚当前改动
2. 改用选择性更精准的高优先级 Selector
3. 考虑使用 CSS Modules 或 Scoped CSS 限制样式作用域
4. 与用户沟通确认影响范围与改动方案