UI/UX Design Principles

When to Apply

• 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

visual-

accessibility-

interaction-

responsive-

feedback-

ia-

performance-

consistency-

mobile-

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

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

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

Full Compiled Document

AGENTS.md