mediahub-fe/docs/DESIGN_SYSTEM.md

# MediaHub Design System

## 📋 Overview

The MediaHub Design System provides a comprehensive set of design tokens, components, and utilities to ensure consistency across the application. This system is built on modern design principles and follows accessibility best practices.

## 🎨 Design Tokens

### Colors

Our color system is organized into semantic categories for consistent usage across the application.

#### Primary Colors
```typescript
import { colors } from '@/lib/design-system';

// Primary brand colors
colors.primary[50]   // Lightest shade
colors.primary[100]  // Very light
colors.primary[500]  // Main brand color
colors.primary[600]  // Darker shade
colors.primary[900]  // Darkest shade
```

#### Neutral Colors
```typescript
// Neutral colors for text, backgrounds, and borders
colors.neutral[50]   // Background colors
colors.neutral[100]  // Light backgrounds
colors.neutral[500]  // Medium text
colors.neutral[700]  // Dark text
colors.neutral[900]  // Darkest text
```

#### Semantic Colors
```typescript
// Success states
colors.semantic.success.DEFAULT
colors.semantic.success[50]   // Light background
colors.semantic.success[500]  // Main success color

// Warning states
colors.semantic.warning.DEFAULT
colors.semantic.warning[50]   // Light background
colors.semantic.warning[500]  // Main warning color

// Error states
colors.semantic.error.DEFAULT
colors.semantic.error[50]     // Light background
colors.semantic.error[500]    // Main error color

// Info states
colors.semantic.info.DEFAULT
colors.semantic.info[50]      // Light background
colors.semantic.info[500]     // Main info color
```

#### Surface Colors
```typescript
// Surface colors for UI elements
colors.surface.background     // Main background
colors.surface.foreground     // Main text
colors.surface.card          // Card backgrounds
colors.surface.border        // Border colors
colors.surface.muted         // Muted backgrounds
```

### Spacing

Our spacing system uses a 4px base unit for consistent spacing across the application.

```typescript
import { spacing } from '@/lib/design-system';

// Base spacing units
spacing.xs    // 4px
spacing.sm    // 8px
spacing.md    // 16px
spacing.lg    // 24px
spacing.xl    // 32px
spacing['2xl'] // 48px
spacing['3xl'] // 64px
spacing['4xl'] // 96px
spacing['5xl'] // 128px

// Component-specific spacing
spacing.component.padding.xs  // 8px
spacing.component.padding.md  // 16px
spacing.component.padding.lg  // 24px

spacing.component.margin.xs   // 8px
spacing.component.margin.md   // 16px
spacing.component.margin.lg   // 24px

spacing.component.gap.xs      // 4px
spacing.component.gap.md      // 16px
spacing.component.gap.lg      // 24px
```

### Typography

Our typography system provides consistent text styles with proper hierarchy.

#### Font Families
```typescript
import { typography } from '@/lib/design-system';

// Font families
typography.fontFamily.sans  // DM Sans, system-ui, sans-serif
typography.fontFamily.mono  // JetBrains Mono, Consolas, monospace
```

#### Font Sizes
```typescript
// Font sizes
typography.fontSize.xs     // 12px
typography.fontSize.sm     // 14px
typography.fontSize.base   // 16px
typography.fontSize.lg     // 18px
typography.fontSize.xl     // 20px
typography.fontSize['2xl'] // 24px
typography.fontSize['3xl'] // 30px
typography.fontSize['4xl'] // 36px
typography.fontSize['5xl'] // 48px
typography.fontSize['6xl'] // 60px
```

#### Typography Presets
```typescript
// Predefined typography styles
typography.presets.h1        // Large headings
typography.presets.h2        // Medium headings
typography.presets.h3        // Small headings
typography.presets.body      // Body text
typography.presets.bodySmall // Small body text
typography.presets.caption   // Caption text
typography.presets.button    // Button text
```

### Border Radius

Consistent border radius values for rounded corners.

```typescript
import { borderRadius } from '@/lib/design-system';

borderRadius.none   // 0
borderRadius.sm     // 2px
borderRadius.md     // 4px
borderRadius.lg     // 8px
borderRadius.xl     // 12px
borderRadius['2xl'] // 16px
borderRadius['3xl'] // 24px
borderRadius.full   // 9999px (fully rounded)
```

### Shadows

Elevation and depth through consistent shadow values.

```typescript
import { shadows } from '@/lib/design-system';

// Elevation shadows
shadows.sm     // Subtle elevation
shadows.md     // Medium elevation
shadows.lg     // Large elevation
shadows.xl     // Extra large elevation
shadows['2xl'] // Maximum elevation

// Custom shadows
shadows.card   // Card shadows
shadows.dropdown // Dropdown shadows
shadows.modal  // Modal shadows
shadows.focus  // Focus ring shadows
```

### Animations

Smooth, consistent animations for better user experience.

```typescript
import { animations } from '@/lib/design-system';

// Animation durations
animations.duration.fast   // 150ms
animations.duration.normal // 250ms
animations.duration.slow   // 350ms
animations.duration.slower // 500ms

// Animation presets
animations.presets.fadeIn           // Fade in animation
animations.presets.fadeOut          // Fade out animation
animations.presets.slideInFromTop   // Slide in from top
animations.presets.slideInFromBottom // Slide in from bottom
animations.presets.scaleIn          // Scale in animation
animations.presets.scaleOut         // Scale out animation
animations.presets.spin             // Spinning animation
animations.presets.pulse            // Pulsing animation
animations.presets.bounce           // Bouncing animation
```

## 🧩 Component Library

### Core Components

Our component library is built on top of shadcn/ui and Radix UI primitives, enhanced with our design system.

#### Button Component
```tsx
import { Button } from '@/components/ui/button';

// Usage examples
<Button variant="default" size="md">
  Primary Button
</Button>

<Button variant="outline" size="sm">
  Secondary Button
</Button>

<Button variant="ghost" size="lg">
  Ghost Button
</Button>
```

#### Card Component
```tsx
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';

<Card>
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
  </CardHeader>
  <CardContent>
    Card content goes here
  </CardContent>
</Card>
```

#### Input Component
```tsx
import { Input } from '@/components/ui/input';

<Input 
  type="text" 
  placeholder="Enter text..."
  className="w-full"
/>
```

### Design System Utilities

#### Color Utilities
```typescript
import { getColor } from '@/lib/design-system';

// Get color with opacity
getColor(colors.primary[500], 0.5) // Primary color with 50% opacity
```

#### Spacing Utilities
```typescript
import { getSpacing } from '@/lib/design-system';

// Get spacing value
getSpacing('md') // Returns '1rem'
```

#### Typography Utilities
```typescript
import { getTypography } from '@/lib/design-system';

// Get typography preset
getTypography('h1') // Returns h1 typography styles
```

#### Shadow Utilities
```typescript
import { getShadow } from '@/lib/design-system';

// Get shadow value
getShadow('card') // Returns card shadow
```

#### Animation Utilities
```typescript
import { getAnimation } from '@/lib/design-system';

// Get animation preset
getAnimation('fadeIn') // Returns fadeIn animation
```

## 🎯 Usage Guidelines

### Color Usage

1. **Primary Colors**: Use for main actions, links, and brand elements
2. **Neutral Colors**: Use for text, backgrounds, and borders
3. **Semantic Colors**: Use for status indicators and feedback
4. **Surface Colors**: Use for UI element backgrounds

### Spacing Guidelines

1. **Use consistent spacing**: Always use our predefined spacing values
2. **Follow the 4px grid**: All spacing should be multiples of 4px
3. **Component spacing**: Use component-specific spacing for internal padding/margins

### Typography Guidelines

1. **Hierarchy**: Use appropriate heading levels (h1-h6)
2. **Readability**: Ensure sufficient contrast and line height
3. **Consistency**: Use typography presets for consistent styling

### Animation Guidelines

1. **Purpose**: Use animations to provide feedback and guide attention
2. **Duration**: Keep animations short (150-350ms) for responsiveness
3. **Easing**: Use smooth easing functions for natural movement

## 🎨 Design Principles

### 1. Consistency
- Use design tokens consistently across all components
- Maintain visual hierarchy through typography and spacing
- Follow established patterns for similar interactions

### 2. Accessibility
- Ensure sufficient color contrast (WCAG 2.1 AA compliance)
- Provide focus indicators for keyboard navigation
- Use semantic HTML and ARIA attributes

### 3. Performance
- Optimize animations for smooth 60fps performance
- Use CSS transforms and opacity for animations
- Minimize layout shifts during interactions

### 4. Scalability
- Design tokens are easily customizable
- Components are composable and reusable
- System supports both light and dark themes

## 🔧 Customization

### Adding New Colors
```typescript
// In lib/design-system.ts
export const colors = {
  // ... existing colors
  custom: {
    50: 'hsl(200, 100%, 95%)',
    500: 'hsl(200, 100%, 50%)',
    900: 'hsl(200, 100%, 25%)',
  },
};
```

### Adding New Spacing Values
```typescript
// In lib/design-system.ts
export const spacing = {
  // ... existing spacing
  'custom': '1.25rem', // 20px
};
```

### Adding New Typography Presets
```typescript
// In lib/design-system.ts
export const typography = {
  presets: {
    // ... existing presets
    custom: {
      fontSize: '1.125rem',
      fontWeight: '600',
      lineHeight: '1.4',
      letterSpacing: '-0.025em',
    },
  },
};
```

## 📱 Responsive Design

Our design system supports responsive design through Tailwind's breakpoint system:

```typescript
// Breakpoints
breakpoints.xs    // 320px
breakpoints.sm    // 640px
breakpoints.md    // 768px
breakpoints.lg    // 1024px
breakpoints.xl    // 1280px
breakpoints['2xl'] // 1536px
```

### Responsive Usage
```tsx
// Responsive spacing
<div className="p-4 md:p-6 lg:p-8">
  Content
</div>

// Responsive typography
<h1 className="text-2xl md:text-3xl lg:text-4xl">
  Responsive Heading
</h1>

// Responsive colors
<div className="bg-neutral-50 dark:bg-neutral-900">
  Theme-aware content
</div>
```

## 🌙 Dark Mode Support

Our design system includes comprehensive dark mode support:

```typescript
// Dark mode colors are automatically applied
// Light mode
colors.surface.background // hsl(0, 0%, 100%)

// Dark mode (applied automatically)
colors.surface.background // hsl(222.2, 47.4%, 11.2%)
```

### Dark Mode Usage
```tsx
// Automatic dark mode support
<div className="bg-background text-foreground">
  Content automatically adapts to theme
</div>

// Manual dark mode classes
<div className="bg-white dark:bg-neutral-900 text-neutral-900 dark:text-white">
  Manual theme control
</div>
```

## 🧪 Testing

### Visual Regression Testing
```typescript
// Example test for design system components
import { render, screen } from '@testing-library/react';
import { Button } from '@/components/ui/button';

describe('Button Component', () => {
  it('renders with correct design system styles', () => {
    render(<Button>Test Button</Button>);
    
    const button = screen.getByRole('button');
    expect(button).toHaveClass('bg-primary text-primary-foreground');
  });
});
```

### Accessibility Testing
```typescript
// Test for accessibility compliance
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

it('should not have accessibility violations', async () => {
  const { container } = render(<Button>Accessible Button</Button>);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});
```

## 📚 Resources

### Documentation
- [Design System Tokens](./DESIGN_SYSTEM.md)
- [Component Library](./COMPONENTS.md)
- [Accessibility Guidelines](./ACCESSIBILITY.md)

### Tools
- [Storybook](./storybook) - Component documentation and testing
- [Figma](./figma) - Design files and specifications
- [Chromatic](./chromatic) - Visual regression testing

### References
- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [Material Design](https://material.io/design)
- [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)

---

**Last Updated**: December 2024  
**Version**: 1.0.0  
**Maintainer**: MediaHub Development Team