Web Interface Guidelines

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

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

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

Theme switching should not trigger transitions and animations on elements ¹
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: ²
- 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 states should not be displayed on touch press; use
```
@media (hover: hover)
```
³
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
```
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 ⁴
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 ⁵
Detect and adapt to the user's device hardware and network capabilities

Accessibility

Disabled buttons should not have tooltips, as they cannot be used accessibly ⁶
Focus rings should use box shadow instead of outline, which cannot match rounded corners ⁷
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

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

Footnotes

Switching between dark and light modes triggers transitions on elements that were intended for explicit interactions (like hover). You can temporarily disable transitions to avoid this. If using Next.js, use next-themes, which has built-in support to avoid this issue. ↩
This is a matter of taste, but some interactions feel better without animations. For example, the native macOS right-click menu only has an animation when closing, not when opening, due to its high frequency of use. ↩
Most touch devices briefly show hover states on press unless explicitly defined for pointer devices only with
@media (hover: hover)
. ↩
Only use
will-change
as a last resort to improve performance. Applying it to a large number of elements in advance for performance may backfire. ↩
This may be controversial, but sometimes directly manipulating the DOM is beneficial. For example, instead of relying on React re-render for every wheel event, track increments in a ref and update relevant elements directly in the callback. ↩
Disabled buttons do not appear in the DOM's tab order, so tooltips will never be heard by keyboard users, who also won't know why the button is disabled. ↩
As of 2023, Safari does not account for an element's border radius when customizing outline styles. Safari 16.4 has added support for outline to follow rounded corners. However, remember that not everyone will update their operating system immediately. ↩

web-interface-guidelines

NPX Install

Tags

SKILL.md Content (Chinese)