UI/UX Design Principles

Comprehensive guide for UI and UX design principles in software development, covering visual design, interaction patterns, accessibility, performance, and responsive design.

When to Apply

Reference these guidelines when:

• Designing new UI components or interfaces
• Implementing user interactions and navigation
• Ensuring accessibility compliance (WCAG 2.1 AA)
• Creating responsive and mobile-first layouts
• Optimizing user feedback and error handling
• Building design systems and maintaining consistency
• Testing and iterating on user experience

Rule Categories by Priority

Quick Reference

1. Visual Design (HIGH)

• visual-hierarchy – Establish clear visual hierarchy
• visual-color-palette – Use cohesive color palette
• visual-typography – Effective typography for readability
• visual-contrast – Maintain WCAG 2.1 AA contrast
• visual-style-consistency – Consistent style across application

2. Accessibility (CRITICAL)

• accessibility-wcag – Follow WCAG guidelines
• accessibility-semantic-html – Use semantic HTML
• accessibility-alt-text – Provide alt text for images
• accessibility-keyboard-navigation – Ensure keyboard navigability
• accessibility-assistive-tech – Test with assistive technologies

3. Interaction Design (HIGH)

• interaction-navigation – Intuitive navigation patterns
• interaction-familiar-components – Use familiar UI components
• interaction-cta – Clear calls-to-action
• interaction-animations – Judicious use of animations
• interaction-responsive – Cross-device compatibility

4. Responsive Design (HIGH)

• responsive-fluid-layouts – Use relative units and flexible layouts
• responsive-media-queries – Breakpoints for different screen sizes
• responsive-images – Responsive images with srcset
• responsive-typography – Relative units for typography
• responsive-content-priority – Prioritize content for mobile

5. User Feedback (MEDIUM-HIGH)

• feedback-mechanisms – Clear feedback for user actions
• feedback-loading – Loading indicators for async operations
• feedback-errors – Clear error messages and recovery
• feedback-analytics – Track user behavior

6. Information Architecture (MEDIUM)

• ia-organization – Logical content organization
• ia-labeling – Clear labeling and categorization
• ia-search – Effective search functionality
• ia-sitemap – Visualize structure with sitemap

7. Performance Optimization (MEDIUM)

• performance-images – Optimize images and assets
• performance-lazy-loading – Lazy load non-critical resources
• performance-code-splitting – Code splitting for initial load
• performance-core-web-vitals – Monitor Core Web Vitals

8. Consistency (MEDIUM)

• consistency-design-system – Develop and adhere to design system
• consistency-terminology – Consistent terminology
• consistency-positioning – Consistent element positioning
• consistency-visual – Visual consistency across sections

9. Mobile-First Design (HIGH)

• mobile-first-approach – Design mobile first, scale up
• mobile-touch-targets – Touch-friendly interface elements
• mobile-gestures – Implement common gestures
• mobile-thumb-zones – Consider thumb zones

10. Testing and Iteration (MEDIUM)

• testing-ab – A/B testing for critical decisions
• testing-heatmaps – Use heatmaps and session recordings
• testing-user-feedback – Gather and incorporate feedback
• testing-iteration – Iterate based on data

How to Use

Read individual rule files for detailed explanations and code examples:

rules/visual-hierarchy.md
rules/accessibility-wcag.md
rules/responsive-fluid-layouts.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

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