用户界面维基

全面的 UI/UX 最佳实践指南，涵盖网页界面。包含 11 个类别的 119 条规则，按影响优先级排序，以指导自动化代码审查和生成。

何时应用

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

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

按优先级分类的规则类别

快速参考

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 – “wait”模式使时长翻倍；需减半时间
• mode-sync-layout-conflict – “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 扩大点击区域
• transition-name-required – 视图过渡需要 view-transition-name
• transition-name-unique – 过渡期间每个过渡名称唯一
• transition-name-cleanup – 完成后移除过渡名称
• transition-over-js-library – 优先使用视图过渡 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 – 未使用的线条使用折叠常量
• morphing-consistent-viewbox – 所有图标共享相同的 viewBox（14×14）
• 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 – 初始渲染时边界为 0，回退到“auto”
• container-use-resize-observer – 使用 ResizeObserver 进行测量，而非 getBoundingClientRect
• container-overflow-hidden – 过渡期间在动画容器上设置 overflow: hidden
• container-no-excessive-use – 谨慎使用：按钮、手风琴、交互元素
• container-callback-ref – 使用回调 ref（而非 useRef）进行测量钩子

9. 用户体验定律（高）

• 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 – 展示当前重要内容，逐步揭示复杂性

10. 预测性预取（中）

• prefetch-trajectory-over-hover – 轨迹预测优于悬停预测；可节省 100-200ms
• prefetch-not-everything – 基于意图预取，而非视口内全部；避免带宽浪费
• prefetch-hit-slop – 使用 hitSlop 提前触发预测
• prefetch-touch-fallback – 在触摸设备上优雅降级（无光标）
• prefetch-keyboard-tab – 键盘导航焦点接近时预取
• prefetch-use-selectively – 在延迟明显的区域使用预测性预取

11. 排版（中）

• 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 防止浏览器合成伪粗体/斜体

如何使用

阅读单个规则文件获取详细解释和代码示例：

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