Design System
Design system and UI component guidelines for the AI Store application.
Color Palette
The color system uses HSL (Hue Saturation Lightness) format for all colors, defined as CSS variables in app/styles/theme.css. All colors should be accessed via CSS variables or Tailwind classes.
Primary Colors
--primary: 221.2 83.2% 53.3%; /* Primary brand color */
--primary-foreground: 210 40% 98%; /* Text on primary background */
Usage:
- Tailwind:
bg-primary,text-primary-foreground - CSS:
hsl(var(--primary)),hsl(var(--primary-foreground)) - Legacy:
hsl(var(--color-primary))
Secondary Colors
--secondary: 210 40% 96.1%; /* Secondary background */
--secondary-foreground: 222.2 47.4% 11.2%; /* Text on secondary */
Usage:
- Tailwind:
bg-secondary,text-secondary-foreground - CSS:
hsl(var(--secondary)),hsl(var(--secondary-foreground)) - Legacy:
hsl(var(--color-secondary))
Semantic Colors
--success: 160 84% 39%; /* Success/Green */
--success-foreground: 210 40% 98%; /* Text on success */
--warning: 38 96% 50%; /* Warning/Amber */
--warning-foreground: 210 40% 98%; /* Text on warning */
--info: 217 91% 60%; /* Info/Blue */
--info-foreground: 210 40% 98%; /* Text on info */
--destructive: 0 84.2% 60.2%; /* Error/Red */
--destructive-foreground: 210 40% 98%; /* Text on error */
Usage:
- Tailwind:
bg-success,text-destructive,bg-warning,bg-info - CSS:
hsl(var(--success)),hsl(var(--destructive)), etc. - Legacy:
hsl(var(--color-success)),hsl(var(--color-error)), etc.
Neutral Colors
--background: 220 14% 96%; /* Main background */
--foreground: 222.2 84% 4.9%; /* Main text */
--card: 0 0% 100%; /* Card background */
--card-foreground: 222.2 84% 4.9%; /* Card text */
--muted: 210 40% 96.1%; /* Muted background */
--muted-foreground: 215.4 16.3% 46.9%; /* Muted text */
--border: 214.3 31.8% 91.4%; /* Border color */
Usage:
- Tailwind:
bg-background,text-foreground,bg-card,border-border - CSS:
hsl(var(--background)),hsl(var(--foreground)), etc. - Legacy:
hsl(var(--color-bg)),hsl(var(--color-text)), etc.
Sidebar Colors
--sidebar-bg: 220 46% 11%; /* Sidebar background */
--sidebar-text: 220 14% 91%; /* Sidebar text */
--sidebar-text-muted: 215 13% 65%; /* Sidebar muted text */
Usage:
- CSS:
hsl(var(--sidebar-bg)),hsl(var(--sidebar-text)), etc.
Accent Colors
--accent-orange: 24 95% 53%; /* Orange accent */
--accent-orange-hover: 24 90% 48%; /* Orange hover state */
Usage:
- CSS:
hsl(var(--accent-orange)),hsl(var(--accent-orange-hover))
Typography
Font Family
font-family: var(--font-inter), system-ui, sans-serif;
Font Sizes
--text-xs: 0.75rem; /* 12px */
--text-sm: 0.875rem; /* 14px */
--text-base: 1rem; /* 16px */
--text-lg: 1.125rem; /* 18px */
--text-xl: 1.25rem; /* 20px */
--text-2xl: 1.5rem; /* 24px */
--text-3xl: 1.875rem; /* 30px */
--text-4xl: 2.25rem; /* 36px */
Font Weights
--font-normal: 400;
--font-medium: 500;
--font-semibold: 600;
--font-bold: 700;
Spacing
Scale
--space-1: 0.25rem; /* 4px */
--space-2: 0.5rem; /* 8px */
--space-3: 0.75rem; /* 12px */
--space-4: 1rem; /* 16px */
--space-6: 1.5rem; /* 24px */
--space-8: 2rem; /* 32px */
--space-12: 3rem; /* 48px */
--space-16: 4rem; /* 64px */
Components
Buttons
Primary Button
<button className="btn btn-primary">
Primary Button
</button>
Secondary Button
<button className="btn btn-secondary">
Secondary Button
</button>
Button Sizes
<button className="btn btn-primary btn-sm">Small</button>
<button className="btn btn-primary">Default</button>
<button className="btn btn-primary btn-lg">Large</button>
Cards
<div className="card">
<div className="card-header">
<h3>Card Title</h3>
</div>
<div className="card-body">
Card content
</div>
<div className="card-footer">
Card footer
</div>
</div>
Forms
<div className="form-group">
<label htmlFor="input">Label</label>
<input
id="input"
type="text"
className="form-input"
placeholder="Placeholder"
/>
<span className="form-hint">Hint text</span>
</div>
Modals
<Modal
isOpen={isOpen}
onClose={handleClose}
title="Modal Title"
size="md"
>
Modal content
</Modal>
Layout
Container
<div className="container">
Content
</div>
Grid
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</div>
Flexbox
<div className="flex items-center justify-between">
<div>Left</div>
<div>Right</div>
</div>
Responsive Design
Breakpoints
/* Mobile */
@media (max-width: 767px) { }
/* Tablet */
@media (min-width: 768px) { }
/* Desktop */
@media (min-width: 1024px) { }
/* Large Desktop */
@media (min-width: 1280px) { }
Mobile-First
// Mobile-first approach
<div className="text-sm md:text-base lg:text-lg">
Responsive text
</div>
Shadows
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
--shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
--shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.1);
Border Radius
--radius-sm: 0.25rem; /* 4px */
--radius: 0.5rem; /* 8px */
--radius-md: 0.75rem; /* 12px */
--radius-lg: 1rem; /* 16px */
--radius-full: 9999px; /* Full circle */
Transitions
--transition-fast: 150ms;
--transition-base: 200ms;
--transition-slow: 300ms;
Icons
Icon Sizes
<svg className="w-4 h-4"> {/* Small */}
<svg className="w-5 h-5"> {/* Default */}
<svg className="w-6 h-6"> {/* Large */}
Accessibility
Focus States
*:focus-visible {
outline: 2px solid var(--color-primary);
outline-offset: 2px;
}
Touch Targets
Minimum size: 44x44px for touch devices.
Color System Architecture
CSS Variable Naming Convention
All colors use HSL format without the hsl() wrapper in the variable definition:
- Format:
--variable-name: hue saturation lightness; - Usage:
hsl(var(--variable-name))or via Tailwind classes
Theme Customization
Colors can be customized via the theme system in app/settings. The useColorTheme hook manages theme persistence and applies colors to CSS variables dynamically.
Legacy Support
For backward compatibility, legacy color variables are mapped to the new HSL system:
--color-primary→hsl(var(--primary))--color-success→hsl(var(--success))--color-error→hsl(var(--destructive))- etc.
Note: Dark mode has been removed as per design requirements. All colors use the light theme.
Best Practices
1. Use Design Tokens
// Good: Use Tailwind classes (preferred)
<div className="bg-primary text-primary-foreground">
// Good: Use CSS variables with hsl() wrapper
<div style={{ color: 'hsl(var(--primary))' }}>
// Good: Use legacy CSS variables (for backward compatibility)
<div style={{ color: 'hsl(var(--color-primary))' }}>
// Bad: Hard-coded hex values
<div style={{ color: '#6366f1' }}>
// Bad: Hard-coded HSL without variables
<div style={{ color: 'hsl(221.2 83.2% 53.3%)' }}>
2. Consistent Spacing
// Good: Use spacing scale
<div className="p-4 m-2">
// Bad: Arbitrary values
<div style={{ padding: '13px', margin: '7px' }}>
3. Semantic Colors
// Good: Use Tailwind semantic classes
<div className="bg-destructive text-destructive-foreground">Error</div>
<div className="bg-success text-success-foreground">Success</div>
<div className="bg-warning text-warning-foreground">Warning</div>
<div className="bg-info text-info-foreground">Info</div>
// Good: Use CSS variables
<div style={{ color: 'hsl(var(--destructive))' }}>Error</div>
// Bad: Direct hex colors
<div style={{ color: '#ef4444' }}>Error</div>