userinterface-wiki

用户界面 Wiki

全面的 Web 界面 UI/UX 最佳实践指南。包含 12 个类别的 152 条规则，并按影响程度排序，用于指导自动化代码审查和生成。

何时应用

在以下情况下参考这些指南：

• 实现或审查动画（CSS transitions、Motion/Framer Motion）
• 在弹簧、缓动曲线或无动画之间进行选择
• 使用 AnimatePresence 和退出动画
• 使用伪元素或 View Transitions API 编写 CSS
• 为 UI 添加音频反馈或程序化音效
• 构建图标变形组件
• 使用动态内容为容器宽度／高度添加动画
• 设计遵循认知心理学规律（菲茨定律、希克定律、米勒定律）的 UI
• 实现预测性预取，以提升感知性能
• 设置排版、OpenType 功能或数字格式

按优先级划分的规则类别

优先级	类别	影响	前缀
1	动画原则	严重	timing-、physics-、staging-
2	缓动函数	高	spring-、easing-、duration-、none-
3	退出动画	高	exit-、presence-、mode-、nested-
4	CSS 伪元素	中	pseudo-、transition-、native-
5	音频反馈	中	a11y-、appropriate-、impl-、weight-
6	音效合成	中	context-、envelope-、design-、param-
7	图标变形	低	morphing-
8	容器动画	中	container-
9	UX 定律	高	ux-
10	预测性预取	中	prefetch-
11	排版	中	type-
12	视觉设计	高	visual-

快速参考

1. 动画原则（严重）

• timing-under-300ms - 用户动画必须在 300ms 内完成
• timing-consistent - 相似元素使用相同的时长值
• timing-no-entrance-context-menu - 上下文菜单：不使用入场动画，只使用退出动画
• easing-natural-decay - 使用指数渐变实现自然衰减，不要使用线性渐变
• easing-no-linear-motion - 线性缓动仅用于进度指示器
• physics-active-state - 交互元素需要 :active 缩放变换
• physics-subtle-deformation - 挤压／拉伸幅度保持在 0.95-1.05 范围内
• physics-spring-for-overshoot - 回弹后稳定使用弹簧，不要使用缓动
• physics-no-excessive-stagger - 每个项目的错开延迟低于 50ms
• staging-one-focal-point - 一次只突出播放一个动画
• staging-dim-background - 调暗模态框／对话框的背景
• staging-z-index-hierarchy - 动画元素应遵循 z-index 层级

2. 缓动函数（高）

• spring-for-gestures - 手势驱动的动作（拖动、轻扫）必须使用弹簧
• spring-for-interruptible - 可中断的动作必须使用弹簧
• spring-preserves-velocity - 弹簧会在释放时保留输入能量
• spring-params-balanced - 避免弹簧参数产生过度振荡
• easing-for-state-change - 系统状态变化使用缓动曲线
• easing-entrance-ease-out - 入场使用 ease-out
• easing-exit-ease-in - 退出使用 ease-in
• easing-transition-ease-in-out - 视图转换使用 ease-in-out
• easing-linear-only-progress - 线性仅用于表示进度／时间
• duration-press-hover - 按下／悬停：120-180ms
• duration-small-state - 小幅状态变化：180-260ms
• duration-max-300ms - 用户发起的操作最长为 300ms
• duration-shorten-before-curve - 感觉迟缓时，先缩短时长，而不是调整曲线
• none-high-frequency - 高频交互不使用动画
• none-keyboard-navigation - 键盘导航应立即完成，不使用动画
• none-context-menu-entrance - 上下文菜单：不使用入场动画，只使用退出动画

3. 退出动画（高）

• exit-requires-wrapper - 条件动画元素需要 AnimatePresence 包装器
• exit-prop-required - AnimatePresence 中的元素需要 exit 属性
• exit-key-required - 动态列表需要唯一键，不能使用索引
• exit-matches-initial - 退出动画应与初始动画相呼应，以保持对称
• presence-hook-in-child - 在子元素中使用 useIsPresent，而不是在父元素中
• presence-safe-to-remove - 异步清理后调用 safeToRemove
• presence-disable-interactions - 禁用正在退出的元素上的交互
• mode-wait-doubles-duration - Mode "wait" 会使时长翻倍；将动画时长减半
• mode-sync-layout-conflict - Mode "sync" 会导致布局冲突
• mode-pop-layout-for-lists - 对列表重排使用 popLayout
• nested-propagate-required - 嵌套的 AnimatePresence 需要 propagate 属性
• nested-consistent-timing - 协调父子元素的退出时长

4. CSS 伪元素（中）

• pseudo-content-required - ::before/::after 需要 content 属性
• pseudo-over-dom-node - 装饰效果优先使用伪元素，而不是额外的 DOM 节点
• pseudo-position-relative-parent - 父元素需要设置 position: relative
• pseudo-z-index-layering - 使用 z-index 正确设置伪元素的层叠顺序
• pseudo-hit-target-expansion - 使用负 inset 扩大命中区域
• pseudo-marker-styling - 使用 ::marker 自定义列表项目符号样式
• pseudo-first-line-styling - 使用 ::first-line 设置排版样式
• transition-name-required - 视图过渡需要 view-transition-name
• transition-name-unique - 过渡期间，每个过渡名称都必须唯一
• transition-name-cleanup - 完成后移除过渡名称
• transition-over-js-library - 优先使用 View Transitions API，而不是 JS 库
• transition-style-pseudo-elements - 设置 ::view-transition-group 的样式以自定义动画
• native-backdrop-styling - 使用 ::backdrop 设置对话框背景
• native-placeholder-styling - 使用 ::placeholder 设置输入框样式
• native-selection-styling - 使用 ::selection 设置文本选中样式

5. 音频反馈（中）

• a11y-visual-equivalent - 每种声音都必须有对应的视觉反馈
• a11y-toggle-setting - 提供关闭声音的切换选项
• a11y-reduced-motion-check - 声音应遵循 prefers-reduced-motion 设置
• a11y-volume-control - 允许独立调节音量
• appropriate-no-high-frequency - 打字或键盘导航时不要播放声音
• appropriate-confirmations-only - 仅在付款、上传和提交时播放确认音
• appropriate-errors-warnings - 对无法忽略的错误播放声音
• appropriate-no-decorative - 悬停或装饰性时刻不要播放声音
• appropriate-no-punishing - 用声音提示，而不要用刺耳的声音惩罚用户
• impl-preload-audio - 预加载音频文件以避免延迟
• impl-default-subtle - 默认音量应轻柔（0.3），不要太响
• impl-reset-current-time - 重播前重置 currentTime
• weight-match-action - 声音的分量应与操作的重要性相符
• weight-duration-matches-action - 声音时长应与操作时长相符

6. 声音合成（中）

• context-reuse-single - 复用单个 AudioContext，不要为每种声音都创建一个
• context-resume-suspended - 播放前恢复已暂停的 AudioContext
• context-cleanup-nodes - 播放后断开音频节点
• envelope-exponential-decay - 使用指数渐变实现自然衰减
• envelope-no-zero-target - 指数渐变的目标值设为 0.001，而不是 0
• envelope-set-initial-value - 渐变前设置初始值
• design-noise-for-percussion - 点击和轻敲声使用滤波噪声
• design-oscillator-for-tonal - 有音高的声音使用带音高扫频的振荡器
• design-filter-for-character - 使用带通滤波器塑造打击音
• param-click-duration - 点击声时长：5-15ms
• param-filter-frequency-range - 点击声滤波器频率：3000-6000Hz
• param-reasonable-gain - 增益低于 1.0，以防止削波
• param-q-value-range - 滤波器 Q 值：2-5，兼顾聚焦感与自然度

7. 变形图标（低优先级）

• morphing-three-lines - 每个图标恰好使用 3 条 SVG 线条
• morphing-use-collapsed - 未使用的线条使用 collapsed 常量
• morphing-consistent-viewbox - 所有图标使用相同的 viewBox（14x14）
• morphing-group-variants - 旋转变体共用同一组和基础线条
• morphing-spring-rotation - 对分组图标旋转使用弹簧物理效果
• morphing-reduced-motion - 遵循 prefers-reduced-motion 设置
• morphing-jump-non-grouped - 非分组图标之间旋转时立即跳转
• morphing-strokelinecap-round - 使用圆形描边端点
• morphing-aria-hidden - 图标 SVG 设置为 aria-hidden

8. 容器动画（中优先级）

• container-two-div-pattern - 外层 div 负责动画，内层 div 负责测量；两者绝不能是同一元素
• container-guard-initial-zero - 在初次渲染时检查 bounds === 0，并回退到 "auto"
• container-use-resize-observer - 使用 ResizeObserver 进行测量，而非 getBoundingClientRect
• container-overflow-hidden - 过渡期间，在动画容器上设置 overflow: hidden
• container-no-excessive-use - 谨慎使用：按钮、手风琴组件和交互元素
• container-callback-ref - 测量钩子使用回调 ref，而非 useRef
• container-transition-delay - 加入短暂延迟，营造自然追上的感觉

9. UX 定律（高优先级）

• ux-fitts-target-size - 交互目标应足够大，便于点击（最小 32px）
• ux-fitts-hit-area - 使用不可见内边距或伪元素扩大点击区域
• ux-hicks-minimize-choices - 减少选项，以缩短决策时间
• ux-millers-chunking - 将数据分成 5-9 项一组，便于快速浏览
• ux-doherty-under-400ms - 在 400ms 内响应，营造即时感
• ux-doherty-perceived-speed - 使用骨架屏、乐观 UI 和进度指示器营造快速感
• ux-postels-accept-messy-input - 接受不规范输入，输出整洁数据
• ux-progressive-disclosure - 显示当前重要内容，稍后再呈现复杂内容
• ux-jakobs-familiar-patterns - 使用用户熟悉的其他网站 UI 模式
• ux-aesthetic-usability - 精致的视觉设计能提升感知可用性
• ux-proximity-grouping - 通过缩小间距，在空间上将相关元素分组
• ux-similarity-consistency - 相似元素的外观应保持一致
• ux-common-region-boundaries - 使用边界对相关内容分组
• ux-von-restorff-emphasis - 让重要元素在视觉上脱颖而出
• ux-serial-position - 将关键项目放在序列的开头或结尾
• ux-peak-end-finish-strong - 以明确的成功状态结束体验
• ux-teslers-complexity - 将复杂性转移给系统，而非用户
• ux-goal-gradient-progress - 显示完成进度
• ux-zeigarnik-show-incomplete - 显示未完成状态，推动用户完成
• ux-pragnanz-simplify - 将复杂视觉内容简化为清晰形式
• ux-pareto-prioritize-features - 优先处理关键的 20% 功能
• ux-cognitive-load-reduce - 尽量减少无关的认知负荷
• ux-uniform-connectedness - 使用线条或边框在视觉上连接相关元素

10. 预测性预取（中优先级）

• prefetch-trajectory-over-hover - 优先采用轨迹预测而非悬停，可节省 100-200ms
• prefetch-not-everything - 根据意图而非视口进行预取，避免浪费带宽
• prefetch-hit-slop - 使用 hitSlop 更早触发预测
• prefetch-touch-fallback - 在触屏设备（无光标）上优雅回退
• prefetch-keyboard-tab - 键盘导航时，在焦点接近时进行预取
• prefetch-use-selectively - 在延迟明显的场景中使用预测性预取

11. 字体排版（MEDIUM）

• type-tabular-nums-for-data - 在列、仪表板和定价信息中使用等宽数字
• type-oldstyle-nums-for-prose - 旧式数字能自然融入正文
• type-slashed-zero - 在代码相关界面中使用带斜线的零
• type-opentype-contextual-alternates - 保持启用 calt，以调整上下文相关字形
• type-disambiguation-stylistic-set - 启用 ss02，以区分 I/l/1 和 0/O
• type-optical-sizing-auto - 将 font-optical-sizing 设为 auto，以适配不同字号的字形
• type-antialiased-on-retina - 在视网膜显示屏上使用抗锯齿字体平滑
• type-text-wrap-balance-headings - 在标题上使用 text-wrap: balance，使各行长度均衡
• type-underline-offset - 调整下划线位置，使其低于字母下伸部
• type-no-font-synthesis - 禁用 font-synthesis，以防止生成伪粗体或伪斜体
• type-font-display-swap - 使用 font-display: swap，避免加载期间文字不可见
• type-variable-weight-continuous - 搭配可变字体使用连续字重值（100-900）
• type-text-wrap-pretty - 在正文中使用 text-wrap: pretty，以减少孤行
• type-justify-with-hyphens - 将 text-align: justify 与 hyphens: auto 配合使用
• type-letter-spacing-uppercase - 为大写和小型大写文本添加 letter-spacing
• type-proper-fractions - 使用 diagonal-fractions 呈现规范的排版分数

12. 视觉设计（HIGH）

• visual-concentric-radius - 嵌套元素的内侧圆角半径 = 外侧圆角半径减去内边距
• visual-layered-shadows - 叠加多个阴影，营造真实的纵深感
• visual-shadow-direction - 所有阴影使用相同的偏移方向（单一光源）
• visual-no-pure-black-shadow - 阴影使用中性色，而非纯黑色
• visual-shadow-matches-elevation - 阴影大小应按照一致的比例体现层级高度
• visual-animate-shadow-pseudo - 通过伪元素的不透明度来生成阴影动画，以提升性能
• visual-consistent-spacing-scale - 使用一致的间距比例，而非任意数值
• visual-border-alpha-colors - 半透明边框可适配任何背景
• visual-button-shadow-anatomy - 使用六层阴影结构，打造精致按钮

使用方法

阅读各个规则文件，了解详细说明和代码示例：

rules/timing-under-300ms.md
rules/spring-for-gestures.md
rules/ux-doherty-under-400ms.md
rules/type-tabular-nums-for-data.md

每个规则文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明

完整汇编文档

如需查看包含所有规则完整内容的指南：AGENTS.md