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

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

// 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

// 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

// 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.

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

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

// 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

// 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.

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.

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.

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

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

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

import { Input } from '@/components/ui/input';

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

Design System Utilities

Color Utilities

import { getColor } from '@/lib/design-system';

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

Spacing Utilities

import { getSpacing } from '@/lib/design-system';

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

Typography Utilities

import { getTypography } from '@/lib/design-system';

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

Shadow Utilities

import { getShadow } from '@/lib/design-system';

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

Animation Utilities

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

// 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

// In lib/design-system.ts
export const spacing = {
  // ... existing spacing
  'custom': '1.25rem', // 20px
};

Adding New Typography Presets

// 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:

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

Responsive Usage

// 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:

// 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

// 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

// 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

// 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
• Component Library
• Accessibility Guidelines

Tools

• Storybook - Component documentation and testing
• Figma - Design files and specifications
• Chromatic - Visual regression testing

References

• WCAG 2.1 Guidelines
• Material Design
• Apple Human Interface Guidelines

---

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