UI Design System & Theming
Relevant source files
The following files were used as context for generating this wiki page:
The Monarch Design System is a comprehensive, token-driven framework designed to ensure visual consistency, accessibility (WCAG 2.2 AA), and performance across the Monarch Property Management platform. It serves as the single source of truth for all visual properties, including colors, typography, spacing, and motion, supporting both light and dark modes through a centralized theme provider.
The system is organized into three phases: foundational design tokens and theming (Phase 1), a token-driven component library (Phase 2), and advanced integrations for CMS, SEO, and analytics (Phase 3). This architecture allows for rapid development while maintaining high standards for accessibility and user experience across various user portals, including Admin, Vendor, and Property Manager interfaces.
Sources: src/design-system/README.md:1-25, src/pages/DesignSystemShowcase.tsx:28-40
Design Token Architecture
The design system utilizes a structured hierarchy of tokens defined in a centralized JSON specification. These tokens are mapped to CSS custom properties (variables) within the global styles, enabling real-time theme switching and consistent application of brand styles.
Core Token Categories
The system categorizes visual properties into several key areas:
- Colors: Brand-specific colors (Monarch Gold, Teal Green), semantic states (Success, Warning, Error, Info), and surface palettes for light/dark modes.
- Typography: Font families (Inter, Playfair Display, JetBrains Mono), sizing scales, and weights.
- Spacing & Layout: A standardized scale from 4px to 128px for consistent padding and margins.
- Elevation & Motion: Shadow systems for depth hierarchy and standardized easing functions for animations.
Sources: src/design-system/tokens.json, src/index.css:12-80, src/pages/admin/DesignTokens.tsx:140-180
Token Data Flow
The following diagram illustrates how design tokens propagate from the JSON source to the rendered UI components:
This flow ensures that any change in the central token file is reflected throughout the application, from CSS variables to Tailwind utility classes.
Sources: src/design-system/README.md:9-15, src/App.tsx:13-20
Theming Engine & Accessibility
The theming engine is built on top of next-themes, providing enhanced capabilities for system preference detection and manual overrides. It is critical for maintaining WCAG 2.2 AA compliance, specifically regarding color contrast ratios.
Color Contrast & Semantic States
All semantic colors are engineered to meet a minimum 4.5:1 contrast ratio. The system provides specific variants for different states:
| State | Light Mode Value | Dark Mode Value | Contrast Purpose |
|---|---|---|---|
| Primary (Gold) | hsl(32 82% 33%) | hsl(34 85% 55%) | Main Brand Identity |
| Success | hsl(155 60% 35%) | hsl(155 55% 45%) | Operations Completed |
| Warning | hsl(38 92% 50%) | hsl(38 90% 55%) | Action Review Required |
| Error | hsl(0 75% 55%) | hsl(0 70% 60%) | Operation Failure |
| Info | hsl(200 70% 50%) | hsl(200 65% 55%) | Additional Context |
Sources: src/index.css:15-60, src/pages/DesignSystemShowcase.tsx:110-140, src/pages/ThemePreview.tsx:50-80
Theme Switching Logic
The ThemeProvider manages the application state for visual modes. It detects the user's system preference (prefers-color-scheme) and handles manual toggles via the ThemeToggle component.
Component Library & Layout Patterns
Phase 2 of the design system implementation focuses on token-driven components. These components utilize the foundation established in Phase 1 to provide interactive, accessible UI elements.
Card & Surface System
The system employs various card variants (Default, Elevated, Neumorphic, Glass) that adapt to the active theme. These surfaces use CSS variables for borders, backgrounds, and shadows to maintain depth hierarchy.
- Neumorphic Cards: Utilize complex gradients and dual-shadowing (light and dark) to simulate physical depth.
- Glass Cards: Use
backdrop-filter: blur()and semi-transparent backgrounds for a modern overlay effect.
Sources: src/index.css:200-240, src/pages/DesignSystemShowcase.tsx:180-210
Layout Utilities
The system includes standardized layout utilities for consistent responsive behavior:
- Breakout Layouts: Utilities like
.breakout-full-widthallow content to ignore container constraints for immersive hero sections. - Safe Area Support: Utilities like
.safe-area-tophandle notched devices and mobile-specific padding.
Sources: src/index.css:750-780, src/index.css:830-860
Technical Implementation Details
Configuration Elements
The design system is integrated into the build process through several configuration files:
tokens.json: The source of truth for W3C-formatted design tokens.tailwind.config.ts: Maps tokens to Tailwind's theme extension.src/index.css: Defines the mapping between HSL values and CSS variables.
/* Example Variable Mapping from src/index.css */
:root {
--primary: 32 82% 33%;
--background: 40 25% 97%;
--radius: 0.75rem;
}
.dark {
--primary: 34 85% 55%;
--background: 0 0% 8%;
}
Sources: src/index.css:15-30, src/design-system/tokens.json
Summary
The UI Design System & Theming module provides a robust foundation for the Monarch Property Management platform. By utilizing a token-driven approach, the system ensures that accessibility (WCAG 2.2 AA) and brand consistency are maintained automatically across both light and dark modes. The layered architecture—from JSON tokens to CSS variables and React providers—enables a scalable and performant UI that supports diverse user roles and device types.
Sources: src/design-system/README.md:40-60, src/pages/DesignSystemShowcase.tsx:280-310