Web Interface Guidelines

When to Load

• Trigger: UI audit, accessibility checks, responsive design review, UX best practices evaluation
• Skip: Backend-only work with no UI components

Self-contained guidelines for reviewing web interfaces. Apply these rules when auditing UI code.

Output Format

Report findings as:

file:line — [RULE_ID] description

Example:

src/Button.tsx:12 — [A11Y-01] Missing aria-label on icon button

1. Accessibility (A11Y)

A11Y-01: Semantic HTML

• Use

  <button>

  for actions,

  <a>

  for navigation,

  <input>

  for data entry
• Never use

  <div onClick>

  or

  <span onClick>

  for interactive elements
• Use

  <nav>

  ,

  <main>

  ,

  <aside>

  ,

  <header>

  ,

  <footer>

  for landmarks

A11Y-02: ARIA Labels

• All interactive elements need accessible names
• Icon-only buttons MUST have

  aria-label

• Form inputs MUST have associated

  <label>

  or

  aria-label

• Images need

  alt

  text (decorative images:

  alt=""

  )

A11Y-03: Keyboard Navigation

• All interactive elements must be reachable via Tab
• Custom components need proper

  role

  ,

  tabIndex

  , and key handlers
• Focus must be visible (never

  outline: none

  without replacement)
• Modal/dialog must trap focus and return focus on close

A11Y-04: Color & Contrast

• Text contrast ratio: 4.5:1 minimum (3:1 for large text)
• Never use color alone to convey meaning (add icons, text, patterns)
• Ensure UI is usable at 200% zoom

A11Y-05: Screen Readers

• Dynamic content changes need

  aria-live

  regions
• Loading states need

  aria-busy="true"

• Error messages linked to inputs via

  aria-describedby

2. Performance (PERF)

PERF-01: Image Optimization

• Use

  next/image

  or responsive images with

  srcset

• Specify

  width

  and

  height

  to prevent layout shift
• Lazy load below-fold images:

  loading="lazy"

• Use WebP/AVIF with fallback

PERF-02: Bundle Size

• No full library imports:

  import { Button } from 'lib'

  not

  import lib

• Tree-shake CSS: use CSS modules or Tailwind purge
• Lazy load routes and heavy components:

  React.lazy()

  or dynamic imports

PERF-03: Rendering

• Avoid layout thrashing: don't read then write DOM in loops
• Use

  will-change

  sparingly (only for known animations)
• Prefer CSS animations over JS animations
• Use

  transform

  and

  opacity

  for 60fps animations (compositor-only)

PERF-04: Core Web Vitals

• LCP < 2.5s: Optimize largest image/text, preload critical resources
• FID/INP < 200ms: No long tasks on main thread, defer non-critical JS
• CLS < 0.1: Set dimensions on images/embeds, no injected content above fold

3. Responsive Design (RD)

RD-01: Mobile First

• Base styles for mobile, then

  @media (min-width)

  for larger screens
• Touch targets minimum 44x44px
• No horizontal scroll on any viewport

RD-02: Fluid Layout

• Use

  rem

  /

  em

  for typography, not

  px

• Use

  clamp()

  for fluid typography:

  font-size: clamp(1rem, 2.5vw, 2rem)

• Flex/Grid over fixed widths
• Max content width:

  max-width: 65ch

  for readability

RD-03: Breakpoints

• Don't target devices, target content breakpoints
• Common: 640px (sm), 768px (md), 1024px (lg), 1280px (xl)
• Test at 320px, 375px, 768px, 1024px, 1440px, 1920px

4. Component Patterns (CP)

CP-01: Forms

• Show validation errors inline, next to the field
• Use

  type="email"

  ,

  type="tel"

  ,

  inputmode="numeric"

  for mobile keyboards
• Disable submit button during submission (prevent double-submit)
• Preserve form state on error (don't clear fields)

CP-02: Loading States

• Show skeleton screens over spinners for content areas
• Indicate progress for long operations (progress bar > spinner)
• Disable interactive elements during loading
• Set

  aria-busy="true"

  on loading containers

CP-03: Error States

• Always show actionable error messages ("Try again" button, not just "Error")
• Don't show technical errors to users (log internally, show friendly message)
• Error boundaries for React component trees
• Retry logic for network failures

CP-04: Empty States

• Never show blank pages — provide helpful empty states
• Include call-to-action: "No items yet. Create your first item."
• Use illustrations sparingly (they add bundle weight)

CP-05: Modals & Dialogs

• Use

  <dialog>

  element or proper

  role="dialog"

• Trap focus within modal
• Close on Escape key and backdrop click
• Return focus to trigger element on close
• Prevent body scroll while open

5. CSS Practices (CSS)

CSS-01: Specificity

• Prefer class selectors over ID or element selectors
• Avoid

  !important

  (use specificity or cascade layers)
• Use CSS custom properties for theming
• One direction for spacing: prefer

  margin-bottom

  over

  margin-top

CSS-02: Layout

• Use Flexbox for 1D layout, Grid for 2D layout
• Avoid

  position: absolute

  for layout (use for overlays only)
• Use

  gap

  over margins between flex/grid children
• Use

  min-height: 100dvh

  (not

  100vh

  ) for full-height layouts

CSS-03: Dark Mode

• Use

  prefers-color-scheme

  media query
• Define all colors as CSS custom properties
• Test both modes — check contrast in both
• Don't just invert colors — design intentionally for dark mode

6. Security (SEC)

SEC-01: Content Security

• Never use

  dangerouslySetInnerHTML

  without sanitization
• Sanitize user-generated content before rendering
• Use

  rel="noopener noreferrer"

  on external links with

  target="_blank"

SEC-02: Forms & Input

• CSRF protection on all forms
• Rate limit form submissions
• Validate on both client AND server

7. Internationalization (I18N)

I18N-01: Text

• Don't hardcode strings — use i18n library or constants
• Support RTL layouts: use

  logical properties

  (

  margin-inline-start

  over

  margin-left

  )
• Don't truncate text — designs must accommodate 40% text expansion
• Use

  lang

  attribute on

  <html>

  tag

Review Checklist

When auditing a file, check in this order (CRITICAL first):

1. CRITICAL: A11Y-01, A11Y-02, SEC-01 — Semantic HTML, ARIA, XSS prevention
2. HIGH: PERF-04, A11Y-03, CP-01 — Core Web Vitals, keyboard, forms
3. MEDIUM: RD-01, CSS-02, CP-02, CP-03 — Responsive, layout, loading/errors
4. LOW: CSS-03, I18N-01, CP-04 — Dark mode, i18n, empty states