web-interface-guidelines

---

name: web-interface-guidelines description: 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.

---

Web Interface Guidelines

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

Quick Reference - Visual Stability

| Issue | Rule | |-------|------| | Images without dimensions | needs explicit width and height (prevents CLS) | | Font loading flash | Critical fonts: 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

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 for CDN/asset domains

Critical fonts: with font-display: swap

Accessibility

Icon-only buttons need aria-label

Form controls need or aria-label

Interactive elements need keyboard handlers (onKeyDown/onKeyUp)

for actions, / for navigation (not

)

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