Comprehensive design token system for consistent styling across the application.
Overview#
Design tokens are the fundamental building blocks of our design system. They provide a centralized source of truth for all design decisions including colors, spacing, typography, animations, and more.
Token Categories#
Our design system includes the following token categories:
Colors (200+ tokens)#
- Primary: Main brand color with 11 shades (50-950)
- Secondary: Secondary brand color with 11 shades
- Neutral: Grayscale with 11 shades
- Success: Green color scale
- Warning: Yellow/orange color scale
- Error: Red color scale
- Info: Blue color scale
- Semantic Colors: Background, foreground, border, etc.
Spacing (24 tokens)#
- Range from 0px to 384px
- Consistent 4px grid system
- Used for margins, padding, gaps
Typography#
- Font Sizes: 10 sizes from xs (0.75rem) to 9xl (8rem)
- Font Weights: 9 weights from thin (100) to black (900)
- Line Heights: 8 values from none (1) to loose (2)
Animations#
- Durations: 10 tokens (0ms to 1000ms)
- Easing: 12 easing functions
- Delays: 6 delay tokens
- Spring Physics: 6 spring presets
Shadows#
- 7 shadow tokens from xs to 2xl
- Consistent elevation system
Border Radius#
- 9 tokens from none (0) to full (9999px)
- Consistent rounding system
Z-Index#
- 10 layers from -1 to 9999
- Predictable layering system
Breakpoints#
- 6 responsive breakpoints
- Mobile-first approach
Transitions & Durations#
- Consistent timing system
- Smooth animations
Usage#
TypeScript#
```typescript import { designTokens } from '@/lib/design-tokens';
// Access tokens const primaryColor = designTokens.colors.primary[500]; const mediumSpacing = designTokens.spacing[4]; const normalDuration = designTokens.duration.normal; ```
CSS Custom Properties#
```css .my-component { color: var(--colors-primary-500); padding: var(--spacing-4); transition: all var(--duration-normal) var(--easing-ease-out); } ```
Utility Functions#
```typescript import { getColor, getSpacing, getFontSize, colorVar, spacingVar } from '@/lib/design-tokens-utils';
// Type-safe token access const color = getColor('primary.500'); const spacing = getSpacing(4); const fontSize = getFontSize('lg');
// CSS variable strings const cssColor = colorVar('primary.500'); const cssSpacing = spacingVar(4); ```
Dark Mode#
All color tokens support dark mode with automatic theme switching:
```typescript import { useTheme } from '@/hooks/use-theme';
function MyComponent() { const { theme, toggleTheme } = useTheme();
return ( <button onClick={toggleTheme}> Current theme: {theme} </button> ); } ```
Best Practices#
- Always use tokens instead of hard-coded values
- Use semantic tokens (e.g.,
colors.text.primary) over specific tokens when available - Leverage utility functions for type safety
- Use CSS custom properties for dynamic theming
- Follow the spacing scale for consistent layouts
- Use animation tokens for consistent motion
- Respect the z-index system for proper layering
Benefits#
- ✅ Consistency: Single source of truth for design decisions
- ✅ Type Safety: Full TypeScript support
- ✅ Dark Mode: Built-in theme support
- ✅ Maintainability: Change once, update everywhere
- ✅ Performance: CSS custom properties for runtime theming
- ✅ Developer Experience: Auto-completion and validation
- ✅ Scalability: Easy to extend and modify