designmd-forge 1.2.0

package/dist/data/designs/ios-headspace-android.md

@@ -0,0 +1,688 @@
+# Headspace (iOS) — Jetpack Compose Implementation Guide
+
+Companion to [DESIGN.md](DESIGN.md) — the framework-neutral spec. This file ports Headspace's visual language to **Android with Jetpack Compose (Material 3)**: a color token object, a `Typography` set, paste-ready `@Composable`s, the breathing sphere, the Aurora wash, and haptics.
+
+> Why a Compose guide for an iOS-referenced app? The DESIGN.md tokens are platform-neutral. This file keeps the *visual* identity (Headspace's butter-cream canvas, Marigold accent, the breathing meditation sphere, illustration-companion warmth) while making everything idiomatic Android — `NavigationBar` instead of a UITabBar, a translucent `Surface` instead of iOS blur, `sp`/`dp` instead of `pt`, and an `Animatable`-driven 4-2-4-2 breath cycle instead of SwiftUI's `withAnimation`.
+
+Assumes Compose BOM `2024.09+`, Kotlin `2.0+`, `minSdk 24`, Material 3, and [Coil](https://coil-kt.github.io/coil/) `2.6+` for the illustration assets (PNG @2x/@3x equivalents bundled as drawables or loaded remotely). Headspace does no runtime color extraction, so no Palette dependency is needed.
+
+## 1. Color Tokens
+
+```kotlin
+// ui/theme/HeadspaceColors.kt
+import androidx.compose.ui.graphics.Color
+
+object HeadspaceColors {
+    // Canvas & Surfaces (light / default mode)
+    val ButterCream  = Color(0xFFFFF7E7)
+    val OffCream     = Color(0xFFFBF1DA)
+    val WarmGray     = Color(0xFFE8DFC9)
+    val SurfaceWhite = Color(0xFFFFFFFF)
+
+    // Brand — Marigold
+    val Marigold        = Color(0xFFFF6B35)
+    val MarigoldPressed = Color(0xFFE55A2B)
+    val MarigoldLight   = Color(0xFFFFB89E)
+
+    // Aurora gradient stops (signature dawn wash)
+    val Aurora1 = Color(0xFFFFB89E) // peachy dawn (top)
+    val Aurora2 = Color(0xFFFFD25C) // butter sun (mid)
+    val Aurora3 = Color(0xFFFF6B35) // marigold morning (bottom)
+
+    // Secondary accents
+    val Butter      = Color(0xFFFFD25C)
+    val SageMoss    = Color(0xFF7E9F4B)
+    val SageLight   = Color(0xFFB4C68F)
+    val CoralFlush  = Color(0xFFF4877E)
+    val SkyLavender = Color(0xFFB7B0DC)
+
+    // Text — Ink Brown (warm purple-brown, never harsh black)
+    val InkBrown     = Color(0xFF2E1A47)
+    val InkBrownSoft = Color(0xFF594675)
+    val InkBrownMute = Color(0xFF8E7DA5)
+
+    // Dusk (Sleep mode)
+    val DuskCanvas   = Color(0xFF1A1430)
+    val DuskSurface1 = Color(0xFF2A2046)
+    val DuskSurface2 = Color(0xFF3A2F5C)
+    val DuskDivider  = Color(0xFF3F3460)
+
+    // Semantic
+    val Success      = Color(0xFF7E9F4B) // same as Sage
+    val Warning      = Color(0xFFFF9F4A)
+    val ErrorCoral   = Color(0xFFE04646)
+
+    // Milestone
+    val MilestoneGold = Color(0xFFE5B85C)
+}
+```
+
+Headspace's default mode is the warm butter-cream light surface, so wire a Material 3 `lightColorScheme` so ripples, dividers, and default component colors inherit the brand. Provide a separate dusk scheme for Sleep mode rather than relying on Android's `isSystemInDarkTheme()` — the dusk world is a deliberate in-app mode, not a system preference.
+
+```kotlin
+// ui/theme/Theme.kt
+import androidx.compose.material3.lightColorScheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.MaterialTheme
+
+private val HeadspaceLight = lightColorScheme(
+    primary        = HeadspaceColors.Marigold,
+    onPrimary      = HeadspaceColors.SurfaceWhite,
+    background     = HeadspaceColors.ButterCream,
+    onBackground   = HeadspaceColors.InkBrown,
+    surface        = HeadspaceColors.OffCream,
+    onSurface      = HeadspaceColors.InkBrown,
+    surfaceVariant = HeadspaceColors.WarmGray,
+    outline        = HeadspaceColors.WarmGray,
+    error          = HeadspaceColors.ErrorCoral,
+)
+
+private val HeadspaceDusk = darkColorScheme(
+    primary        = HeadspaceColors.SageMoss,   // Sage is the Sleep accent, not Marigold
+    onPrimary      = HeadspaceColors.ButterCream,
+    background     = HeadspaceColors.DuskCanvas,
+    onBackground   = HeadspaceColors.ButterCream,
+    surface        = HeadspaceColors.DuskSurface1,
+    onSurface      = HeadspaceColors.ButterCream,
+    surfaceVariant = HeadspaceColors.DuskSurface2,
+    outline        = HeadspaceColors.DuskDivider,
+)
+
+@Composable
+fun HeadspaceTheme(sleepMode: Boolean = false, content: @Composable () -> Unit) =
+    MaterialTheme(
+        colorScheme = if (sleepMode) HeadspaceDusk else HeadspaceLight,
+        typography  = HeadspaceTypography,
+        content     = content,
+    )
+```
+
+## 2. Typography
+
+Apercu is licensed via Colophon Foundry. Drop the TTFs in `res/font/` (lowercase, snake_case) and build a `FontFamily`. Fall back to `Nunito` (the closest soft humanist sans on Google Fonts, sharing Apercu's curled 'a'); the system default Roboto is a colder last resort.
+
+```kotlin
+// ui/theme/HeadspaceType.kt
+import androidx.compose.material3.Typography
+import androidx.compose.ui.text.TextStyle
+import androidx.compose.ui.text.font.Font
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.sp
+
+val Apercu = FontFamily(
+    Font(R.font.apercu_light,   FontWeight.Light),    // 300
+    Font(R.font.apercu_regular, FontWeight.Normal),   // 400
+    Font(R.font.apercu_medium,  FontWeight.Medium),   // 500
+    Font(R.font.apercu_bold,    FontWeight.Bold),     // 700
+    Font(R.font.apercu_black,   FontWeight.Black),    // 900
+)
+
+// Named ramp — mirrors DESIGN.md §3 exactly (pt → sp 1:1, title case only)
+object HeadspaceText {
+    val GreetingHero = TextStyle(Apercu, fontWeight = FontWeight.Bold,   fontSize = 32.sp, lineHeight = 38.sp, letterSpacing = (-0.3).sp)
+    val ScreenTitle  = TextStyle(Apercu, fontWeight = FontWeight.Bold,   fontSize = 28.sp, lineHeight = 34.sp, letterSpacing = (-0.3).sp)
+    val MedTitle     = TextStyle(Apercu, fontWeight = FontWeight.Bold,   fontSize = 22.sp, lineHeight = 29.sp, letterSpacing = (-0.2).sp)
+    val SectionHdr   = TextStyle(Apercu, fontWeight = FontWeight.Bold,   fontSize = 18.sp, lineHeight = 23.sp, letterSpacing = (-0.1).sp)
+    val CardTitle    = TextStyle(Apercu, fontWeight = FontWeight.Medium, fontSize = 17.sp, lineHeight = 22.sp, letterSpacing = (-0.1).sp)
+    val Body         = TextStyle(Apercu, fontWeight = FontWeight.Normal, fontSize = 16.sp, lineHeight = 24.sp) // generous 1.5
+    val BodyBold     = TextStyle(Apercu, fontWeight = FontWeight.Medium, fontSize = 16.sp, lineHeight = 24.sp)
+    val Guidance     = TextStyle(Apercu, fontWeight = FontWeight.Normal, fontSize = 22.sp, lineHeight = 31.sp) // play-screen breath text
+    val Meta         = TextStyle(Apercu, fontWeight = FontWeight.Normal, fontSize = 13.sp, lineHeight = 17.sp)
+    val TagPill      = TextStyle(Apercu, fontWeight = FontWeight.Medium, fontSize = 13.sp, lineHeight = 13.sp, letterSpacing = 0.2.sp)
+    val Caption      = TextStyle(Apercu, fontWeight = FontWeight.Normal, fontSize = 11.sp, lineHeight = 14.sp)
+    val Tab          = TextStyle(Apercu, fontWeight = FontWeight.Medium, fontSize = 11.sp, lineHeight = 11.sp, letterSpacing = 0.1.sp)
+    val Button       = TextStyle(Apercu, fontWeight = FontWeight.Medium, fontSize = 17.sp, lineHeight = 17.sp) // Medium, not Bold
+    val TimerLarge   = TextStyle(Apercu, fontWeight = FontWeight.Bold,   fontSize = 56.sp, lineHeight = 56.sp, letterSpacing = (-0.5).sp)
+    val StreakNumber = TextStyle(Apercu, fontWeight = FontWeight.Bold,   fontSize = 22.sp, lineHeight = 22.sp)
+}
+
+// Map onto Material 3 slots so stock components inherit the brand
+val HeadspaceTypography = Typography(
+    headlineLarge  = HeadspaceText.GreetingHero,
+    headlineMedium = HeadspaceText.ScreenTitle,
+    titleLarge     = HeadspaceText.MedTitle,
+    titleMedium    = HeadspaceText.CardTitle,
+    bodyMedium     = HeadspaceText.Body,
+    labelSmall     = HeadspaceText.Tab,
+)
+```
+
+Set `TimerLarge` and `StreakNumber` digits to align by wrapping the host in `CompositionLocalProvider(LocalTextStyle …)` with `TextStyle(fontFeatureSettings = "tnum")` — Compose has no `monospacedDigit()` shorthand; `fontFeatureSettings = "tnum"` is the equivalent.
+
+## 3. Signature Components
+
+### Breathing Sphere (the hero component)
+
+Headspace's signature move. Drive the 4-2-4-2 cadence with a coroutine + `Animatable` rather than `rememberInfiniteTransition` so the hold phases are exact. **Pure tween easing — never a spring** (springs feel digital and break the meditative tone).
+
+```kotlin
+import androidx.compose.animation.core.Animatable
+import androidx.compose.animation.core.tween
+import androidx.compose.animation.core.EaseInOut
+import androidx.compose.foundation.Canvas
+import androidx.compose.runtime.*
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+
+@Composable
+fun BreathingSphere(
+    diameter: Dp,
+    modifier: Modifier = Modifier,
+    animate: Boolean = true, // pass false when Reduce Motion is on
+) {
+    val scale = remember { Animatable(1f) }
+
+    LaunchedEffect(animate) {
+        if (!animate) { scale.snapTo(1f); return@LaunchedEffect }
+        while (true) {
+            scale.animateTo(1.04f, tween(4000, easing = EaseInOut)) // 4s inhale
+            kotlinx.coroutines.delay(2000)                          // 2s hold high
+            scale.animateTo(0.96f, tween(4000, easing = EaseInOut)) // 4s exhale
+            scale.snapTo(1f)
+            kotlinx.coroutines.delay(2000)                          // 2s hold neutral
+        }
+    }
+
+    Canvas(
+        modifier
+            .size(diameter)
+            .graphicsLayer { scaleX = scale.value; scaleY = scale.value }
+    ) {
+        val r = size.minDimension / 2f
+        drawCircle(
+            brush = Brush.radialGradient(
+                colorStops = arrayOf(
+                    0.0f to HeadspaceColors.Aurora1,        // top-left highlight
+                    0.70f to HeadspaceColors.Marigold,
+                    1.0f to HeadspaceColors.MarigoldPressed, // bottom-right shadow
+                ),
+                center = Offset(size.width * 0.32f, size.height * 0.32f),
+                radius = r * 1.4f,
+            ),
+            radius = r,
+        )
+        drawCircle(
+            color = HeadspaceColors.InkBrown.copy(alpha = 0.08f),
+            radius = r,
+            style = androidx.compose.ui.graphics.drawscope.Stroke(width = 1.dp.toPx()),
+        )
+    }
+}
+```
+
+### Aurora Gradient Background (Today hero)
+
+```kotlin
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.*
+
+@Composable
+fun AuroraBackground(modifier: Modifier = Modifier, content: @Composable BoxScope.() -> Unit) {
+    Box(
+        modifier.background(
+            Brush.verticalGradient(
+                listOf(HeadspaceColors.Aurora1, HeadspaceColors.Aurora2, HeadspaceColors.Aurora3)
+            )
+        ),
+        content = content,
+    )
+}
+```
+
+### Today Hero
+
+```kotlin
+import androidx.compose.material3.Text
+
+@Composable
+fun TodayHero(greeting: String, vibe: String) {
+    AuroraBackground(Modifier.fillMaxWidth().height(280.dp)) {
+        Column(
+            Modifier
+                .align(Alignment.TopStart)
+                .statusBarsPadding()
+                .padding(start = 24.dp, end = 24.dp, top = 16.dp),
+            verticalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            Text(greeting, style = HeadspaceText.GreetingHero, color = HeadspaceColors.InkBrown)
+            Text(
+                "Today's vibe: $vibe",
+                style = HeadspaceText.Body,
+                color = HeadspaceColors.InkBrown.copy(alpha = 0.8f),
+            )
+        }
+    }
+}
+```
+
+### Primary Action Button (gentle warm glow)
+
+```kotlin
+import androidx.compose.animation.core.animateFloatAsState
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.interaction.collectIsPressedAsState
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.ui.draw.scale
+import androidx.compose.ui.draw.shadow
+import androidx.compose.ui.hapticfeedback.HapticFeedbackType
+import androidx.compose.ui.platform.LocalHapticFeedback
+
+@Composable
+fun HeadspaceCTAButton(
+    title: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    val interaction = remember { MutableInteractionSource() }
+    val pressed by interaction.collectIsPressedAsState()
+    val scale by animateFloatAsState(if (pressed) 0.98f else 1f, label = "ctaScale")
+    val haptics = LocalHapticFeedback.current
+    val shape = RoundedCornerShape(28.dp) // full pill on a 56.dp button
+
+    Box(
+        modifier
+            .fillMaxWidth()
+            .padding(horizontal = 24.dp)
+            .scale(scale)
+            .height(56.dp)
+            .shadow(16.dp, shape, spotColor = HeadspaceColors.Marigold.copy(alpha = 0.25f)) // sunrise glow
+            .clip(shape)
+            .background(if (pressed) HeadspaceColors.MarigoldPressed else HeadspaceColors.Marigold)
+            .clickable(interaction, indication = null) {
+                haptics.performHapticFeedback(HapticFeedbackType.LongPress) // ≈ iOS soft impact
+                onClick()
+            },
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(title, style = HeadspaceText.Button, color = HeadspaceColors.SurfaceWhite)
+    }
+}
+```
+
+### Meditation Session Card
+
+```kotlin
+import androidx.compose.foundation.layout.Box
+import androidx.compose.ui.layout.ContentScale
+import androidx.compose.ui.text.style.TextOverflow
+import coil.compose.AsyncImage
+
+@Composable
+fun MeditationCard(
+    illustrationUrl: String,
+    tag: String,
+    title: String,
+    host: String,
+    duration: String,
+    modifier: Modifier = Modifier,
+) {
+    Box(
+        modifier
+            .fillMaxWidth()
+            .padding(horizontal = 24.dp)
+            .height(200.dp)
+            .shadow(16.dp, RoundedCornerShape(24.dp), spotColor = HeadspaceColors.InkBrown.copy(alpha = 0.08f))
+            .clip(RoundedCornerShape(24.dp)),
+    ) {
+        AsyncImage(
+            model = illustrationUrl,
+            contentDescription = null,
+            modifier = Modifier.matchParentSize(),
+            contentScale = ContentScale.Crop,
+        )
+        Box(
+            Modifier.matchParentSize().background(
+                Brush.verticalGradient(listOf(Color.Transparent, HeadspaceColors.InkBrown.copy(alpha = 0.6f)))
+            )
+        )
+        Column(
+            Modifier.align(Alignment.BottomStart).padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            Box(
+                Modifier
+                    .clip(RoundedCornerShape(percent = 50))
+                    .background(Color.White.copy(alpha = 0.25f))
+                    .padding(horizontal = 12.dp, vertical = 4.dp)
+            ) {
+                Text(tag, style = HeadspaceText.TagPill, color = Color.White)
+            }
+            Text(title, style = HeadspaceText.MedTitle, color = Color.White)
+            Text(
+                "$host · $duration",
+                style = HeadspaceText.Meta,
+                color = Color.White.copy(alpha = 0.85f),
+                maxLines = 1, overflow = TextOverflow.Ellipsis,
+            )
+        }
+    }
+}
+```
+
+### Quick Action Tile
+
+```kotlin
+@Composable
+fun QuickActionTile(
+    tileColor: Color,
+    illustrationUrl: String,
+    title: String,
+    subtitle: String,
+) {
+    val interaction = remember { MutableInteractionSource() }
+    val pressed by interaction.collectIsPressedAsState()
+    val scale by animateFloatAsState(if (pressed) 0.98f else 1f, label = "tileScale")
+    val haptics = LocalHapticFeedback.current
+
+    Column(
+        Modifier
+            .scale(scale)
+            .size(width = 140.dp, height = 180.dp)
+            .clip(RoundedCornerShape(20.dp))
+            .background(tileColor)
+            .clickable(interaction, indication = null) {
+                haptics.performHapticFeedback(HapticFeedbackType.LongPress)
+            }
+            .padding(16.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        AsyncImage(
+            model = illustrationUrl,
+            contentDescription = null,
+            modifier = Modifier.size(64.dp),
+        )
+        Text(title, style = HeadspaceText.CardTitle, color = HeadspaceColors.InkBrown)
+        Text(subtitle, style = HeadspaceText.Meta, color = HeadspaceColors.InkBrown.copy(alpha = 0.7f))
+    }
+}
+```
+
+### Player Controls
+
+```kotlin
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Pause
+import androidx.compose.material.icons.filled.PlayArrow
+import androidx.compose.material.icons.filled.Replay10
+import androidx.compose.material.icons.filled.Forward10
+import androidx.compose.material3.Icon
+
+@Composable
+fun PlayerControls(
+    isPlaying: Boolean,
+    onPlayPause: () -> Unit,
+    onSkipBack: () -> Unit,
+    onSkipForward: () -> Unit,
+) {
+    val haptics = LocalHapticFeedback.current
+    Row(
+        horizontalArrangement = Arrangement.spacedBy(32.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        CircleControl(Icons.Filled.Replay10, "Skip back 15 seconds", onSkipBack)
+        Box(
+            Modifier
+                .size(72.dp)
+                .clip(CircleShape)
+                .background(HeadspaceColors.Marigold)
+                .shadow(16.dp, CircleShape, spotColor = HeadspaceColors.Marigold.copy(alpha = 0.25f))
+                .clickable(indication = null, interactionSource = remember { MutableInteractionSource() }) {
+                    haptics.performHapticFeedback(HapticFeedbackType.LongPress)
+                    onPlayPause()
+                },
+            contentAlignment = Alignment.Center,
+        ) {
+            Icon(
+                if (isPlaying) Icons.Filled.Pause else Icons.Filled.PlayArrow,
+                contentDescription = if (isPlaying) "Pause" else "Play",
+                tint = HeadspaceColors.SurfaceWhite,
+                modifier = Modifier.size(28.dp),
+            )
+        }
+        CircleControl(Icons.Filled.Forward10, "Skip forward 15 seconds", onSkipForward)
+    }
+}
+
+@Composable
+private fun CircleControl(
+    icon: androidx.compose.ui.graphics.vector.ImageVector,
+    label: String,
+    onClick: () -> Unit,
+) {
+    Box(
+        Modifier
+            .size(48.dp)
+            .clip(CircleShape)
+            .background(HeadspaceColors.OffCream)
+            .clickable(onClick = onClick),
+        contentAlignment = Alignment.Center,
+    ) {
+        Icon(icon, contentDescription = label, tint = HeadspaceColors.InkBrown, modifier = Modifier.size(22.dp))
+    }
+}
+```
+
+### Streak Ring (Profile)
+
+```kotlin
+@Composable
+fun StreakRing(currentStreak: Int, goal: Int = 30, modifier: Modifier = Modifier) {
+    val target = (currentStreak.toFloat() / goal).coerceIn(0f, 1f)
+    val progress = remember { Animatable(0f) }
+    val haptics = LocalHapticFeedback.current
+
+    LaunchedEffect(target) {
+        progress.animateTo(target, tween(1200, easing = EaseInOut))
+        haptics.performHapticFeedback(HapticFeedbackType.LongPress) // soft success
+    }
+
+    Box(Modifier.size(120.dp), contentAlignment = Alignment.Center) {
+        Canvas(Modifier.fillMaxSize()) {
+            val sw = 8.dp.toPx()
+            drawCircle(HeadspaceColors.OffCream, style = androidx.compose.ui.graphics.drawscope.Stroke(sw))
+            drawArc(
+                color = HeadspaceColors.Marigold,
+                startAngle = -90f,
+                sweepAngle = 360f * progress.value,
+                useCenter = false,
+                style = androidx.compose.ui.graphics.drawscope.Stroke(sw, cap = androidx.compose.ui.graphics.StrokeCap.Round),
+            )
+        }
+        Column(horizontalAlignment = Alignment.CenterHorizontally) {
+            Text("$currentStreak", style = HeadspaceText.TimerLarge, color = HeadspaceColors.InkBrown)
+            Text("days", style = HeadspaceText.Meta, color = HeadspaceColors.InkBrownSoft)
+        }
+    }
+}
+```
+
+### Mood Tag Row
+
+```kotlin
+import androidx.compose.animation.core.spring
+import androidx.compose.animation.core.Spring
+
+@Composable
+fun MoodTag(emoji: String, label: String, selected: Boolean, onToggle: () -> Unit) {
+    val scale by animateFloatAsState(
+        if (selected) 1.05f else 1f,
+        spring(dampingRatio = 0.7f, stiffness = Spring.StiffnessMedium),
+        label = "moodScale",
+    )
+    val haptics = LocalHapticFeedback.current
+
+    Column(
+        Modifier
+            .scale(scale)
+            .size(width = 80.dp, height = 88.dp)
+            .clip(RoundedCornerShape(16.dp))
+            .background(if (selected) HeadspaceColors.Butter else HeadspaceColors.OffCream)
+            .clickable {
+                haptics.performHapticFeedback(HapticFeedbackType.TextHandleMove) // ≈ iOS selection
+                onToggle()
+            },
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.Center,
+    ) {
+        Text(emoji, fontSize = 32.sp)
+        Spacer(Modifier.height(6.dp))
+        Text(label, style = HeadspaceText.Meta, color = HeadspaceColors.InkBrown)
+    }
+}
+```
+
+## 4. Breathing Meditation Sphere — the distinctive system
+
+Headspace does no color extraction; its most distinctive interaction is the **234pt breathing sphere on a 12-second 4-2-4-2 cycle** (≈234.dp on a 390.dp-wide phone — 60% of screen width). The implementation lives in §3 (`BreathingSphere`). The full play screen composes it with guidance text above and the countdown below, on a butter-cream canvas with 80.dp of clearance so the sphere feels uncrowded.
+
+```kotlin
+@Composable
+fun PlayScreen(
+    guidanceText: String, // "Take a deep breath in..."
+    remaining: String,    // "10:00"
+    isPlaying: Boolean,
+    onPlayPause: () -> Unit,
+    reduceMotion: Boolean = false,
+) {
+    Column(
+        Modifier
+            .fillMaxSize()
+            .background(HeadspaceColors.ButterCream)
+            .padding(horizontal = 24.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.Center,
+    ) {
+        Text(
+            guidanceText,
+            style = HeadspaceText.Guidance,
+            color = HeadspaceColors.InkBrown,
+            modifier = Modifier.padding(bottom = 80.dp),
+        )
+        BreathingSphere(diameter = 234.dp, animate = !reduceMotion)
+        Spacer(Modifier.height(80.dp))
+        Text(remaining, style = HeadspaceText.TimerLarge, color = HeadspaceColors.InkBrown)
+        Spacer(Modifier.height(48.dp))
+        PlayerControls(isPlaying, onPlayPause, {}, {})
+    }
+}
+```
+
+A thin progress arc renders at the very top of the screen (`Canvas` `drawArc`, Sage `#7E9F4B` fill over a Warm Gray `#E8DFC9` track, 2.dp stroke, round caps) — overlay it in a `Box` above the `Column`.
+
+## 5. Navigation (Bottom Tab Bar)
+
+Use Material 3 `NavigationBar`. Headspace's iOS tab bar is a butter-cream surface (Sleep mode switches to dusk); Android has no first-class live blur, so use a fully opaque canvas surface. **The active tint is Marigold on Today/Meditate/Move/Profile, but Sage `#7E9F4B` on the Sleep tab** — the only tab with its own color.
+
+```kotlin
+import androidx.compose.material.icons.filled.WbSunny
+import androidx.compose.material.icons.filled.Spa
+import androidx.compose.material.icons.filled.Bedtime
+import androidx.compose.material.icons.filled.DirectionsWalk
+import androidx.compose.material.icons.filled.Person
+import androidx.compose.material3.*
+
+@Composable
+fun HeadspaceBottomBar(selected: Int, onSelect: (Int) -> Unit, sleepMode: Boolean) {
+    val items = listOf(
+        "Today"    to Icons.Filled.WbSunny,
+        "Meditate" to Icons.Filled.Spa,
+        "Sleep"    to Icons.Filled.Bedtime,
+        "Move"     to Icons.Filled.DirectionsWalk,
+        "Profile"  to Icons.Filled.Person,
+    )
+    val haptics = LocalHapticFeedback.current
+    NavigationBar(
+        containerColor = if (sleepMode) HeadspaceColors.DuskCanvas else HeadspaceColors.ButterCream,
+        tonalElevation = 0.dp,
+    ) {
+        items.forEachIndexed { i, (label, icon) ->
+            val isSleepTab = i == 2
+            val activeTint = if (isSleepTab) HeadspaceColors.SageMoss else HeadspaceColors.Marigold
+            NavigationBarItem(
+                selected = selected == i,
+                onClick = {
+                    haptics.performHapticFeedback(HapticFeedbackType.TextHandleMove)
+                    onSelect(i)
+                },
+                icon = { Icon(icon, contentDescription = label, modifier = Modifier.size(24.dp)) },
+                label = { Text(label, style = HeadspaceText.Tab) },
+                colors = NavigationBarItemDefaults.colors(
+                    selectedIconColor   = activeTint,
+                    selectedTextColor   = activeTint,
+                    unselectedIconColor = HeadspaceColors.InkBrownMute,
+                    unselectedTextColor = HeadspaceColors.InkBrownMute,
+                    indicatorColor      = Color.Transparent, // Headspace has no Material pill
+                ),
+            )
+        }
+    }
+}
+```
+
+## 6. Motion
+
+| Moment | Compose recipe |
+|--------|----------------|
+| Breathing sphere | `Animatable` + coroutine: `tween(4000, EaseInOut)` to 1.04, `delay(2000)`, `tween(4000, EaseInOut)` to 0.96, `delay(2000)` — **no spring** |
+| Primary CTA tap | `animateFloatAsState` 1 → 0.98 + `HapticFeedbackType.LongPress`; Marigold glow shadow |
+| Mood tag select | `animateFloatAsState` 1 → 1.05 with `spring(dampingRatio = 0.7f)` + Butter fill + `TextHandleMove` haptic |
+| Streak ring reveal | `Animatable.animateTo(progress, tween(1200, EaseInOut))` + soft success haptic |
+| Tab switch | `TextHandleMove` haptic + Material crossfade between outlined/filled icons |
+| Sleep mode transition | Crossfade the canvas `Color` from `ButterCream` to `DuskCanvas` over 600ms |
+
+```kotlin
+// Sleep mode canvas crossfade — visceral, like dusk falling
+@Composable
+fun rememberSleepCanvas(sleepMode: Boolean): Color {
+    val color by animateColorAsState(
+        targetValue = if (sleepMode) HeadspaceColors.DuskCanvas else HeadspaceColors.ButterCream,
+        animationSpec = tween(600, easing = EaseInOut),
+        label = "sleepCanvas",
+    )
+    return color
+}
+```
+
+Haptics: Headspace's vocabulary is always soft. Prefer `LocalHapticFeedback` (`LongPress` ≈ iOS `.soft` impact, `TextHandleMove` ≈ `.selection`). For a closer match to the iOS soft impact use `LocalView.current.performHapticFeedback(HapticFeedbackConstants.CONTEXT_CLICK)` (API 30+) or a `Vibrator` `VibrationEffect.createOneShot(10, 60)`. **Never use a heavy/long vibration** — it breaks the calm.
+
+## 7. Icons
+
+The SF Symbols map to Material Icons (`androidx.compose.material:material-icons-extended`). The illustration companions are bitmap assets, not glyphs — ship as drawables and render with `Image(painterResource(...))`.
+
+| Component | SF Symbol (iOS) | Material Icon (Compose) |
+|-----------|-----------------|--------------------------|
+| Today tab | `sun.max` / `sun.max.fill` | `Icons.Filled.WbSunny` |
+| Meditate tab | `leaf` / `leaf.fill` | `Icons.Filled.Spa` |
+| Sleep tab | `moon` / `moon.fill` | `Icons.Filled.Bedtime` |
+| Move tab | `figure.walk` / `figure.walk.motion` | `Icons.Filled.DirectionsWalk` |
+| Profile tab | `person` / `person.fill` | `Icons.Filled.Person` |
+| Play | `play.fill` | `Icons.Filled.PlayArrow` |
+| Pause | `pause.fill` | `Icons.Filled.Pause` |
+| Skip back 15s | `gobackward.15` | `Icons.Filled.Replay10` (custom 15s vector preferred) |
+| Skip forward 15s | `goforward.15` | `Icons.Filled.Forward10` (custom 15s vector preferred) |
+| Settings | `gearshape` | `Icons.Filled.Settings` |
+| Search | `magnifyingglass` | `Icons.Filled.Search` |
+| Favorite | `heart` / `heart.fill` | `Icons.Outlined.FavoriteBorder` / `Icons.Filled.Favorite` |
+| Share | `square.and.arrow.up` | `Icons.Filled.IosShare` |
+| Streak flame | `flame.fill` | `Icons.Filled.LocalFireDepartment` (Marigold) |
+| Notifications | `bell` | `Icons.Filled.Notifications` |
+| Milestone trophy | `trophy.fill` | `Icons.Filled.EmojiEvents` (Milestone Gold) |
+
+The Headspace illustration companions (round-headed pastel characters) have no Material equivalent — bundle the PNG/vector assets and size them 80.dp inline, 240.dp for milestone reveals, 64.dp for quick-action thumbnails.
+
+## 8. Minimum SDK & Accessibility Notes
+
+- **minSdk 24** (Compose floor is 21; modern motion + `Animatable` are comfortable at 24). `compileSdk 34+`, Compose BOM `2024.09+`, Kotlin `2.0+`.
+- **Edge-to-edge**: call `enableEdgeToEdge()` in the `Activity`. The butter-cream canvas wants dark-content (`WindowCompat` `isAppearanceLightStatusBars = true`); in Sleep mode flip to light-content. Apply `Modifier.statusBarsPadding()` to the Today greeting and `Scaffold` insets so the tab bar clears the gesture nav.
+- **Font scaling**: `sp` honors the user's font scale automatically — keep it on the greeting, body, guidance, and meditation titles. Pin layout-sensitive text (the 56.sp timer, 11.sp tab labels, tag pills, the streak number) by wrapping in `CompositionLocalProvider(LocalDensity provides Density(LocalDensity.current.density, fontScale = 1f))`.
+- **TalkBack**: the breathing sphere is one element — `Modifier.semantics { contentDescription = "Breathing meditation. Currently exhaling. 10 minutes remaining." }`, updating the description each phase so TalkBack users can follow the breath. Merge meditation-card text with `Modifier.semantics(mergeDescendants = true)`.
+- **Touch targets**: Material guidance is 48.dp minimum. The 72.dp play button is well clear; the 48.dp skip circles already meet it; mood tags (80×88.dp) and tag pills are generous.
+- **Contrast**: Ink Brown `#2E1A47` on Butter Cream `#FFF7E7` passes WCAG AAA at all sizes. Marigold `#FF6B35` on Butter Cream passes AA at 17sp+ Medium — validate any small Marigold text and bump to Marigold Pressed `#E55A2B` if targeting strict compliance. Inverted cream on dusk surfaces passes AAA.
+- **Reduce Motion**: pass `animate = false` to `BreathingSphere` to render it static at scale 1.0; replace the streak-ring animate-in with an instant draw. Honor `Settings.Global.ANIMATOR_DURATION_SCALE == 0f`.
+- **Material You**: do **not** enable `dynamicLightColorScheme()` — Headspace's brand requires the fixed butter-cream canvas, Marigold accent, and the deliberate dusk Sleep palette regardless of wallpaper.