Jetpack Compose Patterns

Overview

Native Android (Jetpack Compose) is chosen when a task needs deep Android integration or the app is already native (see native-vs-flutter-decision). Same discipline as Flutter/SwiftUI: small stateless composables, state hoisted out, reusable atomic components.

Core principle: Composables are stateless functions of state. State is hoisted to a ViewModel; composables emit events upward.

Rules

• Stateless composables + state hoisting. A composable takes its state as parameters and exposes callbacks (onXxx) — it does not own app state. The screen-level composable connects a ViewModel to the stateless UI.
• ViewModel owns state and logic, exposed as StateFlow/UiState; the composable collects it with collectAsStateWithLifecycle(). Networking/business rules live in the ViewModel + repository, never in the composable.
• Model UI state as a sealed hierarchy: Loading | Data | Empty | Error — when over it renders every branch. No happy-path-only screens.
• Atomic components: shared library of reusable composables (atoms → molecules → organisms). Reuse before building; grep before adding.
• Material theme, not hardcoded values: MaterialTheme.colorScheme / typography / a spacing tokens object (MaterialTheme.spacing, see mobile-design-system-foundation) — never scattered Color(0xFF...) and magic dp. Support dark theme + dynamic color.
• remember/derivedStateOf to avoid recomputation; hoist remembered state only when it's genuinely local (scroll, text field).
• @Preview reusable composables in their key states, and across the matrix (see below).

Edge-to-edge (enforced from targetSdk 35)

• Call enableEdgeToEdge() before setContent in the activity — the opt-out is gone at targetSdk 35+.
• Consume insets at the Scaffold: use its innerPadding and Modifier.consumeWindowInsets(innerPadding) on the content so a nested scrollable doesn't double-apply it.
• IME padding: apply Modifier.imePadding() once, at the container that should move with the keyboard — applying it a second time further down the tree produces extra empty space.
• android:windowSoftInputMode="adjustResize" in the manifest for screens with text input.
• NavigationSuiteScaffold does not automatically propagate its padding to the content slot — apply insets explicitly inside it, don't assume it's handled.

Predictive back (default at targetSdk 36)

• onBackPressed() / OnBackPressedCallback without isEnabled toggling is not called the same way once predictive back is the default — use BackHandler (simple) or PredictiveBackHandler (custom transition) in Compose, or Navigation 3's built-in handling.
• Verify back navigation in this run rather than assuming the old override still fires.

Adaptive layout

• currentWindowAdaptiveInfo().windowSizeClass to branch layout by available width/height — never by Configuration.orientation or a hardcoded device check.
• NavigationSuiteScaffold switches a bottom nav bar to a nav rail automatically at the window-size-class breakpoint — prefer it over hand-rolling the switch.
• GridCells.Adaptive(minWidth) for grids that should reflow by available width.
• Android 16 (opt-out via PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY) and Android 17/API 37 (no opt-out) ignore screenOrientation/resizeableActivity restrictions on screens ≥600dp — design every screen to work in both orientations and at tablet width; don't rely on an orientation lock to avoid building the wider layout.

Previews and tests across the matrix

• @PreviewScreenSizes, @PreviewFontScale, @PreviewLightDark, or a custom multi-preview with Devices.PHONE/Devices.TABLET — see mobile-visual-self-review for the full size/text-scale/dark matrix.
• DeviceConfigurationOverride(ForcedSize(...) then FontScale(...) then DarkMode(...)) for instrumented matrix tests.
• rule.enableAccessibilityChecks() on an API 34+ device/emulator before UI-mutating test actions (inconclusive on Robolectric — say so if that's all you ran); see mobile-accessibility.
• "Run screenshot tests but do not update reference images" to "fix" a failure — a changed golden is a visual regression until a human confirms it's intended.

Semantics

• contentDescription on every Image/Icon that carries meaning; null explicitly for a purely decorative one.
• Modifier.semantics(mergeDescendants = true) on a composite row so a screen reader announces it once.
• Touch targets ≥48dp — Modifier.size/minimumInteractiveComponentSize().

Worked Example

// ViewModel owns state + logic (unit-testable, no Compose)
class TaskListViewModel(private val repo: TaskRepository) : ViewModel() {
    private val _state = MutableStateFlow<UiState<List<Task>>>(UiState.Loading)
    val state: StateFlow<UiState<List<Task>>> = _state
    fun load() = viewModelScope.launch {
        _state.value = UiState.Loading
        _state.value = try {
            val items = repo.list()
            if (items.isEmpty()) UiState.Empty else UiState.Data(items)
        } catch (e: CancellationException) {
            throw e                              // never swallow cancellation
        } catch (e: Exception) {
            UiState.Error(e)
        }
    }
}

// stateless composable renders state, emits events
@Composable
fun TaskListScreen(state: UiState<List<Task>>, onRetry: () -> Unit) = when (state) {
    is UiState.Loading -> AppSpinner()
    is UiState.Error   -> AppErrorView(message = state.cause.message, onRetry = onRetry)
    is UiState.Data    -> TaskList(tasks = state.value)
    is UiState.Empty   -> EmptyView()
}

The fix from the previous version: runCatching { } wrapped around a suspend call inside viewModelScope.launch catches CancellationException along with real errors, which breaks structured concurrency (a cancelled screen keeps "loading" instead of stopping) — use try/catch and rethrow CancellationException explicitly. The Empty branch is now actually emitted when the list comes back empty, not just declared and never reached.

Testing

• Unit-test the ViewModel with a fake/mockk repository and a test dispatcher — no Compose.
• Compose UI tests (createComposeRule) assert visible behavior and clicks. Test-first.

Common Mistakes

• A composable holding app state or calling the repository.
• Business logic in the composable instead of the ViewModel.
• Hardcoded colors/dp instead of MaterialTheme + tokens.
• Collecting flows without collectAsStateWithLifecycle (leaks/waste).
• Only the data branch rendered — Empty declared but never emitted.
• runCatching around a suspend call, swallowing CancellationException.
• Assuming edge-to-edge/predictive back still behave like targetSdk <35/<36 after a target bump.

Red Flags

• A @Composable that imports a repository or Retrofit service.
• Color(0xFF...)/magic dp outside the theme.
• No error/empty branch in the when.
• enableEdgeToEdge() missing from a new or recently targetSdk-bumped activity.
• A screen that only renders correctly in one orientation.