frontend-ui-ux

Frontend UI/UX Development Guide

When working on frontend code, follow these principles:

Component Architecture

• Single Responsibility: Each component does one thing well
• Composition over inheritance: Build complex UIs from simple, composable pieces
• Props down, events up: Data flows down, actions flow up
• Colocation: Keep styles, tests, and types near their component

Responsive Design

• Mobile-first: Start with the smallest breakpoint, enhance up
• Fluid layouts: Use relative units (rem, %, vw/vh) over fixed pixels
• Breakpoint strategy: Match the project's existing breakpoints
• Touch targets: Minimum 44x44px for interactive elements

Accessibility (A11y)

• Semantic HTML: Use proper elements (button, nav, main, aside)
• ARIA when needed: Only when semantic HTML isn't sufficient
• Keyboard navigation: All interactive elements must be keyboard-accessible
• Color contrast: WCAG AA minimum (4.5:1 for text, 3:1 for large text)
• Focus management: Visible focus indicators, logical tab order
• Screen readers: Test with VoiceOver/NVDA, use aria-label/aria-describedby

State Management

• Local state first: useState/useReducer before reaching for global state
• Server state: Use the project's data fetching library (React Query, SWR, etc.)
• URL state: Filters, pagination, tabs → URL parameters
• Form state: Use the project's form library (React Hook Form, Formik, etc.)
• Global state: Only for truly app-wide concerns (theme, auth, locale)

Visual Consistency

• Design tokens: Use the project's existing variables/tokens for colors, spacing, typography
• Spacing scale: Follow the project's spacing system (don't use arbitrary values)
• Typography: Use existing type scale, don't create new sizes
• Icons: Use the project's icon system/library

Performance

• Lazy loading: Code-split routes and heavy components
• Image optimization: Proper formats (WebP/AVIF), srcset, lazy loading
• Bundle awareness: Check impact of new dependencies
• Render optimization: Memoize expensive computations, avoid unnecessary re-renders

Testing

• Component tests: Render, interact, assert on DOM output
• Visual regression: Screenshot tests for critical UI
• Accessibility tests: Automated a11y checks (axe-core)
• User flow tests: E2E tests for critical paths