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

Priority	Category	Impact	Prefix
1	Visual Design	HIGH	visual-
2	Accessibility	CRITICAL	accessibility-
3	Interaction Design	HIGH	interaction-
4	Responsive Design	HIGH	responsive-
5	User Feedback	MEDIUM-HIGH	feedback-
6	Information Architecture	MEDIUM	ia-
7	Performance Optimization	MEDIUM	performance-
8	Consistency	MEDIUM	consistency-
9	Mobile-First Design	HIGH	mobile-
10	Testing and Iteration	MEDIUM	testing-

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