Web Interface Guidelines

Reviews UI code for compliance with web interface best practices, auditing code for 100+ rules covering accessibility, performance, and UX.

When to Apply

• Reviewing UI components for accessibility compliance
• Auditing web pages against best practices
• Checking UX patterns and user interactions
• Improving form validation and error handling
• Optimizing animations and transitions

Core Categories

Category	Focus Areas
Accessibility	Semantic HTML, ARIA, keyboard navigation, screen readers
Performance	Loading, rendering, animations, lazy loading
UX Patterns	Forms, feedback, error handling, navigation
Visual Design	Typography, spacing, color contrast, responsiveness
Interactions	Hover states, focus management, touch targets

Key Guidelines

Accessibility (A11Y)

Semantic HTML:

• Use

  <button>

  for actions,

  <a>

  for navigation
• Use heading hierarchy (

  h1

  →

  h2

  →

  h3

  )
• Use

  <nav>

  ,

  <main>

  ,

  <article>

  ,

  <aside>

  landmarks

Keyboard Navigation:

• All interactive elements must be focusable
• Visible focus indicators (never

  outline: none

  without replacement)
• Logical tab order following visual flow
• Escape key closes modals/dropdowns

ARIA:

• Use ARIA only when native HTML insufficient

• aria-label

  for icon-only buttons

• aria-expanded

  for expandable content

• aria-live

  for dynamic content updates

Color & Contrast:

• Minimum 4.5:1 contrast ratio for text
• Don't convey information by color alone
• Support reduced-motion preferences

Forms & Validation

Labels & Instructions:

• Every input needs a visible

  <label>

• Associate labels with

  htmlFor

  /

  id

• Provide clear placeholder text as hints, not labels

Error Handling:

• Show errors inline near the field
• Use

  aria-invalid

  and

  aria-describedby

• Don't clear form on error
• Focus first error field on submit

Input Patterns:

<div className="field">
  <label htmlFor="email">Email</label>
  <input
    id="email"
    type="email"
    aria-invalid={!!error}
    aria-describedby={error ? "email-error" : undefined}
  />
  {error && <span id="email-error" role="alert">{error}</span>}
</div>

Performance

Loading:

• Show skeleton loaders, not spinners
• Progressive loading for large content
• Lazy load below-fold images
• Preload critical assets

Animations:

• Use CSS transforms and opacity (GPU-accelerated)
• Respect

  prefers-reduced-motion

• Keep animations under 300ms for feedback
• Use

  will-change

  sparingly

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Interactive Elements

Buttons & Links:

• Minimum 44x44px touch targets
• Clear hover/focus/active states
• Disabled state visually distinct
• Loading states for async actions

Focus Management:

• Trap focus in modals
• Return focus after modal closes
• Skip links for keyboard users

Responsive Design

• Mobile-first approach
• Fluid typography with

  clamp()

• Touch-friendly spacing on mobile
• Test at common breakpoints (320, 768, 1024, 1440)

Audit Checklist

When reviewing UI code, verify:

1. All images have

   alt

   text
2. Form inputs have associated labels
3. Color contrast meets WCAG 2.1 AA
4. Interactive elements keyboard accessible
5. Focus indicators visible
6. Animations respect reduced-motion
7. Error messages are descriptive
8. Touch targets are 44px minimum
9. Headings follow hierarchy
10. ARIA used correctly (not overused)

Output Format

Report findings as:

file.tsx:42 - Missing alt text on image
file.tsx:67 - Button missing accessible name
file.tsx:89 - Low contrast ratio (2.1:1, needs 4.5:1)