# AudiOhm Design System - Master

## Brand Identity

**AudiOhm** est une plateforme de streaming musicale alternative à Spotify avec une esthétique **cyberpunk moderne**. Notre design combine :
- L'énergie néon du cyberpunk
- La fonctionnalité des plateformes de streaming modernes
- Une expérience utilisateur fluide et immersive

---

## Color Palette

### Primary Colors (Dark Theme Base)

| Role | Hex | Usage |
|------|-----|-------|
| **Background** | `#0A0E27` | Page background, main sections |
| **Surface** | `#151932` | Cards, modals, elevated elements |
| **Surface-Elevated** | `#1F2342` | Hovered cards, active elements |
| **Border** | `#2A2F4A` | Dividers, card borders |

### Neon Accents

| Role | Hex | Usage |
|------|-----|-------|
| **Primary** | `#00F0FF` | Main CTAs, active states, links |
| **Secondary** | `#BF00FF` | Secondary actions, tags |
| **Accent** | `#FF006E` | Highlights, notifications, likes |
| **Success** | `#00FF94` | Success states, now playing |
| **Warning** | `#FFB800` | Warnings, pending states |
| **Error** | `FF3B3B` | Errors, destructive actions |

### Text Colors

| Role | Hex | Usage |
|------|-----|-------|
| **Text-Primary** | `#F0F4F8` | Headings, primary text |
| **Text-Secondary** | `#9BA3B8` | Secondary text, descriptions |
| **Text-Tertiary** | `#6B7280` | Tertiary text, disabled states |
| **Text-Inverted** | `#0A0E27` | Text on neon backgrounds |

### Gradient Overlays

```css
/* Primary Gradient */
--gradient-primary: linear-gradient(135deg, #00F0FF 0%, #BF00FF 100%);

/* Accent Gradient */
--gradient-accent: linear-gradient(135deg, #FF006E 0%, #FF3B3B 100%);

/* Surface Gradient */
--gradient-surface: linear-gradient(180deg, rgba(21,25,50,0.9) 0%, rgba(10,14,39,0.95) 100%);
```

---

## Typography

### Font Families

```css
/* Primary Fonts via Google Fonts */
@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700;800&family=Space+Grotesk:wght@400;500;600;700&display=swap');

/* Heading Font - Modern & Bold */
--font-heading: 'Space Grotesk', sans-serif;

/* Body Font - Clean & Readable */
--font-body: 'Outfit', sans-serif;

/* Monospace - For technical details */
--font-mono: 'JetBrains Mono', 'Fira Code', monospace;
```

### Type Scale

| Role | Size | Weight | Line-Height | Usage |
|------|------|--------|-------------|-------|
| **Display** | 48px | 700 | 1.1 | Hero section, large titles |
| **H1** | 36px | 700 | 1.2 | Page titles |
| **H2** | 28px | 600 | 1.3 | Section headers |
| **H3** | 22px | 600 | 1.4 | Card titles, subtitles |
| **Body-Large** | 18px | 400 | 1.5 | Emphasized body text |
| **Body** | 16px | 400 | 1.6 | Standard body text |
| **Body-Small** | 14px | 400 | 1.6 | Secondary text |
| **Caption** | 12px | 500 | 1.5 | Metadata, timestamps |
| **Overline** | 11px | 600 | 1.4 | Labels, tags, uppercase |

---

## Spacing System

### Scale (Base: 4px)

| Token | Value | Usage |
|-------|-------|-------|
| `--spacing-1` | 4px | Tight gaps, icon padding |
| `--spacing-2` | 8px | Small gaps, button padding |
| `--spacing-3` | 12px | Card padding (compact) |
| `--spacing-4` | 16px | Standard spacing, card padding |
| `--spacing-5` | 20px | Medium gaps |
| `--spacing-6` | 24px | Section padding, form fields |
| `--spacing-8` | 32px | Large gaps, content sections |
| `--spacing-10` | 40px | XL gaps, page padding |
| `--spacing-12` | 48px | XXL gaps, major sections |
| `--spacing-16` | 64px | Hero sections, page margins |

---

## Layout System

### Container Widths

| Breakpoint | Max Width | Usage |
|------------|-----------|-------|
| Mobile | 100% | < 768px |
| Tablet | 768px | 768px - 1024px |
| Desktop | 1200px | 1024px - 1440px |
| Wide | 1440px | > 1440px |

### Grid System

```css
/* 12-column grid */
--grid-columns: 12;
--grid-gap: 24px;

/* Responsive columns */
--cols-mobile: 1fr;
--cols-tablet: repeat(6, 1fr);
--cols-desktop: repeat(12, 1fr);
```

---

## Components

### Buttons

#### Primary Button (Neon)

```css
.btn-primary {
  background: linear-gradient(135deg, #00F0FF 0%, #00C8FF 100%);
  color: #0A0E27;
  padding: 12px 24px;
  border-radius: 8px;
  font-weight: 600;
  font-size: 16px;
  border: none;
  cursor: pointer;
  transition: all 200ms ease;
  box-shadow: 0 0 20px rgba(0, 240, 255, 0.3);
}

.btn-primary:hover {
  box-shadow: 0 0 30px rgba(0, 240, 255, 0.5);
  transform: translateY(-1px);
}

.btn-primary:active {
  transform: translateY(0);
}
```

#### Secondary Button (Ghost)

```css
.btn-secondary {
  background: transparent;
  color: #00F0FF;
  padding: 12px 24px;
  border-radius: 8px;
  font-weight: 600;
  font-size: 16px;
  border: 1px solid #00F0FF;
  cursor: pointer;
  transition: all 200ms ease;
}

.btn-secondary:hover {
  background: rgba(0, 240, 255, 0.1);
  box-shadow: 0 0 20px rgba(0, 240, 255, 0.2);
}
```

### Cards

#### Base Card

```css
.card {
  background: #151932;
  border-radius: 16px;
  padding: 20px;
  border: 1px solid #2A2F4A;
  transition: all 250ms ease;
}

.card:hover {
  border-color: #00F0FF;
  box-shadow: 0 8px 32px rgba(0, 240, 255, 0.15);
  transform: translateY(-2px);
}
```

#### Album Card

```css
.card-album {
  position: relative;
  border-radius: 16px;
  overflow: hidden;
  aspect-ratio: 1/1;
  cursor: pointer;
}

.card-album:hover .play-overlay {
  opacity: 1;
}

.play-overlay {
  position: absolute;
  inset: 0;
  background: rgba(10, 14, 39, 0.7);
  display: flex;
  align-items: center;
  justify-content: center;
  opacity: 0;
  transition: opacity 200ms ease;
}

.play-button {
  width: 56px;
  height: 56px;
  background: #00F0FF;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  box-shadow: 0 4px 24px rgba(0, 240, 255, 0.4);
}
```

### Inputs

```css
.input {
  background: #0A0E27;
  border: 1px solid #2A2F4A;
  border-radius: 8px;
  padding: 12px 16px;
  color: #F0F4F8;
  font-size: 16px;
  transition: all 200ms ease;
}

.input:focus {
  outline: none;
  border-color: #00F0FF;
  box-shadow: 0 0 0 3px rgba(0, 240, 255, 0.1);
}

.input::placeholder {
  color: #6B7280;
}
```

---

## Effects & Animations

### Glow Effects

```css
/* Primary Glow */
.glow-primary {
  box-shadow: 0 0 20px rgba(0, 240, 255, 0.4);
}

/* Secondary Glow */
.glow-secondary {
  box-shadow: 0 0 20px rgba(191, 0, 255, 0.4);
}

/* Accent Glow */
.glow-accent {
  box-shadow: 0 0 20px rgba(255, 0, 110, 0.4);
}
```

### Transitions

| Type | Duration | Easing | Usage |
|------|----------|--------|-------|
| **Fast** | 150ms | ease-out | Micro-interactions |
| **Base** | 200ms | ease-out | Button hovers, color changes |
| **Slow** | 300ms | ease-out | Card transforms, modals |

```css
/* Reduced Motion Support */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

---

## Icons

Use **Lucide Icons** or **Heroicons** (SVG format only - never emojis)

```css
/* Icon Sizing */
--icon-xs: 16px;
--icon-sm: 20px;
--icon-md: 24px;
--icon-lg: 32px;
--icon-xl: 48px;
```

---

## Z-Index Scale

| Layer | Value | Usage |
|-------|-------|-------|
| Base | 0 | Default content |
| Elevated | 10 | Cards, dropdowns |
| Sticky | 20 | Sticky headers, sidebars |
| Overlay | 30 | Modals, tooltips |
| Modal | 40 | Active modal |
| Notification | 50 | Toasts, notifications |

---

## Accessibility Standards

### Color Contrast
- **Text & Background**: Minimum 4.5:1 (WCAG AA)
- **Large Text**: Minimum 3:1 (WCAG AA)
- **Interactive Elements**: Minimum 3:1

### Focus States
```css
.focusable:focus {
  outline: 2px solid #00F0FF;
  outline-offset: 2px;
}
```

### Touch Targets
- Minimum **44x44px** for all interactive elements
- Minimum **48x48px** for primary CTAs

### Screen Reader Support
- All images must have descriptive `alt` text
- Form inputs must have associated labels
- Icon-only buttons need `aria-label`

---

## Anti-Patterns to Avoid

❌ **NEVER use emojis as icons** - Use SVG icons (Lucide/Heroicons)
❌ **NEVER use text color below #9BA3B8 in dark mode** - Insufficient contrast
❌ **NEVER use instant transitions (0ms)** - Use 150-300ms for smoothness
❌ **NEVER skip hover states** - All interactive elements need feedback
❌ **NEVER use `cursor: default` on clickable elements** - Always use `cursor: pointer`
❌ **NEVER use layout-shifting transforms** - Avoid scale on hover, use color/shadow
❌ **NEVER mix inconsistent spacing** - Follow spacing system strictly
❌ **NEVER use transparent borders in light mode** - Must be visible
❌ **NEVER skip reduced-motion checks** - Always respect user preferences

---

## Responsive Breakpoints

```css
/* Mobile First Approach */
/* Mobile: < 768px (default) */
--breakpoint-mobile: 0px;

/* Tablet: >= 768px */
--breakpoint-tablet: 768px;

/* Desktop: >= 1024px */
--breakpoint-desktop: 1024px;

/* Wide: >= 1440px */
--breakpoint-wide: 1440px;
```

---

## Page-Specific Guidelines

For page-specific design overrides, refer to:
- `design-system/pages/home.md` - Home page specific rules
- `design-system/pages/search.md` - Search page specific rules
- `design-system/pages/player.md` - Player page specific rules
- `design-system/pages/library.md` - Library page specific rules

If a page-specific file exists, its rules **override** these master rules.

---

## Implementation Checklist

Before delivering any UI component or page, verify:

### Visual Quality
- [ ] No emojis used as icons (SVG only)
- [ ] All icons from consistent set (Lucide/Heroicons)
- [ ] Hover states use color/shadow, not scale
- [ ] Neon glow effects are subtle, not overwhelming
- [ ] Background and surface colors are consistent

### Interaction
- [ ] All clickable elements have `cursor: pointer`
- [ ] Hover states provide clear visual feedback
- [ ] Transitions are 150-300ms (smooth, not slow)
- [ ] Focus states visible for keyboard navigation

### Accessibility
- [ ] Text contrast minimum 4.5:1
- [ ] All images have alt text
- [ ] Form inputs have labels
- [ ] Interactive elements can be operated via keyboard
- [ ] `prefers-reduced-motion` is respected

### Responsive
- [ ] Layout works at 375px (mobile)
- [ ] Layout works at 768px (tablet)
- [ ] Layout works at 1024px (desktop)
- [ ] Layout works at 1440px (wide)
- [ ] No horizontal scroll on mobile
- [ ] Touch targets minimum 44x44px

### Performance
- [ ] Images use WebP format with fallbacks
- [ ] Large images are lazy-loaded
- [ ] Animations use transform/opacity (not width/height)
- [ ] No layout shifts from async content

---

*This design system is the single source of truth for AudiOhm's UI/UX. All implementations must follow these guidelines unless a page-specific override exists.*