Web
Interface
Guidelines

24/02/2023

Introduction

This document outlines a non-exhaustive list of details that make a good (web) interface. It is a living document, periodically updated based on personal learnings. Some of these may be subjective, but most apply to all websites. The WAI-ARIA spec is deliberately not duplicated in this document. However, some accessibility guidelines may be pointed out.

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

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

Motion

  • Switching themes should not trigger transitions and animations on elements 1
  • Animation duration should not be more than 150ms 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

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

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

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
  • Complex decorative elements should define an explicit aria-label instead of relying on DOM structure
  • 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

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 the success state relative to its trigger:
    • Show a temporary checkmark on a successful copy, not a notification
    • Highlight the relevant input on form errors, not the form

1. Switching between dark mode or light mode will trigger transitions on elements that are meant for explicit interactions like hover. We can disable transitions temporarily to prevent this. For Next.js, use next-themes which prevents transitions out of the box.

2. This is a matter of taste but some interactions just feel better with no motion. For example, the native macOS right click menu only animates out, not in, due to the frequent usage of it.

3. Most touch devices on press will temporarily flash the hover state, unless explicitly only defined for pointer devices with @media (hover: hover).

4. Use will-change as a last resort to improve performance. Pre-emptively throwing it on elements for better performance may have the opposite effect.

5. This might be controversial but sometimes it can be beneficial to manipulate the DOM directly. For example, instead of relying on React re-rendering on every wheel event, we can track the delta in a ref and update relevant elements directly in the callback.

6. Disabled buttons do not appear in tab order in the DOM so the tooltip will never be announced for keyboard users and they won't know why the button is disabled.

7. As of 2023, Safari will not take the border radius of an element into account when defining custom outline styles.