AudiOhm/design-system/MASTER.md

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

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

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

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

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

.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

.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

.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

.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

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

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

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

.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

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