前言¶
用 Cursor、Claude Code、Codex 这类 AI 编程工具写前端，速度很快，但页面上常见的问题也容易一起带出来：图标按钮没有 aria-label、交互元素去掉了焦点环、动画没考虑 prefers-reduced-motion、表单缺标签、图片没写宽高导致布局抖动。很多「看起来能用」的界面，放到可访问性、触控和性能规则下一查，缺口就很明显。
Vercel Labs 维护的 web-design-guidelines 正是为这个问题准备的 Agent Skill。它不教你怎么画界面，而是在你说「帮我 review UI / 查一下无障碍」时，按 Vercel 的 Web Interface Guidelines 去审代码，并给出可直接跳转的 file:line 结果。规范本身放在远程仓库，每次审查前都会重新拉取，规则跟着上游更新。
本文说明它是什么、覆盖哪些检查项、怎么安装启用，以及日常怎么用。
这是什么¶
web-design-guidelines 属于 vercel-labs/agent-skills 官方技能集，作者标注为 vercel，当前元数据版本为 1.0.0。它遵循通用的 Agent Skills（SKILL.md）格式，可用 skills CLI 安装到 Cursor、Claude Code、Codex 等支持该标准的 AI 编程工具中。
一句话定位：按 Vercel Web Interface Guidelines，对指定 UI 代码做可访问性、UX 与性能相关合规审查。
官方仓库对它的描述是：对照 Web 界面最佳实践审查 UI 代码，覆盖 100+ 条规则。触发场景包括：
- Review my UI
- Check accessibility
- Audit design
- Review UX
- Check my site against best practices
规范正文不在 Skill 目录里写死，而是每次审查前从下面地址拉取最新内容：
https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
核心功能与检查范围¶
Skill 的工作流程很直接，官方 SKILL.md 写明了四步：
- 从上述 URL 拉取最新指南
- 读取用户指定的文件（或路径模式）；未指定则先向用户确认
- 按指南中的全部规则逐项检查
- 按指南要求的简洁格式输出发现项
指南按主题分组，和仓库 README 对齐的主要类别包括：
- Accessibility：图标按钮的
aria-label、表单标签、键盘处理、语义化 HTML、aria-live等 - Focus States：可见焦点、
:focus-visible，禁止无替代方案地去掉outline - Forms：
autocomplete/name、正确的type与inputmode、可点击标签、错误提示与提交态 - Animation：尊重
prefers-reduced-motion，优先动画transform/opacity，避免transition: all - Typography：省略号、弯引号、数字等宽（
tabular-nums）等排版细节 - Images：显式宽高、首屏与懒加载策略、
alt - Performance：长列表虚拟化、避免渲染阶段读布局、字体与预连接等
- Navigation & State：URL 反映状态、用链接做导航、危险操作需确认或可撤销
- Touch & Interaction / Safe Areas / Dark Mode / Locale / Hydration 等移动端与主题、国际化、水合安全相关规则
输出要求高信噪比：按文件分组，使用编辑器可点击的 file:line，点出问题与位置，非必要不展开长篇解释。官方示例形态大致如下：
## src/Button.tsx
src/Button.tsx:42 - icon button missing aria-label
src/Button.tsx:18 - input lacks label
src/Button.tsx:55 - animation missing prefers-reduced-motion
src/Button.tsx:67 - transition: all → list properties
## src/Card.tsx
✓ pass
这种形态适合在 PR 前或 AI 批量改 UI 之后做一轮「扫雷」，把模糊的「设计感觉」落成可改的代码位点。
安装与启用¶
该 Skill 随 vercel-labs/agent-skills 发布。只装这一项时，可用 skills CLI（官方文档与 skills.sh 页面均提供同类命令）：
npx skills add vercel-labs/agent-skills --skill web-design-guidelines
也可以用完整 GitHub 地址：
npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines
或直接指向 Skill 目录：
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
若希望一次装入该仓库下全部技能：
npx skills add vercel-labs/agent-skills
常用选项（以 skills CLI 文档为准）：
-g/--global：装到用户目录，跨项目可用-y：跳过确认，适合 CI--list：只列出仓库里有哪些 Skill，不安装
安装完成后，Agent 会在任务与 Skill 描述匹配时自动选用。Vercel 文档说明 skills CLI 可对接包括 Claude Code、GitHub Copilot、Cursor、Cline 等在内的多种 Agent；具体落盘目录因工具而异（例如项目级常见 .cursor/skills/、.claude/skills/、.agents/skills/ 等），以当前工具文档与 CLI 提示为准。
典型用法¶
装好后，不必背命令名，直接用自然语言触发即可。官方推荐的说法包括：
Review my UI
Check accessibility
Audit design for src/components/**
Review UX on the settings page components
Check my site against best practices
更稳妥的做法是带上文件或目录，减少 Agent 再追问的一轮：
用 web-design-guidelines 审查 app/components 下的按钮和表单组件，按 file:line 列出问题
对照 Web Interface Guidelines 检查 src/Modal.tsx，重点看焦点、滚动锁和 reduced-motion
按 Skill 约定，Agent 应先拉取最新 command.md，再读你指定的文件，最后按规范输出。若你没给路径，它会先问要审哪些文件。
审查结束后，建议把结果当 checklist：优先修无障碍与焦点、表单、危险操作确认这类高影响项，再处理排版与文案细则。同一组件改完后可以再跑一轮，确认是否变成 ✓ pass。
适用场景与注意事项¶
比较适合这些场景：
- AI 刚生成或大改过一批 UI，需要快速筛一遍常见合规问题
- 做无障碍与 UX 自检，但暂时没有完整设计系统 / lint 规则落地
- Code Review 前先让 Agent 按统一清单扫文件，人再盯业务逻辑
- 希望团队审查口径对齐 Vercel 公开的 Web Interface Guidelines
使用时注意几点：
- 依赖联网拉取规范。每次审查要能访问
web-interface-guidelines的 raw 内容；离线或网络受限时，规则可能拿不到或不是最新版。 - 它是审查流程，不是自动修完所有问题的魔法。输出偏「指出问题」，具体改法仍要结合组件库和产品约束。
- 规则偏 Web 前端界面。覆盖面广，但不会替代完整的安全审计、视觉设计评审或业务验收。
- 以一手资料为准。Skill 行为以仓库中的
SKILL.md与远程command.md为准；第三方转载若与官方不一致，以 GitHub 原文为准。
小结¶
web-design-guidelines 把 Vercel 的 Web Interface Guidelines 变成可自动触发的 Agent 审查流程：先拉最新规则，再按文件输出高信噪比的 file:line 发现。对经常用 AI 写 UI、又担心无障碍与交互细节被带偏的团队，它是一个成本低、口径清晰的补充环节。
官方地址：
- Skill 目录：https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
- 技能集仓库：https://github.com/vercel-labs/agent-skills
- 目录页：https://skills.sh/vercel-labs/agent-skills/web-design-guidelines
- 规范源：https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
