Web Interface Guidelines#

Review UI code for compliance with Vercel's web interface standards.

Quick Reference - Visual Stability#

IssueRuleImages without dimensions<img> needs explicit width and height (prevents CLS)Font loading flashCritical fonts: <link rel="preload" as="font"> with font-display: swapLarge listsVirtualize lists >50 items ( content-visibility: auto)Layout reads in renderNo getBoundingClientRect, offsetHeight in render path

Full Rules#

Images#

• <img> needs explicit width and height (prevents CLS)
• Below-fold images: loading="lazy"
• Above-fold critical images: priority or fetchpriority="high"

Performance#

• Large lists (>50 items): virtualize ( virtua, content-visibility: auto)
• No layout reads in render ( getBoundingClientRect, offsetHeight, offsetWidth, scrollTop)
• Batch DOM reads/writes; avoid interleaving
• Add <link rel="preconnect"> for CDN/asset domains
• Critical fonts: <link rel="preload" as="font"> with font-display: swap

Accessibility#

• Icon-only buttons need aria-label
• Form controls need <label> or aria-label
• Interactive elements need keyboard handlers ( onKeyDown/ onKeyUp)
• <button> for actions, <a>/ <Link> for navigation (not <div onClick>)
• Images need alt (or alt="" if decorative)

Focus States#

• Interactive elements need visible focus: focus-visible:ring-* or equivalent
• Never outline-none / outline: none without focus replacement
• Use :focus-visible over :focus (avoid focus ring on click)

Animation#

• Honor prefers-reduced-motion (provide reduced variant or disable)
• Animate transform/ opacity only (compositor-friendly)
• Never transition: all—list properties explicitly

Forms#

• Inputs need autocomplete and meaningful name
• Use correct type ( email, tel, url, number) and inputmode
• Never block paste ( onPaste + preventDefault)
• Labels clickable ( htmlFor or wrapping control)

Content Handling#

• Text containers handle long content: truncate, line-clamp-*, or break-words
• Flex children need min-w-0 to allow text truncation
• Handle empty states—don't render broken UI for empty strings/arrays

Anti-patterns (flag these)#

• user-scalable=no or maximum-scale=1 disabling zoom
• transition: all
• outline-none without focus-visible replacement
• Images without dimensions
• Large arrays .map() without virtualization
• Form inputs without labels
• Icon buttons without aria-label