designmd-forge 1.2.0

package/dist/data/designs/ios-apple-music-android.md

@@ -0,0 +1,737 @@
+# Apple Music (iOS) — Jetpack Compose Implementation Guide
+
+Companion to [DESIGN.md](DESIGN.md) — the framework-neutral spec. This file ports Apple Music's visual language to **Android with Jetpack Compose (Material 3)**: a color token object, a `Typography` set, paste-ready `@Composable`s, `Modifier`s, motion, and haptics.
+
+> Why a Compose guide for an iOS-referenced app? The DESIGN.md tokens are platform-neutral. This file keeps the *visual* identity (Apple Music's true-black/true-white canvas, single Apple-Music-Red accent, 12dp softer album corners, album-art-derived Now Playing gradient, time-synced lyrics) while making everything idiomatic Android — `NavigationBar` instead of a UITabBar, AndroidX Palette instead of Core Image `CIAreaAverage`, a translucent `Surface` instead of `.regularMaterial` (Android has no live blur), `sp`/`dp` instead of `pt`. Apple Music supports both light and dark, so we wire a full Material 3 light + dark scheme; dark canvas is true `#000000` (not `#121212`).
+
+Assumes Compose BOM `2024.09+`, Kotlin `2.0+`, `minSdk 24`, Material 3, [Coil](https://coil-kt.github.io/coil/) `2.6+` for artwork, and `androidx.palette:palette-ktx` for the Now Playing album-color extraction.
+
+## 1. Color Tokens
+
+```kotlin
+// ui/theme/AppleMusicColors.kt
+import androidx.compose.ui.graphics.Color
+
+object AMColors {
+    // Brand
+    val Red        = Color(0xFFFA2D48) // Play, heart liked, shuffle active, scrubber fill, tab
+    val Coral      = Color(0xFFFC3C44) // warmer marketing variant
+    val RedPressed = Color(0xFFD4213B)
+
+    // Canvas & Surfaces (Light)
+    val CanvasLight   = Color(0xFFFFFFFF)
+    val Surface1Light = Color(0xFFF2F2F7) // grouped list / section cards
+    val Surface3Light = Color(0xFFE5E5EA) // pressed rows, input fill
+    val DividerLight  = Color(0xFFC6C6C8)
+
+    // Canvas & Surfaces (Dark) — full-contrast true black
+    val CanvasDark   = Color(0xFF000000) // unusual for media apps — NOT #121212
+    val Surface1Dark = Color(0xFF1C1C1E)
+    val Surface2Dark = Color(0xFF2C2C2E)
+    val Surface3Dark = Color(0xFF3A3A3C)
+    val DividerDark  = Color(0xFF38383A)
+
+    // Text base colors (apply alpha for secondary/tertiary tiers)
+    val LabelLight = Color(0xFF000000)        // primary, light
+    val LabelDark  = Color(0xFFFFFFFF)        // primary, dark
+    val SecLight   = Color(0xFF3C3C43)        // .copy(alpha = 0.60f) = secondary
+    val SecDark    = Color(0xFFEBEBF5)        // .copy(alpha = 0.60f) = secondary (dark)
+
+    // Badges
+    val AtmosGold     = Color(0xFFD4A857)
+    val LosslessSilver = Color(0xFF8E8E93)
+
+    // iOS system colors (prefer for links / status, not the brand red)
+    val SystemBlue  = Color(0xFF007AFF) // inline links (artist in description)
+    val SystemGreen = Color(0xFF34C759) // download complete
+    val SystemRed   = Color(0xFFFF3B30) // playback errors (NOT Apple Music red)
+}
+```
+
+Apple Music supports light and dark equally — wire both Material 3 schemes. `primary` is Apple Music Red; dark `background` is true black.
+
+```kotlin
+// ui/theme/Theme.kt
+import androidx.compose.material3.lightColorScheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.foundation.isSystemInDarkTheme
+
+private val AMLight = lightColorScheme(
+    primary        = AMColors.Red,
+    onPrimary      = Color.White,
+    background     = AMColors.CanvasLight,
+    onBackground   = AMColors.LabelLight,
+    surface        = AMColors.CanvasLight,
+    onSurface      = AMColors.LabelLight,
+    surfaceVariant = AMColors.Surface1Light,
+    outline        = AMColors.DividerLight,
+    error          = AMColors.SystemRed,
+)
+
+private val AMDark = darkColorScheme(
+    primary        = AMColors.Red,
+    onPrimary      = Color.White,
+    background     = AMColors.CanvasDark,        // true #000000
+    onBackground   = AMColors.LabelDark,
+    surface        = AMColors.Surface1Dark,
+    onSurface      = AMColors.LabelDark,
+    surfaceVariant = AMColors.Surface2Dark,
+    outline        = AMColors.DividerDark,
+    error          = AMColors.SystemRed,
+)
+
+@Composable
+fun AppleMusicTheme(
+    darkTheme: Boolean = isSystemInDarkTheme(),
+    content: @Composable () -> Unit,
+) = MaterialTheme(
+    colorScheme = if (darkTheme) AMDark else AMLight,
+    typography  = AMTypography,
+    content     = content,
+)
+```
+
+## 2. Typography
+
+Apple Music is 100% SF Pro with automatic Display/Text optical switching. SF Pro is unavailable on Android — use the system font (Roboto) and reserve a bundled `Inter` for a tighter metric match. SF Pro Rounded (Listen Now hero cards) maps to a rounded family if you bundle one; otherwise keep Roboto. Honor font scaling everywhere (Apple Music is a flagship Dynamic Type app).
+
+```kotlin
+// ui/theme/AppleMusicType.kt
+import androidx.compose.material3.Typography
+import androidx.compose.ui.text.TextStyle
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.sp
+
+private val SF = FontFamily.Default          // swap to FontFamily(Font(R.font.inter_…))
+private val SFRounded = FontFamily.Default   // swap to a rounded family for Listen Now heroes
+
+// Named ramp — mirrors DESIGN.md §3 exactly (pt → sp 1:1)
+object AMText {
+    val LargeTitle    = TextStyle(SF, fontWeight = FontWeight.Bold,     fontSize = 34.sp, lineHeight = 37.sp, letterSpacing = 0.37.sp)
+    val Title1        = TextStyle(SF, fontWeight = FontWeight.Bold,     fontSize = 28.sp, lineHeight = 32.sp, letterSpacing = 0.36.sp)
+    val HeroListen    = TextStyle(SFRounded, fontWeight = FontWeight.Bold, fontSize = 24.sp, lineHeight = 29.sp, letterSpacing = (-0.2).sp)
+    val Title2        = TextStyle(SF, fontWeight = FontWeight.Bold,     fontSize = 22.sp, lineHeight = 26.sp, letterSpacing = (-0.26).sp)
+    val Title3        = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 20.sp, lineHeight = 24.sp, letterSpacing = (-0.15).sp)
+    val NowPlaying    = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 18.sp, lineHeight = 23.sp, letterSpacing = (-0.1).sp)
+    val Headline      = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 17.sp, lineHeight = 21.sp, letterSpacing = (-0.43).sp)
+    val Body          = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 17.sp, lineHeight = 25.sp, letterSpacing = (-0.43).sp)
+    val Callout       = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 16.sp, lineHeight = 20.sp, letterSpacing = (-0.32).sp)
+    val Subheadline   = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 15.sp, lineHeight = 20.sp, letterSpacing = (-0.24).sp)
+    val Footnote      = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 13.sp, lineHeight = 17.sp, letterSpacing = (-0.08).sp)
+    val Caption1      = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 12.sp, lineHeight = 16.sp)
+    val Caption2      = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 11.sp, lineHeight = 13.sp, letterSpacing = 0.07.sp)
+    val Button        = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 17.sp, lineHeight = 17.sp, letterSpacing = (-0.43).sp)
+    val Tab           = TextStyle(SF, fontWeight = FontWeight.Medium,   fontSize = 10.sp, lineHeight = 10.sp, letterSpacing = (-0.24).sp)
+    val LyricsCurrent = TextStyle(SF, fontWeight = FontWeight.Bold,     fontSize = 28.sp, lineHeight = 34.sp, letterSpacing = (-0.3).sp)
+    val LyricsOther   = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 22.sp, lineHeight = 29.sp, letterSpacing = (-0.2).sp)
+}
+
+// Map onto Material 3 slots so stock components inherit the brand
+val AMTypography = Typography(
+    headlineLarge  = AMText.LargeTitle,
+    headlineMedium = AMText.Title1,
+    headlineSmall  = AMText.Title3,
+    titleMedium    = AMText.Headline,
+    bodyLarge      = AMText.Body,
+    bodyMedium     = AMText.Subheadline,
+    labelLarge     = AMText.Button,
+    labelSmall     = AMText.Tab,
+)
+```
+
+## 3. Signature Components
+
+### Primary Red Play Button
+
+```kotlin
+import androidx.compose.animation.core.animateFloatAsState
+import androidx.compose.animation.core.spring
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.interaction.collectIsPressedAsState
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Pause
+import androidx.compose.material.icons.filled.PlayArrow
+import androidx.compose.material3.Icon
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.draw.scale
+import androidx.compose.ui.hapticfeedback.HapticFeedbackType
+import androidx.compose.ui.platform.LocalHapticFeedback
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+
+@Composable
+fun ApplePlayButton(
+    isPlaying: Boolean,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    size: Dp = 64.dp,
+) {
+    val interaction = remember { MutableInteractionSource() }
+    val pressed by interaction.collectIsPressedAsState()
+    val scale by animateFloatAsState(
+        if (pressed) 0.92f else 1f,
+        spring(dampingRatio = 0.75f, stiffness = 600f),
+        label = "playScale",
+    )
+    val haptics = LocalHapticFeedback.current
+
+    Box(
+        modifier = modifier
+            .size(size)
+            .scale(scale)
+            .clip(CircleShape)
+            .background(AMColors.Red)
+            .clickable(interaction, indication = null) {
+                haptics.performHapticFeedback(HapticFeedbackType.TextHandleMove) // ~iOS .soft impact
+                onClick()
+            },
+        contentAlignment = Alignment.Center,
+    ) {
+        Icon(
+            imageVector = if (isPlaying) Icons.Filled.Pause else Icons.Filled.PlayArrow,
+            contentDescription = if (isPlaying) "Pause" else "Play",
+            tint = Color.White,
+            modifier = Modifier.size(size * 0.44f),
+        )
+    }
+}
+```
+
+### Pill Button (Play / Shuffle / Join Apple Music)
+
+```kotlin
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Text
+import androidx.compose.ui.graphics.vector.ImageVector
+
+@Composable
+fun AMPillButton(
+    text: String,
+    icon: ImageVector,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    tint: Color = AMColors.Red,
+) {
+    val interaction = remember { MutableInteractionSource() }
+    val pressed by interaction.collectIsPressedAsState()
+    val scale by animateFloatAsState(if (pressed) 0.97f else 1f, label = "pillScale")
+    val haptics = LocalHapticFeedback.current
+
+    Row(
+        modifier = modifier
+            .scale(scale)
+            .clip(RoundedCornerShape(8.dp)) // soft rectangle, NOT a full pill — iOS Music signature
+            .background(if (pressed) AMColors.RedPressed else tint)
+            .clickable(interaction, indication = null) {
+                haptics.performHapticFeedback(HapticFeedbackType.TextHandleMove)
+                onClick()
+            }
+            .padding(horizontal = 24.dp, vertical = 10.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        Icon(icon, contentDescription = null, tint = Color.White, modifier = Modifier.size(15.dp))
+        Text(text, style = AMText.Button, color = Color.White)
+    }
+}
+```
+
+### Album Tile (signature 12dp corner)
+
+```kotlin
+import androidx.compose.ui.draw.shadow
+import androidx.compose.ui.layout.ContentScale
+import androidx.compose.ui.text.style.TextOverflow
+import coil.compose.AsyncImage
+
+@Composable
+fun AlbumTile(
+    artworkUrl: String,
+    title: String,
+    subtitle: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    width: Dp = 160.dp,
+    isDark: Boolean = false,
+) {
+    val haptics = LocalHapticFeedback.current
+    val interaction = remember { MutableInteractionSource() }
+    val pressed by interaction.collectIsPressedAsState()
+    val scale by animateFloatAsState(if (pressed) 0.96f else 1f, label = "tileScale")
+
+    Column(
+        modifier = modifier
+            .width(width)
+            .scale(scale)
+            .clickable(interaction, indication = null) {
+                haptics.performHapticFeedback(HapticFeedbackType.TextHandleMove) // ~iOS .selection
+                onClick()
+            },
+        verticalArrangement = Arrangement.spacedBy(6.dp),
+    ) {
+        AsyncImage(
+            model = artworkUrl,
+            contentDescription = "$title album art",
+            modifier = Modifier
+                .size(width)
+                // generous shadow in light only — dark mode uses surface steps, no shadow
+                .then(if (!isDark)
+                    Modifier.shadow(16.dp, RoundedCornerShape(12.dp),
+                        spotColor = Color.Black.copy(alpha = 0.08f)) else Modifier)
+                .clip(RoundedCornerShape(12.dp)), // signature softer-than-Spotify corner
+            contentScale = ContentScale.Crop,
+        )
+        Text(
+            title,
+            style = AMText.Subheadline.copy(fontWeight = FontWeight.SemiBold, fontSize = 15.sp),
+            color = if (isDark) AMColors.LabelDark else AMColors.LabelLight,
+            maxLines = 2, overflow = TextOverflow.Ellipsis,
+        )
+        Text(
+            subtitle,
+            style = AMText.Footnote,
+            color = (if (isDark) AMColors.SecDark else AMColors.SecLight).copy(alpha = 0.60f),
+            maxLines = 1, overflow = TextOverflow.Ellipsis,
+        )
+    }
+}
+```
+
+### Track Row (with red equalizer + Atmos badge)
+
+```kotlin
+import androidx.compose.material.icons.filled.MoreHoriz
+
+@Composable
+fun TrackRow(
+    title: String,
+    artist: String,
+    artworkUrl: String,
+    isPlaying: Boolean,
+    hasAtmos: Boolean,
+    explicit: Boolean,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    val interaction = remember { MutableInteractionSource() }
+    val pressed by interaction.collectIsPressedAsState()
+
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .height(56.dp)
+            .background(if (pressed) Color.Black.copy(alpha = 0.05f) else Color.Transparent)
+            .clickable(interaction, indication = null, onClick = onClick)
+            .padding(horizontal = 16.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(12.dp),
+    ) {
+        Box {
+            AsyncImage(
+                model = artworkUrl,
+                contentDescription = null,
+                modifier = Modifier.size(44.dp).clip(RoundedCornerShape(8.dp)),
+                contentScale = ContentScale.Crop,
+            )
+            if (isPlaying) {
+                Box(
+                    Modifier
+                        .size(18.dp)
+                        .align(Alignment.Center)
+                        .clip(RoundedCornerShape(4.dp))
+                        .background(Color.Black.copy(alpha = 0.5f)),
+                    contentAlignment = Alignment.Center,
+                ) { Equalizer(color = AMColors.Red) } // red, not Spotify green
+            }
+        }
+        Column(Modifier.weight(1f), verticalArrangement = Arrangement.spacedBy(2.dp)) {
+            Row(verticalAlignment = Alignment.CenterVertically,
+                horizontalArrangement = Arrangement.spacedBy(4.dp)) {
+                if (explicit) {
+                    Box(
+                        Modifier
+                            .clip(RoundedCornerShape(3.dp))
+                            .background(Color.Gray)
+                            .padding(horizontal = 4.dp),
+                    ) { Text("E", style = AMText.Caption2.copy(fontWeight = FontWeight.Bold),
+                        color = Color.White) }
+                }
+                Text(title, style = AMText.Body.copy(fontSize = 17.sp),
+                    color = AMColors.LabelLight, maxLines = 1, overflow = TextOverflow.Ellipsis)
+                if (hasAtmos) AtmosBadge()
+            }
+            Text(artist, style = AMText.Subheadline,
+                color = AMColors.SecLight.copy(alpha = 0.60f),
+                maxLines = 1, overflow = TextOverflow.Ellipsis)
+        }
+        Icon(Icons.Filled.MoreHoriz, contentDescription = "More",
+            tint = AMColors.SecLight.copy(alpha = 0.60f), modifier = Modifier.size(20.dp))
+    }
+}
+
+@Composable
+fun AtmosBadge() {
+    Box(
+        Modifier
+            .clip(CircleShape) // full pill
+            .background(androidx.compose.ui.graphics.Brush.verticalGradient(
+                listOf(AMColors.AtmosGold, AMColors.AtmosGold.copy(alpha = 0.85f))))
+            .padding(horizontal = 8.dp, vertical = 4.dp),
+    ) {
+        Text("Dolby Atmos",
+            style = AMText.Caption2.copy(fontWeight = FontWeight.SemiBold), color = Color.White)
+    }
+}
+```
+
+### Now Playing Hero (album-art-extracted gradient)
+
+```kotlin
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material.icons.filled.SkipNext
+import androidx.compose.material.icons.filled.SkipPrevious
+import androidx.compose.ui.graphics.Brush
+
+@Composable
+fun NowPlayingScreen(
+    trackTitle: String,
+    artist: String,
+    artworkUrl: String,
+    dominantColor: Color,       // from Palette — see §4
+    complementaryColor: Color,  // darker derived — see §4
+    isPlaying: Boolean,
+    progress: Float,
+    onPlayPause: () -> Unit,
+) {
+    Box(
+        Modifier
+            .fillMaxSize()
+            .background(Brush.verticalGradient(listOf(dominantColor, complementaryColor))),
+    ) {
+        Column(
+            Modifier.fillMaxSize().padding(horizontal = 24.dp),
+            horizontalAlignment = Alignment.CenterHorizontally,
+            verticalArrangement = Arrangement.Center,
+        ) {
+            AsyncImage(
+                model = artworkUrl,
+                contentDescription = "$trackTitle album art",
+                modifier = Modifier
+                    .size(340.dp)
+                    .shadow(40.dp, RoundedCornerShape(16.dp),
+                        spotColor = Color.Black.copy(alpha = 0.3f))
+                    .clip(RoundedCornerShape(16.dp)),
+                contentScale = ContentScale.Crop,
+            )
+            Spacer(Modifier.height(24.dp))
+            Text(trackTitle, style = AMText.NowPlaying, color = Color.White, maxLines = 1)
+            Text(artist, style = AMText.Subheadline,
+                color = Color.White.copy(alpha = 0.7f), maxLines = 1)
+            Spacer(Modifier.height(24.dp))
+            AMScrubber(progress = progress)
+            Spacer(Modifier.height(24.dp))
+            Row(verticalAlignment = Alignment.CenterVertically,
+                horizontalArrangement = Arrangement.spacedBy(32.dp)) {
+                Icon(Icons.Filled.SkipPrevious, "Previous",
+                    tint = Color.White, modifier = Modifier.size(32.dp))
+                ApplePlayButton(isPlaying = isPlaying, onClick = onPlayPause, size = 64.dp)
+                Icon(Icons.Filled.SkipNext, "Next",
+                    tint = Color.White, modifier = Modifier.size(32.dp))
+            }
+        }
+    }
+}
+
+@Composable
+fun AMScrubber(progress: Float) {
+    Box(Modifier.fillMaxWidth().height(16.dp), contentAlignment = Alignment.CenterStart) {
+        Box(Modifier.fillMaxWidth().height(4.dp).clip(CircleShape)
+            .background(Color.White.copy(alpha = 0.2f)))
+        Box(Modifier.fillMaxWidth(progress).height(4.dp).clip(CircleShape)
+            .background(AMColors.Red)) // Apple Music Red fill
+        Box(
+            Modifier
+                .fillMaxWidth(progress)
+                .height(16.dp),
+            contentAlignment = Alignment.CenterEnd,
+        ) {
+            Box(Modifier.size(16.dp).clip(CircleShape).background(Color.White)
+                .shadow(2.dp, CircleShape, spotColor = Color.Black.copy(alpha = 0.2f)))
+        }
+    }
+}
+```
+
+### Mini-Player (translucent surface — no live blur on Android)
+
+```kotlin
+import androidx.compose.material.icons.filled.SkipNext
+import androidx.compose.material3.Surface
+
+@Composable
+fun MiniPlayer(
+    trackTitle: String,
+    artist: String,
+    artworkUrl: String,
+    isPlaying: Boolean,
+    onPlayPause: () -> Unit,
+    onExpand: () -> Unit,
+    isDark: Boolean = false,
+) {
+    Surface(
+        color = (if (isDark) AMColors.Surface1Dark else AMColors.CanvasLight).copy(alpha = 0.80f),
+        tonalElevation = 0.dp,
+        modifier = Modifier.fillMaxWidth().height(64.dp).clickable(onClick = onExpand),
+    ) {
+        Row(
+            Modifier.padding(start = 12.dp, end = 12.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(12.dp),
+        ) {
+            AsyncImage(
+                model = artworkUrl, contentDescription = null,
+                modifier = Modifier.size(44.dp).clip(RoundedCornerShape(8.dp)),
+                contentScale = ContentScale.Crop,
+            )
+            Column(Modifier.weight(1f)) {
+                Text(trackTitle,
+                    style = AMText.Subheadline.copy(fontWeight = FontWeight.Medium, fontSize = 15.sp),
+                    color = if (isDark) AMColors.LabelDark else AMColors.LabelLight, maxLines = 1)
+                Text(artist, style = AMText.Footnote,
+                    color = (if (isDark) AMColors.SecDark else AMColors.SecLight).copy(alpha = 0.60f),
+                    maxLines = 1)
+            }
+            Icon(
+                if (isPlaying) Icons.Filled.Pause else Icons.Filled.PlayArrow,
+                contentDescription = if (isPlaying) "Pause" else "Play",
+                tint = if (isDark) AMColors.LabelDark else AMColors.LabelLight,
+                modifier = Modifier.size(22.dp).clickable(onClick = onPlayPause),
+            )
+            Icon(Icons.Filled.SkipNext, contentDescription = "Next",
+                tint = if (isDark) AMColors.LabelDark else AMColors.LabelLight,
+                modifier = Modifier.size(22.dp))
+        }
+    }
+}
+```
+
+## 4. Time-Synced Lyrics + Album-Art Color Extraction
+
+Apple Music's defining feature is the **time-synced lyrics view** (current line scales up + brightens, auto-scrolls to playback). iOS uses `ScrollViewReader`; Compose uses `LazyColumn` + `LaunchedEffect(currentTimeMs)` + `animateScrollToItem`. Line size/opacity animate via `animateFloatAsState`.
+
+```kotlin
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.foundation.lazy.rememberLazyListState
+
+data class LyricLine(val startMs: Long, val endMs: Long, val text: String)
+
+@Composable
+fun LyricsView(lines: List<LyricLine>, currentTimeMs: Long, gradient: Brush) {
+    val listState = rememberLazyListState()
+    val currentIndex = lines.indexOfLast { currentTimeMs >= it.startMs }
+
+    LaunchedEffect(currentIndex) {
+        if (currentIndex >= 0) listState.animateScrollToItem(
+            index = currentIndex.coerceAtLeast(0),
+            scrollOffset = -300, // keep the active line centered
+        )
+    }
+
+    LazyColumn(
+        state = listState,
+        modifier = Modifier.fillMaxSize().background(gradient),
+        contentPadding = PaddingValues(horizontal = 24.dp, vertical = 80.dp),
+        verticalArrangement = Arrangement.spacedBy(24.dp),
+    ) {
+        itemsIndexed(lines) { i, line ->
+            val isCurrent = i == currentIndex
+            val isPast = i < currentIndex
+            val targetAlpha = when {
+                isCurrent -> 1f
+                isPast    -> 0.3f   // faded above
+                else      -> 0.6f   // upcoming below
+            }
+            val alpha by animateFloatAsState(targetAlpha,
+                spring(dampingRatio = 0.85f), label = "lyricAlpha")
+            Text(
+                line.text,
+                style = if (isCurrent) AMText.LyricsCurrent else AMText.LyricsOther,
+                color = Color.White.copy(alpha = alpha),
+            )
+        }
+    }
+}
+```
+
+Album-art color extraction (the Now Playing / Lyrics gradient): Android's analog to iOS Core Image `CIAreaAverage` is **AndroidX Palette**. Load with Coil (software bitmap), pull a vibrant swatch as the dominant, and derive a darker complementary by scaling RGB — exactly Apple Music's "primary at top, darker complementary at bottom".
+
+```kotlin
+// build.gradle: implementation("androidx.palette:palette-ktx:1.0.0")
+import android.content.Context
+import android.graphics.drawable.BitmapDrawable
+import androidx.palette.graphics.Palette
+import coil.imageLoader
+import coil.request.ImageRequest
+
+suspend fun extractGradient(context: Context, url: String): Pair<Color, Color> {
+    val request = ImageRequest.Builder(context)
+        .data(url)
+        .allowHardware(false) // Palette needs a software bitmap
+        .build()
+    val bitmap = (context.imageLoader.execute(request).drawable as? BitmapDrawable)?.bitmap
+        ?: return AMColors.CanvasDark to AMColors.CanvasDark
+    val palette = Palette.from(bitmap).generate()
+    val rgb = (palette.vibrantSwatch ?: palette.dominantSwatch)?.rgb
+        ?: return AMColors.CanvasDark to AMColors.CanvasDark
+    val dominant = Color(rgb)
+    val complementary = Color( // darker derived variant
+        red = dominant.red * 0.4f,
+        green = dominant.green * 0.4f,
+        blue = dominant.blue * 0.4f,
+    )
+    return dominant to complementary
+}
+```
+
+Hoist into a `ViewModel` and cache per track so scrubbing never re-computes:
+
+```kotlin
+val gradient by produceState(AMColors.CanvasDark to AMColors.CanvasDark, artworkUrl) {
+    value = extractGradient(context, artworkUrl)
+}
+```
+
+The mini-player → Now Playing artwork morph is Compose `SharedTransitionLayout` + `Modifier.sharedElement()` (Compose 1.7+) on the 44dp ↔ 340dp artwork; fall back to `AnimatedVisibility` + `scaleIn` over a 0.35s `spring(dampingRatio = 0.8f)`.
+
+## 5. Bottom Navigation (Tab Bar)
+
+Use Material 3 `NavigationBar`. Apple Music's iOS tab bar is `.regularMaterial` blur; Android has no first-class live blur, so use an 80%-opaque canvas surface. **Active tint is Apple Music Red** (distinctive — most apps use the system accent for the tab indicator). Five tabs, always labeled.
+
+```kotlin
+import androidx.compose.material.icons.filled.*
+import androidx.compose.material3.NavigationBar
+import androidx.compose.material3.NavigationBarItem
+import androidx.compose.material3.NavigationBarItemDefaults
+
+@Composable
+fun AppleMusicBottomBar(selected: Int, onSelect: (Int) -> Unit, isDark: Boolean = false) {
+    NavigationBar(
+        containerColor = (if (isDark) AMColors.CanvasDark else AMColors.CanvasLight)
+            .copy(alpha = 0.80f),
+        tonalElevation = 0.dp,
+    ) {
+        val items = listOf(
+            "Home"    to Icons.Filled.Home,
+            "New"     to Icons.Filled.LibraryMusic,
+            "Radio"   to Icons.Filled.Podcasts,
+            "Library" to Icons.Filled.LibraryBooks,
+            "Search"  to Icons.Filled.Search,
+        )
+        items.forEachIndexed { i, (label, icon) ->
+            NavigationBarItem(
+                selected = selected == i,
+                onClick = { onSelect(i) },
+                icon = { Icon(icon, contentDescription = label, modifier = Modifier.size(25.dp)) },
+                label = { Text(label, style = AMText.Tab) },
+                colors = NavigationBarItemDefaults.colors(
+                    selectedIconColor = AMColors.Red,   // Apple Music Red, not system accent
+                    selectedTextColor = AMColors.Red,
+                    unselectedIconColor = (if (isDark) AMColors.SecDark else AMColors.SecLight)
+                        .copy(alpha = 0.60f),
+                    unselectedTextColor = (if (isDark) AMColors.SecDark else AMColors.SecLight)
+                        .copy(alpha = 0.60f),
+                    indicatorColor = Color.Transparent, // no Material pill — Apple Music has none
+                ),
+            )
+        }
+    }
+}
+```
+
+The persistent **mini-player** sits directly above this bar — render it in the `Scaffold` `bottomBar` slot stacked above `AppleMusicBottomBar`. The collapsing iOS large-title nav maps to `LargeTopAppBar` + `exitUntilCollapsedScrollBehavior()` (34sp → 17sp on scroll).
+
+## 6. Motion
+
+| Moment | Compose recipe |
+|--------|----------------|
+| Play button tap | `animateFloatAsState` 1 → 0.92 `spring(dampingRatio = 0.75f)`; `HapticFeedbackType.TextHandleMove` (~iOS `.soft`) |
+| Track change on Now Playing | `Crossfade` artwork with scale 0.98 → 1 over 400ms |
+| Mini-player → full Now Playing | `SharedTransitionLayout` 44 → 340dp, 0.35s `spring(dampingRatio = 0.8f)`; fallback `scaleIn` |
+| Equalizer bars | `rememberInfiniteTransition` 3 bars' `fillMaxHeight`, frozen when paused |
+| Lyrics scroll | active line `animateFloatAsState` alpha 0.6 → 1, size 22 → 28sp, ~300ms, sync to audio |
+| Heart like | `Animatable` 1 → 1.2 → 1 over 300ms, fill → Red; `HapticFeedbackType.LongPress` (~`.success`) |
+| Shuffle toggle | `animateColorAsState` secondary → Red, 200ms; selection haptic |
+| Long-press tile | scale → 0.96 + haptic; context menu via `DropdownMenu` |
+
+```kotlin
+// Equalizer — red bars on the currently-playing row
+@Composable
+fun Equalizer(color: Color, playing: Boolean = true) {
+    val t = rememberInfiniteTransition(label = "eq")
+    Row(horizontalArrangement = Arrangement.spacedBy(2.dp)) {
+        repeat(3) { i ->
+            val h by t.animateFloat(
+                0.3f, 1f,
+                infiniteRepeatable(tween(400 + i * 120), RepeatMode.Reverse),
+                label = "bar$i",
+            )
+            Box(
+                Modifier
+                    .width(3.dp)
+                    .fillMaxHeight(if (playing) h else 0.3f)
+                    .background(color),
+            )
+        }
+    }
+}
+```
+
+Haptics: prefer `LocalHapticFeedback`. For richer control use `LocalView.current.performHapticFeedback(HapticFeedbackConstants.CONTEXT_CLICK)` (API 30+) — map `.soft` (Play) to `VibrationEffect.createOneShot(10, ...)`, `.success` (heart like) to a double-buzz `VibrationEffect.createWaveform(longArrayOf(0, 40, 60, 40), -1)`, and `.selection` (shuffle / tab / chip) to a short tick.
+
+## 7. Icons
+
+Apple Music uses SF Symbols exclusively; the closest first-party set is `androidx.compose.material:material-icons-extended`. The explicit `E` badge is a custom rounded-rect composable (shown in §3); ship any non-matching glyph as a vector drawable via `ImageVector.vectorResource(R.drawable.…)`.
+
+| Component | SF Symbol (iOS) | Material Icon (Compose) |
+|-----------|-----------------|--------------------------|
+| Play | `play.fill` | `Icons.Filled.PlayArrow` |
+| Pause | `pause.fill` | `Icons.Filled.Pause` |
+| Forward / Previous | `forward.fill` / `backward.fill` | `Icons.Filled.SkipNext` / `SkipPrevious` |
+| Shuffle | `shuffle` | `Icons.Filled.Shuffle` |
+| Repeat | `repeat` / `repeat.1` | `Icons.Filled.Repeat` / `RepeatOne` |
+| Heart | `heart` / `heart.fill` | `Icons.Outlined.FavoriteBorder` / `Icons.Filled.Favorite` |
+| Download | `arrow.down.circle` | `Icons.Filled.DownloadForOffline` |
+| Share | `square.and.arrow.up` | `Icons.Filled.IosShare` |
+| More | `ellipsis` | `Icons.Filled.MoreHoriz` |
+| Search | `magnifyingglass` | `Icons.Filled.Search` |
+| Home (Listen Now) | `house` / `house.fill` | `Icons.Filled.Home` |
+| New (Browse) | `music.note.list` | `Icons.Filled.LibraryMusic` |
+| Radio | `dot.radiowaves.left.and.right` | `Icons.Filled.Podcasts` |
+| Library | `square.stack` | `Icons.Filled.LibraryBooks` |
+| Lyrics | `quote.bubble` | `Icons.Filled.Lyrics` |
+| AirPlay | `airplayaudio` | `Icons.Filled.Cast` |
+| Queue | `list.bullet` | `Icons.AutoMirrored.Filled.QueueMusic` |
+| Chevron | `chevron.right` | `Icons.AutoMirrored.Filled.KeyboardArrowRight` |
+| Explicit | custom 'E' in rounded rect | custom composable (see §3) |
+
+## 8. Minimum SDK & Accessibility Notes
+
+- **minSdk 24** (Compose floor is 21; Palette + `SharedTransitionLayout` + modern motion are comfortable at 24). `compileSdk 34+`, Compose BOM `2024.09+`, Kotlin `2.0+`.
+- **Edge-to-edge**: call `enableEdgeToEdge()` in the `Activity`. Light canvas wants dark-content (dark icons) system bars; the true-black dark canvas wants light-content. Now Playing's full-bleed gradient should draw under the system bars. Apply `Scaffold` insets so the mini-player clears the gesture nav.
+- **Font scaling**: Apple Music is a flagship Dynamic Type app — `sp` honors the user's font scale; keep it on track titles, artist names, headers, body, and lyrics (current line scales up to ~36sp). Pin layout-sensitive geometry (the 64dp play glyph, scrubber thumb, mini-player frame, 10sp tab labels) by deriving from `dp` or `CompositionLocalProvider(LocalDensity provides Density(density, fontScale = 1f))`. At the largest scales the mini-player drops text and shows only artwork + play.
+- **TalkBack**: the Play button reads `"Play Blinding Lights by The Weeknd"`; the heart reads `"Add to Favorites"` / `"Remove from Favorites"`. Merge track-row text with `Modifier.semantics(mergeDescendants = true)` and mark the trailing ellipsis as a separate button. Lyrics lines expose their text; the current line can announce via `liveRegion`.
+- **Touch targets**: Material guidance is 48.dp minimum. The 64dp Now Playing play button is well clear; inline play buttons and tab items are 44–49dp — bump the 20dp ellipsis and 22dp mini-player controls to a 48.dp hit box via padding.
+- **Contrast**: pure black on white (and white on true black) is WCAG AAA. Secondary at 60% (`#3C3C43`@60% light / `#EBEBF5`@60% dark) passes AA at ≥14sp Medium — acceptable for artist/metadata, not for primary information at small sizes.
+- **Reduce motion**: when `Settings.Global.ANIMATOR_DURATION_SCALE == 0f`, skip the mini-player spring expansion (use a `Crossfade`), freeze the equalizer, and render the current lyric line plainly without the scale animation.
+- **Dynamic color**: do **not** enable Material You `dynamicColorScheme()` — Apple Music Red `#FA2D48`, the true-black `#000000` dark canvas, and the 12dp album corner are signature, intentionally system-Apple choices that must not recolor to the user's wallpaper. The Now Playing gradient comes from album art (Palette), never from the system accent.