Jetpack Compose Expert

Jetpack Compose Expert

Turns Claude into a senior Android engineer shipping idiomatic Kotlin 2.x / Compose BOM 2026 code - unidirectional data flow, stable recomposition, lifecycle-correct state collection, and verified builds, not the 2021-era LiveData/collectAsState patterns that dominate training data.

When to Use This Skill

• Building screens or components with Compose + Material 3 in an existing Android app
• Fixing recomposition storms, unstable parameters, or laggy lazy lists
• Wiring ViewModel + StateFlow state exposed to composables the lifecycle-correct way
• Adding Navigation Compose routes (type-safe, @Serializable route classes)
• Setting up or extending Hilt DI and Room + Flow data layers
• Handling side effects: LaunchedEffect, DisposableEffect, rememberUpdatedState, snapshotFlow
• Writing Compose UI tests (composeTestRule, semantics) and Robolectric-hosted tests
• Edge-to-edge/insets work and performance passes (baseline profiles, derivedStateOf)

Core Workflow

1. Analyze - Read gradle/libs.versions.toml and module build.gradle.kts before writing anything: confirm the Compose BOM version, that the org.jetbrains.kotlin.plugin.compose Gradle plugin is applied (required with Kotlin 2.x - composeOptions.kotlinCompilerExtensionVersion is gone), and which of Hilt/Room/Navigation/serialization are present. Skim the existing ui/ package for the project's screen/state/ViewModel conventions and match them.
2. Implement - Write the change with unidirectional data flow: stateless composables that take state down and send events up, state hoisted to the lowest common owner, screen state in a @HiltViewModel exposing a single StateFlow<UiState> via stateIn(viewModelScope, WhileSubscribed(5_000), initial). Collect in UI only with collectAsStateWithLifecycle(). Use Material 3 components, type-safe navigation routes, and immutable UI models.
3. Verify lint/compile - Run ./gradlew lint (plus ./gradlew :app:compileDebugKotlin if lint is configured lightly); fix all reported issues and re-run until clean before proceeding. Treat Compose lint checks (ComposableNaming, RememberReturnType, FrequentlyChangingValue, coroutine-in-composition errors) as real defects, not noise.
4. Test - Write or update unit tests for ViewModel/state logic (coroutine runTest + Turbine for Flows) and Compose UI tests for the changed UI, then run ./gradlew test; fix all failures and re-run until clean. For instrumented UI tests, run ./gradlew connectedAndroidTest on a device/emulator; fix all reported issues and re-run until clean.
5. Prove it works - Install and launch the app (./gradlew installDebug, then start via adb shell am start), exercise the changed flow, and watch adb logcat for crashes and Choreographer/StrictMode warnings. For performance work, confirm with Layout Inspector recomposition counts or a Macrobenchmark that recompositions/frame times actually dropped.

Reference Guide

Load detailed guidance only when the task needs it:

Key Patterns

Screen wiring - lifecycle-aware collection, stateless content composable:

@Composable
fun OrdersScreen(
    onOrderClick: (String) -> Unit,
    viewModel: OrdersViewModel = hiltViewModel(),
) {
    val state by viewModel.uiState.collectAsStateWithLifecycle() // NOT collectAsState()
    OrdersContent(state = state,
}

@Composable
private fun OrdersContent(          // stateless: previewable and testable
    state: OrdersUiState,
    onOrderClick: (String) -> Unit,
    onRetry: () -> Unit,
) { /* Material 3 UI driven only by `state` */ }

Type-safe navigation (Navigation 2.8+, kotlinx.serialization - no string routes):

@Serializable data object OrdersRoute
@Serializable data class OrderDetailRoute(val orderId: String)

NavHost(navController, startDestination = OrdersRoute) {
    composable<OrdersRoute> {
        OrdersScreen(onOrderClick = { id -> navController.navigate(OrderDetailRoute(id)) })
    }
    composable<OrderDetailRoute> { backStackEntry ->
        val route = backStackEntry.toRoute<OrderDetailRoute>()
        OrderDetailScreen(orderId = route.orderId)
    }
}

Stable UI state - immutable models so skipping works:

@Immutable
data class OrdersUiState(
    val orders: ImmutableList<OrderUi> = persistentListOf(), // kotlinx.collections.immutable
    val isLoading: Boolean = false,
    val error: String? = null,
)

Effect keyed correctly, latest callback without restart:

@Composable
fun SessionTimeout(onTimeout: () -> Unit) {
    val currentOnTimeout by rememberUpdatedState(onTimeout)
    LaunchedEffect(Unit) {           // effect must run once for the composable's lifetime
        delay(SESSION_MS)
        currentOnTimeout()           // always calls the latest lambda
    }
}

Common Mistakes

• collectAsState() instead of collectAsStateWithLifecycle() - collectAsState() keeps collecting while the app is backgrounded, wasting work and keeping upstream flows (location, DB observers) alive. Always use collectAsStateWithLifecycle() from lifecycle-runtime-compose; pair it with stateIn(..., WhileSubscribed(5_000), ...) in the ViewModel so upstream stops too.
• Assuming pre-strong-skipping rules. With Kotlin 2.0.20+ the Compose compiler enables strong skipping by default: composables with unstable params still skip on equals-same values, and lambdas are auto-remembered. Do not blanket-wrap every lambda in remember; do still fix genuinely churning values - a List rebuilt every emission fails equals and defeats skipping. Prefer ImmutableList/@Immutable UI models over sprinkling @Stable on mutable classes.
• Wrong LaunchedEffect keys. LaunchedEffect(Unit) with a captured callback runs stale code (use rememberUpdatedState); keying on an object that changes identity every recomposition restarts the effect every frame. Key on the values whose change should cancel-and-restart the work - nothing more, nothing less.
• rememberCoroutineScope for business logic. That scope dies when the composable leaves composition - a save/upload launched there is cancelled by rotation. Business work belongs in viewModelScope; rememberCoroutineScope is only for UI-lifetime calls like snackbarHostState.showSnackbar(), LazyListState.animateScrollToItem(), or drawer/sheet animations.
• LazyColumn without key (or with index keys) - inserts/removals recompose every following item and break animateItem() and scroll position. Provide a stable id: items(orders, key = { it.id }) { ... }. Also never put a LazyColumn with fillMaxHeight semantics inside a scrollable Column - use one lazy container with multiple item/items blocks.
• String routes and manual argument parsing - navigate("detail/$id") plus NavType boilerplate is the deprecated idiom. Use @Serializable route classes with composable<Route> and toRoute(); pass ids, not full objects, and reload data in the destination's ViewModel via SavedStateHandle.toRoute().
• Computing derived values without derivedStateOf - e.g. val showButton = listState.firstVisibleItemIndex > 0 directly in composition recomposes on every scroll frame. Wrap frequently-changing reads whose result changes rarely: val showButton by remember { derivedStateOf { listState.firstVisibleItemIndex > 0 } }. Conversely, don't use derivedStateOf for plain combinations of infrequently-changing state - that's just remember(a, b).
• Ignoring edge-to-edge. Targeting SDK 35+ the app is edge-to-edge whether you opt in or not. Call enableEdgeToEdge() in the Activity, let Material 3 Scaffold pass innerPadding to content (and actually apply it), and use WindowInsets.safeDrawing/imePadding() for custom layouts - hardcoded status-bar heights and systemUiVisibility flags are dead APIs.