web-interface-guidelines

Vercel's comprehensive UI guidelines for building accessible, performant web interfaces. Use this skill when reviewing or building UI components for compliance with best practices around accessibility, performance, animations, and visual stability.

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

Quick Reference - Visual Stability

Issue	Rule
Images without dimensions	<img> needs explicit width and height (prevents CLS)
Font loading flash	Critical fonts: <link rel="preload" as="font"> with font-display: swap
Large lists	Virtualize lists >50 items (content-visibility: auto)
Layout reads in render	No 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