Vercel Design Guidelines

A living document of interface design decisions from Vercel. Most guidelines are framework-agnostic; some are specific to React and Next.js.

Interactions

• Keyboard everywhere — all flows follow the WAI-ARIA Authoring Patterns with visible focus rings (:focus-visible over :focus, :focus-within for grouped controls).
• Hit targets — visual targets under 24px get expanded hit areas; 44px minimum on mobile.
• URL as state — persist state in the URL so share, refresh, and Back/Forward navigation work (e.g. via nuqs).
• Optimistic updates — update the UI immediately when success is likely, reconcile on server response, roll back on failure.
• Deep-link everything — filters, tabs, pagination, expanded panels — anytime useState is used, put it in the URL.
• Links are links — use <a> or <Link> for navigation so Cmd/Ctrl+Click, middle-click, and right-click work.
• No dead zones — if part of a control looks interactive, it should be interactive.
• Tooltip timing — delay the first tooltip in a group; subsequent peers have no delay.
• Announce async updates — use polite aria-live for toasts and inline validation.

Animations

• Prefer CSS — CSS over Web Animations API over JavaScript libraries. Prioritise GPU-accelerated properties (transform, opacity).
• Honour prefers-reduced-motion — every animation must have a reduced variant.
• Interruptible and input-driven — animations are cancelable by user input and never autoplay.
• Never transition: all — explicitly list only the properties you intend to animate.

Layout

• Optical alignment — adjust ±1px when perception beats geometry.
• Deliberate alignment — every element aligns with something intentionally.
• Let the browser size things — prefer flex, grid, and intrinsic layout over measuring in JS.
• Responsive coverage — verify on mobile, laptop, and ultra-wide (50% zoom).
• Respect safe areas — account for notches and insets with safe-area variables.

Content

• Accurate page titles — <title> reflects the current context.
• No dead ends — every screen offers a next step or recovery path.
• All states designed — empty, sparse, dense, and error states.
• Icons have labels — icon-only buttons carry a descriptive aria-label.
• Semantics before ARIA — prefer native elements (<button>, <a>, <label>) before aria-*.
• Headings and skip link — hierarchical <h1>–<h6> and a skip-to-content link.
• Locale-aware formats — dates, times, numbers, and currencies for the user's locale.

Forms

• Enter submits — when a text input is focused, Enter submits if it is the only control.
• Labels everywhere — every control has a <label>; clicking it focuses the associated control.
• Don't block typing — allow any input and show validation feedback rather than blocking keystrokes.
• Don't pre-disable submit — allow submitting incomplete forms to surface validation feedback.
• Error placement — show errors next to their fields; on submit, focus the first error.
• Autocomplete and names — set autocomplete and meaningful name values for autofill.

Performance

• Device and browser matrix — test iOS Low Power Mode and macOS Safari.
• Throttle when profiling — test with CPU and network throttling.
• Preload wisely — preload only above-the-fold images; lazy-load the rest.
• No image-caused CLS — set explicit image dimensions and reserve space.
• Preload fonts — for critical text, avoid flash and layout shift.
• Large lists — virtualize with virtua or content-visibility: auto.

Design

• Layered shadows — mimic ambient and direct light with at least two layers.
• Crisp borders — combine borders and shadows; semi-transparent borders improve edge clarity.
• Nested radii — child radius ≤ parent radius, concentric so curves align.
• Minimum contrast — prefer APCA over WCAG 2 for more accurate perceptual contrast.
• Browser UI matches background — set <meta name="theme-color"> and color-scheme.

Vercel-specific copywriting

• Active voice — "Install the CLI" not "The CLI will be installed".
• Headings and buttons use Title Case (Chicago) for product UI; sentence case on marketing pages.
• Prefer & over and — action-oriented language, second person.
• Numerals for counts — "8 deployments" not "eight deployments".
• Separate numbers and units with a space: 10 MB not 10MB.
• Error messages guide the exit — tell the user how to fix it, not just what went wrong.