186 lines
5.0 KiB
Markdown
186 lines
5.0 KiB
Markdown
# 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:
|
|
|
|
```tsx
|
|
import { SongCard, type SongCardProps } from '@/components'
|
|
```
|
|
|
|
## Usage Examples
|
|
|
|
### Audio Player
|
|
```tsx
|
|
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
|
|
```tsx
|
|
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
|
|
```tsx
|
|
import { AuthForm } from '@/components'
|
|
|
|
<AuthForm
|
|
mode="login"
|
|
onSubmit={(data) => console.log(data)}
|
|
onModeChange={(mode) => console.log('Mode changed to', mode)}
|
|
/>
|
|
```
|
|
|
|
### Search Bar
|
|
```tsx
|
|
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
|