designmd-forge 1.2.0

package/dist/data/designs/ios-sleep-cycle-android.md

@@ -0,0 +1,436 @@
+# Sleep Cycle (iOS) — Jetpack Compose Implementation Guide
+
+Companion to [DESIGN.md](DESIGN.md) — the framework-neutral spec. This file ports Sleep Cycle's visual language to **Android with Jetpack Compose (Material 3)**: a color token object, a `Typography` set, the signature hypnogram + score ring as `@Composable`s, navigation, motion, and haptics.
+
+> Why a Compose guide for an iOS-referenced app? The DESIGN.md tokens are platform-neutral. This keeps the *visual* identity (the indigo→night gradient shell, the glowing aqua hypnogram, the single aqua accent, soft floating cards) while making everything idiomatic Android — `NavigationBar` instead of a UITabBar, `Canvas`/`drawPath` instead of SwiftUI `Path`, `dp`/`sp` instead of `pt`.
+
+Assumes Compose BOM `2024.09+`, Kotlin `2.0+`, `minSdk 24`, Material 3. No color extraction — Sleep Cycle's palette is a fixed, intentional set, so Palette is not needed. Sleep Cycle is **dark-first**; a Dawn light scheme is provided but the night gradient is the primary experience.
+
+## 1. Color Tokens
+
+```kotlin
+// ui/theme/SleepCycleColors.kt
+import androidx.compose.ui.graphics.Color
+
+object SCColors {
+    // Night gradient & canvas (dark, default)
+    val NightTop   = Color(0xFF2A2D5A)
+    val NightMid   = Color(0xFF3B4371)
+    val CanvasDeep = Color(0xFF14152E) // NOT pure black
+    val Surface1   = Color(0xFF1E2046)
+    val Surface2   = Color(0xFF292C58)
+    val Divider    = Color(0xFF353974)
+
+    // Canvas (light — Dawn)
+    val DawnCanvas  = Color(0xFFF4F5FC)
+    val DawnSurface = Color(0xFFFFFFFF)
+    val DawnDivider = Color(0xFFE3E5F2)
+
+    // Text
+    val TextPrimary   = Color(0xFFF2F3FB)
+    val TextSecondary = Color(0xFFA6A9D4)
+    val TextTertiary  = Color(0xFF6C70A8)
+    val TextPrimaryLt = Color(0xFF1B1D3A)
+
+    // Accents
+    val Accent        = Color(0xFF6C7BFF)
+    val AccentPressed = Color(0xFF5563E6)
+    val DeepSleep     = Color(0xFF3D4ABF)
+    val Aqua          = Color(0xFF4FD1E6)
+    val AquaSoft      = Color(0xFF7FE3F0)
+
+    // Sleep stages (semantic)
+    val StageAwake = Color(0xFFFF8FB1)
+    val StageLight = Color(0xFF6C7BFF)
+    val StageDeep  = Color(0xFF3D4ABF)
+    val StageREM   = Color(0xFF4FD1E6)
+
+    // Semantic
+    val Success = Color(0xFF4FD1A0)
+    val Error   = Color(0xFFFF6B81)
+    val Gold    = Color(0xFFFFC56B)
+}
+
+fun scoreColor(score: Int): Color = when {
+    score < 50 -> SCColors.StageAwake // rose
+    score < 75 -> SCColors.Accent     // indigo
+    else       -> SCColors.Aqua       // aqua
+}
+```
+
+Wire it into both schemes. Sleep Cycle is dark-first; the dark scheme is the signature.
+
+```kotlin
+// ui/theme/Theme.kt
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.material3.*
+import androidx.compose.runtime.Composable
+
+private val SCDark = darkColorScheme(
+    primary        = SCColors.Accent,
+    onPrimary      = Color(0xFFFFFFFF),
+    background     = SCColors.CanvasDeep,
+    onBackground   = SCColors.TextPrimary,
+    surface        = SCColors.Surface1,
+    onSurface      = SCColors.TextPrimary,
+    surfaceVariant = SCColors.Surface2,
+    outline        = SCColors.Divider,
+    secondary      = SCColors.Aqua,
+    error          = SCColors.Error,
+)
+
+private val SCLight = lightColorScheme(
+    primary        = SCColors.Accent,
+    onPrimary      = Color(0xFFFFFFFF),
+    background     = SCColors.DawnCanvas,
+    onBackground   = SCColors.TextPrimaryLt,
+    surface        = SCColors.DawnSurface,
+    onSurface      = SCColors.TextPrimaryLt,
+    surfaceVariant = SCColors.DawnDivider,
+    outline        = SCColors.DawnDivider,
+    secondary      = SCColors.Aqua,
+    error          = SCColors.Error,
+)
+
+@Composable
+fun SleepCycleTheme(
+    dark: Boolean = isSystemInDarkTheme(),
+    content: @Composable () -> Unit,
+) = MaterialTheme(
+    colorScheme = if (dark) SCDark else SCLight,
+    typography = SCTypography,
+    content = content,
+)
+```
+
+## 2. Typography (M3)
+
+Sleep Cycle uses **Nunito** (Google Fonts, SIL OFL). Drop the TTFs in `res/font/`. Numerals heavy (ExtraBold/Black); body light (Normal).
+
+```kotlin
+// ui/theme/SCType.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 Nunito = FontFamily(
+    Font(R.font.nunito_regular,   FontWeight.Normal),
+    Font(R.font.nunito_medium,    FontWeight.Medium),
+    Font(R.font.nunito_semibold,  FontWeight.SemiBold),
+    Font(R.font.nunito_bold,      FontWeight.Bold),
+    Font(R.font.nunito_extrabold, FontWeight.ExtraBold),
+    Font(R.font.nunito_black,     FontWeight.Black),
+)
+
+object SCText {
+    val ScreenTitle = TextStyle(Nunito, fontWeight = FontWeight.Black,     fontSize = 32.sp, lineHeight = 37.sp, letterSpacing = (-0.4).sp)
+    val HeroStat    = TextStyle(Nunito, fontWeight = FontWeight.Black,     fontSize = 34.sp, lineHeight = 37.sp, letterSpacing = (-0.5).sp)
+    val Section     = TextStyle(Nunito, fontWeight = FontWeight.ExtraBold, fontSize = 22.sp, lineHeight = 28.sp, letterSpacing = (-0.2).sp)
+    val CardTitle   = TextStyle(Nunito, fontWeight = FontWeight.Bold,      fontSize = 18.sp, lineHeight = 23.sp)
+    val Body        = TextStyle(Nunito, fontWeight = FontWeight.Normal,    fontSize = 16.sp, lineHeight = 24.sp)
+    val ListItem    = TextStyle(Nunito, fontWeight = FontWeight.SemiBold,  fontSize = 15.sp, lineHeight = 21.sp)
+    val Meta        = TextStyle(Nunito, fontWeight = FontWeight.Normal,    fontSize = 14.sp, lineHeight = 20.sp)
+    val Eyebrow     = TextStyle(Nunito, fontWeight = FontWeight.Bold,      fontSize = 12.sp, lineHeight = 12.sp, letterSpacing = 1.4.sp)
+    val Button      = TextStyle(Nunito, fontWeight = FontWeight.ExtraBold, fontSize = 16.sp, lineHeight = 16.sp, letterSpacing = 0.2.sp)
+    val Pill        = TextStyle(Nunito, fontWeight = FontWeight.ExtraBold, fontSize = 11.sp, lineHeight = 11.sp, letterSpacing = 0.2.sp)
+    val Axis        = TextStyle(Nunito, fontWeight = FontWeight.Bold,      fontSize = 9.sp,  lineHeight = 9.sp)
+    val Tab         = TextStyle(Nunito, fontWeight = FontWeight.Bold,      fontSize = 10.sp, lineHeight = 10.sp, letterSpacing = 0.1.sp)
+}
+
+val SCTypography = Typography(
+    headlineLarge = SCText.ScreenTitle,
+    headlineMedium = SCText.Section,
+    titleMedium   = SCText.CardTitle,
+    bodyMedium    = SCText.Body,
+    labelSmall    = SCText.Tab,
+)
+```
+
+## 3. Signature Components
+
+### Night Shell (gradient background)
+
+```kotlin
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.*
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.Brush
+
+@Composable
+fun NightShell(content: @Composable BoxScope.() -> Unit) {
+    Box(
+        Modifier
+            .fillMaxSize()
+            .background(
+                Brush.verticalGradient(
+                    0.0f to SCColors.NightTop,
+                    0.3f to SCColors.NightMid,
+                    1.0f to SCColors.CanvasDeep,
+                )
+            ),
+        content = content,
+    )
+}
+```
+
+### Sleep-Analysis Graph (Hypnogram)
+
+```kotlin
+import androidx.compose.animation.core.*
+import androidx.compose.foundation.Canvas
+import androidx.compose.runtime.*
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.*
+import androidx.compose.ui.graphics.drawscope.Stroke
+import androidx.compose.ui.unit.dp
+
+/** points: normalized x:0..1 (time), y:0..1 (0=awake/top, 1=deep/bottom) */
+@Composable
+fun HypnogramCard(points: List<Offset>, modifier: Modifier = Modifier) {
+    val progress = remember { Animatable(0f) }
+    LaunchedEffect(Unit) {
+        progress.animateTo(1f, tween(900, easing = EaseOutCubic))
+    }
+
+    Column(
+        modifier
+            .fillMaxWidth()
+            .shadow(24.dp, RoundedCornerShape(20.dp), spotColor = Color.Black.copy(alpha = 0.35f))
+            .clip(RoundedCornerShape(20.dp))
+            .background(SCColors.Surface1)
+            .border(1.dp, SCColors.Divider, RoundedCornerShape(20.dp))
+            .padding(16.dp),
+    ) {
+        Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+            Text("Sleep stages", style = SCText.CardTitle.copy(fontSize = 13.sp), color = SCColors.TextPrimary)
+            Text("23:42 — 07:18", style = SCText.Axis.copy(fontSize = 11.sp), color = SCColors.TextTertiary)
+        }
+        Spacer(Modifier.height(12.dp))
+
+        Canvas(Modifier.fillMaxWidth().height(110.dp)) {
+            val w = size.width; val h = size.height
+            fun pt(o: Offset) = Offset(o.x * w, 8.dp.toPx() + o.y * (h - 16.dp.toPx()))
+
+            val line = Path().apply {
+                moveTo(pt(points.first()).x, pt(points.first()).y)
+                for (i in 1 until points.size) {
+                    val prev = pt(points[i - 1]); val cur = pt(points[i])
+                    val mid = Offset((prev.x + cur.x) / 2, (prev.y + cur.y) / 2)
+                    quadraticBezierTo(prev.x, prev.y, mid.x, mid.y)
+                    quadraticBezierTo(cur.x, cur.y, cur.x, cur.y)
+                }
+            }
+            // Gradient fill under the wave
+            val fill = Path().apply {
+                addPath(line); lineTo(w, h); lineTo(0f, h); close()
+            }
+            drawPath(fill, Brush.verticalGradient(
+                0f to SCColors.Accent.copy(alpha = 0.45f),
+                1f to SCColors.Accent.copy(alpha = 0.02f),
+            ), alpha = progress.value)
+            // Glowing aqua wave — clip-reveal left→right
+            clipRect(right = w * progress.value) {
+                drawPath(line, SCColors.AquaSoft, style = Stroke(width = 2.5.dp.toPx(), cap = StrokeCap.Round, join = StrokeJoin.Round))
+            }
+        }
+
+        Spacer(Modifier.height(6.dp))
+        Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+            listOf("00", "02", "04", "06", "07").forEach { Text(it, style = SCText.Axis, color = SCColors.TextTertiary) }
+        }
+        Spacer(Modifier.height(12.dp))
+        Row(horizontalArrangement = Arrangement.spacedBy(14.dp)) {
+            listOf("Awake" to SCColors.StageAwake, "Light" to SCColors.StageLight,
+                   "Deep" to SCColors.StageDeep, "REM" to SCColors.StageREM).forEach { (label, c) ->
+                Row(verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(5.dp)) {
+                    Box(Modifier.size(9.dp).clip(RoundedCornerShape(3.dp)).background(c))
+                    Text(label, style = SCText.Tab, color = SCColors.TextSecondary)
+                }
+            }
+        }
+    }
+}
+```
+
+### Sleep-Quality Ring
+
+```kotlin
+@Composable
+fun ScoreRing(score: Int, size: androidx.compose.ui.unit.Dp = 92.dp) {
+    val progress = remember { Animatable(0f) }
+    LaunchedEffect(score) { progress.animateTo(1f, tween(800, easing = EaseOutCubic)) }
+    val arcColor = scoreColor(score)
+
+    Box(Modifier.size(size), contentAlignment = Alignment.Center) {
+        Canvas(Modifier.fillMaxSize()) {
+            val sw = 9.dp.toPx()
+            val d = size.toPx() - sw
+            drawArc(SCColors.Surface2, 0f, 360f, false,
+                topLeft = Offset(sw / 2, sw / 2), size = androidx.compose.ui.geometry.Size(d, d),
+                style = Stroke(sw))
+            drawArc(arcColor, -90f, 360f * progress.value, false,
+                topLeft = Offset(sw / 2, sw / 2), size = androidx.compose.ui.geometry.Size(d, d),
+                style = Stroke(sw, cap = StrokeCap.Round))
+        }
+        Column(horizontalAlignment = Alignment.CenterHorizontally) {
+            Text("${(score * progress.value).toInt()}", style = SCText.HeroStat.copy(fontSize = 26.sp), color = SCColors.TextPrimary)
+            Text("SLEEP QUALITY", style = SCText.Tab.copy(fontSize = 9.sp), color = SCColors.TextSecondary)
+        }
+    }
+}
+```
+
+### Smart-Alarm Card
+
+```kotlin
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Alarm
+import androidx.compose.material3.Icon
+
+@Composable
+fun SmartAlarmCard(time: String = "07:30", modifier: Modifier = Modifier) {
+    Row(
+        modifier
+            .fillMaxWidth()
+            .clip(RoundedCornerShape(18.dp))
+            .background(SCColors.Surface1)
+            .border(1.dp, SCColors.Divider, RoundedCornerShape(18.dp))
+            .padding(14.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(14.dp),
+    ) {
+        Box(
+            Modifier.size(38.dp).clip(RoundedCornerShape(12.dp))
+                .background(Brush.linearGradient(listOf(SCColors.Accent, SCColors.DeepSleep))),
+            contentAlignment = Alignment.Center,
+        ) { Icon(Icons.Filled.Alarm, null, tint = Color.White, modifier = Modifier.size(20.dp)) }
+        Column(Modifier.weight(1f)) {
+            Text("Smart alarm", style = SCText.ListItem.copy(fontWeight = FontWeight.ExtraBold), color = SCColors.TextPrimary)
+            Text("Wakes you in your lightest sleep", style = SCText.Tab.copy(fontSize = 11.sp), color = SCColors.TextSecondary)
+        }
+        Text(time, style = SCText.HeroStat.copy(fontSize = 19.sp), color = SCColors.TextPrimary)
+    }
+}
+```
+
+### Primary Button
+
+```kotlin
+@Composable
+fun SCPrimaryButton(title: String, onClick: () -> Unit, modifier: Modifier = Modifier) {
+    Box(
+        modifier
+            .fillMaxWidth()
+            .shadow(20.dp, RoundedCornerShape(16.dp), spotColor = SCColors.Accent.copy(alpha = 0.35f))
+            .clip(RoundedCornerShape(16.dp))
+            .background(Brush.linearGradient(listOf(SCColors.Accent, SCColors.DeepSleep)))
+            .clickable(onClick = onClick)
+            .padding(vertical = 15.dp, horizontal = 30.dp),
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(title, style = SCText.Button, color = Color.White)
+    }
+}
+```
+
+## 4. Navigation
+
+Sleep Cycle has minimal chrome: a 5-tab bottom strip and no opaque top bar (the title lives in scroll content). Model the strip as a `NavigationBar`; active state is just the aqua color — **no Material tint pill**.
+
+```kotlin
+import androidx.compose.material.icons.filled.*
+
+@Composable
+fun SCBottomBar(selected: Int, onSelect: (Int) -> Unit) {
+    NavigationBar(
+        containerColor = SCColors.CanvasDeep.copy(alpha = 0.92f),
+        tonalElevation = 0.dp,
+    ) {
+        val items = listOf(
+            "Sleep"   to Icons.Filled.MonitorHeart,
+            "Journal" to Icons.Filled.CalendarMonth,
+            "Alarm"   to Icons.Filled.Alarm,
+            "Sounds"  to Icons.Filled.QueueMusic,
+            "Profile" to Icons.Filled.AccountCircle,
+        )
+        items.forEachIndexed { i, (label, icon) ->
+            NavigationBarItem(
+                selected = selected == i,
+                onClick = { onSelect(i) },
+                icon = { Icon(icon, label, Modifier.size(22.dp)) },
+                label = { Text(label, style = SCText.Tab) },
+                colors = NavigationBarItemDefaults.colors(
+                    selectedIconColor = SCColors.Aqua,    // aqua, no pill
+                    selectedTextColor = SCColors.Aqua,
+                    unselectedIconColor = SCColors.TextTertiary,
+                    unselectedTextColor = SCColors.TextTertiary,
+                    indicatorColor = Color.Transparent,   // Sleep Cycle has no tint pill
+                ),
+            )
+        }
+    }
+}
+```
+
+The screen header is content, not a `TopAppBar`: an eyebrow ("SLEEP ANALYSIS", `SCText.Eyebrow` in `Aqua`, 1.4sp tracking, uppercase), the title ("Last night", `SCText.ScreenTitle`), and a date line (`SCText.Meta` in `TextSecondary`), all over the night gradient.
+
+## 5. Motion
+
+Sleep Cycle motion is slow and calming — 200–900ms ease-out, never aggressive. The primary button glows (colored shadow), it does not bounce.
+
+| Moment | Compose recipe |
+|--------|----------------|
+| Hypnogram draw-in | `Animatable` 0→1 `tween(900, EaseOutCubic)`; `clipRect(right = w * progress)` reveal + fill `alpha = progress` |
+| Score ring sweep | `drawArc(sweepAngle = 360f * progress)` with `Animatable` `tween(800, EaseOutCubic)`; center number counts via `(score * progress).toInt()` |
+| Weekly bars grow | each bar `animateFloatAsState` with `tween(500)` + staggered `delayMillis = i * 40` |
+| Segmented control | indicator `animateDpAsState(tween(220, EaseOutCubic))` slides between segments |
+| Sheet present | `ModalBottomSheet` default slide-up (~300ms); scrim fades in |
+| Toggle | thumb `animateDpAsState(tween(200))` + `HapticFeedbackType.LongPress` |
+| Tab switch | `Crossfade(tween(200))` between destinations |
+| Session start | moon `infiniteRepeatable(tween(1200), RepeatMode.Reverse)` scale 1→1.06, then ramp screen brightness down |
+
+```kotlin
+// Canonical hypnogram reveal
+val progress = remember { Animatable(0f) }
+LaunchedEffect(Unit) { progress.animateTo(1f, tween(900, easing = EaseOutCubic)) }
+// in Canvas: clipRect(right = size.width * progress.value) { drawPath(wave, ...) }
+```
+
+Haptics: `LocalHapticFeedback.performHapticFeedback(HapticFeedbackType.LongPress)` for the soft impact on toggle and session start. Session auto-dim uses `window.attributes.screenBrightness` — request to lower it during tracking, never below `0.05f`, and **always restore** the prior value on session end and `onDispose`.
+
+## 6. Icons
+
+Closest first-party set is `androidx.compose.material:material-icons-extended`.
+
+| Purpose | SF Symbol (iOS) | Material Icon (Compose) |
+|---------|-----------------|--------------------------|
+| Sleep (tab) | `waveform.path.ecg` | `Icons.Filled.MonitorHeart` |
+| Journal (tab) | `calendar` | `Icons.Filled.CalendarMonth` |
+| Alarm (tab) | `alarm` / `alarm.fill` | `Icons.Filled.Alarm` |
+| Sounds (tab) | `music.note.list` | `Icons.Filled.QueueMusic` |
+| Profile (tab) | `person.crop.circle` | `Icons.Filled.AccountCircle` |
+| Smart alarm tile | `alarm` | `Icons.Filled.Alarm` |
+| Moon / session | `moon.stars.fill` | `Icons.Filled.Bedtime` |
+| Play / pause | `play.fill` / `pause.fill` | `Icons.Filled.PlayArrow` / `Icons.Filled.Pause` |
+| Trend up | `arrow.up.right` | `Icons.Filled.TrendingUp` |
+| Streak | `flame.fill` | `Icons.Filled.LocalFireDepartment` |
+| Settings | `gearshape` | `Icons.Filled.Settings` |
+| Back / close | `chevron.left` / `xmark` | `Icons.Filled.ArrowBack` / `Icons.Filled.Close` |
+| Snooze | `zzz` | `Icons.Filled.Snooze` |
+| Heart rate | `heart.fill` | `Icons.Filled.Favorite` |
+
+## 7. Minimum SDK & Accessibility Notes
+
+- **minSdk 24** (Compose floor is 21; `Canvas` paths + modern motion are comfortable at 24). `compileSdk 34+`, Compose BOM `2024.09+`, Kotlin `2.0+`.
+- **Edge-to-edge**: call `enableEdgeToEdge()`; the night gradient must extend under the status bar and nav bar — use light-content system bars on dark (the default), dark-content on the Dawn theme. Add bottom content padding for the `NavigationBar` height + system insets.
+- **Font scaling**: `sp` honors the user's font scale — keep it on screen title, hero stat, section, card title, body, list item; pin layout-sensitive text (axis labels, 10sp tab labels, pill text, ring sublabel) via `dp`-derived sizing or a fixed-`fontScale` `LocalDensity`. Cap the hero stat scale so the ring/stat row doesn't break.
+- **TalkBack**: expose the hypnogram and score ring as single elements with a summarizing `contentDescription` ("Slept 7 hours 36 minutes, sleep quality 78 of 100, 2 awakenings") instead of the raw path; mark the legend swatches `Modifier.semantics { hideFromAccessibility() }` and read the stage names in the summary.
+- **Touch targets**: Material guidance is 48.dp — give 22.dp tab icons and 14.dp chevrons a 48.dp hit area; primary button ≥ 50.dp tall; toggle uses Material `Switch` sizing.
+- **Contrast**: `#F2F3FB` on `#1E2046` and on the gradient passes WCAG AA. Stage chips pair fills with dark ink (Awake on `#3A1430`, REM on `#07303A`) — validate any custom pairing, especially the rose Awake.
+- **Reduce motion**: when `Settings.Global.ANIMATOR_DURATION_SCALE == 0`, render the hypnogram and ring at final value (no draw-in/sweep), substitute a `Crossfade`, and disable the moon pulse — keep the score color band (it conveys state).
+- **Dark mode**: invert via the Dawn `lightColorScheme` — `#F4F5FC` field, white cards; accent `#6C7BFF`, aqua `#4FD1E6`, and all stage colors stay identical in both modes. Do **not** enable Material You `dynamicColorScheme()` — Sleep Cycle's calm indigo identity must hold regardless of wallpaper (the single aqua accent has no wallpaper to harmonize with).
+- **Brightness**: session auto-dim via `window.attributes.screenBrightness` — gate behind a user setting, never below `0.05f`, always restore on session end and `DisposableEffect.onDispose`.