web-design-guidelines

用途

Web Design Guidelines 技能用于审查并修复网页界面，使其符合 Web Interface Guidelines。它通过静态代码分析和浏览器可视化检查两种手段，发现界面在布局、响应式、可访问性和视觉一致性方面的问题，并给出修复。

适用范围

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

工作流程

整体流程为：信息收集 → 指南获取与静态分析 → 可视化检查（若提供 URL）→ 问题修复 → 复验，若问题仍存在则循环。

步骤 1：信息收集

根据输入确定审查模式：仅文件/模式为静态分析；仅 URL 为可视化检查；URL 加文件为完整审查。若请求可视化检查但未提供 URL，会询问待审查网站地址（如 http://localhost:3000）。随后尝试从工作区文件自动检测项目类型（package.json、tailwind.config.、next.config.、nuxt.config.、vite.config.），并识别样式方案（纯 CSS、SCSS/Sass、CSS Modules、Tailwind CSS、styled-components、CSS-in-JS），以确定编辑目标。

步骤 2：指南获取与静态分析

每次审查前从 https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md 获取最新指南，使用 WebFetch 检索规则与输出格式说明。然后读取指定文件，对照全部规则检查，收集带 file:line 引用的发现。

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

前提是目标网站正在运行（本地开发服务器或远程），且具备浏览器自动化能力（Playwright MCP 或 cursor-browser-extension）。操作包括导航到指定 URL、截图、获取 DOM 结构/快照，并通过导航遍历其他页面。在移动端 375px、平板 768px、桌面 1280px、宽屏 1920px 四种视口下测试响应式问题。

可视化检查清单涵盖：

布局问题：元素溢出（高）、元素重叠（高）、对齐问题（中）、间距不一致（中）、文本裁剪（中）
响应式问题：非移动友好（高）、断点问题（中）、触摸目标过小（中）
可访问性问题：对比度不足（高）、无焦点状态（高）、缺少 alt 文本（中）
视觉一致性：字体不一致（中）、颜色不一致（中）、间距不一致（低）

步骤 4：问题修复

按优先级处理：P1 影响功能的布局问题立即修复；P2 降低体验的视觉问题其次；P3 轻微视觉不一致尽量修复。通过选择器搜索、组件搜索或文件模式过滤定位源文件。修复原则：最小改动、遵循现有代码风格、避免破坏性变更、适当添加注释说明修复原因。

步骤 5：复验

修复后重新加载浏览器（或等待 HMR）、截图对比前后、进行回归测试确认未影响其他区域且响应式显示正常。若问题仍存在则返回步骤 3，每个问题最多尝试修复 3 次后咨询用户。

输出格式

输出审查结果报告，包含摘要表（目标、框架、样式、审查模式、检测问题数、已修复问题数）、静态分析发现、可视化检查发现（按 P1/P2 分级，含页面、元素、问题、修复文件、修复详情）、未修复问题（原因与建议）以及改进建议。

使用示例

仅静态分析：

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

最佳实践

建议：修复前始终保存截图；一次只修一个问题并逐一验证；遵循项目现有代码风格；重大变更前与用户确认。避免：未经确认的大规模重构；忽略设计系统或品牌规范；一次修复多个问题（难以验证）；修复后跳过复验。

故障排查

找不到样式文件：检查 package.json 依赖，考虑 CSS-in-JS 可能，询问用户样式方案
修复未生效：检查开发服务器 HMR 是否工作、清除浏览器缓存、检查 CSS 优先级问题
修复影响其他区域：回滚更改、使用更具体的选择器、考虑 CSS Modules 或 scoped 样式

技能介绍

用途