494 lines
12 KiB
Markdown
494 lines
12 KiB
Markdown
# 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 |