---
name: web-design-best-practices
description: Use when designing or implementing a UI from scratch, or reviewing one for quality. Modern web design/UX conventions to apply by default, not just when explicitly asked for "modern design."
---

# Web Design Best Practices

## Visual hierarchy and typography

- One clear primary action per screen/section — a page with 4 equally-
  weighted CTAs has no CTA.
- Type scale: use a consistent, limited set of sizes (a modular scale,
  not ad-hoc pixel values scattered through the CSS). Headline/body/
  caption is usually enough tiers for a marketing page.
- Line length: body text at 60-75 characters per line max — full-width
  text on a wide viewport is hard to read, constrain with `max-width`.
- Line height: 1.4-1.6 for body text, tighter (1.05-1.2) for large
  display headlines.

## Spacing and layout

- Consistent spacing scale (e.g. 4px/8px increments), not arbitrary
  margins per element — this is what makes a layout feel "designed"
  rather than assembled ad-hoc.
- Generous whitespace around primary content — cramped layouts read as
  low-quality regardless of the actual visual polish of individual
  elements.
- Responsive by default: design/build mobile and desktop simultaneously,
  not desktop-first-then-retrofit. A single-column collapse at a sensible
  breakpoint (usually 600-900px) is the baseline, not an afterthought.

## Color and contrast

- A real design-token system (CSS custom properties for the brand
  palette), not hardcoded hex values scattered through templates —
  changing the brand color should be a one-line change, not a
  find-and-replace across every file.
- Every accent/brand color needs a check against WCAG contrast ratios
  where it's used for text or meaningful UI — see the
  `web-accessibility` skill.

## Motion

- Subtle, purposeful, and **always gated behind
  `prefers-reduced-motion`** — animation should communicate state change
  (a hover, a loading state, an entrance), not be decorative for its own
  sake. Anything that loops indefinitely (a marquee, a pulsing dot)
  especially needs the reduced-motion escape hatch.

## Forms

- Label every input (visually, not just via `placeholder` — placeholder
  text disappears the moment the user starts typing and isn't a
  substitute for a real `<label>`).
- Inline validation feedback near the field it applies to, not just a
  generic error banner at the top of the form.
- Clear loading/success/error states on submit — a button that just sits
  there with no visual change while a request is in flight reads as
  broken.

## Before calling a design "modern" or "done"

Actually look at it — screenshot it (real browser, real viewport sizes:
mobile ~390px, desktop ~1280px+) rather than trusting that correct CSS
implies correct visual result. A CSS bug that's invisible when reading
the source is often immediately obvious in a screenshot.