designmd-forge 1.2.0

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

@@ -0,0 +1,402 @@
+# Zwift (iOS) — Jetpack Compose Implementation Guide
+
+Companion to [DESIGN.md](DESIGN.md) — the framework-neutral spec. This file ports Zwift's visual language to **Android with Jetpack Compose (Material 3)**: a color token object, a `Typography` set, paste-ready `@Composable`s for the rider HUD over a 3D world, 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 (Zwift's full-bleed 3D world, glassmorphic overlays, the fixed metric color semantics, tall condensed numerals, the Power-Up game affordance) while making everything idiomatic Android — `NavigationBar` instead of a UITabBar, a `HazeChild`/blur-backed surface instead of `.ultraThinMaterial`, `sp`/`dp` instead of `pt`.
+
+Assumes Compose BOM `2024.09+`, Kotlin `2.0+`, `minSdk 26` (RenderEffect blur is `API 31+`; below that, fall back to a translucent scrim), Material 3. Zwift is effectively always-dark — no light scheme. Do **not** enable Material You dynamic color — the fixed metric semantics and Zwift Orange must hold regardless of wallpaper.
+
+## 1. Color Tokens
+
+```kotlin
+// ui/theme/ZwiftColors.kt
+import androidx.compose.ui.graphics.Color
+
+object ZwiftColors {
+    // Brand / action
+    val Orange        = Color(0xFFFC6719)
+    val OrangePressed = Color(0xFFD9530E)
+    val OrangeSoft    = Color(0xFF3A2110)
+
+    // Ride metric semantics (FIXED — do not remap)
+    val Power   = Color(0xFFFC6719) // power = orange (hero metric)
+    val Cadence = Color(0xFFE8C547)
+    val Heart   = Color(0xFFF0413E)
+    val Wkg     = Color(0xFF2BD4D9)
+
+    // App-shell surfaces (solid, off-ride)
+    val Canvas   = Color(0xFF161616)
+    val Card     = Color(0xFF1F1F1F)
+    val Surface2 = Color(0xFF2A2A2A)
+    val Surface3 = Color(0xFF353535)
+    val Divider  = Color(0xFF303030)
+
+    // Text
+    val TextPrimary   = Color(0xFFFFFFFF)
+    val TextSecondary = Color(0xFFA8AAAD)
+    val TextTertiary  = Color(0xFF6C6E72)
+
+    // Semantic
+    val Success = Color(0xFF57C84D)
+
+    // Glass tints (layer over a blurred surface)
+    val Glass       = Color(0xFF0C0C0C).copy(alpha = 0.60f)
+    val GlassHeavy  = Color(0xFF121212).copy(alpha = 0.92f)
+    val GlassStroke = Color(0xFFFFFFFF).copy(alpha = 0.10f)
+    val GlassButton = Color(0xFFFFFFFF).copy(alpha = 0.10f)
+}
+```
+
+Zwift is always-dark; there is no light scheme. Wire the off-ride shell:
+
+```kotlin
+// ui/theme/Theme.kt
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.darkColorScheme
+
+private val ZwiftDark = darkColorScheme(
+    primary        = ZwiftColors.Orange,
+    onPrimary      = Color(0xFFFFFFFF),
+    background     = ZwiftColors.Canvas,
+    onBackground   = ZwiftColors.TextPrimary,
+    surface        = ZwiftColors.Card,
+    onSurface      = ZwiftColors.TextPrimary,
+    surfaceVariant = ZwiftColors.Surface2,
+    outline        = ZwiftColors.Divider,
+    error          = ZwiftColors.Heart,
+)
+
+@Composable
+fun ZwiftTheme(content: @Composable () -> Unit) = MaterialTheme(
+    colorScheme = ZwiftDark,          // always dark — no light scheme
+    typography = ZwiftTypography,
+    content = content,
+)
+```
+
+## 2. Typography
+
+Two faces: **Barlow Semi Condensed** (the closest free analog to Zwift's condensed numerics) for numbers/titles/buttons, **Inter** for body/lists. Drop both in `res/font/`. Every metric style sets a tabular-figures `FontFeatureSetting`.
+
+```kotlin
+// ui/theme/ZwiftType.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 Barlow = FontFamily(
+    Font(R.font.barlow_semi_condensed_bold,      FontWeight.Bold),
+    Font(R.font.barlow_semi_condensed_extrabold, FontWeight.ExtraBold),
+)
+val Inter = FontFamily(
+    Font(R.font.inter_regular,  FontWeight.Normal),
+    Font(R.font.inter_medium,   FontWeight.Medium),
+    Font(R.font.inter_semibold, FontWeight.SemiBold),
+    Font(R.font.inter_bold,     FontWeight.Bold),
+)
+
+private const val TNUM = "tnum"   // tabular figures — HUD must not jump
+
+object ZwiftText {
+    // Display / numeric — Barlow Semi Condensed
+    val HUD         = TextStyle(Barlow, fontWeight = FontWeight.ExtraBold, fontSize = 34.sp, lineHeight = 34.sp, letterSpacing = (-0.3).sp, fontFeatureSettings = TNUM)
+    val HUDCompact  = TextStyle(Barlow, fontWeight = FontWeight.ExtraBold, fontSize = 28.sp, lineHeight = 28.sp, letterSpacing = (-0.2).sp, fontFeatureSettings = TNUM)
+    val ScreenTitle = TextStyle(Barlow, fontWeight = FontWeight.ExtraBold, fontSize = 28.sp, lineHeight = 31.sp, letterSpacing = 0.4.sp)
+    val Section     = TextStyle(Barlow, fontWeight = FontWeight.Bold,      fontSize = 22.sp, lineHeight = 26.sp, letterSpacing = 0.2.sp)
+    val CardTitle   = TextStyle(Barlow, fontWeight = FontWeight.Bold,      fontSize = 18.sp, lineHeight = 23.sp, letterSpacing = 0.2.sp)
+    val Unit        = TextStyle(Barlow, fontWeight = FontWeight.Bold,      fontSize = 11.sp, lineHeight = 12.sp, letterSpacing = 0.6.sp)
+    val Button      = TextStyle(Barlow, fontWeight = FontWeight.Bold,      fontSize = 16.sp, lineHeight = 16.sp, letterSpacing = 0.3.sp)
+    val Badge       = TextStyle(Barlow, fontWeight = FontWeight.ExtraBold, fontSize = 11.sp, lineHeight = 12.sp, letterSpacing = 0.4.sp)
+    // Body / UI — Inter
+    val Body        = TextStyle(Inter,  fontWeight = FontWeight.Normal,    fontSize = 16.sp, lineHeight = 24.sp)
+    val ListRow     = TextStyle(Inter,  fontWeight = FontWeight.SemiBold,  fontSize = 15.sp, lineHeight = 20.sp)
+    val Caption     = TextStyle(Inter,  fontWeight = FontWeight.Medium,    fontSize = 13.sp, lineHeight = 18.sp)
+    val Tab         = TextStyle(Inter,  fontWeight = FontWeight.SemiBold,  fontSize = 10.sp, lineHeight = 11.sp, letterSpacing = 0.1.sp)
+}
+
+// Map onto Material 3 slots so stock components inherit the brand
+val ZwiftTypography = Typography(
+    headlineLarge = ZwiftText.ScreenTitle,
+    headlineMedium = ZwiftText.Section,
+    titleMedium   = ZwiftText.CardTitle,
+    bodyMedium    = ZwiftText.Body,
+    labelSmall    = ZwiftText.Tab,
+)
+```
+
+## 3. Signature Components
+
+### Glass surface modifier
+
+```kotlin
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.unit.dp
+
+// API 31+: blur the content behind via a HazeChild or RenderEffect on the parent.
+// This modifier supplies the tint + stroke that complete the glass look.
+fun Modifier.zwiftGlass(radius: Int = 12, heavy: Boolean = false) = this
+    .clip(RoundedCornerShape(radius.dp))
+    .background(if (heavy) ZwiftColors.GlassHeavy else ZwiftColors.Glass)
+    .border(1.dp, ZwiftColors.GlassStroke, RoundedCornerShape(radius.dp))
+```
+
+### HUD Metric Tile (the core atom)
+
+```kotlin
+import androidx.compose.animation.core.animateFloatAsState
+import androidx.compose.animation.core.tween
+import androidx.compose.foundation.layout.*
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.graphics.Color
+import kotlin.math.roundToInt
+
+enum class RideMetric(val color: Color, val unit: String, val dp: Int) {
+    Power(ZwiftColors.Power, "WATTS", 0),
+    Cadence(ZwiftColors.Cadence, "RPM", 0),
+    Heart(ZwiftColors.Heart, "BPM", 0),
+    Wkg(ZwiftColors.Wkg, "W/KG", 1),
+}
+
+@Composable
+fun HUDTile(metric: RideMetric, value: Float) {
+    // Interpolate so the number ticks, never jumps
+    val shown by animateFloatAsState(value, tween(200), label = "hud-${metric.name}")
+    Column(
+        Modifier.widthIn(min = 88.dp).zwiftGlass(12).padding(vertical = 10.dp, horizontal = 8.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+    ) {
+        Text(
+            if (metric.dp == 1) String.format("%.1f", shown) else shown.roundToInt().toString(),
+            style = ZwiftText.HUD, color = metric.color,
+        )
+        Text(metric.unit, style = ZwiftText.Unit, color = ZwiftColors.TextSecondary)
+    }
+}
+
+@Composable
+fun RiderHUD(power: Float, cadence: Float, heart: Float) {
+    Row(
+        Modifier.fillMaxWidth().padding(horizontal = 14.dp),
+        horizontalArrangement = Arrangement.SpaceAround,
+    ) {
+        HUDTile(RideMetric.Power, power)
+        HUDTile(RideMetric.Cadence, cadence)
+        HUDTile(RideMetric.Heart, heart)
+    }
+}
+```
+
+### Route Banner
+
+```kotlin
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Flag
+import androidx.compose.material3.Icon
+
+@Composable
+fun RouteBanner(route: String, sub: String, progress: Float) {
+    Column(Modifier.fillMaxWidth().padding(horizontal = 14.dp).zwiftGlass(12).padding(14.dp),
+           verticalArrangement = Arrangement.spacedBy(8.dp)) {
+        Row(verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(10.dp)) {
+            Box(Modifier.size(30.dp).clip(RoundedCornerShape(8.dp)).background(ZwiftColors.Orange),
+                contentAlignment = Alignment.Center) {
+                Icon(Icons.Filled.Flag, null, tint = Color.White, modifier = Modifier.size(16.dp))
+            }
+            Column(Modifier.weight(1f)) {
+                Text(route, style = ZwiftText.CardTitle, color = Color.White)
+                Text(sub, style = ZwiftText.Caption, color = ZwiftColors.TextSecondary)
+            }
+        }
+        Box(Modifier.fillMaxWidth().height(4.dp).clip(RoundedCornerShape(2.dp))
+            .background(Color.White.copy(alpha = 0.18f))) {
+            Box(Modifier.fillMaxHeight().fillMaxWidth(progress).background(ZwiftColors.Orange))
+        }
+    }
+}
+```
+
+### Power-Up Tile
+
+```kotlin
+import androidx.compose.animation.core.Spring
+import androidx.compose.animation.core.spring
+import androidx.compose.material.icons.filled.Bolt
+import androidx.compose.runtime.*
+import androidx.compose.ui.graphics.graphicsLayer
+import androidx.compose.ui.hapticfeedback.HapticFeedbackType
+import androidx.compose.ui.platform.LocalHapticFeedback
+
+@Composable
+fun PowerUpTile(armed: Boolean, onDeploy: () -> Unit) {
+    val scale by animateFloatAsState(
+        if (armed) 1f else 0.8f,
+        spring(dampingRatio = Spring.DampingRatioMediumBouncy, stiffness = Spring.StiffnessHigh),
+        label = "powerup",
+    )
+    val haptics = LocalHapticFeedback.current
+    LaunchedEffect(armed) { if (armed) haptics.performHapticFeedback(HapticFeedbackType.LongPress) }
+
+    Box(
+        Modifier.size(56.dp).graphicsLayer { scaleX = scale; scaleY = scale }
+            .clip(RoundedCornerShape(10.dp))
+            .background(if (armed) ZwiftColors.Orange else ZwiftColors.GlassButton)
+            .border(1.dp, ZwiftColors.GlassStroke, RoundedCornerShape(10.dp))
+            .clickable(enabled = armed) { onDeploy() },
+        contentAlignment = Alignment.Center,
+    ) {
+        Icon(Icons.Filled.Bolt, "Power-up", tint = Color.White, modifier = Modifier.size(24.dp))
+    }
+}
+```
+
+### Achievement Burst
+
+```kotlin
+import androidx.compose.foundation.shape.CircleShape
+
+@Composable
+fun AchievementBurst(label: String) {
+    var shown by remember { mutableStateOf(false) }
+    val scale by animateFloatAsState(
+        if (shown) 1f else 0.8f,
+        spring(dampingRatio = Spring.DampingRatioMediumBouncy, stiffness = Spring.StiffnessLow),
+        label = "achv",
+    )
+    val haptics = LocalHapticFeedback.current
+    LaunchedEffect(Unit) { shown = true; haptics.performHapticFeedback(HapticFeedbackType.LongPress) }
+
+    Box(
+        Modifier.graphicsLayer { scaleX = scale; scaleY = scale; alpha = if (shown) 1f else 0f }
+            .clip(CircleShape).background(ZwiftColors.Success)
+            .padding(horizontal = 18.dp, vertical = 8.dp),
+    ) { Text(label.uppercase(), style = ZwiftText.Badge, color = Color.White) }
+}
+```
+
+### Primary CTA
+
+```kotlin
+import androidx.compose.material3.Button
+import androidx.compose.material3.ButtonDefaults
+
+@Composable
+fun ZwiftPrimaryButton(title: String, onClick: () -> Unit) {
+    Button(
+        onClick = onClick,
+        shape = RoundedCornerShape(10.dp),
+        colors = ButtonDefaults.buttonColors(containerColor = ZwiftColors.Orange),
+        contentPadding = PaddingValues(horizontal = 30.dp, vertical = 14.dp),
+        modifier = Modifier.fillMaxWidth(),
+    ) { Text(title.uppercase(), style = ZwiftText.Button, color = Color.White) }
+}
+```
+
+## 4. Navigation
+
+In-ride is a game-control surface; off-ride is a standard `NavigationBar`. No tint pill — active is Zwift Orange.
+
+```kotlin
+import androidx.compose.material.icons.filled.*
+import androidx.compose.material3.*
+
+@Composable
+fun ZwiftBottomBar(selected: Int, onSelect: (Int) -> Unit) {
+    NavigationBar(containerColor = ZwiftColors.Canvas, tonalElevation = 0.dp) {
+        val items = listOf(
+            "Home"     to Icons.Filled.Home,
+            "Workouts" to Icons.Filled.DirectionsBike,
+            "Events"   to Icons.Filled.CalendarMonth,
+            "Clubs"    to Icons.Filled.Groups,
+            "Profile"  to Icons.Filled.AccountCircle,
+        )
+        items.forEachIndexed { i, (label, icon) ->
+            NavigationBarItem(
+                selected = selected == i,
+                onClick = { onSelect(i) },
+                icon = { Icon(icon, label, modifier = Modifier.size(22.dp)) },
+                label = { Text(label, style = ZwiftText.Tab) },
+                colors = NavigationBarItemDefaults.colors(
+                    selectedIconColor = ZwiftColors.Orange,
+                    selectedTextColor = ZwiftColors.Orange,
+                    unselectedIconColor = ZwiftColors.TextTertiary,
+                    unselectedTextColor = ZwiftColors.TextTertiary,
+                    indicatorColor = Color.Transparent, // no Material pill
+                ),
+            )
+        }
+    }
+}
+```
+
+The **in-ride action bar** is a `zwiftGlass(heavy = true)` row of game controls (Action / Power-Up / Workout / Riders / Menu) overlaid on the rendered 3D scene — not page navigation. The 3D world itself is drawn by the engine (a `SurfaceView` / `GLSurfaceView`) behind the Compose overlay.
+
+## 5. Motion
+
+Zwift overlay motion is quiet (200–300ms); the *world's* motion is the rendered 3D scene.
+
+| Moment | Compose recipe |
+|--------|----------------|
+| HUD metric tick | `animateFloatAsState(value, tween(200))` — interpolate, never jump |
+| Power-Up collected | `animateFloatAsState` 0.8→1.0 `spring(MediumBouncy, High)` + glow; medium haptic |
+| Power-Up deployed | scale back + a world VFX (engine-side) |
+| Achievement burst | `animateFloatAsState` 0.8→1.0 `spring(MediumBouncy, Low)` + alpha; success haptic; orange confetti |
+| Ride-On burst | `AnimatedVisibility` `fadeIn/fadeOut` ~600ms + soft haptic |
+| Route progress | `Box` fill width animates linearly with distance |
+| Overlay show/hide | `AnimatedVisibility` `fadeIn + slideInVertically(8.dp)` `tween(200)` |
+| App-shell nav | Nav3/`NavHost` slide push `tween(300)` |
+
+```kotlin
+// HUD metric tick — the canonical Zwift overlay motion
+val shown by animateFloatAsState(value, tween(200), label = "hud")
+```
+
+Haptics: `LocalHapticFeedback.performHapticFeedback(HapticFeedbackType.LongPress)` for the power-up collect and the achievement; for Ride-On / lap use `LocalView.current.performHapticFeedback(HapticFeedbackConstants.CLOCK_TICK)`.
+
+## 6. Icons
+
+The closest first-party set is `androidx.compose.material:material-icons-extended`. The 3D world is engine-rendered; these are for overlays + app shell.
+
+| Purpose | SF Symbol (iOS) | Material Icon (Compose) |
+|---------|-----------------|--------------------------|
+| Home (tab) | `house` / `house.fill` | `Icons.Filled.Home` |
+| Workouts (tab) | `figure.indoor.cycle` | `Icons.Filled.DirectionsBike` |
+| Events (tab) | `calendar` | `Icons.Filled.CalendarMonth` |
+| Clubs (tab) | `person.3.fill` | `Icons.Filled.Groups` |
+| Profile (tab) | `person.crop.circle` | `Icons.Filled.AccountCircle` |
+| Route flag | `flag.fill` | `Icons.Filled.Flag` |
+| Power-Up (generic) | `bolt.fill` | `Icons.Filled.Bolt` |
+| Power-Up: light | `feather` | `Icons.Filled.Air` |
+| Action (U-turn) | `arrow.uturn.left` | `Icons.Filled.UTurnLeft` |
+| Workout | `stopwatch` | `Icons.Filled.Timer` |
+| Riders nearby | `person.2.fill` | `Icons.Filled.Groups` |
+| Menu | `line.3.horizontal` | `Icons.Filled.Menu` |
+| Heart-rate | `heart.fill` | `Icons.Filled.Favorite` |
+| Power | `bolt.fill` | `Icons.Filled.Bolt` |
+| Elevation / climb | `mountain.2.fill` | `Icons.Filled.Terrain` |
+| Ride On (kudos) | `hand.thumbsup.fill` | `Icons.Filled.ThumbUp` |
+| Map | `map.fill` | `Icons.Filled.Map` |
+| Camera angle | `camera.fill` | `Icons.Filled.Videocam` |
+| Achievement | `rosette` | `Icons.Filled.MilitaryTech` |
+
+## 7. Minimum SDK & Accessibility Notes
+
+- **minSdk 26** recommended (Compose floor is 21; `RenderEffect` blur for true glass is `API 31+` — below 31, fall back to a solid `GlassHeavy` scrim instead of blur). `compileSdk 34+`, Compose BOM `2024.09+`, Kotlin `2.0+`.
+- **Edge-to-edge**: call `enableEdgeToEdge()`; the world bleeds full-screen behind transparent system bars (light-content). The route banner must clear the camera cutout; the action bar respects the navigation bar — inset the *overlays*, not the world.
+- **Tabular figures**: every metric `TextStyle` sets `fontFeatureSettings = "tnum"`; interpolate value changes with `animateFloatAsState(tween(200))` so the HUD ticks smoothly and never jumps.
+- **Font scaling**: `sp` honors the user's font scale — keep it on body/lists/captions (Inter). Pin HUD metrics, unit labels, screen titles, button labels, and tab labels by deriving from `dp` or `CompositionLocalProvider(LocalDensity provides Density(density, fontScale = 1f))` — glance-legibility and glass-tile layout depend on fixed sizing.
+- **TalkBack**: label HUD tiles "Power, 248 watts" / "Heart rate, 156 BPM" (value + metric name); the Power-Up is a button labelled with its type + armed state; announce achievements with `LiveRegionMode.Assertive`.
+- **Touch targets**: Material guidance is 48.dp. HUD tiles are large by nature; give the 56.dp Power-Up and action-bar items a ≥48.dp hit area; app-shell rows ≥48.dp.
+- **Contrast**: white on the glass tiles passes AA because the glass darkens the world beneath; each metric color is paired with a unit label + glyph so color is never the sole differentiator.
+- **Reduce transparency / blur unavailable**: when `RenderEffect` blur is unavailable (< API 31) or the user reduces transparency, swap glass to a solid `GlassHeavy` (`rgba(18,18,18,0.92+)`) so overlays stay legible.
+- **Reduce motion**: when `Settings.Global.ANIMATOR_DURATION_SCALE == 0`, disable the power-up pop, achievement spring, and confetti (use a `Crossfade`); keep the smooth metric tick and route-progress fill.
+- **Orientation**: in-ride is landscape-preferred (the trainer layout) — lock the ride Activity/screen to landscape; the app shell is portrait-primary.
+- **Always dark**: there is no light scheme. Do **not** enable `dynamicColorScheme()` — the fixed metric semantics and Zwift Orange identity must hold regardless of wallpaper.