# Apple TV (iOS) — Jetpack Compose Implementation Guide

Companion to [DESIGN.md](DESIGN.md) — the framework-neutral spec. This file ports the Apple TV app's visual language to **Android with Jetpack Compose (Material 3)**: a color token object, a `Typography` set, paste-ready `@Composable`s, the inset hero card + Up Next rail, 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 (the true-black canvas, the inset rounded floating hero, the Up Next rail with white resume bars, the single system-blue accent) while making everything idiomatic Android — `NavigationBar` instead of a UITabBar, `LazyRow` instead of horizontal `ScrollView`, `dp`/`sp` instead of `pt`. The Apple TV app exists on Android TV / Google TV, so this is a real surface.

Assumes Compose BOM `2024.09+`, Kotlin `2.0+`, `minSdk 24`, Material 3, and Coil `2.6+` for key art. The browse experience is true-black — no light scheme, no Material You dynamic color (the restrained Apple identity must hold regardless of wallpaper).

## 1. Color Tokens

```kotlin
// ui/theme/AppleTVColors.kt
import androidx.compose.ui.graphics.Color

object AppleTVColors {
    // Canvas & surfaces (true-black product)
    val Canvas   = Color(0xFF000000) // pure true black — OLED pixels off
    val Surface1 = Color(0xFF1C1C1E)
    val Surface2 = Color(0xFF2C2C2E)
    val Divider  = Color(0xFF38383A)

    // Text (iOS dark label ramp)
    val TextPrimary   = Color(0xFFFFFFFF)
    val TextSecondary = Color(0xFF98989F)
    val TextTertiary  = Color(0xFF636366)

    // Primary CTA (always white)
    val Cta        = Color(0xFFFFFFFF)
    val CtaPressed = Color(0xFFE5E5EA)
    val CtaLabel   = Color(0xFF000000)

    // Accent (the only one — iOS dark systemBlue)
    val Blue        = Color(0xFF0A84FF)
    val BluePressed = Color(0xFF0060DF)

    // iOS translucent control fill (secondary buttons, search base)
    val GlassFill = Color(0x5C78787F) // ~36% (120,120,128)

    // Semantic
    val MLS     = Color(0xFFED1A6F) // MLS Season Pass ONLY
    val Live    = Color(0xFFFF453A)
    val Success = Color(0xFF30D158)
    val Gold    = Color(0xFFFFD60A)
}
```

The browse experience is true-black-first. Wire a single dark scheme; the light scheme is intentionally a copy (only embedded Store/account, out of scope here).

```kotlin
// ui/theme/Theme.kt
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.runtime.Composable

private val AppleTVDark = darkColorScheme(
    primary        = AppleTVColors.Cta,         // white CTA
    onPrimary      = AppleTVColors.CtaLabel,
    secondary      = AppleTVColors.Blue,        // the single accent (links / active tab)
    background     = AppleTVColors.Canvas,      // pure black
    onBackground   = AppleTVColors.TextPrimary,
    surface        = AppleTVColors.Surface1,
    onSurface      = AppleTVColors.TextPrimary,
    surfaceVariant = AppleTVColors.Surface2,
    outline        = AppleTVColors.Divider,
    error          = AppleTVColors.Live,
)

@Composable
fun AppleTVTheme(content: @Composable () -> Unit) =
    MaterialTheme(
        colorScheme = AppleTVDark,   // true-black only; do NOT use dynamicDarkColorScheme()
        typography  = AppleTVTypography,
        content     = content,
    )
```

## 2. Typography

The brand face is **SF Pro** (not redistributable). On Android, ship **Inter** (SIL OFL) in `res/font/` as the standard SF substitute — it shares the geometric-grotesque idiom. HIG-canonical ramp; `pt → sp` 1:1.

```kotlin
// ui/theme/AppleTVType.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 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),
    Font(R.font.inter_extrabold, FontWeight.ExtraBold),
)

object AppleTVText {
    val LargeTitle = TextStyle(Inter, fontWeight = FontWeight.ExtraBold, fontSize = 34.sp, lineHeight = 36.sp, letterSpacing = (-0.8).sp)
    val HeroTitle  = TextStyle(Inter, fontWeight = FontWeight.ExtraBold, fontSize = 28.sp, lineHeight = 30.sp, letterSpacing = (-0.6).sp)
    val RowHeader  = TextStyle(Inter, fontWeight = FontWeight.Bold,      fontSize = 22.sp, lineHeight = 26.sp, letterSpacing = (-0.3).sp)
    val Title3     = TextStyle(Inter, fontWeight = FontWeight.SemiBold,  fontSize = 20.sp, lineHeight = 25.sp, letterSpacing = (-0.2).sp)
    val Body       = TextStyle(Inter, fontWeight = FontWeight.Normal,    fontSize = 17.sp, lineHeight = 25.sp)
    val Headline   = TextStyle(Inter, fontWeight = FontWeight.SemiBold,  fontSize = 15.sp, lineHeight = 20.sp)
    val Subhead    = TextStyle(Inter, fontWeight = FontWeight.Normal,    fontSize = 13.sp, lineHeight = 18.sp)
    val Caption    = TextStyle(Inter, fontWeight = FontWeight.Medium,    fontSize = 12.sp, lineHeight = 14.sp)
    val Eyebrow    = TextStyle(Inter, fontWeight = FontWeight.Bold,      fontSize = 11.sp, lineHeight = 11.sp, letterSpacing = 1.2.sp)
    val Button     = TextStyle(Inter, fontWeight = FontWeight.SemiBold,  fontSize = 15.sp, lineHeight = 15.sp)
    val ChannelTag = TextStyle(Inter, fontWeight = FontWeight.Bold,      fontSize = 9.sp,  lineHeight = 9.sp,  letterSpacing = 0.4.sp)
}

val AppleTVTypography = Typography(
    headlineLarge  = AppleTVText.LargeTitle,
    headlineMedium = AppleTVText.HeroTitle,
    titleLarge     = AppleTVText.RowHeader,
    titleMedium    = AppleTVText.Title3,
    bodyLarge      = AppleTVText.Body,
    labelSmall     = AppleTVText.Caption,
)
```

## 3. Signature Components

### Inset Rounded Hero Card

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.*
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Add
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material3.*
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.unit.dp
import coil.compose.AsyncImage

@Composable
fun HeroCard(
    artUrl: String,
    eyebrow: String,    // "Apple TV+ · New Episode"
    title: String,
    meta: String,
    onPlay: () -> Unit,
    onAdd: () -> Unit,
) {
    Box(
        Modifier
            .fillMaxWidth()
            .padding(horizontal = 14.dp)   // inset — the floating-gallery treatment
            .height(380.dp)
            .clip(RoundedCornerShape(16.dp))
    ) {
        AsyncImage(
            model = artUrl, contentDescription = title,
            modifier = Modifier.matchParentSize(), contentScale = ContentScale.Crop,
        )
        Box(
            Modifier.matchParentSize().background(
                Brush.verticalGradient(
                    0.40f to Color.Transparent,
                    0.72f to Color.Black.copy(alpha = 0.65f),
                    1.0f  to Color.Black.copy(alpha = 0.92f),
                )
            )
        )
        Column(
            Modifier.align(Alignment.BottomStart).padding(18.dp),
            verticalArrangement = Arrangement.spacedBy(7.dp),
        ) {
            Text(eyebrow.uppercase(), style = AppleTVText.Eyebrow, color = AppleTVColors.TextSecondary)
            Text(title, style = AppleTVText.HeroTitle, color = AppleTVColors.TextPrimary)
            Text(meta, style = AppleTVText.Caption, color = AppleTVColors.TextSecondary)
            Row(horizontalArrangement = Arrangement.spacedBy(10.dp)) {
                Button(
                    onClick = onPlay,
                    colors = ButtonDefaults.buttonColors(containerColor = AppleTVColors.Cta, contentColor = AppleTVColors.CtaLabel),
                    shape = RoundedCornerShape(12.dp),
                    contentPadding = PaddingValues(horizontal = 30.dp, vertical = 13.dp),
                ) {
                    Icon(Icons.Filled.PlayArrow, null, modifier = Modifier.size(14.dp))
                    Spacer(Modifier.width(7.dp))
                    Text("Play", style = AppleTVText.Button)
                }
                Surface(
                    onClick = onAdd,
                    color = AppleTVColors.GlassFill,
                    shape = CircleShape,
                    modifier = Modifier.size(44.dp),
                ) {
                    Box(contentAlignment = Alignment.Center) {
                        Icon(Icons.Filled.Add, null, tint = Color.White, modifier = Modifier.size(20.dp))
                    }
                }
            }
        }
    }
}
```

### Up Next Thumbnail (16:9 + resume bar)

```kotlin
import androidx.compose.animation.core.animateFloatAsState
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.interaction.collectIsPressedAsState
import androidx.compose.ui.draw.scale

@Composable
fun UpNextThumb(
    artUrl: String,
    title: String,
    subhead: String,            // "S3 E8 · 24 min left"
    progress: Float = 0f,       // 0..1; 0 hides the bar
    channelTag: String? = "Apple TV+",
) {
    val interaction = remember { MutableInteractionSource() }
    val pressed by interaction.collectIsPressedAsState()
    val s by animateFloatAsState(if (pressed) 0.97f else 1f, label = "thumb")

    Column(Modifier.width(196.dp)) {
        Box(
            Modifier.size(196.dp, 110.dp).scale(s).clip(RoundedCornerShape(10.dp))
        ) {
            AsyncImage(model = artUrl, contentDescription = title,
                modifier = Modifier.matchParentSize(), contentScale = ContentScale.Crop)
            if (channelTag != null) {
                Box(
                    Modifier.align(Alignment.TopStart).padding(8.dp)
                        .clip(RoundedCornerShape(5.dp))
                        .background(Color.Black.copy(alpha = 0.40f)) // Android has no live blur; tinted scrim
                        .padding(horizontal = 6.dp, vertical = 3.dp)
                ) { Text(channelTag, style = AppleTVText.ChannelTag, color = Color.White) }
            }
            if (progress > 0f) {
                Box(
                    Modifier.align(Alignment.BottomStart).fillMaxWidth().height(4.dp)
                        .background(Color.White.copy(alpha = 0.28f))
                ) {
                    Box(Modifier.fillMaxWidth(progress).fillMaxHeight().background(Color.White))
                }
            }
        }
        Spacer(Modifier.height(8.dp))
        Text(title, style = AppleTVText.Headline, color = AppleTVColors.TextPrimary, maxLines = 1)
        Spacer(Modifier.height(2.dp))
        Text(subhead, style = AppleTVText.Subhead, color = AppleTVColors.TextSecondary, maxLines = 1)
    }
}
```

### Live Badge & MLS Chip

```kotlin
import androidx.compose.animation.core.*

@Composable
fun LiveBadge() {
    val t = rememberInfiniteTransition(label = "live")
    val a by t.animateFloat(1f, 0.4f, infiniteRepeatable(tween(1200), RepeatMode.Reverse), label = "dot")
    Row(
        Modifier.clip(RoundedCornerShape(6.dp)).background(AppleTVColors.Live)
            .padding(horizontal = 10.dp, vertical = 5.dp),
        verticalAlignment = Alignment.CenterVertically,
        horizontalArrangement = Arrangement.spacedBy(6.dp),
    ) {
        Box(Modifier.size(7.dp).clip(CircleShape).background(Color.White.copy(alpha = a)))
        Text("LIVE", style = AppleTVText.Eyebrow.copy(letterSpacing = 0.6.sp), color = Color.White)
    }
}

@Composable
fun MLSChip(title: String) {
    // #ED1A6F is the ONLY non-system brand color — MLS Season Pass surfaces only
    Box(
        Modifier.clip(RoundedCornerShape(10.dp)).background(AppleTVColors.MLS)
            .padding(horizontal = 14.dp, vertical = 7.dp)
    ) { Text(title, style = AppleTVText.Caption.copy(fontWeight = FontWeight.Bold), color = Color.White) }
}
```

### Shelf Header

```kotlin
import androidx.compose.material.icons.filled.ChevronRight

@Composable
fun ShelfHeader(title: String, accessory: (@Composable () -> Unit)? = null) {
    Row(
        Modifier.fillMaxWidth().padding(horizontal = 18.dp).padding(bottom = 10.dp),
        verticalAlignment = Alignment.CenterVertically,
        horizontalArrangement = Arrangement.spacedBy(8.dp),
    ) {
        Text(title, style = AppleTVText.RowHeader, color = AppleTVColors.TextPrimary)
        accessory?.invoke()
        Spacer(Modifier.weight(1f))
        Icon(Icons.Filled.ChevronRight, null, tint = AppleTVColors.TextTertiary, modifier = Modifier.size(16.dp))
    }
}
```

## 4. Navigation

The Apple TV app has a 4-tab bottom strip and a large title. On Android, model the strip as a `NavigationBar` with a translucent surface; there is no tint pill — active is the system-blue icon.

```kotlin
import androidx.compose.material.icons.filled.*

@Composable
fun AppleTVBottomBar(selected: Int, onSelect: (Int) -> Unit) {
    NavigationBar(
        containerColor = AppleTVColors.Canvas.copy(alpha = 0.92f),
        tonalElevation = 0.dp,
    ) {
        val items = listOf(
            "Watch Now" to Icons.Filled.PlayArrow,
            "TV+"       to Icons.Filled.Tv,
            "Store"     to Icons.Filled.ShoppingBag,
            "Search"    to Icons.Filled.Search,
        )
        items.forEachIndexed { i, (label, icon) ->
            NavigationBarItem(
                selected = selected == i,
                onClick = { onSelect(i) },
                icon = { Icon(icon, contentDescription = label, modifier = Modifier.size(24.dp)) },
                label = { Text(label, style = AppleTVText.Caption) },
                colors = NavigationBarItemDefaults.colors(
                    selectedIconColor   = AppleTVColors.Blue,   // system blue, no pill
                    selectedTextColor   = AppleTVColors.Blue,
                    unselectedIconColor = AppleTVColors.TextTertiary,
                    unselectedTextColor = AppleTVColors.TextTertiary,
                    indicatorColor      = Color.Transparent,     // no Material pill — Apple TV has none
                ),
            )
        }
    }
}
```

The large title is a `Text` in `AppleTVText.LargeTitle` with a trailing 30.dp circular avatar; collapse it to an inline `TopAppBar` on scroll via a `nestedScroll` connection. Content shelves are `LazyRow`s with `contentPadding = PaddingValues(horizontal = 18.dp)` so the last thumbnail clips off the trailing edge. The detail page is a standard pushed screen with the inset hero and the white Play CTA.

## 5. Motion

Apple TV motion is system-canonical and quiet — springs and standard transitions, no custom flourishes.

| Moment | Compose recipe |
|--------|----------------|
| Thumbnail press | `collectIsPressedAsState()` → `animateFloatAsState(0.97f, tween(120))` on `Modifier.scale` |
| Live dot pulse | `rememberInfiniteTransition` → `animateFloat(1f, 0.4f, infiniteRepeatable(tween(1200), Reverse))` |
| Hero cross-fade (~10s, if multiple) | `Crossfade(targetState = featuredIndex, animationSpec = tween(400))` |
| Large title collapse | `TopAppBarDefaults.enterAlwaysScrollBehavior()` / custom `nestedScroll` tied to offset |
| Detail open | `NavHost` slide push `tween(350)` (system-feeling) |
| Resume bar | rendered at value, no animation (it is state, not feedback) |
| Shelf scroll | `LazyRow` native fling — free scroll, no snap |

```kotlin
// Thumbnail press — the canonical quiet Apple TV motion
val s by animateFloatAsState(if (pressed) 0.97f else 1f, tween(120), label = "press")
Modifier.scale(s)
```

Haptics: keep it sparing and system-like — `LocalHapticFeedback.performHapticFeedback(HapticFeedbackType.TextHandleMove)` (a light selection tick) on thumbnail tap; nothing custom. Playback start/stop is silent. Apple's restraint extends to haptics — do not over-buzz.

## 6. Icons

The closest first-party set is `androidx.compose.material:material-icons-extended` (its glyphs read close to SF Symbols). The Apple TV logomark must be a vector drawable / `ImageVector` — it is not an icon-font glyph.

| Purpose | SF Symbol (iOS) | Material Icon (Compose) |
|---------|-----------------|--------------------------|
| Watch Now (tab) | `play.tv` / `play.tv.fill` | `Icons.Filled.PlayArrow` |
| TV+ (tab) | `play.rectangle.on.rectangle` | `Icons.Filled.Tv` |
| Store (tab) | `bag` / `bag.fill` | `Icons.Filled.ShoppingBag` |
| Search (tab) | `magnifyingglass` | `Icons.Filled.Search` |
| MLS (when subscribed) | `sportscourt` / `soccerball` | `Icons.Filled.SportsSoccer` |
| Play (CTA) | `play.fill` | `Icons.Filled.PlayArrow` |
| Add | `plus` / `checkmark` | `Icons.Filled.Add` / `Icons.Filled.Check` |
| Back | `chevron.left` | `Icons.Filled.ArrowBack` |
| More / disclosure | `chevron.right` | `Icons.Filled.ChevronRight` |
| Download | `arrow.down.circle` | `Icons.Filled.Download` |
| Cast / AirPlay | `airplayvideo` | `Icons.Filled.Cast` |
| Profile | (avatar) / `person.crop.circle` | `Icons.Filled.AccountCircle` |
| Live | `dot.radiowaves.left.and.right` | `Icons.Filled.SensorsOutlined` |
| Trailer | `play.rectangle` | `Icons.Filled.SmartDisplay` |
| Info | `info.circle` | `Icons.Filled.InfoOutline` |
| Settings | `gearshape` | `Icons.Filled.Settings` |

## 7. Minimum SDK & Accessibility Notes

- **minSdk 24** (Compose floor is 21; modern motion is comfortable at 24). `compileSdk 34+`, Compose BOM `2024.09+`, Kotlin `2.0+`.
- **Edge-to-edge**: call `enableEdgeToEdge()`; the true-black canvas wants light-content system bars in all states. The hero card is inset (so it never reaches the status bar); the bottom bar respects the navigation bar inset.
- **True-black only**: ship only `AppleTVDark`; do **not** call `dynamicDarkColorScheme()` — Apple TV's restrained identity must hold regardless of wallpaper. Ignore `isSystemInDarkTheme()` for browse.
- **Pure `#000000` matters**: the inset hero's "floating" effect depends on a true-black canvas (OLED pixels off). Do not substitute a charcoal `Surface`.
- **Font scaling**: `sp` honors the user's font scale — keep it on Large Title, hero, row headers, body, subhead. Pin layout-sensitive text (tab labels, channel tags, eyebrows, "LIVE") via `CompositionLocalProvider(LocalDensity provides Density(density, fontScale = 1f))` so it never overflows thumbnail art.
- **TalkBack**: label Up Next thumbnails "{title}, {subhead}, {progress} percent watched"; the white CTA "Play {title}"; live cards "Live now"; group hero eyebrow+title+meta into one `Modifier.semantics(mergeDescendants = true)` node; mark the pulsing live dot `Modifier.clearAndSetSemantics {}` (decorative).
- **Touch targets**: Material guidance is 48.dp. Up Next thumbnails far exceed it; give the 24.dp tab icons a 48.dp hit area (`NavigationBarItem` handles this); the Play button is ≥ 44.dp tall; the round glass add is 44.dp.
- **Contrast**: white `#FFFFFF` and `#98989F` on `#000000` pass WCAG AA; the white CTA with black label passes AAA; `#0A84FF` is the system link color (AA on black); MLS pink `#ED1A6F` with white passes AA. Never place body text on the blue accent.
- **Reduce motion / transparency**: when `Settings.Global.ANIMATOR_DURATION_SCALE == 0`, replace the hero `Crossfade` with an instant swap and stop the live-dot pulse (static dot); keep the press scale subtle. The Android tab background is already a tinted scrim (no live blur), so no transparency fallback is needed — but keep it ≥ 0.92 opacity for contrast.
- **Restraint is the brand**: do not add extra elevation, shadows, badges, or accent colors to "improve" the design — Apple TV's value is its minimalism. MLS pink `#ED1A6F` is the ONLY non-system brand color, used on MLS Season Pass surfaces only.