name: web-design-guidelines description: Review UI code for compliance with web interface best practices. Audits code for 100+ rules covering accessibility, performance, and UX. Use when asked to review UI code, check accessibility, audit design, or check site against best practices. metadata: author: vercel version: "1.0.0" license: MIT

Web Design Guidelines

Comprehensive web interface best practices covering accessibility, performance, and UX. Use when reviewing UI code for compliance with web standards.

When to Use

• "Review my UI"
• "Check accessibility"
• "Audit design"
• "Review UX"
• "Check my site against best practices"

Categories

1. Accessibility (a11y)

Semantic HTML:

• Use <button> for buttons, not <div> with onClick
• Use <a> for links, not <span> with onClick
• Use proper heading hierarchy (h1 → h2 → h3)
• Use <label> with form inputs

ARIA Labels:

• Add aria-label to icon-only buttons
• Use aria-describedby for additional context
• Add aria-hidden to decorative icons
• Use aria-expanded for toggle states

Keyboard Navigation:

• Ensure all interactive elements are focusable
• Add visible focus indicators
• Support Tab and arrow key navigation
• Implement proper tab order

Screen Readers:

• Add descriptive alt text for images
• Use role attributes where needed
• Announce dynamic content changes
• Provide skip-to-content links

2. Focus States

Visible Focus:

/* ✅ GOOD - visible focus */
:focus-visible {
  outline: 2px solid var(--focus-color);
  outline-offset: 2px;
}

/* Hide default, add custom */
:focus {
  outline: none;
}
:focus-visible {
  outline: 2px solid blue;
}

Focus Patterns:

• Use :focus-visible to avoid always-visible focus
• Ensure sufficient contrast for focus indicators
• Test with keyboard navigation only

3. Forms

Autocomplete:

<!-- ✅ GOOD - autocomplete attributes -->
<input type="email" name="email" autocomplete="email" />
<input type="tel" name="phone" autocomplete="tel" />
<input type="text" name="country" autocomplete="country" />

Validation:

• Provide clear error messages
• Indicate required fields
• Validate on blur, not every keystroke
• Show success state for valid inputs

Labels:

<!-- ✅ GOOD - explicit labels -->
<label for="email">Email</label>
<input id="email" type="email" />

<!-- ✅ GOOD - implicit labels -->
<label>
  Email
  <input type="email" name="email" />
</label>

4. Animation

Prefers Reduced Motion:

/* ✅ GOOD - respect motion preferences */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

Transforms:

• Use transform and opacity for animations (GPU-accelerated)
• Avoid animating width/height (causes reflow)
• Use will-change sparingly

5. Typography

Curly Quotes:

<!-- ❌ BAD - straight quotes -->
<p>"Hello," she said.</p>

<!-- ✅ GOOD - curly quotes -->
<p>"Hello," she said.</p>

Ellipsis:

/* ✅ GOOD - proper ellipsis */
.truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

Tabular Numbers:

/* ✅ GOOD - for data tables */
.tabular-nums {
  font-variant-numeric: tabular-nums;
}

6. Images

Dimensions:

<!-- ✅ GOOD - include dimensions -->
<img
  src="/hero.jpg"
  alt="Hero image"
  width="1200"
  height="600"
  loading="lazy"
/>

<!-- ✅ GOOD - Next.js Image component -->
<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1200}
  height={600}
/>

Lazy Loading:

<!-- ✅ GOOD - lazy load below fold -->
<img src="hero.jpg" loading="eager" />
<img src="content.jpg" loading="lazy" />

Alt Text:

<!-- ❌ BAD - decorative alt text -->
<img src="decorative.jpg" alt="decorative flower" />

<!-- ✅ GOOD - empty alt for decorative -->
<img src="decorative.jpg" alt="" />

<!-- ✅ GOOD - descriptive alt -->
<img src="chart.jpg" alt="Bar chart showing 50% increase" />

7. Performance

Virtualization:

• Use virtual lists for long lists (100+ items)
• Libraries: react-window, react-virtual

Layout Thrashing:

// ❌ BAD - causes reflow
elements.forEach(el => {
  const height = el.offsetHeight // read
  el.style.height = height + 'px' // write
})

// ✅ GOOD - batch reads then writes
const heights = elements.map(el => el.offsetHeight) // all reads
elements.forEach((el, i) => {
  el.style.height = heights[i] + 'px' // all writes
})

Preconnect:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="dns-prefetch" href="https://api.example.com" />

8. Navigation & State

URL Reflects State:

• Update URL for filter changes
• Use query params for shareable state
• Support browser back/forward

Deep Linking:

• Every view should have a URL
• Support direct links to content
• Handle query parameters properly

9. Dark Mode & Theming

Color Scheme:

<meta name="color-scheme" content="dark light" />

CSS Variables:

:root {
  --bg: #ffffff;
  --fg: #000000;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #000000;
    --fg: #ffffff;
  }
}

body {
  background: var(--bg);
  color: var(--fg);
}

10. Touch & Interaction

Touch Action:

/* ✅ GOOD - prevent double-tap zoom on buttons */
button {
  touch-action: manipulation;
}

/* ✅ GOOD - custom gestures */
.swipeable {
  touch-action: pan-x;
}

Tap Highlight:

/* Remove tap highlight color */
* {
  -webkit-tap-highlight-color: transparent;
}

Target Size:

• Minimum touch target: 44×44px
• Spacing between adjacent targets: 8px

11. Locale & i18n

Date Formatting:

// ✅ GOOD - locale-aware dates
new Intl.DateTimeFormat('en-US').format(date)

Number Formatting:

// ✅ GOOD - locale-aware numbers
new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).format(amount)

Quick Checklist

Before marking UI as complete:

• All images have alt text (or empty alt for decorative)
• All buttons have aria-label if icon-only
• All inputs have associated labels
• Focus indicators are visible
• Reduced motion is respected
• Images have dimensions
• Above-fold images use loading="eager"
• Below-fold images use loading="lazy"
• Color contrast meets WCAG AA (4.5:1 for text)
• Touch targets are at least 44×44px
• URL reflects current view state
• Dark mode is supported (or color-scheme meta tag)

Related Skills

• vercel-react-best-practices - React/Next.js performance
• react-native-guidelines - Mobile-specific guidelines

Resources

• Web.dev Accessibility
• A11y Project Checklist
• MDN Web Accessibility