web-design-guidelines

Web 界面指南

通过静态代码分析和浏览器视觉检查，检查并修复 UI，使其符合 Web 界面指南。

适用范围

• 静态网站（HTML/CSS/JS）
• SPA 框架：React / Vue / Angular / Svelte
• 全栈框架：Next.js / Nuxt / SvelteKit
• 任何源代码可访问的 Web 应用

工作流概览

Step 1: Information Gathering
    ↓
Step 2: Guidelines Fetch + Static Analysis
    ↓
Step 3: Visual Inspection (if URL provided)
    ↓
Step 4: Issue Fixing
    ↓
Step 5: Re-verification
    ↓
(Loop if issues remain)

---

第 1 步：收集信息

1.1 确定检查模式

输入	模式	操作
仅文件/模式	静态分析	根据指南检查代码
仅 URL	视觉检查	通过浏览器进行视觉检查
URL + 文件	全面检查	同时进行静态和视觉分析

1.2 确认 URL（视觉模式）

如果用户请求视觉检查，但未提供 URL，请询问：

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

1.3 检测项目

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

文件	检测内容
package.json	框架和依赖项
tailwind.config.*	Tailwind CSS
next.config.*	Next.js
nuxt.config.*	Nuxt
vite.config.*	Vite

1.4 识别样式方法

方法	检测方式	编辑目标
纯 CSS	*.css 文件	全局或组件 CSS
SCSS/Sass	*.scss、*.sass	SCSS 文件
CSS Modules	*.module.css	模块 CSS 文件
Tailwind CSS	tailwind.config.*	组件中的 className
styled-components	代码中的 styled.	JS/TS 文件
CSS-in-JS	内联样式	JS/TS 文件

---

第 2 步：获取指南 + 静态分析

2.1 获取最新指南

每次检查前都获取最新指南：

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

使用 WebFetch 获取最新规则。获取的内容包含所有规则和输出格式说明。

2.2 静态代码分析

1. 阅读指定文件（或请用户提供文件/模式）
2. 根据获取的指南检查所有规则
3. 收集包含 file:line 引用的检查结果

---

第 3 步：视觉检查（浏览器模式）

3.1 前提条件

• 目标网站必须正在运行（本地开发服务器或远程服务）
• 必须具备浏览器自动化功能（Playwright MCP 或 cursor-browser-extension）

3.2 页面检查

1. 导航至指定 URL
2. 截取屏幕截图
3. 获取 DOM 结构/快照
4. 如果还有其他页面，则通过导航逐一查看

3.3 视口测试

在以下视口中测试响应式问题：

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

3.4 视觉检查清单

布局问题

问题	描述	严重性
元素溢出	内容溢出容器或视口	高
元素重叠	元素之间出现非预期重叠	高
对齐问题	网格或 flex 对齐问题	中
间距不一致	内边距/外边距不一致	中
文本裁切	长文本未得到妥善处理	中

响应式问题

问题	描述	严重性
不适配手机	布局在小屏幕上错乱	高
断点问题	在断点处出现不自然的变化	中
触控目标	按钮在手机上过小	中

无障碍问题

问题	描述	严重性
对比度不足	文本与背景的对比度过低	高
无焦点状态	键盘导航时无法看到焦点	高
缺少 alt 文本	图片缺少替代文本	中

视觉一致性

问题	描述	严重程度
字体不一致	混用不同字体系列	中
颜色不一致	品牌色不统一	中
间距不一致	间距模式不统一	低

---

第 4 步：修复问题

4.1 问题优先级排序

优先级	标准	操作
P1	影响功能的布局问题	立即修复
P2	降低用户体验的视觉问题	接下来修复
P3	轻微的视觉不一致	尽可能修复

4.2 确定源文件

1. 基于选择器搜索：按类名或 ID 搜索代码库
2. 基于组件搜索：根据元素文本或结构确定组件
3. 按文件模式筛选：src/**/*.css、styles/**/*、src/components/**/*

4.3 修复原则

1. 尽量少改动：只进行必要的最小改动
2. 遵循现有模式：遵循现有代码风格
3. 避免破坏性更改：注意不要影响其他区域
4. 添加注释：在适当的地方说明修复原因

---

第 5 步：重新验证

5.1 修复后确认

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

5.2 回归测试

• 确认修复未影响其他区域
• 确认响应式显示正常

5.3 迭代

如果修复后仍有问题，请返回第 3 步。每个问题最多尝试修复 3 次，之后请咨询用户。

---

输出格式

审查结果报告

# Web Design Review Results

## Summary

| Item | Value |
|------|-------|
| Target | {URL or files} |
| Framework | {Detected framework} |
| Styling | {CSS / Tailwind / etc.} |
| Review Mode | {Static / Visual / Full} |
| Issues Detected | {N} |
| Issues Fixed | {M} |

## Static Analysis Findings

{file:line format findings from guidelines check}

## Visual Inspection Findings

### [P1] {Issue Title}

- **Page**: {Page path}
- **Element**: {Selector or description}
- **Issue**: {Detailed description}
- **Fixed File**: `{File path}`
- **Fix Details**: {Description of changes}

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

## Unfixed Issues (if any)

### {Issue Title}
- **Reason**: {Why it was not fixed}
- **Recommended Action**: {Recommendations for user}

## Recommendations

- {Suggestions for future improvements}

---

使用示例

仅进行静态分析

Review my UI in src/components/
Check accessibility of my forms
Audit design of src/pages/

视觉检查

Review the design at http://localhost:3000
Check the UI at http://localhost:5173/dashboard
Find layout problems on my site

完整审查（推荐）

Review my UI at localhost:3000 and fix issues in src/
Audit the design and fix responsive problems

---

最佳实践

应该做

• 修复前始终保存屏幕截图
• 一次修复一个问题，并逐一验证
• 遵循项目现有的代码风格
• 进行重大更改前先征得用户同意

不应该做

• 未经确认就进行大规模重构
• 忽略设计系统或品牌指南
• 一次修复多个问题（难以验证）
• 修复后跳过重新验证

---

故障排除

未找到样式文件

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

修复未生效

1. 检查开发服务的 HMR 是否正常工作
2. 清除浏览器缓存
3. 检查 CSS 优先级问题

修复影响其他区域

1. 回滚更改
2. 使用更具体的选择器
3. 考虑使用 CSS Modules 或作用域样式