web-interface-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web Interface Guidelines

Web界面设计指南

Concise rules for building accessible, fast, delightful UIs. Use MUST/SHOULD/NEVER to guide decisions and reviews.

构建可访问、快速、愉悦UI的简洁规则。使用MUST/SHOULD/NEVER来指导决策和评审。

How to apply

如何应用

Prioritize MUST items first; NEVER items are hard constraints.
When reviewing, scan each section and confirm every MUST is satisfied or consciously justified.
If a guideline conflicts with product requirements, surface the conflict explicitly.

优先处理MUST项；NEVER项是硬性约束。
评审时，浏览每个章节并确认所有MUST项都已满足或有明确的合理说明。
如果指南与产品需求冲突，需明确指出该冲突。

Quick reference

快速参考

Area	Top MUST checks
Keyboard	Full keyboard support per WAI-ARIA APG; visible focus rings; manage focus (trap/move/return)
Forms	No paste blocking; loading buttons keep label + spinner; inline errors + focus first error
Navigation	URL reflects state; links are links; back/forward restores scroll
Motion	Respect prefers-reduced-motion; animate transform/opacity only; animations interruptible
Layout	Respect safe areas; avoid unwanted scrollbars; verify mobile/laptop/ultra-wide
Content	Accurate labels; skip link + proper headings; resilient to long user content
Performance	Measure reliably; batch layout reads/writes; prevent CLS from images

领域	核心MUST检查项
键盘	遵循WAI-ARIA APG的完整键盘支持；可见的焦点环；管理焦点（捕获/移动/返回）
表单	禁止阻止粘贴；加载状态的按钮保留标签+加载动画；内联错误提示+自动聚焦首个错误项
导航	URL反映页面状态；链接使用正确的链接元素；前进/后退恢复滚动位置
动效	尊重prefers-reduced-motion设置；仅对transform/opacity属性做动画；动画可中断
布局	尊重安全区域；避免不必要的滚动条；适配移动端/笔记本/超宽屏
内容	准确的标签；跳过链接+规范的标题层级；兼容长用户内容
性能	可靠的性能测量；批量处理布局读取/写入；避免图片导致的CLS

Interactions

交互规范

Keyboard
- MUST: Full keyboard support per WAI-ARIA APG patterns
- MUST: Visible focus rings (
```
:focus-visible
```
  ; group with
```
:focus-within
```
  )
- MUST: Manage focus (trap, move, and return) per APG patterns
Targets & input
- MUST: Hit target >= 24px (mobile >= 44px). If visual < 24px, expand hit area.
- MUST: Mobile
```
<input>
```
  font-size >= 16px or set:
  html
```
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover">
```
- NEVER: Disable browser zoom
- MUST:
```
touch-action: manipulation
```
  to prevent double-tap zoom; set
```
-webkit-tap-highlight-color
```
  to match design
Inputs & forms (behavior)
- MUST: Hydration-safe inputs (no lost focus/value)
- NEVER: Block paste in
```
<input>/<textarea>
```
- MUST: Loading buttons show spinner and keep original label
- MUST: Enter submits focused text input. In
```
<textarea>
```
  , Cmd/Ctrl+Enter submits; Enter adds newline.
- MUST: Keep submit enabled until request starts; then disable, show spinner, use idempotency key
- MUST: Don’t block typing; accept free text and validate after
- 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 pattern (e.g.,
```
+1 (123) 456-7890
```
  ,
```
sk-012345…
```
  )
- MUST: Warn on unsaved changes before navigation
- MUST: Compatible with password managers and 2FA; allow pasting one-time codes
- MUST: Trim values to handle text expansion trailing spaces
- MUST: No dead zones on checkboxes/radios; label+control share one generous hit target
State & navigation
- MUST: URL reflects state (deep-link filters/tabs/pagination/expanded panels). Prefer libs like nuqs.
- MUST: Back/Forward restores scroll
- MUST: Links are links: use
```
<a>
```
  /
```
<Link>
```
  for navigation (support Cmd/Ctrl/middle-click)
Feedback
- SHOULD: Optimistic UI; reconcile on response; on failure show error and rollback or offer Undo
- MUST: Confirm destructive actions or provide Undo window
- MUST: Use polite
```
aria-live
```
  for toasts/inline validation
- SHOULD: Ellipsis (
```
…
```
  ) for options that open follow-ups (e.g., "Rename…") and loading states (e.g., "Loading…")
Touch/drag/scroll
- MUST: Design forgiving interactions (generous targets, clear affordances; avoid finickiness)
- MUST: Delay first tooltip in a group; subsequent peers no delay
- MUST: Intentional
```
overscroll-behavior: contain
```
  in modals/drawers
- MUST: During drag, disable text selection and set
```
inert
```
  on dragged element/containers
- MUST: No “dead-looking” interactive zones—if it looks clickable, it is
Autofocus
- SHOULD: Autofocus on desktop when there’s a single primary input; rarely on mobile (avoid layout shift)

键盘
- MUST：遵循WAI-ARIA APG模式的完整键盘支持
- MUST：可见的焦点环（
```
:focus-visible
```
  ；结合
```
:focus-within
```
  使用）
- MUST：按照APG模式管理焦点（捕获、移动和返回）
目标与输入
- MUST：点击目标区域≥24px（移动端≥44px）。如果视觉尺寸小于24px，扩大点击区域。
- MUST：移动端
```
<input>
```
  字体大小≥16px，或设置：
  html
```
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover">
```
- NEVER：禁用浏览器缩放
- MUST：设置
```
touch-action: manipulation
```
  以防止双击缩放；设置
```
-webkit-tap-highlight-color
```
  匹配设计风格
输入与表单（行为）
- MUST：支持Hydration的输入组件（不会丢失焦点/值）
- NEVER：阻止
```
<input>/<textarea>
```
  的粘贴操作
- MUST：加载状态的按钮显示加载动画并保留原始标签
- MUST：按下Enter提交聚焦的文本输入框。在
```
<textarea>
```
  中，Cmd/Ctrl+Enter提交；Enter添加换行。
- MUST：提交按钮在请求发起前保持可用；发起后禁用，显示加载动画，使用幂等键
- MUST：不阻止输入；允许自由输入后再验证
- MUST：允许提交不完整的表单以显示验证错误
- MUST：错误提示显示在对应字段旁；提交时自动聚焦首个错误项
- MUST：设置
```
autocomplete
```
  +有意义的
```
name
```
  ；正确的
```
type
```
  和
```
inputmode
```
- SHOULD：对邮箱/验证码/用户名禁用拼写检查
- SHOULD：占位符以省略号结尾并显示示例格式（如：
```
+1 (123) 456-7890
```
  ,
```
sk-012345…
```
  ）
- MUST：在导航前提示未保存的更改
- MUST：兼容密码管理器和2FA；允许粘贴一次性验证码
- MUST：自动修剪输入值的首尾空格
- MUST：复选框/单选框无无效点击区域；标签和控件共享一个较大的点击目标
状态与导航
- MUST：URL反映页面状态（支持深度链接到筛选器/标签页/分页/展开面板）。优先使用nuqs等库。
- MUST：前进/后退操作恢复滚动位置
- MUST：链接就是链接：使用
```
<a>
```
  /
```
<Link>
```
  进行导航（支持Cmd/Ctrl/中键点击）
反馈
- SHOULD：乐观UI；根据响应结果调整状态；失败时显示错误并回滚或提供撤销选项
- MUST：对破坏性操作进行确认或提供撤销窗口
- MUST：使用polite级别的
```
aria-live
```
  处理提示框/内联验证
- SHOULD：对于会打开后续操作的选项使用省略号（
```
…
```
  ）（如：“重命名…”）和加载状态（如：“加载中…”）
触摸/拖拽/滚动
- MUST：设计容错性交互（较大的点击目标、清晰的交互提示；避免过于精细的操作）
- MUST：一组工具提示中的第一个延迟显示；后续的工具提示无延迟
- MUST：在模态框/抽屉中设置
```
overscroll-behavior: contain
```
- MUST：拖拽过程中禁用文本选择，并为拖拽元素/容器设置
```
inert
```
- MUST：没有“看起来不可交互”的可交互区域——如果看起来可点击，就必须可点击
自动聚焦
- SHOULD：桌面端当只有一个主要输入框时自动聚焦；移动端尽量少用（避免布局偏移）

Animation

动画规范

MUST: Honor
```
prefers-reduced-motion
```
(provide reduced variant)
SHOULD: Prefer CSS > Web Animations API > JS libraries
MUST: Animate compositor-friendly props (
```
transform
```
,
```
opacity
```
); avoid layout/repaint props (
```
top/left/width/height
```
)
SHOULD: Animate only to clarify cause/effect or add deliberate delight
SHOULD: Choose easing to match the change (size/distance/trigger)
MUST: Animations are interruptible and input-driven (avoid autoplay)
MUST: Correct
```
transform-origin
```
(motion starts where it "physically" should)

MUST：遵循
```
prefers-reduced-motion
```
设置（提供简化版本）
SHOULD：优先使用CSS > Web Animations API > JS库
MUST：仅对合成器友好的属性（
```
transform
```
,
```
opacity
```
）做动画；避免使用会触发布局/重绘的属性（
```
top/left/width/height
```
）
SHOULD：仅为了明确因果关系或增加愉悦感而添加动画
SHOULD：根据变化的类型（尺寸/距离/触发方式）选择合适的缓动函数
MUST：动画可中断且由输入驱动（避免自动播放）
MUST：正确设置
```
transform-origin
```
（动画起始位置符合物理直觉）

Layout

布局规范

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

SHOULD：视觉对齐；当视觉效果优于几何对齐时，可调整±1px
MUST：有意识地对齐到网格/基线/边缘/视觉中心（避免随意放置）
SHOULD：平衡图标/文本组合（描边/粗细/尺寸/间距/颜色）
MUST：验证移动端、笔记本、超宽屏（以50%缩放模拟超宽屏）
MUST：尊重安全区域（使用
```
env(safe-area-inset-*)
```
）
MUST：避免不必要的滚动条；修复溢出问题

Content & accessibility

内容与可访问性

SHOULD: Inline help first; tooltips last resort
MUST: Skeletons mirror final content to 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
```
or a mono like Geist Mono)
MUST: Redundant status cues (not color-only); icons have text labels
MUST: Don’t ship the schema—visuals may omit labels but accessible names still exist
MUST: Use the ellipsis character
```
…
```
MUST:
```
scroll-margin-top
```
on headings for anchored links; include a “Skip to content” link; hierarchical
```
<h1–h6>
```
MUST: Resilient to user-generated content (short/avg/very long)
MUST: Locale-aware dates/times/numbers/currency
MUST: Accurate names (
```
aria-label
```
), decorative elements
```
aria-hidden
```
, verify in the Accessibility Tree
MUST: Icon-only buttons have descriptive
```
aria-label
```
MUST: Prefer native semantics (
```
button
```
,
```
a
```
,
```
label
```
,
```
table
```
) before ARIA
SHOULD: Right-clicking the nav logo surfaces brand assets
MUST: Use non-breaking spaces to glue terms:
```
10&nbsp;MB
```
,
```
⌘&nbsp;+&nbsp;K
```
,
```
Vercel&nbsp;SDK
```

SHOULD：优先使用内联帮助；工具提示作为最后手段
MUST：骨架屏与最终内容结构一致，避免布局偏移
MUST：
```
<title>
```
与当前上下文匹配
MUST：没有死胡同；始终提供下一步操作/恢复方式
MUST：设计空状态/稀疏状态/密集状态/错误状态
SHOULD：使用弯引号（“ ”）；避免孤行/寡行
MUST：使用等宽数字进行比较（
```
font-variant-numeric: tabular-nums
```
或使用Geist Mono等等宽字体）
MUST：提供冗余的状态提示（不能仅依赖颜色）；图标配有文本标签
MUST：不要直接展示架构——视觉上可省略标签，但必须存在可访问的名称
MUST：使用省略号字符
```
…
```
MUST：为锚点链接的标题设置
```
scroll-margin-top
```
；添加“跳转到内容”链接；使用层级化的
```
<h1–h6>
```
MUST：兼容用户生成的内容（短/平均/极长文本）
MUST：支持本地化的日期/时间/数字/货币格式
MUST：准确的名称（
```
aria-label
```
），装饰元素设置
```
aria-hidden
```
，在可访问性树中验证
MUST：纯图标按钮配有描述性的
```
aria-label
```
MUST：优先使用原生语义标签（
```
button
```
,
```
a
```
,
```
label
```
,
```
table
```
），再考虑ARIA
SHOULD：右键点击导航栏Logo可显示品牌资源

MUST：使用非断空格连接术语：

10&nbsp;MB

⌘&nbsp;+&nbsp;K

Vercel&nbsp;SDK

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 unnecessary reflows/repaints
MUST: Mutations (
```
POST/PATCH/DELETE
```
) target < 500 ms
SHOULD: Prefer uncontrolled inputs; make controlled loops cheap (keystroke cost)
MUST: Virtualize large lists (e.g., virtua)
MUST: Preload only above-the-fold images; lazy-load the rest
MUST: Prevent CLS from images (explicit dimensions or reserved space)

SHOULD：测试iOS低电量模式和macOS Safari
MUST：可靠地测量性能（禁用影响运行时的扩展）
MUST：跟踪并最小化重渲染（使用React DevTools/React Scan）
MUST：在CPU/网络节流下进行性能分析
MUST：批量处理布局读取/写入；避免不必要的回流/重绘
MUST：突变操作（
```
POST/PATCH/DELETE
```
）耗时<500ms
SHOULD：优先使用非受控输入；使受控输入的循环成本低廉（按键操作开销小）
MUST：对大型列表进行虚拟化（如使用virtua）
MUST：仅预加载首屏图片；其余图片懒加载
MUST：防止图片导致的CLS（设置明确尺寸或预留空间）

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: Meet contrast (prefer APCA over WCAG 2)
MUST: Increase contrast on
```
:hover
```
/
```
:active
```
/
```
:focus
```
SHOULD: Match browser UI to bg
SHOULD: Avoid gradient banding (use masks when needed)

SHOULD：分层阴影（环境阴影+直接阴影）
SHOULD：通过半透明边框+阴影实现清晰的边缘
SHOULD：嵌套圆角：子元素圆角≤父元素；同心圆角
SHOULD：色调一致性：边框/阴影/文本的色调向背景色调靠拢
MUST：可访问的图表（色盲友好的配色方案）
MUST：满足对比度要求（优先使用APCA而非WCAG 2）
MUST：在
```
:hover
```
/
```
:active
```
/
```
:focus
```
状态下提高对比度
SHOULD：浏览器UI与背景匹配
SHOULD：避免渐变条带（必要时使用遮罩）

Example: loading submit button with inline error focus

示例：带内联错误聚焦的加载状态提交按钮

tsx

type Props = {
  pending: boolean;
  errorId?: string;
};

export function SubmitButton({ pending, errorId }: Props) {
  return (
    <button
      type="submit"
      aria-describedby={errorId}
      aria-busy={pending}
      disabled={pending}
    >
      {pending ? (
        <span aria-live="polite">
          <span className="spinner" aria-hidden="true" />
          Saving…
        </span>
      ) : (
        "Save"
      )}
    </button>
  );
}

tsx

type Props = {
  pending: boolean;
  errorId?: string;
};

export function SubmitButton({ pending, errorId }: Props) {
  return (
    <button
      type="submit"
      aria-describedby={errorId}
      aria-busy={pending}
      disabled={pending}
    >
      {pending ? (
        <span aria-live="polite">
          <span className="spinner" aria-hidden="true" />
          Saving…
        </span>
      ) : (
        "Save"
      )}
    </button>
  );
}

Common mistakes

常见错误

Missing focus management in dialogs/drawers (no trap/return)
Blocking paste in inputs or disabling zoom on mobile
Loading states that replace labels instead of adding a spinner
Links implemented as buttons (breaks Cmd/Ctrl/middle-click)
Animating layout properties instead of
```
transform
```
/
```
opacity
```
Shipping icons without accessible labels or text alternatives

对话框/抽屉中缺少焦点管理（未捕获/返回焦点）
阻止输入框粘贴或禁用移动端缩放
加载状态替换了标签而非添加加载动画
用按钮实现链接功能（破坏Cmd/Ctrl/中键点击）
对布局属性做动画而非
```
transform
```
/
```
opacity
```
发布未添加可访问标签或文本替代的图标

Red flags

危险信号

Keyboard users cannot reach or activate every interactive element
Forms fail when autofill or password managers are used
Scroll position is lost on back/forward
CLS occurs when images load
Motion plays for users who prefer reduced motion

键盘用户无法到达或激活所有可交互元素
表单在自动填充或使用密码管理器时失效
前进/后退操作丢失滚动位置
图片加载时发生CLS
为偏好减少动效的用户播放动画