web-design-guidelines 多维度简评

来源：vercel-labs/agent-skills 类别：前端开发 / UI/UX 审查 核心数据：100+ 条规则，覆盖 10+ UI/UX 类别

一、核心定位与价值

react-best-practices 管性能，web-design-guidelines 管UI/UX。

它是 Vercel 团队的 UI/UX 质量审查工具，100+ 条规则覆盖可访问性、焦点处理、表单、动画、排版、图像、导航、深色模式、触摸交互、国际化。

Skill 的工作方式：

1. 从 https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md 获取最新指南
2. 读取指定文件
3. 对照所有规则进行检查
4. 以 file:line 格式输出发现的问题

最佳搭配：

• react-best-practices：性能（CRITICAL → LOW 8 个类别）
• web-design-guidelines：UI/UX（10+ 个类别）
• frontend-design：美学方向

三者一起 = React 项目的”质量铁三角”。

二、10 大类别详解

类别 1：可访问性（Accessibility）

规则 1.1：所有交互元素必须有 ARIA 属性

// ❌ 错误
<button onClick={handleClick}>
  <svg>...</svg>
</button>

// ✅ 正确
<button aria-label="关闭对话框" onClick={handleClick}>
  <svg aria-hidden="true">...</svg>
</button>

规则 1.2：颜色对比度满足 WCAG AA

• 正文：4.5:1
• 大字体：3:1
• 工具：WebAIM Contrast Checker

规则 1.3：图片必须有 alt

// ❌ <img src="hero.jpg" />

// ✅ <img src="hero.jpg" alt="产品仪表板截图" />

规则 1.4：表单控件有关联标签

// ❌
<input type="email" />

// ✅
<label htmlFor="email">邮箱</label>
<input id="email" type="email" />

类别 2：焦点处理（Focus）

规则 2.1：键盘可访问

所有功能必须能通过 Tab/Shift+Tab/Enter/Space 完成。

规则 2.2：可见的焦点指示

/* ❌ 默认浏览器焦点太弱 */
*:focus { outline: none; }

/* ✅ 自定义清晰焦点 */
button:focus-visible {
  outline: 2px solid #4f46e5;
  outline-offset: 2px;
}

规则 2.3：跳过导航链接

<a href="#main-content" className="skip-link">
  跳到主要内容
</a>

类别 3：表单（Forms）

规则 3.1：实时验证 + 错误提示

// ✅ 实时验证
<form onSubmit={handleSubmit}>
  <input
    type="email"
    aria-invalid={hasError}
    aria-describedby="email-error"
  />
  {hasError && <span id="email-error">邮箱格式不正确</span>}
</form>

规则 3.2：必填字段标记

<label htmlFor="name">
  姓名 <span aria-label="必填">*</span>
</label>

规则 3.3：自动完成属性

<input type="email" autoComplete="email" />
<input type="password" autoComplete="current-password" />

类别 4：动画（Animation）

规则 4.1：尊重用户的减少运动偏好

@media (prefers-reduced-motion: reduce) {
  .card {
    transition: none;
  }
}

规则 4.2：动效时长合理

• 微交互动效：100-200ms
• 页面切换：200-400ms
• 不要超过 500ms（用户会感觉”卡”）

规则 4.3：缓动函数

/* ✅ ease-out 自然 */
transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1);

类别 5：排版（Typography）

规则 5.1：响应式字号

.title {
  font-size: clamp(1.5rem, 4vw, 2.5rem);
}

规则 5.2：行高合理

• 正文：1.5-1.7
• 标题：1.2-1.3

规则 5.3：字体回退

font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;

类别 6：图像（Images）

规则 6.1：使用 next/image 或类似优化

<Image
  src="/hero.jpg"
  alt="产品仪表板"
  width={1200}
  height={600}
  priority
  placeholder="blur"
/>

规则 6.2：懒加载非首屏图片

<Image src="/footer.jpg" alt="..." loading="lazy" />

规则 6.3：合适的格式

• 照片：WebP / AVIF
• 图标：SVG

类别 7：导航（Navigation）

规则 7.1：当前页标记

<NavLink to="/tools/" aria-current={isActive ? 'page' : undefined}>
  产品
</NavLink>

规则 7.2：面包屑

首页 > 产品 > 详情

类别 8：深色模式（Dark Mode）

规则 8.1：使用 CSS 变量

:root {
  --bg: #ffffff;
  --text: #111827;
}

[data-theme="dark"] {
  --bg: #111827;
  --text: #f9fafb;
}

规则 8.2：尊重系统偏好

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #111827;
    --text: #f9fafb;
  }
}

类别 9：触摸交互（Touch）

规则 9.1：按钮最小尺寸 44x44px

.button {
  min-width: 44px;
  min-height: 44px;
  padding: 12px 16px;
}

规则 9.2：避免 hover-only 交互

移动端没有 hover——必须有 tap 或 click 替代。

类别 10：国际化（i18n）

规则 10.1：硬编码字符串集中管理

// ❌ <h1>Welcome</h1>
// ✅ <h1>{t('welcome')}</h1>

规则 10.2：日期/数字格式化

const formatter = new Intl.DateTimeFormat(locale)
formatter.format(new Date())

规则 10.3：RTL 支持

[dir="rtl"] .icon-arrow {
  transform: scaleX(-1);
}

三、5 大实战场景

场景 1：UI 审查

用 web-design-guidelines 审查我的产品落地页，重点检查可访问性。

场景 2：表单优化

优化我的注册表单：
- 实时验证
- 必填字段标记
- 错误提示友好
- 键盘可访问

场景 3：深色模式适配

为我的网站添加完整的深色模式支持，包括：
- CSS 变量重构
- 尊重系统偏好
- 切换按钮

场景 4：动画优化

为我的卡片列表添加动效：
- 进场动画
- hover 反馈
- 尊重 prefers-reduced-motion

场景 5：移动端适配

为我的 Dashboard 优化移动端体验：
- 触摸目标 ≥ 44px
- 导航汉堡菜单
- 表格响应式

四、安装

# 一键安装
npx skills add vercel-labs/agent-skills

# 选择性安装
npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines

五、配合使用

npx skills add vercel-labs/agent-skills
# → react-best-practices（性能 40+）+ web-design-guidelines（UI/UX 100+）+ vercel-deploy-claimable（部署）

三者一起装：

• 写代码时：react-best-practices 提示性能
• 设计时：frontend-design 提供美学方向
• 审查时：web-design-guidelines 检查 UI/UX

六、6 条实战建议

1. 审查时启用：每个 PR 必跑
2. 关键页面优先：先审查首页、登录、支付
3. 可访问性优先：WCAG AA 是底线
4. 真实设备测试：模拟器和真机差异大
5. 用 axe DevTools：自动检测可访问性问题
6. 建立设计系统：把规则沉淀为组件库

七、常见 Q&A

Q: 规则会更新吗？ A: 每次审查前从 GitHub 拉取最新规则，始终保持最新。

Q: 支持什么框架？ A: 大多数指南是框架无关的，部分特定于 React/Next.js。

Q: 怎么集成 CI？ A: 生成的审查输出可集成到 CI pipeline。

八、总结

web-design-guidelines 是 UI/UX 质量审查的事实标准。

核心价值：

• 100+ 条 Vercel 官方规则
• 覆盖 10+ UI/UX 类别
• 配合 react-best-practices 效果翻倍

适用人群：

• ✅ 前端开发者（所有）
• ✅ 关注可访问性
• ✅ 团队规范化

本文基于官方文档和公开资料整理，未经过 MagicNetWorld 实测。

参考资料

• vercel-labs/agent-skills GitHub — 官方仓库（21.8K+ stars）
• vercel-labs/web-interface-guidelines — 规则源文件（650+ stars）
• web-design-guidelines SKILL.md — 官方 Skill 定义
• Vercel Web Interface Guidelines 详解 — 技术博客
• lzw.me: Web Design Guidelines 教程 — 中文教程