web-design-guidelines 是 Vercel Labs 维护的 Web 界面指南，仓库为 vercel-labs/web-interface-guidelines，官网在 vercel.com/design/guidelines。它是一份持续更新的、非穷尽的清单，把界面里容易被忽略的决定写成可检查条目；Vercel 的 agent-skills 里另有一个同名 Skill，可以拿它审查 UI 代码。按官方 README 整理，未在本机完整实测。
清单覆盖什么
README 把条目分成交互、动效、布局、内容、表单、性能、设计、Vercel 专属和“与 Agent 集成”几块。多数条目与框架无关，少数针对 React/Next.js。Vercel 专属那一节明确说明它反映的是 Vercel 的品牌和产品偏好，不是通用规则。
这份指南的写法不是抽象原则，而是能直接落到属性上的判断。例如焦点环要用 :focus-visible，粘性页头不能盖住获得焦点的元素；点击目标至少 24px，移动端至少 44px；移动端输入框字号至少 16px，否则 iOS Safari 会自动放大；不要禁用浏览器缩放，也不要阻止粘贴。
交互、动效与布局
交互部分强调键盘可达、焦点管理和可预测性：所有流程能用键盘完成，遵循 WAI-ARIA 模式；破坏性操作要确认或给撤销窗口；能用 <a> 导航就不要用 <button> 或 <div> 冒充链接；异步更新用 aria-live 播报；筛选、标签页、分页和展开面板的状态尽量写进 URL，保证刷新、分享和前进后退都能复原。
动效部分要求尊重 prefers-reduced-motion，优先 CSS，其次 Web Animations API，最后才是 JS 库；只动 transform 和 opacity 这类合成友好的属性；不要写 transition: all；自动播放超过五秒的动效要提供暂停、停止或隐藏。布局部分则要求元素有明确对齐关系、检查移动端到超宽屏、处理安全区、避免无意义的滚动条，并尽量让 flex/grid 自己算尺寸，而不是用 JS 测量。
表单与内容
表单条目很具体：每个控件都要有 <label>；只有一个输入框时 Enter 提交，多控件时作用于最后一个；发送请求期间才禁用提交按钮，不要一开始就禁用；错误显示在字段旁边，提交后聚焦第一个错误；设置 autocomplete 和有意义的 name；用正确的 type 和 inputmode；占位符以省略号结尾并给出示例值；离开前提示未保存的修改。
内容部分要求所有状态都有设计，包括空、稀疏、密集和错误；标题要反映当前页面；图标按钮要有可访问名称；语义元素优先于 ARIA；提供“跳到正文”链接；数字比较用等宽数字；日期、货币和数字按用户 locale 格式化。
性能与设计细节
性能条目包括：在 iOS 低电量模式和 macOS Safari 上测试；测性能时关闭扩展并做 CPU/网络限速；减少重渲染和布局抖动；POST/PATCH/DELETE 的网络预算控制在 500ms 内；大列表虚拟化；只预加载首屏图片，其余懒加载；图片写明尺寸避免 CLS；对字体做 preconnect、预加载和子集化；把长任务移到 Web Worker；循环动画优先用 <video> 而不是 GIF。
设计条目的例子：阴影至少两层，模拟环境光和直射光；边框和阴影配合使用；子元素圆角不大于父元素并保持同心；非中性背景上的边框、阴影和文字要同色相；图表用色盲友好的配色；对比度优先用 APCA 而不是 WCAG 2；hover、active、focus 状态的对比度要高于静止状态；用 theme-color 和 color-scheme 让浏览器 UI 与页面一致。
怎么让 Agent 用上
安装审查 Skill：
npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines |
也可以把仓库里的 AGENTS.md 下载到项目根目录，让 agent 在生成阶段就带上这些约束。前者适合生成后审查，后者适合从第一行代码开始约束；两者都做也可以。
一次生成后的审查
AI 刚生成一个设置表单，按这份指南逐项看：焦点环是否可见、label 是否关联、错误是否贴着字段、移动端字号会不会触发缩放、提交时按钮是否只在请求期间禁用、危险操作有没有确认、加载状态是否加了 150–300ms 的显示延迟和最短可见时间。把问题按“会阻断操作”和“只是不够好”分开，先修前者。
与 Impeccable、axe/Lighthouse 的分工
Impeccable 提供一套设计语言和确定性检测器，偏重识别 AI 界面的模板感；这份指南覆盖面更广，包含表单、文案、性能和 React/Next.js 细节，并附带一个审查 Skill。axe、Lighthouse 能自动测可访问性和性能指标，但不会告诉你“焦点环被粘性页头盖住了”这类具体交互问题。三者可以叠加，不能互相替代。
它不是品牌指南
清单是非穷尽的，逐条打勾也不会自动产生品牌识别和视觉层级。Vercel 专属的 Title Case、偏好 &、第二人称等规则，是 Vercel 自己的写法，不应直接套到所有产品。自动聚焦、工具提示、动效这些条目也要结合场景判断；规则冲突时，以用户能否顺利完成任务为准。
项目入口
- 仓库：vercel-labs/web-interface-guidelines
- 在线指南：vercel.com/design/guidelines
- 许可：MIT
- 适合：用 AI 生成或改版 Web 界面、需要在交付前做系统审查的前端和设计工程师