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