web-design-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web Interface Guidelines

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

通过静态代码分析和浏览器视觉检查，评审并修复UI以符合Web Interface Guidelines规范。

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: 信息收集
    ↓
Step 2: 规范获取 + 静态分析
    ↓
Step 3: 视觉检查（若提供URL）
    ↓
Step 4: 问题修复
    ↓
Step 5: 重新验证
    ↓
（若仍有问题则循环）

Step 1: Information Gathering

Step 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

Step 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

读取指定文件（或提示用户提供文件/匹配规则）
对照获取的规范检查所有规则
收集带有
```
file:line
```
引用的问题

Step 3: Visual Inspection (Browser Mode)

Step 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

Step 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	降低用户体验的视觉问题	接下来修复
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

Step 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.

若修复后仍存在问题，返回Step 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}

{来自规范检查的file:line格式问题}

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

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

Best Practices

最佳实践

DO

建议

Always save screenshots before making fixes
Fix one issue at a time and verify each
Follow the project's existing code style
Confirm with user before major changes

修复前务必保存截图
一次修复一个问题并逐一验证
遵循项目现有代码风格
重大变更前需与用户确认

DON'T

不建议

Large-scale refactoring without confirmation
Ignore design systems or brand guidelines
Fix multiple issues at once (difficult to verify)
Skip re-verification after fixes

未经确认进行大规模重构
忽略设计系统或品牌规范
同时修复多个问题（难以验证）
修复后跳过重新验证步骤

Troubleshooting

故障排除

Style files not found

未找到样式文件

Check dependencies in
```
package.json
```
Consider CSS-in-JS possibility
Ask user about styling method

检查
```
package.json
```
中的依赖
考虑是否使用CSS-in-JS方案
询问用户样式实现方式

Fixes not reflected

修复未生效

Check if dev server HMR is working
Clear browser cache
Check CSS specificity issues

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

Fixes affecting other areas

修复影响其他区域

Rollback changes
Use more specific selectors
Consider CSS Modules or scoped styles

回滚变更
使用更具体的选择器
考虑使用CSS Modules或作用域样式