web-design-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web Interface Guidelines

Web界面指南

Review and fix UI for compliance with Web Interface Guidelines through static code analysis and visual browser inspection.

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

Scope of Application

适用范围

Static sites (HTML/CSS/JS)
SPA frameworks: React / Vue / Angular / Svelte
Full-stack frameworks: Next.js / Nuxt / SvelteKit
Any web application with accessible source code

静态站点（HTML/CSS/JS）
SPA框架：React / Vue / Angular / Svelte
全栈框架：Next.js / Nuxt / SvelteKit
所有可获取源代码的Web应用

Workflow Overview

工作流概览

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)

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)

Step 1: Information Gathering

步骤1：信息收集

1.1 Determine Review Mode

1.1 确定审查模式

Input	Mode	Actions
File/pattern only	Static Analysis	Code review against guidelines
URL only	Visual Inspection	Browser-based visual review
URL + files	Full Review	Both static and visual analysis

输入	模式	操作
仅提供文件/匹配规则	静态分析	依据指南开展代码审查
仅提供URL	视觉检查	基于浏览器的视觉审查
URL+文件	全量审查	同时开展静态和视觉分析

1.2 URL Confirmation (Visual Mode)

1.2 URL确认（视觉模式）

If visual inspection requested but no URL provided, ask:

Please provide the URL of the website to review (e.g.,
http://localhost:3000
)

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

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

1.3 Project Detection

1.3 项目检测

Attempt automatic detection from workspace files:

File	Detection
`package.json`	Framework and dependencies
`tailwind.config.*`	Tailwind CSS
`next.config.*`	Next.js
`nuxt.config.*`	Nuxt
`vite.config.*`	Vite

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

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

1.4 Styling Method Identification

1.4 样式方案识别

Method	Detection	Edit Target
Pure CSS	`*.css` files	Global or component CSS
SCSS/Sass	`.scss` , `.sass`	SCSS files
CSS Modules	`*.module.css`	Module CSS files
Tailwind CSS	`tailwind.config.*`	className in components
styled-components	`styled.` in code	JS/TS files
CSS-in-JS	Inline styles	JS/TS files

方案	检测依据	编辑目标
纯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文件

Step 2: Guidelines Fetch + Static Analysis

步骤2：拉取指南+静态分析

2.1 Fetch Latest Guidelines

2.1 拉取最新指南

Fetch fresh guidelines before each review:

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

Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.

每次审查前拉取最新指南：

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

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

2.2 Static Code Analysis

2.2 静态代码分析

Read the specified files (or prompt user for files/pattern)
Check against all rules in the fetched guidelines
Collect findings with
```
file:line
```
references

读取指定文件（或提示用户提供文件/匹配规则）
对照拉取的指南中的所有规则进行检查
收集问题并标注
```
文件:行号
```
引用

Step 3: Visual Inspection (Browser Mode)

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

3.1 Prerequisites

3.1 前置条件

Target website must be running (local dev server or remote)
Browser automation available (Playwright MCP or cursor-browser-extension)

目标网站必须处于运行状态（本地开发服务器或远程服务）
浏览器自动化工具可用（Playwright MCP或cursor-browser-extension）

3.2 Page Inspection

3.2 页面检查

Navigate to the specified URL
Capture screenshots
Retrieve DOM structure/snapshot
If additional pages exist, traverse through navigation

访问指定URL
截图
获取DOM结构/快照
如果存在其他页面，通过导航遍历所有页面

3.3 Viewport Testing

3.3 视口测试

Test at the following viewports for responsive issues:

Name	Width	Representative Device
Mobile	375px	iPhone SE/12 mini
Tablet	768px	iPad
Desktop	1280px	Standard PC
Wide	1920px	Large display

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

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

3.4 Visual Inspection Checklist

3.4 视觉检查清单

Layout Issues

布局问题

Issue	Description	Severity
Element Overflow	Content overflows container or viewport	High
Element Overlap	Unintended overlapping of elements	High
Alignment Issues	Grid or flex alignment problems	Medium
Inconsistent Spacing	Padding/margin inconsistencies	Medium
Text Clipping	Long text not handled properly	Medium

问题	描述	严重程度
元素溢出	内容超出容器或视口范围	高
元素重叠	非预期的元素重叠	高
对齐问题	Grid或flex布局对齐异常	中
间距不一致	内边距/外边距不统一	中
文本截断	长文本处理不当	中

Responsive Issues

响应式问题

Issue	Description	Severity
Non-mobile Friendly	Layout breaks on small screens	High
Breakpoint Issues	Unnatural transitions at breakpoints	Medium
Touch Targets	Buttons too small on mobile	Medium

问题	描述	严重程度
移动端适配差	小屏幕下布局错乱	高
断点问题	断点处过渡不自然	中
点击区域问题	移动端按钮尺寸过小	中

Accessibility Issues

无障碍问题

Issue	Description	Severity
Insufficient Contrast	Low contrast ratio text/background	High
No Focus State	Cannot see focus during keyboard nav	High
Missing alt Text	No alternative text for images	Medium

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

Visual Consistency

视觉一致性

Issue	Description	Severity
Font Inconsistency	Mixed font families	Medium
Color Inconsistency	Non-unified brand colors	Medium
Spacing Inconsistency	Non-uniform spacing patterns	Low

问题	描述	严重程度
字体不一致	字体家族混用	中
颜色不一致	品牌色不统一	中
间距不一致	间距规范不统一	低

Step 4: Issue Fixing

步骤4：问题修复

4.1 Issue Prioritization

4.1 问题优先级

Priority	Criteria	Action
P1	Layout issues affecting functionality	Fix immediately
P2	Visual issues degrading UX	Fix next
P3	Minor visual inconsistencies	Fix if possible

优先级	判定标准	处理方式
P1	影响功能的布局问题	立即修复
P2	影响UX的视觉问题	次优先修复
P3	轻微视觉不一致	尽量修复

4.2 Identifying Source Files

4.2 定位源文件

Selector-based Search: Search codebase by class name or ID
Component-based Search: Identify components from element text/structure

File Pattern Filtering:

src/**/*.css

styles/**/*

src/components/**/*

基于选择器搜索：通过类名或ID搜索代码库
基于组件搜索：通过元素文本/结构识别对应组件

文件模式过滤：

src/**/*.css

、

styles/**/*

、

src/components/**/*

4.3 Fix Principles

4.3 修复原则

Minimal Changes: Only make minimum changes necessary
Respect Existing Patterns: Follow existing code style
Avoid Breaking Changes: Be careful not to affect other areas
Add Comments: Explain reason for fixes where appropriate

最小改动：仅进行必要的最小范围修改
遵循现有规范：保持现有代码风格
避免破坏性改动：注意不要影响其他功能模块
添加注释：必要时添加注释说明修复原因

Step 5: Re-verification

步骤5：重新验证

5.1 Post-fix Confirmation

5.1 修复后确认

Reload browser (or wait for HMR)
Capture screenshots of fixed areas
Compare before and after

重载浏览器（或等待HMR更新）
对修复区域截图
对比修复前后效果

5.2 Regression Testing

5.2 回归测试

Verify fixes haven't affected other areas
Confirm responsive display is not broken

确认修复未影响其他区域
确认响应式展示未被破坏

5.3 Iteration

5.3 迭代

If issues remain after fix, return to Step 3. Limit to 3 fix attempts per issue before consulting user.

如果修复后仍存在问题，返回步骤3。每个问题最多尝试3次修复，若仍未解决需咨询用户。

Output Format

输出格式

Review Results Report

审查结果报告

markdown

undefined

markdown

undefined

Web Design Review Results

Web设计审查结果

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}

项	值
审查目标	{URL或文件路径}
所用框架	{检测到的框架}
样式方案	{CSS / Tailwind / 其他}
审查模式	{静态 / 视觉 / 全量}
检测到的问题数	{N}
已修复的问题数	{M}

Static Analysis Findings

静态分析结果

{file:line format findings from guidelines check}

{依据指南检查得到的

文件:行号

格式的问题列表}

Visual Inspection Findings

视觉检查结果

[P1] {Issue Title}

[P1] {问题标题}

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

页面：{页面路径}
元素：{选择器或描述}
问题：{详细描述}
已修复文件：
```
{文件路径}
```
修复详情：{修改内容描述}

[P2] {Issue Title}

[P2] {问题标题}

...

Unfixed Issues (if any)

未修复问题（如有）

{Issue Title}

{问题标题}

Reason: {Why it was not fixed}
Recommended Action: {Recommendations for user}

原因：{未修复的原因}
建议操作：{给用户的建议}

Recommendations

优化建议

{Suggestions for future improvements}

---

{后续改进建议}

---

Usage Examples

使用示例

Static Analysis Only

仅静态分析

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

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

Visual Inspection

仅视觉检查

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

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

Full Review (Recommended)

全量审查（推荐）

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

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