web-interface-guidelines

# Web Interface Guidelines 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`