Design Guidelines
Principles, rules, and best practices for building consistent, accessible, and performant interfaces with Retailys UI Design Framework.
Design Principles
Core values that guide every design and engineering decision.
Consistency
Maintain visual and behavioral consistency across all interfaces. Reuse existing components and patterns rather than creating new ones.
Accessibility
Build for everyone. All components use React Aria for keyboard navigation, screen reader support, and WCAG 2.1 AA compliance.
Responsiveness
Design mobile-first. Every component and layout adapts seamlessly from 320px mobile to 2560px ultrawide displays.
Performance
Keep bundles small and interactions fast. Use code splitting, lazy loading, and efficient re-renders.
Color Usage
Guidelines for applying colors consistently across the design system.
Semantic Color Roles
Dark Mode
The design system uses CSS custom properties (--color-*) that automatically adapt between light and dark themes. Use semantic color classes (bg-primary, text-secondary, border-secondary) rather than hardcoded colors.
Typography Rules
Consistent type hierarchy for readability and visual rhythm.
Hierarchy
Font Weights
font-semibold (600)Headings, buttons, labelsfont-medium (500)Navigation items, sub-headingsfont-normal (400)Body text, descriptionsSpacing System
A consistent spatial scale based on a 4px grid.
Scale
Conventions
p-4 (16px) for cards, p-6 (24px) for sections, p-8 (32px) for page containers
gap-2 (8px) tight, gap-4 (16px) standard, gap-6 (24px) spacious, gap-8 (32px) sections
px-4 md:px-8 (16px → 32px responsive)
Component Composition
Recurring layout recipes for common UI patterns.
Common Patterns
Form Layout
Stack inputs vertically with gap-4. Use label + input + hint pattern. Group related fields in fieldsets.
Card Layout
rounded-xl border border-secondary bg-primary p-6. Use FeaturedIcon for visual anchor.
Table Page
TableCard.Header for title/description/actions → Table with sortable headers → Pagination footer.
Dashboard Grid
Stats row (grid-cols-4) → Charts row (grid-cols-2) → Detail table below.
Accessibility
Building interfaces that work for everyone.
React Aria Foundation
All interactive components are built on React Aria Components, providing out-of-the-box accessibility including keyboard navigation, focus management, screen reader announcements, and ARIA attributes.
Key Patterns
- All form fields have associated labels (visible or aria-label)
- Focus rings use outline-focus-ring utility
- Modals trap focus and restore on close
- Tooltips are announced on focus, not just hover
- Color is never the sole indicator of state (always paired with text/icons)
Dark Mode
Seamless light and dark theming across every component.
Implementation
Guidelines
Responsive Design
Adapting layouts across all screen sizes.
Breakpoints
| Token | Min-Width | Description |
|---|---|---|
sm | 640px | Mobile landscape |
md | 768px | Tablet |
lg | 1024px | Desktop |
xl | 1280px | Large desktop |
2xl | 1536px | Ultra-wide |