Web UI Best Practices

When invoked generally, apply these opinionated constraints for building better interfaces and for any UI work in this conversation.

When invoked with a file specified (i.e. web-ui-best-practices <file>), review the file against all constraints below and output:

1. violations (quote the exact line/snippet)
2. why it matters (1 short sentence)
3. a concrete fix (code-level suggestion)

Stack

• MUST use Tailwind CSS defaults unless custom values already exist or are explicitly requested
• MUST use motion/react (formerly framer-motion) when JavaScript animation is required
• SHOULD use tw-animate-css for entrance and micro-animations in Tailwind CSS
• MUST use cn utility (clsx + tailwind-merge) for class logic

Components

• MUST use accessible component primitives for anything with keyboard or focus behavior (Base UI, Radix, React-Aria)
• MUST use the project’s existing component primitives first
• NEVER mix primitive systems within the same interaction surface
• SHOULD prefer `Base UI` for new primitives if compatible with the stack
• MUST add an aria-label to icon-only buttons
• NEVER rebuild keyboard or focus behavior by hand unless explicitly requested

Interaction

• MUST use an AlertDialog for destructive or irreversible actions
• SHOULD use structural skeletons for loading states
• NEVER use h-screen, use h-dvh
• MUST show errors next to where the action happens
• NEVER block paste in input or textarea elements

Navigation & State

• SHOULD reflect UI state in the URL (filters, tabs, pagination, expanded panels via query params)
• MUST use <a> / <Link> for navigation (Cmd/Ctrl+click and middle-click should work)
• SHOULD deep-link stateful UI (if it uses useState, consider URL sync via nuqs or similar)
• MUST require confirmation or undo window for destructive actions (never immediate)

Touch & Interaction

• SHOULD set touch-action: manipulation on tappable controls (prevents double-tap zoom delay)
• SHOULD set -webkit-tap-highlight-color intentionally
• MUST use overscroll-behavior: contain in modals/drawers/sheets
• SHOULD during drag: disable text selection, inert on dragged elements
• SHOULD use autoFocus sparingly (desktop only, single primary input; avoid on mobile)

Animation

• NEVER add animation unless it is explicitly requested
• MUST animate only compositor props (transform, opacity)
• NEVER animate layout properties (width, height, top, left, margin, padding)
• SHOULD avoid animating paint properties (background, color) except for small, local UI (text, icons)
• SHOULD use ease-out on entrance
• NEVER exceed 200ms for interaction feedback
• MUST pause looping animations when off-screen
• SHOULD respect prefers-reduced-motion
• NEVER introduce custom easing curves unless explicitly requested
• SHOULD avoid animating large images or full-screen surfaces
• SHOULD never transition: all—list properties explicitly
• SHOULD set correct transform-origin
• SHOULD have animations be interruptible—respond to user input mid-animation

Typography

• MUST use text-balance for headings and text-pretty for body/paragraphs
• MUST use tabular-nums for data
• SHOULD use truncate or line-clamp for dense UI
• NEVER modify letter-spacing (tracking-*) unless explicitly requested
• SHOULD use … not ...
• SHOULD use curly quotes " " not straight "
• SHOULD have non-breaking spaces: 10 MB, ⌘ K, brand names
• SHOULD have loading states end with …: "Loading…", "Saving…"
• SHOULD use font-variant-numeric: tabular-nums for number columns/comparisons
• SHOULD have flex children need min-w-0 to allow text truncation
• SHOULD handle empty states—don't render broken UI for empty strings/arrays
• SHOULD consider that user-generated input fields may have short, average, and very long inputs

Layout

• MUST use a fixed z-index scale (no arbitrary z-*)
• SHOULD use size-* for square elements instead of w-* + h-*

Safe Areas & Layout

• MUST respect env(safe-area-inset-*) for full-bleed layouts and fixed elements on notched devices
• SHOULD avoid unwanted scrollbars (use overflow-x-hidden on containers and fix overflow at the source)
• SHOULD prefer flex/grid over JS measurement for layout

Dark Mode & Theming

• MUST set color-scheme: dark on <html> for dark themes (fixes scrollbars and native inputs)
• SHOULD set <meta name="theme-color"> to match the page background
• SHOULD set explicit background-color and color on native <select> (Windows dark mode)

Locale & i18n

• MUST use Intl.DateTimeFormat (no hardcoded date/time formats)
• MUST use Intl.NumberFormat (no hardcoded number/currency formats)
• SHOULD detect language via Accept-Language / navigator.languages, not IP

Hydration Safety

• MUST provide onChange for inputs with value (or use defaultValue for uncontrolled inputs)
• MUST guard date/time rendering against hydration mismatches (server vs client)
• SHOULD use suppressHydrationWarning only where truly needed

Hover & Interactive States

• SHOULD provide hover: states for buttons/links (visual feedback)
• SHOULD increase contrast for interactive states (hover/active/focus more prominent than rest)

Images

• MUST set explicit width and height on <img> (prevents CLS)
• SHOULD set loading="lazy" for below-fold images
• SHOULD set priority or fetchpriority="high" for above-fold critical images

Performance

• NEVER animate large blur() or backdrop-filter surfaces
• NEVER apply will-change outside an active animation
• NEVER use useEffect for anything that can be expressed as render logic
• SHOULD virtualize large lists (>50 items) (e.g. virtua or content-visibility: auto where appropriate)
• MUST avoid layout reads during render (getBoundingClientRect, offsetHeight, offsetWidth, scrollTop)
• SHOULD batch DOM reads/writes (avoid interleaving)
• SHOULD prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
• SHOULD add <link rel="preconnect"> for CDN/asset domains
• SHOULD preload critical fonts (<link rel="preload" as="font">) and use font-display: swap

Design

• NEVER use gradients unless explicitly requested
• NEVER use purple or multicolor gradients
• NEVER use glow effects as primary affordances
• SHOULD use Tailwind CSS default shadow scale unless explicitly requested
• MUST give empty states one clear next action
• SHOULD limit accent color usage to one per view
• SHOULD use existing theme or Tailwind CSS color tokens before introducing new ones

Design Direction (when aesthetics requested)

• MUST choose a clear aesthetic direction and execute consistently (e.g., brutally minimal, editorial, utilitarian, playful)
• SHOULD use deliberate typography (1 display + 1 body) and avoid accidental defaults; follow product font system when it exists
• SHOULD define theme/palette via CSS variables; use one dominant base + sharp accent
• SHOULD match implementation complexity to the aesthetic (minimal = restraint; maximal = elaborate but controlled)
• If motion is explicitly requested: prefer one cohesive high-impact sequence (load stagger, scroll reveal) over scattered micro-interactions
• SHOULD avoid cookie-cutter layout/component patterns; make 1-2 distinctive choices grounded in context

Content & Copy

• SHOULD use active voice ("Install the CLI" not "The CLI will be installed")
• SHOULD use specific button labels ("Save API Key" not "Continue")
• SHOULD write error messages with a fix/next step, not just the problem
• SHOULD write in second person; avoid first person
• SHOULD use & over "and" where space-constrained

Anti-patterns (flag these)

• user-scalable=no or maximum-scale=1 disabling zoom
• onPaste with preventDefault
• transition: all
• outline-none without a focus-visible replacement
• Inline onClick navigation without <a> / <Link>
• <div> / <span> with click handlers (use <button>)
• Images without dimensions
• Large arrays .map() without virtualization
• Form inputs without labels
• Icon buttons without aria-label
• Hardcoded date/number formats (use Intl.*)
• autoFocus without clear justification

Rules if not found in primitives

The below rules apply if the pattern is either explicitly requested or not found in the primitive itself already.

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)
• Decorative icons need aria-hidden="true"
• Async updates (toasts, validation) need aria-live="polite"
• Use semantic HTML (<button>, <a>, <label>, <table>) before ARIA
• Headings hierarchical <h1>–<h6>; include skip link for main content
• scroll-margin-top on heading anchors

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)
• Group focus with :focus-within for compound controls

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)
• Disable spellcheck on emails, codes, usernames (spellCheck={false})
• Checkboxes/radios: label + control share single hit target (no dead zones)
• Submit button stays enabled until request starts; spinner during request
• Errors inline next to fields; focus first error on submit
• Placeholders end with … and show example pattern
• autocomplete="off" on non-auth fields to avoid password manager triggers
• Warn before navigation with unsaved changes (beforeunload or router guard)