```
---
## Implementation Guide
### Setting Up the Color System
The color system is defined in `/src/styles/theme.css`. All colors use CSS custom properties (variables) for easy theming.
### Tailwind CSS Configuration
All color tokens are automatically available as Tailwind classes through the `@theme inline` directive:
```css
/* Colors are available as: */
bg-primary
text-primary-foreground
border-primary-container
bg-surface-container-low
bg-status-in-progress
bg-priority-high
/* etc. */
```
### Dark Mode Toggle
Toggle dark mode with JavaScript:
```tsx
// Toggle dark mode
document.documentElement.classList.toggle('dark');
// Set dark mode
document.documentElement.classList.add('dark');
// Set light mode
document.documentElement.classList.remove('dark');
// React component example
function DarkModeToggle() {
const [isDark, setIsDark] = useState(false);
const toggleDark = () => {
setIsDark(!isDark);
document.documentElement.classList.toggle('dark');
};
return (
);
}
```
### Using with shadcn Components
All shadcn/ui components work seamlessly with this color system. The legacy color tokens (card, popover, muted, accent, destructive) are mapped to appropriate MD3 colors.
```tsx
// shadcn Button component automatically uses the color system
```
---
## Accessibility
### Contrast Ratios
All color combinations meet **WCAG AA** standards:
- **Normal text**: Minimum 4.5:1 contrast ratio
- **Large text**: Minimum 3:1 contrast ratio
- **UI components**: Minimum 3:1 contrast ratio
### Color Blindness Considerations
The color system is designed to be distinguishable for users with common types of color blindness:
1. **Status colors** use distinct hues that remain distinguishable in deuteranopia, protanopia, and tritanopia
2. **Priority levels** use a progression from cool (low) to warm (high) colors
3. **All status indicators** should include text labels, not just color
### Best Practices for Accessibility
```tsx
// ✅ Good: Color + Icon + Text
Done
// ❌ Bad: Color only
// ✅ Good: Semantic HTML + ARIA
// ✅ Good: Status with aria-label
Blocked
```
---
## Best Practices
### 1. Use Surface Elevation for Depth
❌ **Don't use shadows for elevation**
```tsx
Card
```
✅ **Do use surface tones**
```tsx
Card
```
### 2. Use Container Variants for Lower Emphasis
❌ **Don't reduce opacity**
```tsx
```
✅ **Do use container variants**
```tsx
```
### 3. Consistent Status Colors
❌ **Don't use arbitrary colors**
```tsx
CompleteFinished
```
✅ **Do use semantic status colors**
```tsx
CompleteFinished
```
### 4. Semantic Color Usage
❌ **Don't use colors for decoration only**
```tsx
This is important information
```
✅ **Do use colors for their semantic meaning**
```tsx
Error: Failed to save changes
This is important information
```
### 5. Proper Text Contrast
❌ **Don't forget foreground colors**
```tsx
```
✅ **Do include foreground colors**
```tsx
```
### 6. Layering and Nesting
When nesting containers, move down the elevation scale:
```tsx
{/* Outer container */}
{/* Inner container - lower elevation */}
{/* Deepest container - lowest elevation */}
```
### 7. Interactive States
```tsx
// Buttons with hover states
// Cards with hover states
Interactive card
// Focus states (automatically handled by theme)
```
---
## Quick Reference
### Most Common Combinations
```tsx
// Primary button
bg-primary text-primary-foreground
// Secondary button
bg-secondary text-secondary-foreground
// Card
bg-card text-card-foreground border border-border
// Success message
bg-success-container text-success-container-foreground
// Warning banner
bg-warning text-warning-foreground
// Error alert
bg-error text-error-foreground
// Info panel
bg-info-container text-info-container-foreground
// Status badge - To Do
bg-status-todo text-white
// Status badge - In Progress
bg-status-in-progress text-white
// Status badge - Done
bg-status-done text-white
// Priority badge - High
bg-priority-high text-white
// Muted text
text-muted-foreground
// Border
border-border
```
---
## Additional Resources
### Color Tools
- **Material Theme Builder**: https://m3.material.io/theme-builder
- **Contrast Checker**: https://webaim.org/resources/contrastchecker/
- **Color Blind Simulator**: https://www.color-blindness.com/coblis-color-blindness-simulator/
### Documentation
- **Material Design 3**: https://m3.material.io
- **Tailwind CSS**: https://tailwindcss.com
- **shadcn/ui**: https://ui.shadcn.com
---
## Version History
### Version 1.0 (April 22, 2026)
- Initial color scheme based on Material Design 3
- Complete light and dark theme support
- Project management specific colors (status, priority)
- Full shadcn/ui compatibility
- Accessibility WCAG AA compliant
---
## Support
For questions or issues with the color system:
- Review the live demo in the application
- Check `COLOR_SYSTEM.md` for additional examples
- Refer to `/src/styles/theme.css` for color definitions
---
**End of Documentation**