UI/UX Best Practices Frontend Design

Comprehensive UI/UX and frontend design best practices guide. Contains 42 rules across 8 categories, prioritized by impact to guide accessible, performant, and user-friendly interface development.

When to Apply

Reference these guidelines when:

• •Structuring HTML for accessibility and semantics
• •Writing CSS for responsive layouts and visual hierarchy
• •Optimizing images and fonts for Core Web Vitals
• •Designing forms with proper validation and error handling
• •Adding animations and interactive elements

Rule Categories by Priority

Quick Reference

1. Accessibility & WCAG Compliance (CRITICAL)

• •access-semantic-html - Use semantic HTML elements for screen readers
• •access-keyboard-navigation - Ensure full keyboard navigation
• •access-focus-indicators - Provide visible focus indicators
• •access-alt-text - Provide meaningful alt text for images
• •access-aria-labels - Use ARIA labels for icon-only controls
• •access-target-size - Ensure minimum touch target size (24×24px)
• •access-heading-hierarchy - Maintain logical heading hierarchy

2. Core Web Vitals Optimization (CRITICAL)

• •cwv-optimize-lcp - Optimize Largest Contentful Paint under 2.5s
• •cwv-minimize-cls - Minimize Cumulative Layout Shift under 0.1
• •cwv-improve-inp - Improve Interaction to Next Paint under 200ms
• •cwv-responsive-images - Serve responsive images with srcset
• •cwv-lazy-load-offscreen - Lazy load offscreen images and iframes
• •cwv-critical-css - Inline critical CSS and defer the rest

3. Visual Hierarchy & Layout (HIGH)

• •layout-visual-hierarchy - Establish clear visual hierarchy
• •layout-whitespace - Use whitespace to improve readability
• •layout-f-pattern - Design for F-pattern reading behavior
• •layout-grid-system - Use a consistent grid system
• •layout-single-cta - Limit to one primary CTA per screen
• •layout-proximity-grouping - Group related elements with proximity

4. Responsive & Mobile-First Design (HIGH)

• •resp-mobile-first - Design mobile-first with min-width queries
• •resp-fluid-typography - Use fluid typography with clamp()
• •resp-container-queries - Use container queries for components
• •resp-touch-targets - Size touch targets for mobile (44×44px)
• •resp-viewport-meta - Configure viewport meta tag correctly

5. Typography & Font Loading (MEDIUM-HIGH)

• •typo-font-display - Use font-display to control loading behavior
• •typo-preload-fonts - Preload critical web fonts
• •typo-readable-line-length - Constrain line length (45-75ch)
• •typo-line-height - Set appropriate line height (1.5-1.7)
• •typo-system-font-stack - Use system font stack for UI elements

6. Color & Contrast (MEDIUM)

• •color-contrast-ratio - Meet WCAG contrast ratio requirements (4.5:1)
• •color-not-only-indicator - Never use color alone to convey information
• •color-dark-mode - Support dark mode with prefers-color-scheme
• •color-semantic-palette - Use semantic color names in design tokens

7. Forms & Validation UX (MEDIUM)

• •form-inline-validation - Use inline validation after field blur
• •form-error-messages - Write actionable error messages
• •form-labels-above - Place labels above input fields
• •form-input-types - Use correct HTML input types for mobile
• •form-autocomplete - Enable browser autocomplete with correct attributes

8. Animation & Performance (LOW-MEDIUM)

• •anim-gpu-properties - Animate only GPU-accelerated properties
• •anim-will-change - Use will-change sparingly for animation hints
• •anim-reduced-motion - Respect user motion preferences
• •anim-duration-easing - Use appropriate animation duration and easing

How to Use

Read individual reference files for detailed explanations and code examples:

• •Section definitions - Category structure and impact levels
• •Rule template - Template for adding new rules
• •Example: access-semantic-html

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md