ui-ux-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UI/UX Implementation Details

UI/UX实现细节

Note: For high-level design rules (hit targets, focus rings, contrast, etc.), defer to
vercel-design-guidelines
which fetches live standards from Vercel. This skill provides implementation-specific details.

注意： 如需了解高阶设计规则（点击目标、聚焦环、对比度等），请参考
vercel-design-guidelines
，它会从Vercel拉取最新的官方标准。本skill提供实现层面的专属细节。

Interactions

交互

Keyboard & Focus

键盘与聚焦

MUST: Full keyboard support per WAI-ARIA APG
MUST: Manage focus (trap, move, return) per APG patterns
MUST: Group focus with
```
:focus-within
```
where appropriate

必须：遵循WAI-ARIA APG规范提供完整的键盘支持
必须：按照APG模式管理焦点（捕获、移动、返回）
必须：合适场景下使用
```
:focus-within
```
对焦点进行分组

Touch & Input

触控与输入

MUST:
```
touch-action: manipulation
```
to prevent double-tap zoom
MUST: Set
```
-webkit-tap-highlight-color
```
to match design

MUST: Mobile

<input>

font-size ≥16px to prevent iOS zoom, or use:

html

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover">

必须：设置
```
touch-action: manipulation
```
防止双击缩放
必须：设置
```
-webkit-tap-highlight-color
```
匹配设计规范

必须：移动端

<input>

字体大小≥16px以避免iOS自动缩放，或使用如下配置：

html

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover">

Form Behavior

表单行为

MUST: Hydration-safe inputs (no lost focus/value)
NEVER: Block paste in
```
<input>
```
/
```
<textarea>
```
MUST: Enter submits text input; in
```
<textarea>
```
, Cmd/Ctrl+Enter submits
MUST: Keep submit enabled until request starts; use idempotency key
MUST: Allow submitting incomplete forms to surface validation
MUST: Errors inline next to fields; on submit, focus first error
MUST:
```
autocomplete
```
+ meaningful
```
name
```
; correct
```
type
```
and
```
inputmode
```
SHOULD: Disable spellcheck for emails/codes/usernames
SHOULD: Placeholders end with ellipsis and show example (e.g.,
```
sk-012345...
```
)
MUST: Warn on unsaved changes before navigation
MUST: Compatible with password managers & 2FA
MUST: Trim values to handle text expansion trailing spaces
MUST: No dead zones on checkboxes/radios; label+control share hit target

必须：输入组件支持hydration安全（不会丢失焦点/输入值）
禁止：在
```
<input>
```
/
```
<textarea>
```
中阻止粘贴操作
必须：回车提交文本输入；在
```
<textarea>
```
中，Cmd/Ctrl+回车提交
必须：在请求发起前保持提交按钮可用；使用幂等键
必须：允许提交未完成的表单以展示校验结果
必须：错误信息内嵌展示在对应字段旁；提交后聚焦第一个错误字段
必须：设置
```
autocomplete
```
属性和有意义的
```
name
```
属性；使用正确的
```
type
```
和
```
inputmode
```
建议：对邮箱/验证码/用户名输入框禁用拼写检查
建议：占位符以省略号结尾并展示示例（例如
```
sk-012345...
```
）
必须：导航前如果有未保存的更改需要提示用户
必须：兼容密码管理器和双因素认证（2FA）
必须：对输入值进行去首尾空格处理，避免文本扩展产生的尾部空格问题
必须：复选框/单选框没有点击死区；标签和控件共享点击区域

State & Navigation

状态与导航

MUST: URL reflects state (filters/tabs/pagination). Prefer nuqs
MUST: Back/Forward restores scroll
MUST: Links use
```
<a>
```
/
```
<Link>
```
(support Cmd/Ctrl/middle-click)

必须：URL反映页面状态（筛选/标签页/分页）。推荐使用nuqs
必须：前进/后退操作恢复滚动位置
必须：链接使用
```
<a>
```
/
```
<Link>
```
组件（支持Cmd/Ctrl/鼠标中键点击）

Feedback

反馈

SHOULD: Optimistic UI with reconciliation; on failure show error or Undo
MUST: Confirm destructive actions or provide Undo window
MUST: Use polite
```
aria-live
```
for toasts/inline validation
SHOULD: Ellipsis for follow-ups ("Rename...") and loading ("Saving...")

建议：使用乐观UI搭配状态校验；操作失败时展示错误信息或提供撤销入口
必须：破坏性操作需要二次确认或提供撤销窗口期
必须：对toast/内嵌校验使用polite模式的
```
aria-live
```
属性
建议：后续操作和加载状态使用省略号（例如"重命名..."、"保存中..."）

Touch/Drag

触控/拖拽

MUST: Delay first tooltip; subsequent peers no delay
MUST:
```
overscroll-behavior: contain
```
in modals/drawers
MUST: During drag, disable text selection and set
```
inert
```
on dragged element

必须：首次展示tooltip添加延迟，后续相邻元素的tooltip无需延迟
必须：在模态框/抽屉中设置
```
overscroll-behavior: contain
```
必须：拖拽过程中禁用文本选择，并为被拖拽元素设置
```
inert
```
属性

Animation

动画

SHOULD: Prefer CSS > Web Animations API > JS libraries
MUST: Animations are interruptible and input-driven (avoid autoplay)
MUST: Correct
```
transform-origin
```
(motion starts where it "physically" should)

建议：优先选择CSS > Web Animations API > JS动画库
必须：动画可中断且由输入触发（避免自动播放）
必须：设置正确的
```
transform-origin
```
（动画应该从"物理上"合理的位置开始）

Cross-Browser

跨浏览器兼容

MUST: Apply CSS transforms to SVG children (
```
<g>
```
), not parent
```
<svg>
```

MUST: Set

transform-box: fill-box

and

transform-origin: center

on SVG

SHOULD: Use
```
translateZ(0)
```
or
```
will-change: transform
```
for text anti-aliasing artifacts

必须：给SVG的子元素（
```
<g>
```
）而非父级
```
<svg>
```
应用CSS transform

必须：给SVG设置

transform-box: fill-box

和

transform-origin: center

建议：使用
```
translateZ(0)
```
或
```
will-change: transform
```
解决文本抗锯齿异常问题

Layout

布局

SHOULD: Optical alignment; adjust by +/-1px when perception beats geometry
MUST: Deliberate alignment to grid/baseline/edges
SHOULD: Balance icon/text lockups (stroke/weight/size/spacing/color)
MUST: Verify mobile, laptop, ultra-wide (simulate at 50% zoom)
MUST: Respect safe areas (
```
env(safe-area-inset-*)
```
)
MUST: Avoid unwanted scrollbars; fix overflows

建议：采用视觉对齐；当视觉感知效果优于几何对齐时可调整±1px
必须：有意识地和网格/基线/边缘对齐
建议：平衡图标/文本组合（描边/字重/尺寸/间距/颜色）
必须：验证移动端、笔记本、超宽屏的展示效果（模拟50%缩放场景）
必须：适配安全区域（
```
env(safe-area-inset-*)
```
）
必须：避免出现非预期的滚动条；修复溢出问题

Content & Accessibility

内容与无障碍

SHOULD: Inline help first; tooltips last resort
MUST: Skeletons mirror final content (avoid layout shift)
MUST:
```
<title>
```
matches current context
MUST: No dead ends; always offer next step/recovery
MUST: Design empty/sparse/dense/error states
SHOULD: Curly quotes (" "); avoid widows/orphans
MUST: Tabular numbers for comparisons (
```
font-variant-numeric: tabular-nums
```
)
MUST: Redundant status cues (not color-only); icons have text labels
MUST: Use ellipsis character
```
...
```
(not
```
...
```
)
MUST:
```
scroll-margin-top
```
on headings; include "Skip to content" link
MUST: Resilient to user-generated content (short/avg/very long)
MUST: Locale-aware dates/times/numbers/currency
MUST: Use non-breaking spaces:
```
10&nbsp;MB
```
,
```
Cmd&nbsp;+&nbsp;K
```
MUST: Detect language via
```
Accept-Language
```
header, NOT IP geolocation

建议：优先使用内嵌帮助提示， tooltip作为最后备选方案
必须：骨架屏和最终内容结构一致（避免布局偏移）
必须：
```
<title>
```
和当前页面上下文匹配
必须：没有访问死路；始终提供下一步操作或错误恢复路径
必须：设计空状态/稀疏状态/密集状态/错误状态
建议：使用弯引号（" "）；避免孤行/寡行
必须：对比场景下使用表格数字（
```
font-variant-numeric: tabular-nums
```
）
必须：提供冗余的状态提示（不能仅用颜色区分）；图标要有文本标签
必须：使用省略号字符
```
…
```
而非三个点
```
...
```
必须：给标题设置
```
scroll-margin-top
```
；提供"跳转到内容"链接
必须：兼容各种长度的用户生成内容（短/中等/超长）
必须：日期/时间/数字/货币支持本地化适配
必须：使用非换行空格：
```
10&nbsp;MB
```
、
```
Cmd&nbsp;+&nbsp;K
```
必须：通过
```
Accept-Language
```
请求头检测用户语言，而非IP地理位置

Performance

性能

SHOULD: Test iOS Low Power Mode and macOS Safari
MUST: Measure reliably (disable extensions that skew runtime)
MUST: Track and minimize re-renders (React DevTools/React Scan)
MUST: Profile with CPU/network throttling
MUST: Batch layout reads/writes; avoid reflows/repaints
MUST: Mutations complete in <500ms
SHOULD: Prefer uncontrolled inputs; make controlled loops cheap
MUST: Virtualize large lists (virtua) or
```
content-visibility: auto
```
MUST: Preload only above-the-fold images; lazy-load rest
MUST: Prevent CLS from images (explicit dimensions)
SHOULD:
```
<link rel="preconnect">
```
for asset/CDN domains
SHOULD: Preload critical fonts; subset via
```
unicode-range
```
SHOULD: Move expensive work to Web Workers

建议：测试iOS低功耗模式和macOS Safari下的表现
必须：进行可靠的性能测量（禁用会影响运行时间的浏览器扩展）
必须：监控并最小化重渲染（使用React DevTools/React Scan）
必须：在CPU/网络节流条件下进行性能分析
必须：批量处理布局读/写操作；避免重排/重绘
必须：DOM变更操作在<500ms内完成
建议：优先使用非受控组件；降低受控组件循环的性能开销
必须：对长列表进行虚拟化（virtua）或使用
```
content-visibility: auto
```
必须：仅预加载首屏图片；其余图片懒加载
必须：给图片设置明确尺寸避免CLS（累积布局偏移）
建议：给静态资源/CDN域名添加
```
<link rel="preconnect">
```
建议：预加载关键字体；通过
```
unicode-range
```
进行字体子集化
建议：将计算密集型任务转移到Web Workers执行

Design

设计

SHOULD: Layered shadows (ambient + direct)
SHOULD: Crisp edges via semi-transparent borders + shadows
SHOULD: Nested radii: child <= parent; concentric
SHOULD: Hue consistency: tint borders/shadows/text toward bg hue
MUST: Accessible charts (color-blind-friendly palettes)
MUST: Increase contrast on
```
:hover
```
/
```
:active
```
/
```
:focus
```
SHOULD: Set
```
<meta name="theme-color">
```
to match page background
MUST: Set
```
color-scheme: dark
```
on
```
<html>
```
in dark themes
MUST: On Windows, set explicit
```
background-color
```
and
```
color
```
on
```
<select>
```
SHOULD: Avoid gradient banding (use masks when needed)

建议：使用分层阴影（环境光+直射光）
建议：通过半透明边框+阴影实现锐利边缘
建议：嵌套圆角规则：子元素圆角≤父元素圆角；保持同心
建议：色调一致性：边框/阴影/文本的色调向背景色靠拢
必须：图表支持无障碍访问（使用色盲友好的配色方案）
必须：在
```
:hover
```
/
```
:active
```
/
```
:focus
```
状态下提高对比度
建议：设置
```
<meta name="theme-color">
```
匹配页面背景色
必须：深色主题下给
```
<html>
```
标签设置
```
color-scheme: dark
```
必须：在Windows系统下给
```
<select>
```
设置明确的
```
background-color
```
和
```
color
```
建议：避免渐变色带（必要时使用遮罩）

Common Violations

常见违规示例

Blocking paste

阻止粘贴操作

tsx

// Bad
<input onPaste={(e) => e.preventDefault()} />

// Good
<input type="email" autoComplete="email" />

tsx

// Bad
<input onPaste={(e) => e.preventDefault()} />

// Good
<input type="email" autoComplete="email" />

Non-semantic button

非语义化按钮

tsx

// Bad
<div onClick={handleClick}>Click me</div>

// Good
<button onClick={handleClick}>Click me</button>

tsx

// Bad
<div onClick={handleClick}>Click me</div>

// Good
<button onClick={handleClick}>Click me</button>

Windows select dark mode

Windows下select组件深色模式适配

tsx

// Bad
<select><option>Option 1</option></select>

// Good
<select className="bg-white dark:bg-gray-900 text-black dark:text-white">
  <option>Option 1</option>
</select>

tsx

// Bad
<select><option>Option 1</option></select>

// Good
<select className="bg-white dark:bg-gray-900 text-black dark:text-white">
  <option>Option 1</option>
</select>