project-standalo-sonic-cloud/components/README.md

Sonic Cloud Components

This directory contains all 22 UI components for the Sonic Cloud music platform.

Component Categories

Audio Player (3 components)

• AudioPlayer - Global audio player with play/pause, progress, volume controls
• PlayerControls - Reusable control buttons (play, pause, next, previous, shuffle, repeat)
• WaveformDisplay - Visual audio waveform with seek functionality

Cards (4 components)

• SongCard - Song display with cover, title, artist, play button
• AlbumCard - Album display with cover, title, artist, track count
• ArtistCard - Artist display with avatar, name, followers, verified badge
• PlaylistCard - Playlist display with cover, title, description, song count

Headers (5 components)

• ArtistHeader - Artist profile header with banner, avatar, bio, stats
• AlbumHeader - Album header with cover, title, artist, release info
• PlaylistHeader - Playlist header with cover, title, actions
• GenreHeader - Genre page header with gradient background
• SectionHeader - Reusable section title with "See all" link

Lists (1 component)

• TrackList - Song list with play buttons, position numbers, duration

Forms (4 components)

• AuthForm - Login/register/forgot-password form (3 modes)
• UploadForm - Song upload form with file input, metadata fields
• ProfileForm - User profile edit form with validation
• AvatarUpload - Avatar image upload with drag-and-drop preview

Search (2 components)

• SearchBar - Search input with autocomplete suggestions
• SearchResults - Search results display (songs, artists, albums)

Modals (1 component)

• CreatePlaylistModal - Modal for creating new playlists

Utility (2 components)

• GenreBadge - Small genre tag with variants (default, outlined, minimal)
• SocialLinks - Social media link icons (Twitter, Instagram, etc.)

Design System

Colors

• Background: zinc-900, zinc-950
• Surface: zinc-800
• Accent: purple-500, purple-600
• Text: white, zinc-100 (primary), zinc-400 (secondary)
• Border: zinc-700, zinc-800

Spacing

• Cards: p-4 (padding)
• Sections: mb-6, mb-8 (margin bottom)
• Gaps: gap-3, gap-4, gap-6

Border Radius

• Small: rounded-lg (8px)
• Medium: rounded-xl (12px)
• Large: rounded-2xl (16px)
• Circle: rounded-full

Typography

• Headings: font-bold, font-semibold
• Body: font-medium (default)
• Sizes: text-sm, text-base, text-lg, text-xl, text-2xl

Component Props

All components use TypeScript interfaces for type safety. Import types like this:

import { SongCard, type SongCardProps } from '@/components'

Usage Examples

Audio Player

import { AudioPlayer } from '@/components'

<AudioPlayer
  songId="123"
  songTitle="My Song"
  artistName="Artist Name"
  audioUrl="/audio/song.mp3"
  coverUrl="/images/cover.jpg"
  onPlayCountIncrement={() => console.log('Play counted')}
/>

Song Card

import { SongCard } from '@/components'

<SongCard
  id="123"
  title="My Song"
  artistName="Artist Name"
  coverUrl="/images/cover.jpg"
  duration={180}
  plays={1000}
  onPlay={() => console.log('Play clicked')}
/>

Auth Form

import { AuthForm } from '@/components'

<AuthForm
  mode="login"
  onSubmit={(data) => console.log(data)}
  onModeChange={(mode) => console.log('Mode changed to', mode)}
/>

Search Bar

import { SearchBar } from '@/components'

<SearchBar
  placeholder="Search..."
  onSearch={(query) => console.log('Searching for:', query)}
  suggestions={[
    { type: 'song', id: '1', title: 'Song Title', subtitle: 'Artist' }
  ]}
  onSuggestionClick={(suggestion) => console.log('Clicked:', suggestion)}
/>

Accessibility

All components follow accessibility best practices:

• Semantic HTML - Proper element usage (button, nav, etc.)
• ARIA labels - Screen reader support
• Keyboard navigation - Tab, Enter, Escape support
• Focus states - Visible focus indicators
• Color contrast - WCAG AA compliant

Responsive Design

Components are mobile-first and responsive:

• Mobile: Base styles
• Tablet: sm: breakpoint (640px)
• Desktop: md: breakpoint (768px), lg: breakpoint (1024px)

Component States

All interactive components support:

• Default - Initial state
• Hover - Mouse hover effect
• Focus - Keyboard focus ring
• Active - Click/tap state
• Disabled - Non-interactive state
• Loading - Async operation state

Performance

Components are optimized for performance:

• 'use client' - Client-side rendering where needed
• Lazy loading - Images with proper alt text
• Debouncing - Search input optimized
• Memoization - React hooks for expensive operations

Browser Support

Components work in all modern browsers:

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Related Files

• components/index.ts - Barrel export for all components
• project_manifest.json - Component definitions and dependencies
• CLAUDE.md - Project workflow and guidelines