dwsy/vercel-design

Vercel 设计指南技能

Vercel 设计原则和最佳实践的全面参考。在构建 Web 应用程序时使用此技能以确保：

• UI 卓越 - 清晰、直观且易于访问的用户界面
• 性能 - 快速、响应式的用户体验
• 国际化 - 支持区域设置和语言友好
• 无障碍 - 符合 WCAG 标准且支持屏幕阅读器
• 一致的设计 - 连贯的视觉语言和交互

快速参考

导航

• UI 指南
• 国际化
• 表单
• 性能
• 视觉设计
• 文案写作

---

UI 指南

锚点和导航

为标题设置 scroll-margin-top 以便链接到章节：

h2, h3, h4 {
  scroll-margin-top: 1rem;
}

用户生成内容

对用户生成内容具有弹性。 布局应能处理短、平均和非常长的内容。

无障碍

无障碍内容：

• 设置准确的名称（aria-label）
• 隐藏装饰（aria-hidden）
• 在无障碍树中验证

仅图标按钮需要命名：

<button aria-label="关闭模态框">×</button>

语义优于 ARIA： 优先使用原生元素（button、a、label、table），然后再使用 aria-*。

标题和跳转链接： 使用层级化的 <h1–h6> 和"跳转到内容"链接。

粘合术语使用不换行空格： 使用   保持单位、快捷键和名称在一起：

• 10 MB → 10 MB
• ⌘ + K → ⌘ + K
• Vercel SDK → Vercel SDK
• 不需要空格时使用 ⁠

品牌资源

从 Logo 获取品牌资源： 右键单击导航 Logo 可快速访问品牌资源。

---

国际化

语言和区域设置

区域感知格式： 根据用户的区域设置格式化日期、时间、数字、分隔符和货币。

优先选择语言设置而非位置： 通过 Accept-Language 头和 navigator.languages 检测语言。永远不要依赖 IP/GPS 来确定语言。

日期/时间格式化

使用区域感知的格式化器：

// JavaScript
const date = new Date(2024, 0, 15);
date.toLocaleDateString('zh-CN', { 
  year: 'numeric',
  month: 'long',
  day: 'numeric' 
});
// → "2024年1月15日"

date.toLocaleTimeString('zh-CN', { 
  hour: 'numeric', 
  minute: '2-digit' 
});
// → "上午9:00"

数字和货币

一致的货币格式： 在任何给定上下文中，货币显示应为 0 或 2 位小数，不要混用。

// 一致的 0 位小数
¥50

// 一致的 2 位小数
¥50.00

// 不要在同一上下文中混用：¥50 和 ¥50.00

数字和单位之间用空格分隔：

• 10 MB（而不是 10MB）
• 使用不换行空格：10 MB

---

表单

键盘交互

回车提交： 当文本输入框被聚焦时，如果是唯一控件，回车键提交。如果有多个控件，对最后一个控件应用此规则。

文本区域行为： 在 <textarea> 中，⌘/⌃+Enter 提交；Enter 插入新行。

标签

所有地方都要有标签： 每个控件都有 <label> 或与标签关联，以支持辅助技术。

// 显式标签
<label>
  电子邮箱
  <input type="email" name="email" />
</label>

// 隐式关联
<label for="email">电子邮箱</label>
<input id="email" type="email" name="email" />

标签激活： 单击 <label> 会聚焦关联的控件。

提交

提交规则： 在提交开始前保持提交按钮启用；然后在请求进行中时禁用，显示加载指示器，并包含幂等键。

不要预先禁用提交： 允许提交不完整的表单以显示验证反馈。

未保存的更改： 当可能丢失数据时，在导航前警告用户。

验证

不要阻止输入： 即使字段只接受数字，也允许任何输入并显示验证反馈。完全阻止按键会令人困惑，因为用户无法获得解释。

错误放置： 在字段旁边显示错误；提交时，聚焦第一个错误。

输入最佳实践

自动完成和名称： 设置 autocomplete 和有意义的 name 值以启用自动填充。

<input type="email" name="email" autocomplete="email" />
<input type="tel" name="phone" autocomplete="tel" />
<input type="text" name="username" autocomplete="username" />

选择性拼写检查： 对电子邮件、代码、用户名等禁用。

<input type="email" name="email" spellcheck="false" />

正确的类型和输入模式： 使用正确的 type 和 inputmode 以获得更好的键盘和验证。

<input type="email" inputmode="email" />
<input type="tel" inputmode="tel" />
<input type="number" inputmode="numeric" />

占位符表示为空： 以省略号结尾。

<input placeholder="请输入您的电子邮箱..." />

占位符值： 将占位符设置为例值或模式：

• +1 (123) 456-7890
• sk-012345679…

控件和点击区域

控件上没有死区： 复选框和单选按钮避免死区；标签和控件共享一个宽大的点击目标。

Windows <select> 背景： 在原生 <select> 上显式设置 background-color 和 color 以避免 Windows 上的暗模式对比度错误。

认证字段

密码管理器和 2FA： 确保兼容性并允许粘贴一次性验证码。

不要为非认证字段触发密码管理器： 对于"搜索"等输入，避免保留名称（例如密码），使用 autocomplete="off" 或特定标记如 autocomplete="one-time-code" 用于 OTP 字段。

文本替换和扩展： 某些输入方法会添加尾随空格。输入应修剪值以避免显示令人困惑的错误消息。

---

性能

测试和测量

设备/浏览器矩阵： 测试 iOS 低功耗模式和 macOS Safari。

可靠测量： 禁用增加开销或改变运行时行为的扩展。

跟踪重渲染： 最小化并加快重渲染。使用 React DevTools 或 React Scan。

分析时限制： 使用 CPU 和网络限制进行测试。

布局和渲染

最小化布局工作： 批量读取/写入；避免不必要的重排/重绘。

网络延迟预算： POST/PATCH/DELETE 在 <500ms 内完成。

按键成本： 优先使用非受控输入；使受控循环成本低廉。

列表和大型内容

大型列表： 虚拟化大型列表（例如 virtua 或 content-visibility: auto）。

图像和媒体

智能预加载： 仅预加载首屏图像；延迟加载其余部分。

无图像导致的 CLS： 设置明确的图像尺寸并保留空间。

<img 
  src="hero.jpg" 
  alt="Hero 图像"
  width="800" 
  height="400"
  loading="lazy"
/>

预连接到源： 使用 <link rel="preconnect"> 连接资源/CDN 域名（需要时使用 crossorigin）以减少 DNS/TLS 延迟。

<link rel="preconnect" href="https://cdn.example.com" />
<link rel="preconnect" href="https://cdn.example.com" crossorigin />

字体

预加载字体： 对于关键文本以避免闪烁和布局偏移。

<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin />

子集字体： 通过 unicode-range 仅发送您使用的码点/脚本（将可变轴限制在您需要的范围内）以缩小大小。

@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-var.woff2') format('woff2');
  unicode-range: U+0000-00FF;
}

工作线程

不要将主线程用于昂贵的工作： 将特别长的任务移至 Web Workers 以避免阻塞页面的交互。

// main.js
const worker = new Worker('expensive-task.js');

worker.postMessage({ data: largeDataset });

worker.onmessage = (event) => {
  console.log('结果:', event.data);
};

---

视觉设计

阴影

分层阴影： 使用至少两层模拟环境光和直射光。

box-shadow: 
  0 1px 1px rgba(0, 0, 0, 0.05),
  0 4px 6px rgba(0, 0, 0, 0.1);

边框

清晰的边框： 结合边框和阴影；半透明边框提高边缘清晰度。

border: 1px solid rgba(0, 0, 0, 0.1);

边框圆角

嵌套圆角： 子元素圆角 ≤ 父元素圆角且同心，使曲线对齐。

.card {
  border-radius: 12px;
}

.card .button {
  border-radius: 8px; /* ≤ 12px */
}

颜色

色调一致性： 在非中性背景上，边框/阴影/文本向相同色调着色。

.surface-blue {
  border-color: rgba(59, 130, 246, 0.2);
  box-shadow: 0 2px 8px rgba(59, 130, 246, 0.15);
}

无障碍图表： 使用色盲友好的调色板。

最小对比度： 优先使用 APCA 而非 WCAG 2 以获得更准确的感知对比度。

交互增加对比度： :hover、:active、:focus 比静止状态具有更多对比度。

button {
  background: #2563eb;
}

button:hover {
  background: #1d4ed8; /* 更深以增加对比度 */
}

button:focus {
  outline: 2px solid #000;
  outline-offset: 2px;
}

浏览器集成

浏览器 UI 匹配您的背景： 设置 <meta name="theme-color" content="#000000"> 以将浏览器的主题颜色与页面背景对齐。

<meta name="theme-color" content="#000000" media="(prefers-color-scheme: dark)" />

设置适当的 color-scheme： 在暗主题中为 <html> 标签设置 color-scheme: dark，以便滚动条和其他设备 UI 具有适当的对比度。

:root {
  color-scheme: light dark;
}

排版

文本抗锯齿和变换： 缩放文本可能会改变平滑度。优先动画化包装器而不是文本节点。如果持续存在伪影，设置 translateZ(0) 或 will-change: transform 将其提升到自己的图层。

.scale-wrapper {
  transform: scale(1.1);
  will-change: transform;
}

渐变

避免渐变条纹： 某些颜色和显示类型会有颜色条纹。可以使用遮罩代替。

---

文案写作

语气和语调

主动语态：

• ❌ "CLI 将被安装"
• ✅ "安装 CLI"

标题和按钮使用标题大小写（芝加哥）。在营销页面上，使用句子大小写。

清晰简洁： 使用尽可能少的词语。

优先使用 & 而非 and。

以行动为导向的语言：

• ❌ "您将需要 CLI…"
• ✅ "安装 CLI…"

保持名词一致： 引入尽可能少的独特术语。

使用第二人称： 避免第一人称。

占位符和示例

使用一致的占位符：

• 字符串：YOUR_API_TOKEN_HERE
• 数字：0123456789

数字和度量

使用数字表示计数：

• ❌ "八个部署"
• ✅ "8 个部署"

数字和单位之间用空格分隔：

• ❌ 10MB
• ✅ 10 MB
• 使用不换行空格：10 MB

错误消息

默认使用积极语言： 以鼓励性和解决问题的方式表达消息，即使是错误消息。

• ❌ "您的部署失败"
• ✅ "出现了问题—请重试或联系支持。"

错误消息引导退出： 不要只说明出了什么问题—告诉用户如何修复它。

• ❌ "无效的 API 密钥"
• ✅ "您的 API 密钥不正确或已过期。在您的账户设置中生成新密钥。"

文案和按钮/链接应该教育并提供明确的操作。

清晰度

避免歧义： 标签清晰且具体。

• ❌ 按钮标签"继续"
• ✅ "保存 API 密钥"

---

资源

• Vercel 设计指南
• Chrome 无障碍树
• APCA 对比度
• React DevTools
• React Scan
• Virtua 虚拟化
• Web Workers API
• 标题大小写转换器

---

使用示例

构建表单

1. 使用正确的输入类型和自动完成属性
2. 为所有控件添加标签
3. 处理键盘交互（回车提交）
4. 不要阻止输入；显示验证反馈
5. 在字段旁边显示错误
6. 在提交期间禁用提交，显示加载指示器

优化性能

1. 设置明确的图像尺寸
2. 预加载首屏内容
3. 延迟加载下方的图像
4. 预连接到 CDN 源
5. 对昂贵操作使用 Web Workers
6. 虚拟化大型列表

改善无障碍

1. 使用语义化 HTML 元素
2. 为仅图标按钮添加 ARIA 标签
3. 设置适当的标题层次结构
4. 添加跳转到内容链接
5. 确保足够的颜色对比度
6. 使用屏幕阅读器测试

国际化

1. 通过 Accept-Language 头检测语言
2. 为用户的区域设置格式化日期/数字/货币
3. 对粘合术语使用不换行空格
4. 不要依赖 IP/GPS 进行语言检测