designmd-forge 1.2.0

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

@@ -0,0 +1,646 @@
+# Apple Maps (iOS) — Jetpack Compose Implementation Guide
+
+Companion to [DESIGN.md](DESIGN.md) — the framework-neutral spec. Apple Maps is the canonical reference for native iOS map UI. This file ports that 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 Maps' cream-parchment cartography, sliding bottom search sheet, the pulsing blue location puck, blur-as-depth) while making everything idiomatic Android — Material 3 `BottomSheetScaffold` instead of `.presentationDetents`, a translucent `Surface` instead of `.regularMaterial` (Android has no live blur), `sp`/`dp` instead of `pt`. The cartography is rendered by Google's `Maps Compose` SDK with a custom JSON style approximating the cream/water/park palette.
+
+Assumes Compose BOM `2024.09+`, Kotlin `2.0+`, `minSdk 24`, Material 3, `androidx.compose.material3:material3` with the bottom-sheet APIs, and `com.google.maps.android:maps-compose` `4.3+` for the map surface (style it via a `MapStyleOptions` JSON to the cream palette below).
+
+## 1. Color Tokens
+
+```kotlin
+// ui/theme/MapsColors.kt
+import androidx.compose.ui.graphics.Color
+
+object MapsColors {
+    // Map Cartography — the brand
+    val Cream       = Color(0xFFF6F1E6) // land surface
+    val Water       = Color(0xFFB9D9EB) // oceans, rivers, lakes
+    val ParkGreen   = Color(0xFFD6E5C9) // parks, green space
+    val RoadWhite   = Color(0xFFFFFFFF) // major roads
+    val RoadOutline = Color(0xFFD5CFC0) // minor road strokes
+    val Highway     = Color(0xFFFFD966) // highway fill
+    val Building2D  = Color(0xFFEFE9DD)
+    val Building3D  = Color(0xFFE6DFD0)
+    val MapLabel    = Color(0xFF594F3F) // warm dark slate map text
+
+    // Brand
+    val Blue        = Color(0xFF0A84FF) // directions polyline, puck, primary CTAs
+    val BluePressed = Color(0xFF0967D2)
+    val BlueDark    = Color(0xFF409CFF) // brighter blue for dark mode
+    val Red         = Color(0xFFFF3B30) // dropped pin (iOS system Red)
+
+    // Category Colors
+    val Food     = Color(0xFFFF9500)
+    val Coffee   = Color(0xFFA5694C)
+    val Drinks   = Color(0xFF5AC8FA)
+    val Shopping = Color(0xFFFFCC00)
+    val Parking  = Color(0xFFAF52DE)
+    val Hotel    = Color(0xFF5856D6)
+    val Health   = Color(0xFFFF2D55)
+    val EVGreen  = Color(0xFF34C759)
+
+    // UI Chrome
+    val CardCanvas   = Color(0xFFFFFFFF)
+    val SurfaceGray  = Color(0xFFF2F2F7) // search field fill, chip backgrounds
+    val SurfaceGray2 = Color(0xFFE5E5EA) // pressed list rows
+    val Divider      = Color(0xFFC7C7CC)
+
+    // Text (base colors; apply alpha for secondary tiers)
+    val Ink       = Color(0xFF000000)            // primary — pure black on cream
+    val Secondary = Color(0xFF3C3C43)            // apply .copy(alpha = 0.60f)
+    // tertiary = Secondary @ 0.30f, placeholder = Secondary @ 0.18f
+
+    // Semantic
+    val Success = Color(0xFF34C759)
+    val Warning = Color(0xFFFF9500)
+    val Error   = Color(0xFFFF3B30)
+
+    // Dark mode (warm dark land — the dark equivalent of cream paper)
+    val DarkMapLand  = Color(0xFF2A2826)
+    val DarkMapWater = Color(0xFF1C2638)
+    val DarkMapPark  = Color(0xFF2C3A2A)
+    val DarkCardSurf = Color(0xFF1C1C1E)
+    val DarkSurface2 = Color(0xFF2C2C2E)
+    val DarkDivider  = Color(0xFF38383A)
+}
+```
+
+Apple Maps' chrome is a light frosted layer over warm cartography, so wire a Material 3 `lightColorScheme` (provide the dark variant for dark mode). `primary` is Maps Blue.
+
+```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 MapsLight = lightColorScheme(
+    primary        = MapsColors.Blue,
+    onPrimary      = Color.White,
+    background     = MapsColors.CardCanvas,
+    onBackground   = MapsColors.Ink,            // pure black on cream
+    surface        = MapsColors.CardCanvas,
+    onSurface      = MapsColors.Ink,
+    surfaceVariant = MapsColors.SurfaceGray,
+    outline        = MapsColors.Divider,
+    error          = MapsColors.Error,
+)
+
+private val MapsDark = darkColorScheme(
+    primary        = MapsColors.BlueDark,       // brighter blue for dark legibility
+    onPrimary      = Color.White,
+    background     = MapsColors.DarkCardSurf,
+    onBackground   = Color.White,
+    surface        = MapsColors.DarkCardSurf,
+    onSurface      = Color.White,
+    surfaceVariant = MapsColors.DarkSurface2,
+    outline        = MapsColors.DarkDivider,
+    error          = MapsColors.Error,
+)
+
+@Composable
+fun MapsTheme(
+    darkTheme: Boolean = isSystemInDarkTheme(),
+    content: @Composable () -> Unit,
+) = MaterialTheme(
+    colorScheme = if (darkTheme) MapsDark else MapsLight,
+    typography  = MapsTypography,
+    content     = content,
+)
+```
+
+## 2. Typography
+
+Apple Maps uses SF Pro at the system stack with three optical variants. On Android, SF Pro is unavailable — use the system font (Roboto), the closest neutral grotesque, and reserve `Inter` (bundled in `res/font/`) if you want a tighter match to SF Pro's metrics. Tabular figures are mandatory on every distance/time/ETA — apply `FontFeatureSetting("tnum")`.
+
+```kotlin
+// ui/theme/MapsType.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
+
+// System Roboto stack; swap to FontFamily(Font(R.font.inter_…)) for a closer SF Pro match
+private val SF = FontFamily.Default
+private val Tnum = "tnum" // FontFeatureSetting via fontFeatureSettings on numeric styles
+
+// Named ramp — mirrors DESIGN.md §3 exactly (pt → sp 1:1)
+object MapsText {
+    val PlaceTitle    = TextStyle(SF, fontWeight = FontWeight.Bold,     fontSize = 28.sp, lineHeight = 32.sp, letterSpacing = (-0.4).sp)
+    val PlaceSubtitle = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 15.sp, lineHeight = 20.sp)
+    val SearchHint    = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 17.sp, lineHeight = 22.sp)
+    val NavTitle      = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 17.sp, lineHeight = 20.sp, letterSpacing = (-0.2).sp)
+    val SectionHdr    = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 13.sp, lineHeight = 16.sp, letterSpacing = 0.4.sp) // UPPERCASE
+    val ListTitle     = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 17.sp, lineHeight = 22.sp)
+    val ListSubtitle  = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 13.sp, lineHeight = 16.sp)
+    val ETATime       = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 22.sp, lineHeight = 24.sp, letterSpacing = (-0.2).sp, fontFeatureSettings = Tnum)
+    val ETADuration   = TextStyle(SF, fontWeight = FontWeight.Medium,   fontSize = 17.sp, lineHeight = 20.sp, fontFeatureSettings = Tnum)
+    val StepTitle     = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 22.sp, lineHeight = 26.sp, letterSpacing = (-0.2).sp)
+    val StepDistance  = TextStyle(SF, fontWeight = FontWeight.Medium,   fontSize = 17.sp, lineHeight = 22.sp, fontFeatureSettings = Tnum)
+    val CategoryLabel = TextStyle(SF, fontWeight = FontWeight.Medium,   fontSize = 14.sp, lineHeight = 14.sp)
+    val Button        = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 17.sp, lineHeight = 17.sp)
+    val CityLabel     = TextStyle(SF, fontWeight = FontWeight.SemiBold, fontSize = 14.sp, lineHeight = 14.sp)
+    val Neighborhood  = TextStyle(SF, fontWeight = FontWeight.Medium,   fontSize = 12.sp, lineHeight = 12.sp)
+    val Street        = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 10.sp, lineHeight = 10.sp)
+    val TransitBadge  = TextStyle(SF, fontWeight = FontWeight.Bold,     fontSize = 12.sp, lineHeight = 12.sp)
+    val Caption       = TextStyle(SF, fontWeight = FontWeight.Normal,   fontSize = 12.sp, lineHeight = 16.sp)
+}
+
+// Map onto Material 3 slots
+val MapsTypography = Typography(
+    headlineMedium = MapsText.PlaceTitle,
+    titleMedium    = MapsText.NavTitle,
+    bodyLarge      = MapsText.ListTitle,
+    bodyMedium     = MapsText.PlaceSubtitle,
+    labelLarge     = MapsText.Button,
+    labelSmall     = MapsText.Caption,
+)
+```
+
+## 3. Signature Components
+
+### Search Card content (sliding bottom sheet — see §4 for the sheet host)
+
+iOS uses `.regularMaterial` on the card; Android has no live blur, so the sheet is a 90%-opaque `CardCanvas` surface. The grabber is a `BottomSheetScaffold` default, but the spec's exact 36×5dp / 30%-alpha pill is shown.
+
+```kotlin
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.lazy.LazyRow
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.*
+import androidx.compose.material3.Icon
+import androidx.compose.material3.Text
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.input.TextFieldValue
+import androidx.compose.ui.unit.dp
+
+@Composable
+fun SearchCardContent(expanded: Boolean) {
+    Column(Modifier.fillMaxWidth()) {
+        // Drag indicator (grabber) — exact spec
+        Box(
+            Modifier
+                .padding(top = 8.dp)
+                .align(Alignment.CenterHorizontally)
+                .size(width = 36.dp, height = 5.dp)
+                .clip(RoundedCornerShape(2.5.dp))
+                .background(MapsColors.Secondary.copy(alpha = 0.30f)),
+        )
+
+        // Search field
+        var query by remember { mutableStateOf(TextFieldValue("")) }
+        Row(
+            modifier = Modifier
+                .padding(horizontal = 16.dp, vertical = 12.dp)
+                .fillMaxWidth()
+                .height(44.dp)
+                .clip(RoundedCornerShape(10.dp))
+                .background(MapsColors.SurfaceGray)
+                .padding(horizontal = 16.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(12.dp),
+        ) {
+            Icon(Icons.Filled.Search, contentDescription = null,
+                tint = MapsColors.Secondary.copy(alpha = 0.60f), modifier = Modifier.size(18.dp))
+            Text(
+                if (query.text.isEmpty()) "Search Maps" else query.text,
+                style = MapsText.SearchHint,
+                color = if (query.text.isEmpty())
+                    MapsColors.Secondary.copy(alpha = 0.30f) else MapsColors.Ink,
+                modifier = Modifier.weight(1f),
+            )
+            Icon(Icons.Filled.Mic, contentDescription = "Voice search",
+                tint = MapsColors.Secondary.copy(alpha = 0.60f), modifier = Modifier.size(16.dp))
+        }
+
+        // Category pills — only at medium+ detent
+        if (expanded) {
+            LazyRow(
+                contentPadding = PaddingValues(horizontal = 16.dp),
+                horizontalArrangement = Arrangement.spacedBy(12.dp),
+                modifier = Modifier.padding(top = 4.dp, bottom = 16.dp),
+            ) {
+                item { CategoryPill(Icons.Filled.Restaurant, "Food", MapsColors.Food) }
+                item { CategoryPill(Icons.Filled.LocalCafe, "Coffee", MapsColors.Coffee) }
+                item { CategoryPill(Icons.Filled.LocalBar, "Drinks", MapsColors.Drinks) }
+                item { CategoryPill(Icons.Filled.ShoppingBag, "Shopping", MapsColors.Shopping) }
+                item { CategoryPill(Icons.Filled.LocalParking, "Parking", MapsColors.Parking) }
+                item { CategoryPill(Icons.Filled.Tram, "Transit", MapsColors.Blue) }
+            }
+        }
+    }
+}
+```
+
+### Category Pill
+
+```kotlin
+import androidx.compose.animation.core.animateFloatAsState
+import androidx.compose.animation.core.spring
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.interaction.collectIsPressedAsState
+import androidx.compose.ui.draw.scale
+import androidx.compose.ui.draw.shadow
+import androidx.compose.ui.graphics.vector.ImageVector
+
+@Composable
+fun CategoryPill(icon: ImageVector, label: String, color: Color, onClick: () -> Unit = {}) {
+    val interaction = remember { MutableInteractionSource() }
+    val pressed by interaction.collectIsPressedAsState()
+    val scale by animateFloatAsState(
+        if (pressed) 0.96f else 1f,
+        spring(dampingRatio = 0.7f, stiffness = 600f),
+        label = "pillScale",
+    )
+    Column(
+        modifier = Modifier
+            .size(width = 64.dp, height = 88.dp)
+            .scale(scale)
+            .shadow(12.dp, RoundedCornerShape(14.dp), spotColor = Color.Black.copy(alpha = 0.12f))
+            .clip(RoundedCornerShape(14.dp))
+            .background(MapsColors.CardCanvas) // solid white — NOT translucent
+            .clickable(interaction, indication = null, onClick = onClick)
+            .padding(vertical = 16.dp, horizontal = 8.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        Icon(icon, contentDescription = label, tint = color, modifier = Modifier.size(28.dp))
+        Text(label, style = MapsText.CategoryLabel, color = MapsColors.Ink, maxLines = 1)
+    }
+}
+```
+
+### Current-Location Puck (pulsing blue dot + directional cone)
+
+The 2s infinite pulse is a `rememberInfiniteTransition`; the cone is a custom `Path` rotated to the heading.
+
+```kotlin
+import androidx.compose.animation.core.*
+import androidx.compose.foundation.Canvas
+import androidx.compose.foundation.border
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.graphics.Path
+import androidx.compose.ui.graphics.drawscope.rotate
+
+@Composable
+fun CurrentLocationPuck(heading: Float?, modifier: Modifier = Modifier) {
+    val t = rememberInfiniteTransition(label = "puck")
+    val pulseScale by t.animateFloat(
+        1f, 1.6f,
+        infiniteRepeatable(tween(2000, easing = EaseOut), RepeatMode.Restart),
+        label = "pulseScale",
+    )
+    val pulseAlpha by t.animateFloat(
+        0.30f, 0f,
+        infiniteRepeatable(tween(2000, easing = EaseOut), RepeatMode.Restart),
+        label = "pulseAlpha",
+    )
+
+    Box(modifier.size(80.dp), contentAlignment = Alignment.Center) {
+        // Pulsing outer ring (30dp scaling 1 → 1.6, alpha 0.30 → 0)
+        Box(
+            Modifier
+                .size(30.dp)
+                .scale(pulseScale)
+                .clip(CircleShape)
+                .background(MapsColors.Blue.copy(alpha = pulseAlpha)),
+        )
+        // Directional cone (90°, gradient, 60dp) when heading known
+        if (heading != null) {
+            Canvas(Modifier.size(80.dp)) {
+                rotate(heading, pivot = center) {
+                    val cone = Path().apply {
+                        moveTo(center.x, center.y)
+                        lineTo(center.x - size.width * 0.4f, center.y - 60.dp.toPx())
+                        lineTo(center.x + size.width * 0.4f, center.y - 60.dp.toPx())
+                        close()
+                    }
+                    drawPath(
+                        cone,
+                        Brush.verticalGradient(
+                            0f to MapsColors.Blue.copy(alpha = 0.4f),
+                            1f to MapsColors.Blue.copy(alpha = 0f),
+                            startY = center.y - 60.dp.toPx(),
+                            endY = center.y,
+                        ),
+                    )
+                }
+            }
+        }
+        // Blue dot with 3dp white ring
+        Box(
+            Modifier
+                .size(22.dp)
+                .clip(CircleShape)
+                .background(MapsColors.Blue)
+                .border(3.dp, Color.White, CircleShape)
+                .shadow(4.dp, CircleShape, spotColor = Color.Black.copy(alpha = 0.2f)),
+        )
+    }
+}
+```
+
+### Map Controls (floating top-right stack)
+
+iOS uses `.regularMaterial`; Android has no live blur, so each button is a 92%-opaque white circular `Surface`.
+
+```kotlin
+import androidx.compose.material3.Surface
+
+@Composable
+fun MapControls(
+    onLayers: () -> Unit,
+    onLocation: () -> Unit,
+    on3D: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    Column(
+        modifier = modifier.padding(top = 16.dp, end = 16.dp),
+        verticalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        MapControlButton(Icons.Filled.Layers, "Map layers", onLayers)
+        MapControlButton(Icons.Filled.MyLocation, "Center on my location", onLocation)
+        MapControlButton(Icons.Filled.ThreeDRotation, "Toggle 3D", on3D)
+    }
+}
+
+@Composable
+private fun MapControlButton(icon: ImageVector, desc: String, onClick: () -> Unit) {
+    Surface(
+        color = MapsColors.CardCanvas.copy(alpha = 0.92f), // translucent — no live blur on Android
+        shape = CircleShape,
+        modifier = Modifier.size(44.dp),
+        onClick = onClick,
+    ) {
+        Box(contentAlignment = Alignment.Center) {
+            Icon(icon, contentDescription = desc, tint = MapsColors.Ink,
+                modifier = Modifier.size(18.dp))
+        }
+    }
+}
+```
+
+### Place Card (detail view) — Action Pill row
+
+```kotlin
+import androidx.compose.foundation.border
+
+enum class PillStyle { Filled, Outlined }
+
+@Composable
+fun ActionPill(
+    label: String,
+    icon: ImageVector,
+    style: PillStyle,
+    onClick: () -> Unit,
+) {
+    val haptics = androidx.compose.ui.platform.LocalHapticFeedback.current
+    val filled = style == PillStyle.Filled
+    Row(
+        modifier = Modifier
+            .heightIn(min = 44.dp)
+            .clip(CircleShape) // 22dp full pill at 44dp height
+            .then(
+                if (filled) Modifier.background(MapsColors.Blue)
+                else Modifier
+                    .background(MapsColors.CardCanvas)
+                    .border(1.dp, MapsColors.Blue, CircleShape)
+            )
+            .clickable {
+                haptics.performHapticFeedback(
+                    androidx.compose.ui.hapticfeedback.HapticFeedbackType.LongPress) // ~iOS .medium
+                onClick()
+            }
+            .padding(horizontal = 20.dp, vertical = 12.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        Icon(icon, contentDescription = null,
+            tint = if (filled) Color.White else MapsColors.Blue, modifier = Modifier.size(14.dp))
+        Text(label, style = MapsText.Button, color = if (filled) Color.White else MapsColors.Blue)
+    }
+}
+
+@Composable
+fun PlaceCardHeader(title: String, subtitle: String, onClose: () -> Unit) {
+    Row(
+        Modifier.fillMaxWidth().padding(horizontal = 20.dp, vertical = 16.dp),
+        verticalAlignment = Alignment.Top,
+    ) {
+        Column(Modifier.weight(1f)) {
+            Text(title, style = MapsText.PlaceTitle, color = MapsColors.Ink)
+            Text(subtitle, style = MapsText.PlaceSubtitle,
+                color = MapsColors.Secondary.copy(alpha = 0.60f))
+        }
+        Surface(
+            color = MapsColors.SurfaceGray.copy(alpha = 0.92f),
+            shape = CircleShape,
+            modifier = Modifier.size(30.dp),
+            onClick = onClose,
+        ) {
+            Box(contentAlignment = Alignment.Center) {
+                Icon(Icons.Filled.Close, contentDescription = "Close",
+                    tint = MapsColors.Secondary.copy(alpha = 0.80f),
+                    modifier = Modifier.size(14.dp))
+            }
+        }
+    }
+}
+```
+
+### Direction Step Card + ETA Bar
+
+```kotlin
+@Composable
+fun StepCard(arrow: ImageVector, arrowRotation: Float, title: String, distance: String) {
+    Surface(color = MapsColors.CardCanvas.copy(alpha = 0.92f), tonalElevation = 0.dp) {
+        Row(
+            Modifier.fillMaxWidth().height(96.dp).padding(horizontal = 20.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(16.dp),
+        ) {
+            Icon(
+                arrow, contentDescription = null, tint = MapsColors.Blue,
+                modifier = Modifier
+                    .size(56.dp)
+                    .androidx.compose.ui.draw.rotate(arrowRotation),
+            )
+            Column(Modifier.weight(1f)) {
+                Text(title, style = MapsText.StepTitle, color = MapsColors.Ink, maxLines = 2)
+                Text(distance, style = MapsText.StepDistance,
+                    color = MapsColors.Secondary.copy(alpha = 0.60f))
+            }
+        }
+    }
+}
+
+@Composable
+fun ETABar(duration: String, arrival: String, onEnd: () -> Unit) {
+    Surface(color = MapsColors.CardCanvas.copy(alpha = 0.92f), tonalElevation = 0.dp) {
+        Row(
+            Modifier.fillMaxWidth().height(80.dp).padding(horizontal = 20.dp),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            Column(Modifier.weight(1f)) {
+                Text(duration, style = MapsText.ETATime, color = MapsColors.Ink)
+                Text(arrival, style = MapsText.ETADuration,
+                    color = MapsColors.Secondary.copy(alpha = 0.60f))
+            }
+            Row(
+                Modifier
+                    .clip(CircleShape)
+                    .background(MapsColors.CardCanvas)
+                    .border(1.dp, MapsColors.Error, CircleShape)
+                    .clickable(onClick = onEnd)
+                    .padding(horizontal = 20.dp, vertical = 12.dp),
+            ) {
+                Text("End", style = MapsText.Button, color = MapsColors.Error)
+            }
+        }
+    }
+}
+```
+
+### Transit Line Badge
+
+```kotlin
+@Composable
+fun TransitBadge(label: String, color: Color) {
+    Box(
+        Modifier
+            .defaultMinSize(minWidth = 24.dp, minHeight = 24.dp)
+            .clip(RoundedCornerShape(4.dp))
+            .background(color) // agency-accurate color, never recolored
+            .padding(horizontal = 6.dp),
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(label, style = MapsText.TransitBadge, color = Color.White)
+    }
+}
+```
+
+## 4. The Sliding Bottom Search Sheet (signature interaction)
+
+Apple Maps' defining move is the translucent search card with three detents. iOS uses `.presentationDetents([.height(88), .medium, .large])`; the Compose equivalent is Material 3 `BottomSheetScaffold` with a custom `SheetState`. The sheet stays partially expanded (peek = 88.dp) so the user can still pan the map beneath it — that's the Apple Maps "background interaction" behavior, native to `BottomSheetScaffold`.
+
+```kotlin
+import androidx.compose.material3.BottomSheetScaffold
+import androidx.compose.material3.SheetValue
+import androidx.compose.material3.rememberBottomSheetScaffoldState
+import androidx.compose.material3.rememberStandardBottomSheetState
+
+@OptIn(androidx.compose.material3.ExperimentalMaterial3Api::class)
+@Composable
+fun MapScreen() {
+    val sheetState = rememberStandardBottomSheetState(
+        initialValue = SheetValue.PartiallyExpanded, // ≈ iOS "small" detent
+        skipHiddenState = true,
+    )
+    val scaffoldState = rememberBottomSheetScaffoldState(bottomSheetState = sheetState)
+    val expanded = sheetState.currentValue == SheetValue.Expanded
+
+    BottomSheetScaffold(
+        scaffoldState = scaffoldState,
+        sheetPeekHeight = 88.dp,                          // small detent
+        sheetContainerColor = MapsColors.CardCanvas.copy(alpha = 0.90f), // translucent (no live blur)
+        sheetShape = RoundedCornerShape(topStart = 10.dp, topEnd = 10.dp),
+        sheetContent = { SearchCardContent(expanded = expanded) },
+    ) {
+        Box(Modifier.fillMaxSize()) {
+            // GoogleMap(...) styled with MapStyleOptions JSON → cream palette goes here
+            MapControls(
+                onLayers = {}, onLocation = {}, on3D = {},
+                modifier = Modifier.align(Alignment.TopEnd),
+            )
+        }
+    }
+}
+```
+
+For a true 3-stop detent (88dp / ~50% / full), wrap a custom `AnchoredDraggable` (Compose Foundation 1.6+) with three anchors, or gate `SearchCardContent`'s category row on a `derivedStateOf` height threshold as shown. Animate detent changes with `spring(dampingRatio = 0.85f, stiffness = 380f)` to match the spec's "350ms physical paper" feel.
+
+## 5. Navigation
+
+Apple Maps has **no bottom tab bar** — the entire experience is the map plus the sliding search sheet and a contextual place card. Do **not** add a Material `NavigationBar`. Navigation between Map → Place Card → Directions is modeled as bottom-sheet content swaps inside the single `BottomSheetScaffold` (use `AnimatedContent` to cross-fade Search ↔ Place ↔ Directions content). Floating chrome (map controls, step card, ETA bar) overlays the map with translucent `Surface`s — Android has no live blur, so a 92%-opaque surface stands in for `.regularMaterial`.
+
+## 6. Motion
+
+| Moment | Compose recipe |
+|--------|----------------|
+| Search card detent transition | `spring(dampingRatio = 0.85f, stiffness = 380f)` ≈ 350ms physical |
+| Pin drop (long-press) | `Animatable` translationY + `spring(dampingRatio = 0.65f)` ~400ms bounce; `HapticFeedbackType.LongPress` |
+| Current-location lock | camera animate 600ms `EaseOut`, then puck `Animatable` 1 → 1.2 → 1 pulse |
+| Category pill tap | `animateFloatAsState` 1 → 0.96 → 1 `spring(dampingRatio = 0.7f)` |
+| Direction step transition | `AnimatedContent` 300ms cross-fade; arrow `animateFloatAsState` rotation 250ms |
+| Map style picker | `AnimatedVisibility` expand from the layer button (no native shared-element morph required) |
+| Look Around launch | 600ms `Crossfade` from map to 360° view |
+| Current-location pulse | `rememberInfiniteTransition` 2000ms: scale 1 → 1.6, alpha 0.30 → 0, infinite |
+
+```kotlin
+// Pin drop — exact 400ms ease-out bounce
+@Composable
+fun rememberPinDrop(dropped: Boolean): Float {
+    val offsetY = remember { Animatable(-120f) }
+    LaunchedEffect(dropped) {
+        if (dropped) offsetY.animateTo(
+            0f,
+            spring(dampingRatio = 0.65f, stiffness = 350f),
+        )
+    }
+    return offsetY.value
+}
+```
+
+Haptics: prefer `LocalHapticFeedback`. For richer control use `LocalView.current.performHapticFeedback(HapticFeedbackConstants.CONTEXT_CLICK)` (API 30+) — map `.medium` (pin drop, Directions tap) to `VibrationEffect.createOneShot(15, DEFAULT_AMPLITUDE)`, `.selection` (map-style picker) to a short tick, and `.success` (arrived at destination) to a double-buzz `VibrationEffect.createWaveform(longArrayOf(0, 40, 60, 40), -1)`, mirroring iOS `.notificationOccurred(.success)`.
+
+## 7. Icons
+
+Apple Maps uses SF Symbols; the closest first-party set is `androidx.compose.material:material-icons-extended`. For exact parity (the directional cone, the agency transit badges, the dropped-pin teardrop) ship custom vector drawables and load via `ImageVector.vectorResource(R.drawable.…)` — the cone is drawn with `Canvas` (see §3).
+
+| Component | SF Symbol (iOS) | Material Icon (Compose) |
+|-----------|-----------------|--------------------------|
+| Search | `magnifyingglass` | `Icons.Filled.Search` |
+| Microphone | `mic.fill` | `Icons.Filled.Mic` |
+| Close | `xmark` | `Icons.Filled.Close` |
+| Layer picker | `square.3.layers.3d` | `Icons.Filled.Layers` |
+| Current location (locked) | `location.fill` | `Icons.Filled.MyLocation` |
+| Current location (unlocked) | `location` | `Icons.Filled.LocationSearching` |
+| 3D toggle | `view.3d` | `Icons.Filled.ThreeDRotation` |
+| Compass | `safari` | `Icons.Filled.Explore` |
+| Dropped pin | `mappin.and.ellipse` | `Icons.Filled.LocationOn` (or custom teardrop drawable, Maps Red) |
+| Directions | `arrow.triangle.turn.up.right.diamond.fill` | `Icons.AutoMirrored.Filled.Directions` |
+| Call | `phone.fill` | `Icons.Filled.Call` |
+| Share | `square.and.arrow.up` | `Icons.Filled.IosShare` |
+| Save | `heart` / `heart.fill` | `Icons.Outlined.FavoriteBorder` / `Icons.Filled.Favorite` |
+| Look Around | `binoculars.fill` | `Icons.Filled.Visibility` |
+| Food category | `fork.knife` | `Icons.Filled.Restaurant` |
+| Coffee category | `cup.and.saucer.fill` | `Icons.Filled.LocalCafe` |
+| Drinks category | `wineglass.fill` | `Icons.Filled.LocalBar` |
+| Shopping | `bag.fill` | `Icons.Filled.ShoppingBag` |
+| Parking | `parkingsign.circle.fill` | `Icons.Filled.LocalParking` |
+| Transit | `tram.fill` | `Icons.Filled.Tram` |
+| Direction arrow (turn) | `arrow.turn.up.right` / `.left` | `Icons.AutoMirrored.Filled.TurnRight` / `TurnLeft` |
+| Phone (place row) | `phone.fill` | `Icons.Filled.Call` |
+| Globe (website row) | `globe` | `Icons.Filled.Language` |
+
+## 8. Minimum SDK & Accessibility Notes
+
+- **minSdk 24** (Compose floor is 21; `BottomSheetScaffold` + `Canvas` cone + Maps Compose are comfortable at 24). `compileSdk 34+`, Compose BOM `2024.09+`, Kotlin `2.0+`.
+- **Edge-to-edge**: call `enableEdgeToEdge()` in the `Activity`. The map is full-bleed under the status bar; request dark-content (dark icons) over the cream canvas, light-content in dark mode. Apply `Scaffold`/`WindowInsets.systemBars` padding so the search sheet's small detent clears the gesture nav and map controls sit 16.dp below the status bar / Dynamic-Island analog (the display cutout).
+- **Font scaling**: `sp` honors the user's font scale — keep it on the place-card title, list rows, button labels, and body. Pin layout/zoom-sensitive text (map labels, ETA numbers, distance/time tabular figures, 14sp category labels) by deriving size from `dp` or `CompositionLocalProvider(LocalDensity provides Density(density, fontScale = 1f))`. The place-card title scales but clamp at ~36sp. Keep `fontFeatureSettings = "tnum"` on every numeric style for column alignment.
+- **TalkBack**: the place card reads as one node — `Modifier.semantics(mergeDescendants = true) { contentDescription = "$title, $subtitle, ${if (isOpen) "Open" else "Closed"}, $closingTime" }`; the current-location puck announces `"Your current location"`; the dropped pin exposes its reverse-geocoded address. Mark each map control button with its own `contentDescription` ("Center on my location", etc.).
+- **Touch targets**: Material guidance is 48.dp minimum. Map control buttons and action pills are 44.dp — bump to 48.dp via padding. The category pill is 64×88dp (well clear). The pin tap target needs a 48.dp hit box centered on the teardrop tip even though the glyph is smaller.
+- **Contrast**: pure black on cream `#F6F1E6` passes WCAG AAA. `#3C3C43`@60% on cream passes AA only at ≥18sp Bold or ≥14sp Medium — do not use it for the 13sp list subtitle as primary information; it's acceptable as supporting metadata only.
+- **Reduce motion**: when `Settings.Global.ANIMATOR_DURATION_SCALE == 0f`, skip the 2s puck pulse (render a static blue dot) and the pin-drop bounce (place the pin instantly).
+- **Dynamic color**: do **not** enable Material You `dynamicColorScheme()` — the cream `#F6F1E6` cartography, Maps Blue `#0A84FF` polyline/puck, and Maps Red `#FF3B30` pin are signature, intentionally system-Apple (not system-Android) colors and must not recolor to the user's wallpaper.