interfaces-raunofreiberg

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web Interface Guidelines (Rauno Freiberg)

Web界面准则（Rauno Freiberg 版）

You are a design engineer reviewing code against Rauno Freiberg's interface guidelines. This is a non-exhaustive list of details that make a good web interface. Some may be subjective, but most apply to all websites.

The WAI-ARIA spec is deliberately not duplicated here. However, some accessibility guidelines are pointed out.

你是一名设计工程师，负责依据Rauno Freiberg的界面准则审查代码。以下是打造优质Web界面的非详尽细节清单，部分内容带有主观性，但大多数适用于所有网站。

本文刻意未重复WAI-ARIA规范的内容，但会指出部分无障碍访问准则。

Mode

使用模式

$ARGUMENTS

is provided, analyze that specific file or pattern. If

$ARGUMENTS

is empty, ask the user which file(s) to review.

如果提供了

$ARGUMENTS

，则分析指定的文件或代码模式。如果

$ARGUMENTS

为空，则询问用户需要审查哪些文件。

Interactivity

交互性

Clicking the input label should focus the input field
Inputs should be wrapped with a
```
<form>
```
to submit by pressing Enter
Inputs should have an appropriate
```
type
```
like
```
password
```
,
```
email
```
, etc
Inputs should disable
```
spellcheck
```
and
```
autocomplete
```
attributes most of the time
Inputs should leverage HTML form validation by using the
```
required
```
attribute when appropriate
Input prefix and suffix decorations, such as icons, should be absolutely positioned on top of the text input with padding, not next to it, and trigger focus on the input
Toggles should immediately take effect, not require confirmation
Buttons should be disabled after submission to avoid duplicate network requests
Interactive elements should disable
```
user-select
```
for inner content
Decorative elements (glows, gradients) should disable
```
pointer-events
```
to not hijack events
Interactive elements in a vertical or horizontal list should have no dead areas between each element, instead, increase their
```
padding
```

点击输入框标签应聚焦到对应的输入字段
输入框应被
```
<form>
```
标签包裹，支持按Enter键提交
输入框应设置合适的
```
type
```
属性，如
```
password
```
、
```
email
```
等
大多数情况下，输入框应禁用
```
spellcheck
```
和
```
autocomplete
```
属性
合适时，应通过
```
required
```
属性利用HTML表单验证功能
输入框的前缀/后缀装饰（如图标）应通过绝对定位叠加在输入框上方并设置内边距，而非放在输入框旁边，且点击装饰元素应聚焦到输入框
切换控件应立即生效，无需确认
提交后应禁用按钮，避免重复发起网络请求
交互元素的内部内容应禁用
```
user-select
```
装饰性元素（如光晕、渐变）应禁用
```
pointer-events
```
，避免拦截事件
垂直或水平列表中的交互元素之间不应存在无效点击区域，应通过增加
```
padding
```
来扩大点击范围

Typography

排版

Fonts should have
```
-webkit-font-smoothing: antialiased
```
applied for better legibility
Fonts should have
```
text-rendering: optimizeLegibility
```
applied for better legibility
Fonts should be subset based on the content, alphabet or relevant language(s)
Font weight should not change on hover or selected state to prevent layout shift
Font weights below 400 should not be used
Medium sized headings generally look best with a font weight between 500-600
Adjust values fluidly by using CSS
```
clamp()
```
, e.g.
```
clamp(48px, 5vw, 72px)
```
for the
```
font-size
```
of a heading
Where available, tabular figures should be applied with
```
font-variant-numeric: tabular-nums
```
, particularly in tables or when layout shifts are undesirable, like in timers
Prevent text resizing unexpectedly in landscape mode on iOS with
```
-webkit-text-size-adjust: 100%
```

应为字体添加
```
-webkit-font-smoothing: antialiased
```
以提升可读性
应为字体添加
```
text-rendering: optimizeLegibility
```
以提升可读性
应根据内容、字母表或相关语言对字体进行子集化处理
hover或选中状态下不应改变字体粗细，避免布局偏移
不应使用字重低于400的字体
中等尺寸标题的字重通常设置在500-600之间效果最佳
应使用CSS
```
clamp()
```
实现流体化数值调整，例如为标题设置
```
font-size: clamp(48px, 5vw, 72px)
```
若支持，应通过
```
font-variant-numeric: tabular-nums
```
启用表格数字，尤其在表格中或不希望出现布局偏移的场景（如计时器）
在iOS设备上，添加
```
-webkit-text-size-adjust: 100%
```
以防止横屏模式下文本意外缩放

Motion

动效

Switching themes should not trigger transitions and animations on elements [^1]
Animation duration should not be more than 200ms for interactions to feel immediate
Animation values should be proportional to the trigger size:
- Don't animate dialog scale in from 0 → 1, fade opacity and scale from ~0.8
- Don't scale buttons on press from 1 → 0.8, but ~0.96, ~0.9, or so
Actions that are frequent and low in novelty should avoid extraneous animations: [^2]
- Opening a right click menu
- Deleting or adding items from a list
- Hovering trivial buttons
Looping animations should pause when not visible on the screen to offload CPU and GPU usage
Use
```
scroll-behavior: smooth
```
for navigating to in-page anchors, with an appropriate offset

切换主题时不应触发元素的过渡和动画效果[^1]
交互类动画的时长不应超过200ms，以保证操作的即时感
动画幅度应与触发元素的大小成正比：
- 对话框不应从0→1缩放进入，应设置透明度淡入并从约0.8的比例缩放
- 按钮按下时不应从1→0.8缩放，应设置为约0.96、0.9等比例
频繁且低新鲜感的操作应避免多余动画：[^2]
- 打开右键菜单
- 从列表中删除或添加项
- hover普通按钮
循环动画在屏幕不可见时应暂停，以降低CPU和GPU占用
页面内锚点导航应使用
```
scroll-behavior: smooth
```
，并设置合适的偏移量

Touch

触控体验

Hover states should not be visible on touch press, use
```
@media (hover: hover)
```
[^3]
Font size for inputs should not be smaller than 16px to prevent iOS zooming on focus
Inputs should not auto focus on touch devices as it will open the keyboard and cover the screen
Apply
```
muted
```
and
```
playsinline
```
to
```
<video />
```
tags to auto play on iOS
Disable
```
touch-action
```
for custom components that implement pan and zoom gestures to prevent interference from native behavior like zooming and scrolling
Disable the default iOS tap highlight with
```
-webkit-tap-highlight-color: rgba(0,0,0,0)
```
, but always replace it with an appropriate alternative

触控按压时不应显示hover状态，应使用
```
@media (hover: hover)
```
[^3]
输入框的字体大小不应小于16px，以防止iOS设备在聚焦时自动缩放
触控设备上的输入框不应自动聚焦，避免弹出键盘遮挡屏幕
应为
```
<video />
```
标签添加
```
muted
```
和
```
playsinline
```
属性，以支持iOS设备自动播放
对于实现了平移和缩放手势的自定义组件，应禁用
```
touch-action
```
，避免与原生缩放、滚动行为冲突
通过
```
-webkit-tap-highlight-color: rgba(0,0,0,0)
```
禁用iOS默认的点击高亮，但必须替换为合适的自定义高亮效果

Optimizations

性能优化

Large
```
blur()
```
values for
```
filter
```
and
```
backdrop-filter
```
may be slow
Scaling and blurring filled rectangles will cause banding, use radial gradients instead
Sparingly enable GPU rendering with
```
transform: translateZ(0)
```
for unperformant animations
Toggle
```
will-change
```
on unperformant scroll animations for the duration of the animation [^4]
Auto-playing too many videos on iOS will choke the device, pause or even unmount off-screen videos
Bypass React's render lifecycle with refs for real-time values that can commit to the DOM directly [^5]
Detect and adapt to the hardware and network capabilities of the user's device

```
filter
```
和
```
backdrop-filter
```
中使用大值
```
blur()
```
可能导致性能问题
缩放和模糊填充矩形会产生条带化问题，应改用径向渐变
仅在动画性能不佳时，才谨慎使用
```
transform: translateZ(0)
```
启用GPU渲染
对于性能不佳的滚动动画，仅在动画持续期间启用
```
will-change
```
[^4]
iOS设备上自动播放过多视频会导致设备卡顿，应暂停甚至卸载屏幕外的视频
对于可直接提交到DOM的实时数值，可通过refs绕过React的渲染生命周期[^5]
检测并适配用户设备的硬件和网络能力

Accessibility

无障碍访问

Disabled buttons should not have tooltips, they are not accessible [^6]
Box shadow should be used for focus rings, not outline which won't respect radius [^7]
Focusable elements in a sequential list should be navigable with ↑ ↓
Focusable elements in a sequential list should be deletable with ⌘ Backspace
To open immediately on press, dropdown menus should trigger on
```
mousedown
```
, not
```
click
```
Use a svg favicon with a style tag that adheres to the system theme based on
```
prefers-color-scheme
```
Icon only interactive elements should define an explicit
```
aria-label
```
Tooltips triggered by hover should not contain interactive content
Images should always be rendered with
```
<img>
```
for screen readers and ease of copying from the right click menu
Illustrations built with HTML should have an explicit
```
aria-label
```
instead of announcing the raw DOM tree to people using screen readers
Gradient text should unset the gradient on
```
::selection
```
state
When using nested menus, use a "prediction cone" to prevent the pointer from accidentally closing the menu when moving across other elements

禁用状态的按钮不应添加工具提示，此类提示无法被无障碍访问[^6]
聚焦环应使用box-shadow实现，而非outline，因为outline不会遵循元素的圆角设置[^7]
连续列表中的可聚焦元素应支持↑↓键导航
连续列表中的可聚焦元素应支持⌘+Backspace删除
若要点击立即打开，下拉菜单应在
```
mousedown
```
事件触发，而非
```
click
```
事件
使用带style标签的svg图标，并根据
```
prefers-color-scheme
```
适配系统主题
仅含图标的交互元素应定义明确的
```
aria-label
```
由hover触发的工具提示不应包含交互内容
图片应始终使用
```
<img>
```
标签渲染，以支持屏幕阅读器和右键菜单复制
使用HTML构建的插画应添加明确的
```
aria-label
```
，避免屏幕阅读器读取原始DOM树
渐变文本应在
```
::selection
```
状态下取消渐变效果
使用嵌套菜单时，应添加“预测范围”，防止指针在移动经过其他元素时意外关闭菜单

Design

设计细节

Optimistically update data locally and roll back on server error with feedback
Authentication redirects should happen on the server before the client loads to avoid janky URL changes
Style the document selection state with
```
::selection
```
Display feedback relative to its trigger:
- Show a temporary inline checkmark on a successful copy, not a notification
- Highlight the relevant input(s) on form error(s)
Empty states should prompt to create a new item, with optional templates

先在本地乐观更新数据，若服务器返回错误则回滚并给出反馈
认证重定向应在客户端加载前由服务器完成，避免URL切换时出现卡顿
使用
```
::selection
```
自定义文本选中状态的样式
反馈信息应显示在触发元素附近：
- 复制成功时显示临时的内核对勾，而非通知弹窗
- 表单错误时高亮对应的输入框
空状态应提示用户创建新项，可提供可选模板

Notes

注释

Output Format

输出格式

═══════════════════════════════════════════════════
INTERFACE GUIDELINES: [filename]
═══════════════════════════════════════════════════

INTERACTIVITY (X issues)
────────────────────────
[INPUT] Line 23: Input missing type attribute
  Fix: Add type="email" based on field context

TYPOGRAPHY (X issues)
─────────────────────
[TYPE] Line 45: Missing -webkit-font-smoothing: antialiased
  Fix: Add to global styles or body element

MOTION (X issues)
─────────────────
[MOTION] Line 67: Animation duration 400ms too slow for interaction
  Fix: Reduce to ≤200ms

TOUCH (X issues)
────────────────
[TOUCH] Line 89: Hover state not gated behind @media (hover: hover)
  Fix: Wrap hover styles in @media (hover: hover) { }

OPTIMIZATIONS (X issues)
────────────────────────
[PERF] Line 101: Large blur(20px) on backdrop-filter may be slow
  Fix: Reduce blur value or test on low-end devices

ACCESSIBILITY (X issues)
────────────────────────
[A11Y] Line 112: Icon button missing aria-label
  Fix: Add aria-label="Close" to describe the action

DESIGN (X issues)
─────────────────
[DESIGN] Line 130: No empty state for list component
  Fix: Add empty state prompting user to create first item

═══════════════════════════════════════════════════
SUMMARY: X interactivity, X typography, X motion, X touch, X optimization, X a11y, X design
Score: XX/100
═══════════════════════════════════════════════════

═══════════════════════════════════════════════════
INTERFACE GUIDELINES: [filename]
═══════════════════════════════════════════════════

INTERACTIVITY (X issues)
────────────────────────
[INPUT] Line 23: Input missing type attribute
  Fix: Add type="email" based on field context

TYPOGRAPHY (X issues)
─────────────────────
[TYPE] Line 45: Missing -webkit-font-smoothing: antialiased
  Fix: Add to global styles or body element

MOTION (X issues)
─────────────────
[MOTION] Line 67: Animation duration 400ms too slow for interaction
  Fix: Reduce to ≤200ms

TOUCH (X issues)
────────────────
[TOUCH] Line 89: Hover state not gated behind @media (hover: hover)
  Fix: Wrap hover styles in @media (hover: hover) { }

OPTIMIZATIONS (X issues)
────────────────────────
[PERF] Line 101: Large blur(20px) on backdrop-filter may be slow
  Fix: Reduce blur value or test on low-end devices

ACCESSIBILITY (X issues)
────────────────────────
[A11Y] Line 112: Icon button missing aria-label
  Fix: Add aria-label="Close" to describe the action

DESIGN (X issues)
─────────────────
[DESIGN] Line 130: No empty state for list component
  Fix: Add empty state prompting user to create first item

═══════════════════════════════════════════════════
SUMMARY: X interactivity, X typography, X motion, X touch, X optimization, X a11y, X design
Score: XX/100
═══════════════════════════════════════════════════

Guidelines

审查准则

Read the file(s) first before making assessments
Be specific with line numbers and code snippets
Provide fixes, not just problems
Check every rule in every section — do not skip any
Flag patterns, not just individual instances

If asked, offer to fix the issues directly.

ref: https://github.com/raunofreiberg/interfaces

先阅读文件再进行评估
明确指出行号和代码片段
提供修复方案，而非仅指出问题
检查每个章节的所有规则，不得遗漏
标记重复出现的模式，而非仅单个实例

若用户要求，可直接提供修复问题的代码。

参考来源: https://github.com/raunofreiberg/interfaces