web-interface-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web Interface Guidelines

本文件列出一些能讓（網頁）介面變好的細節，並非窮舉。這是一份會依經驗持續更新的文件。其中有些項目可能帶有主觀性，但大多數適用於所有網站。

本文刻意不重複 WAI-ARIA 規格內容，但仍可能點出部分無障礙相關準則。歡迎貢獻：編輯此檔案並提交 pull request。

This document lists details that can make (web) interfaces better, and is not exhaustive. It is a document that will be continuously updated based on experience. Some items may be subjective, but most apply to all websites.

We intentionally do not repeat content from the WAI-ARIA specification, but may still highlight some accessibility-related guidelines. Contributions are welcome: edit this file and submit a pull request.

Interactivity

點擊輸入欄位的 label 應讓該輸入欄位取得焦點
輸入欄位應包在
```
<form>
```
內，以便按下 Enter 送出
輸入欄位應使用適當的
```
type
```
，例如
```
password
```
、
```
email
```
等
多數情況下，輸入欄位應停用
```
spellcheck
```
與
```
autocomplete
```
屬性
適當時，輸入欄位應透過
```
required
```
屬性善用 HTML 表單驗證
輸入欄位的前綴與後綴裝飾（例如圖示）應以絕對定位疊在文字輸入框上並配合 padding，而非擺在旁邊，且點擊時應讓輸入欄位取得焦點
切換開關（Toggles）應立即生效，無需再經確認
送出後應停用按鈕，以避免重複的網路請求
可互動元素應對其內層內容停用
```
user-select
```
裝飾性元素（光暈、漸層等）應停用
```
pointer-events
```
，以免攔截事件
垂直或水平列表中的可互動元素之間不應有無法點擊的空白；應改為增加它們的
```
padding
```

Clicking the label of an input field should focus that input field
Input fields should be wrapped in
```
<form>
```
to allow submission via Enter key
Input fields should use appropriate
```
type
```
attributes, such as
```
password
```
,
```
email
```
, etc.
In most cases, input fields should disable
```
spellcheck
```
and
```
autocomplete
```
attributes
When appropriate, input fields should leverage HTML form validation via the
```
required
```
attribute
Prefix and suffix decorations (e.g., icons) for input fields should be absolutely positioned over the text input box with matching padding, instead of placed beside it, and clicking them should focus the input field
Toggles should take effect immediately without requiring confirmation
Buttons should be disabled after submission to avoid duplicate network requests
Interactive elements should disable
```
user-select
```
for their inner content
Decorative elements (glows, gradients, etc.) should disable
```
pointer-events
```
to prevent event interception
There should be no unclickable gaps between interactive elements in vertical or horizontal lists; instead, increase their
```
padding
```

Typography

字體應套用
```
-webkit-font-smoothing: antialiased
```
以提升易讀性
字體應套用
```
text-rendering: optimizeLegibility
```
以提升易讀性
字體應依內容、字母表或相關語言進行子集化（subset）
在 hover 或選取狀態下不應改變字重，以免版面位移
不應使用低於 400 的字重
中等尺寸的標題一般以字重 500–600 看起來最佳
使用 CSS
```
clamp()
```
流暢調整數值，例如標題的
```
font-size
```
：
```
clamp(48px, 5vw, 72px)
```
在適用情況下應使用
```
font-variant-numeric: tabular-nums
```
套用等寬數字（tabular figures），特別是在表格中，或在不希望版面位移的情況（例如計時器）
在 iOS 的橫向模式下，使用
```
-webkit-text-size-adjust: 100%
```
避免文字意外縮放

Apply
```
-webkit-font-smoothing: antialiased
```
to fonts to improve readability
Apply
```
text-rendering: optimizeLegibility
```
to fonts to improve readability
Fonts should be subset based on content, alphabet, or related language
Do not change font weight on hover or selection to avoid layout shifts
Do not use font weights lower than 400
Medium-sized titles generally look best with font weights 500–600
Use CSS
```
clamp()
```
for smooth value adjustment, such as
```
font-size
```
for titles:
```
clamp(48px, 5vw, 72px)
```
Apply
```
font-variant-numeric: tabular-nums
```
for tabular figures when applicable, especially in tables or situations where layout shifts are undesirable (e.g., timers)
Use
```
-webkit-text-size-adjust: 100%
```
in iOS landscape mode to prevent unexpected text scaling

Motion

切換主題時，不應觸發元素上的 transition 與動畫 [^1]
互動動畫的持續時間不應超過 200ms，才會感覺即時
動畫數值應與觸發元素的尺寸成比例：
- 不要將對話框從 scale 0 動到 1；改為淡入透明度並從約 0.8 縮放
- 按鈕按下時不要從 1 縮到 0.8，而是約 0.96、0.9 之類
頻繁且新鮮感低的操作應避免多餘動畫：[^2]
- 開啟右鍵選單
- 從列表刪除或新增項目
- 對瑣碎按鈕 hover
循環播放的動畫在畫面上不可見時應暫停，以減輕 CPU 與 GPU 負載
導向頁內錨點時使用
```
scroll-behavior: smooth
```
，並保留適當的偏移量

Theme switching should not trigger transitions and animations on elements [^1]
Interactive animations should not last longer than 200ms to feel instant
Animation values should be proportional to the size of the triggering element:
- Do not animate dialogs from scale 0 to 1; instead, fade in opacity and scale from around 0.8
- Do not scale buttons from 1 to 0.8 when pressed; use values like 0.96 or 0.9 instead
Avoid unnecessary animations for frequent, low-freshness operations: [^2]
- Opening right-click menus
- Deleting or adding items from/to lists
- Hovering over trivial buttons
Looping animations should pause when not visible on screen to reduce CPU and GPU load
Use
```
scroll-behavior: smooth
```
for in-page anchor navigation, with appropriate offset

Touch

觸控按下時不應顯示 hover 狀態，請使用
```
@media (hover: hover)
```
[^3]
輸入欄位字體不應小於 16px，以免 iOS 在聚焦時放大畫面
觸控裝置上不應自動聚焦輸入欄位，否則會開啟鍵盤並遮住畫面
在
```
<video />
```
標籤套用
```
muted
```
與
```
playsinline
```
以便在 iOS 自動播放
對實作平移與縮放手勢的自訂元件停用
```
touch-action
```
，以免與縮放、捲動等原生行為互相干擾
以
```
-webkit-tap-highlight-color: rgba(0,0,0,0)
```
停用 iOS 預設的點擊高亮，但務必改以合適的替代視覺回饋

Hover states should not be displayed on touch press; use
```
@media (hover: hover)
```
[^3]
Input field fonts should not be smaller than 16px to prevent iOS from zooming the screen on focus
Input fields should not auto-focus on touch devices, as this will open the keyboard and block the screen
Apply
```
muted
```
and
```
playsinline
```
to
```
<video />
```
tags for auto-play on iOS
Disable
```
touch-action
```
for custom components implementing pan and zoom gestures to avoid conflicts with native behaviors like zooming and scrolling
Disable iOS default tap highlight with
```
-webkit-tap-highlight-color: rgba(0,0,0,0)
```
, but be sure to replace it with appropriate alternative visual feedback

Optimizations

```
filter
```
與
```
backdrop-filter
```
若使用過大的
```
blur()
```
數值可能很慢
對填滿的矩形做縮放與模糊會造成色帶（banding），請改用放射狀漸層（radial gradients）
僅在必要時少量使用
```
transform: translateZ(0)
```
啟用 GPU 繪製，以改善效能不佳的動畫
針對效能不佳的捲動動畫，僅在動畫進行期間切換
```
will-change
```
[^4]
在 iOS 上自動播放過多影片會拖垮裝置；請暫停或卸載畫面外的影片
對可即時寫入 DOM 的數值，可用 ref 繞過 React 的 render 生命週期直接提交 [^5]
偵測並適應使用者裝置的硬體與網路能力

```
filter
```
and
```
backdrop-filter
```
with overly large
```
blur()
```
values may be slow
Scaling and blurring filled rectangles can cause banding; use radial gradients instead
Only use
```
transform: translateZ(0)
```
sparingly when necessary to enable GPU rendering and improve poorly performing animations
For poorly performing scroll animations, switch
```
will-change
```
only during the animation [^4]
Auto-playing too many videos on iOS will slow down the device; pause or unload off-screen videos
For values that can be written to the DOM in real-time, use refs to bypass React's render lifecycle and submit directly [^5]
Detect and adapt to the user's device hardware and network capabilities

Accessibility

停用的按鈕不應有 tooltip，否則無法被無障礙使用 [^6]
焦點環（focus rings）應使用 box shadow，而非無法配合圓角的 outline [^7]
可循序聚焦列表中的元素應能以 <kbd>↑</kbd> <kbd>↓</kbd> 導覽
可循序聚焦列表中的元素應能以 <kbd>⌘</kbd> <kbd>Backspace</kbd> 刪除
若要按下後立即開啟，下拉選單應在
```
mousedown
```
觸發，而非
```
click
```
使用內含可依
```
prefers-color-scheme
```
配合系統主題的 style 標籤之 SVG favicon
僅有圖示的可互動元素應定義明確的
```
aria-label
```
由 hover 觸發的 tooltip 不應包含可互動內容
圖片應一律以
```
<img>
```
呈現，以利螢幕閱讀器與從右鍵選單複製
以 HTML 構成的插圖應有明確的
```
aria-label
```
，而不要向螢幕閱讀器朗讀原始 DOM 樹
漸層文字在
```
::selection
```
狀態應取消漸層
使用巢狀選單時，使用「預測錐（prediction cone）」避免滑鼠移經其他元素時誤關閉選單

Disabled buttons should not have tooltips, as they cannot be used accessibly [^6]
Focus rings should use box shadow instead of outline, which cannot match rounded corners [^7]
Elements in sequentially focusable lists should be navigable with <kbd>↑</kbd> <kbd>↓</kbd>
Elements in sequentially focusable lists should be deletable with <kbd>⌘</kbd> <kbd>Backspace</kbd>
Dropdown menus that open immediately when pressed should trigger on
```
mousedown
```
instead of
```
click
```
Use SVG favicons with style tags that adapt to system themes via
```
prefers-color-scheme
```
Icon-only interactive elements should define a clear
```
aria-label
```
Tooltips triggered by hover should not contain interactive content
Images should always be presented with
```
<img>
```
to support screen readers and right-click copying
Illustrations composed of HTML should have a clear
```
aria-label
```
instead of having the raw DOM tree read aloud by screen readers
Gradient text should remove the gradient in
```
::selection
```
state
When using nested menus, use a "prediction cone" to avoid accidental closure when the mouse moves over other elements

Design

樂觀地在本地更新資料，若伺服器錯誤則回滾並給予回饋
認證導向應在 client 載入前於伺服器端完成，以避免 URL 變更不順暢
以
```
::selection
```
設定文件選取狀態的樣式
回饋應相對於觸發來源呈現：
- 複製成功時顯示短暫的行內勾選，而非通知
- 表單錯誤時標示相關輸入欄位
空狀態應提示建立新項目，並可選附範本

Optimistically update data locally, roll back and provide feedback if a server error occurs
Authentication redirection should be completed on the server side before client loading to avoid URL change issues
Style document selection state with
```
::selection
```
Feedback should be presented relative to the trigger source:
- Show a brief inline checkmark when copy is successful, instead of a notification
- Mark relevant input fields when form errors occur
Empty states should prompt users to create new items, with optional templates