playbooks

home / skills / benchflow-ai / skillsbench / web-interface-guidelines

web-interface-guidelines skill

/tasks/fix-visual-stability/environment/skills/web-interface-guidelines

This skill reviews UI components against Vercel's web interface guidelines to improve accessibility, performance, and visual stability.

npx playbooks add skill benchflow-ai/skillsbench --skill web-interface-guidelines

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.8 KB
---
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 | `<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`

Overview

This skill provides Vercel-aligned UI guidelines to review and build accessible, performant, and visually stable web interfaces. It focuses on practical checks for images, fonts, lists, animations, forms, and focus behavior. Use it to flag common anti-patterns and enforce pragmatic best practices.

How this skill works

The skill inspects component code and markup for common issues: missing image dimensions, improper font preloading, layout reads during render, and missing accessibility attributes. It also evaluates performance patterns like large un-virtualized lists, improper animations, and DOM read/write interleaving. The output highlights violations, explains impact (CLS, keyboard accessibility, jank), and recommends concrete fixes.

When to use it

  • Code reviews for UI components and pages
  • Pre-commit or CI checks focused on frontend quality
  • Accessibility audits and remediation sprints
  • Performance reviews targeting layout shift and render jank
  • Design-to-development handoffs to validate implementation

Best practices

  • Always set explicit width and height on <img> to prevent CLS and use loading="lazy" for below-fold images
  • Preload critical fonts with <link rel="preload" as="font"> and use font-display: swap
  • Virtualize large lists (>50 items) or use content-visibility: auto to avoid long renders
  • Avoid layout reads in render (getBoundingClientRect, offsetHeight/Width, scrollTop) and batch DOM reads/writes
  • Use semantic controls: <button> for actions, <a> for navigation, labels or aria-label for form controls and icon buttons
  • Respect prefers-reduced-motion, animate only transform/opacity, and never use transition: all

Example use cases

  • Reviewing a product list component that renders thousands of items to ensure virtualization
  • Auditing a landing page for CLS issues and missing image dimensions
  • Checking a modal or dialog for keyboard focus, focus-visible styling, and accessible labels
  • Validating font loading strategy and preconnect/preload for third-party CDNs
  • Ensuring form fields use correct input types, autocomplete, and label associations

FAQ

What counts as a critical image vs below-fold?

Critical images are visible on initial load or above the fold; they should be prioritized (priority or fetchpriority="high"). Below-fold images can use loading="lazy".

How do I handle decorative images?

Use alt="" for purely decorative images so assistive tech ignores them, while meaningful images need descriptive alt text.