web-design-reviewer

Web Design Reviewer

此 Skill 支持对网站设计品质进行视觉检查与验证，并在源代码层级找出并修正问题。

适用范围

• 静态网站 (HTML/CSS/JS)
• SPA 框架，例如 React / Vue / Angular / Svelte
• 全端框架，例如 Next.js / Nuxt / SvelteKit
• CMS 平台，例如 WordPress / Drupal
• 任何其他 Web 应用程序

事前准备

必需条件

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

   • 本机开发伺服器（例如 http://localhost:3000）
   • Staging 测试环境
   • 正式环境（仅限只读审查）

2. 必须支持浏览器自动化

   • 抓取萤幕截图
   • 页面导航
   • 取得 DOM 资讯

3. 拥有源代码存取权限（进行修正时）

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

工作流程概览

flowchart TD
    A[步骤 1：资讯收集] --> B[步骤 2：视觉检查]
    B --> C[步骤 3：问题修正]
    C --> D[步骤 4：重新验证]
    D --> E{是否仍有残留问题？}
    E -->|是| B
    E -->|否| F[完成报告]

---

步骤 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 (其他)	行内样式 (Inline styles)	JS/TS 文件

---

步骤 2：视觉检查阶段

2.1 页面遍历

1. 导航至指定的 URL
2. 抓取萤幕截图
3. 取得 DOM 结构/快照（若可行）
4. 若存在其他页面，通过导航进行遍历

2.2 检查项目

版面问题

问题	描述	严重程度
元件溢出	内容超出父元件或视埠 (Viewport)	高
元件重叠	元件发生非预期的重叠现象	高
对齐问题	Grid 或 Flex 对齐异常	中
间距不一致	Padding/Margin 间距规则混乱	中
文字裁切	长文字未进行妥善溢出处理	中

响应式问题

问题	描述	严重程度
行动端不友好	小萤幕下版面破版	高
断点过渡问题	萤幕尺寸改变时产生不自然的过渡	中
触控目标过小	行动端按钮尺寸太小不易点击	中

无障碍功能问题

问题	描述	严重程度
对比度不足	文字与背景颜色的对比度过低	高
缺少焦点状态	键盘导航时无法辨识当前 Focus 状态	高
缺少 alt 文字	图片未设定替代文字	中

视觉一致性

问题	描述	严重程度
字型不统一	混用了不同的字型系列 (Font Family)	中
颜色不统一	品牌色彩使用不一致	中
间距不统一	相似元件之间的间距不一致	低

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["优先级矩阵"]
        P1["P1：立即修正\n(影响功能的版面破版)"]
        P2["P2：优先修正\n(损害 UX 的视觉缺陷)"]
        P3["P3：尽力修正\n(轻微的视觉不一致)"]
    end

3.2 定位源代码文件

从出现问题的元件定位对应的源代码文件：

1. 基于选择器的搜寻

   • 通过 Class 名称或 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. 重新载入浏览器（或等待开发伺服器 HMR 热更新）
2. 抓取已修正区域的萤幕截图
3. 比对修正前后的差异

4.2 回归测试

• 确认修正动作未引发其他区域异常
• 确认响应式显示正常无破版

4.3 迭代决策

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

迭代上限：针对单一问题若尝试修正超过 3 次仍未解决，请主动咨询用户意见

---

输出格式

审查结果报告

# Web 设计审查结果

## 概要

| 项目 | 内容 |
|------|-------|
| 目标 URL | {URL} |
| 框架 | {检测到的框架} |
| 样式处理 | {CSS / Tailwind / 等} |
| 测试视埠 | 桌面端, 行动端 |
| 发现问题数 | {N} |
| 已修正问题数 | {M} |

## 发现的问题

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

- **页面**：{页面路径}
- **元件**：{选择器或描述}
- **问题描述**：{问题的详细说明}
- **修正文件**：`{文件路径}`
- **修正详情**：{变更说明}
- **萤幕截图**：修正前/修正后

### [P2] {Issue Title}
...

## 未修正问题（如有）

### {问题标题}
- **未修正原因**：{为何未修正/无法修正的原因}
- **建议处理方案**：{给用户的下一步建议}

## 改进建议

- {针对未来可进一步优化的建议}

---

必备能力

能力	描述	是否必需
网页导航	存取 URL、页面跳转	✅
萤幕截图抓取	抓取页面影像	✅
图像分析	识别视觉设计缺陷	✅
DOM 资讯取得	取得页面 DOM 结构	建议
文件读写	存取与编辑源代码	修正问题必需
代码搜寻	在项目内搜寻代码	修正问题必需

---

参考实现

Playwright MCP 参考实现

建议将 Playwright MCP 作为本 Skill 的参考实现。

能力	Playwright MCP 工具	用途
页面导航	browser_navigate	存取 URL
快照取得	browser_snapshot	取得 DOM 结构
萤幕截图	browser_take_screenshot	抓取视觉检查用的影像
点击操作	browser_click	与互动元件进行交互
调整尺寸	browser_resize	响应式测试
Console 监控	browser_console_messages	检测 JS 执行错误

范例配置 (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) 或品牌规范
• ❌ 提出损害效能的修正方案
• ❌ 一次修正多个问题（难以比对与验证）

---

疑难排解

问题：找不到样式文件

1. 检查 package.json 中的依赖项
2. 确认是否使用了 CSS-in-JS
3. 检查样式是否由 Build 构建过程动态生成
4. 向用户询问项目使用的样式处理方式

问题：修正未能生效

1. 检查开发伺服器的 HMR 热更新功能是否正常运作
2. 清除浏览器快取
3. 若项目需要构建，请重新执行 Build
4. 检查 CSS 权重 (Specificity) 问题

问题：修正动作影响到了其他区域

1. 还原 (Rollback) 变更
2. 使用精准度更高的 CSS 选择器
3. 考虑改用 CSS Modules 或 Scoped 样式
4. 咨询用户以确认受影响的范围