KMP Compose Screen Architecture

All screens are written with Compose Multiplatform in commonMain and run on Android and iOS. Imports stay androidx.compose.* / androidx.lifecycle.*; the artifacts are the JetBrains ones (org.jetbrains.compose.*, org.jetbrains.androidx.lifecycle:*) — see kmp-module-structure.

Core Principle

The UI is dumb. Composables render state and forward user actions — nothing more. All state lives in the ViewModel. All logic lives in the ViewModel, domain, or data layer. Compose code should contain zero business logic, zero data transformation, and minimal side effects.

Stability & Recomposition

Strong skipping mode is enabled by default in modern Compose — no explicit opt-in needed.

Only annotate a state data class with @Stable when it contains fields the Compose compiler considers unstable (e.g., List, Map, Set, interfaces, or abstract types). If all fields are primitive types, String, or other stable types, no annotation is needed.

// Needs @Stable — contains a List (unstable by default)
@Stable
data class NoteListState(
    val notes: List<NoteUi> = emptyList(),
    val isLoading: Boolean = false
)

// No annotation needed — all fields are stable
data class NoteDetailState(
    val title: String = "",
    val body: String = "",
    val isSaving: Boolean = false
)

State Ownership

All state lives in the ViewModel. Do not use remember or rememberSaveable for application state — that belongs in the ViewModel's StateFlow and is surfaced via collectAsStateWithLifecycle().

The only exception is Compose-internal state that the framework requires you to hold in composition, such as LazyListState, ScrollState, or PagerState. For these, use remember* as needed:

// Acceptable — Compose-owned UI state
val lazyListState = rememberLazyListState()

// Reacting to Compose-owned state with derivedStateOf
val showScrollToTop by remember {
    derivedStateOf { lazyListState.firstVisibleItemIndex > 5 }
}

derivedStateOf should only be used in these rare scenarios where Compose-internal state drives a derived value. If the derivation can happen in the ViewModel, it should.

Always collect ViewModel state with lifecycle awareness:

// import androidx.lifecycle.compose.collectAsStateWithLifecycle
// artifact: org.jetbrains.androidx.lifecycle:lifecycle-runtime-compose
val state by viewModel.state.collectAsStateWithLifecycle()

This is lifecycle-aware on iOS as well: Compose Multiplatform maps the iOS app lifecycle onto Lifecycle (ON_STOP when the app goes to the background, ON_START when it returns).

Side Effects

Side effects should be avoided when possible. If something can be handled by the ViewModel through an Action, do that instead of using a side effect in a composable.

When a side effect is truly necessary (e.g., interacting with Lifecycle APIs that have no ViewModel equivalent), extract it into a dedicated composable to keep the Screen composable clean:

// Extracted into its own composable
@Composable
fun ObserveLifecycle(onStart: () -> Unit, onStop: () -> Unit) {
    // import androidx.lifecycle.compose.LocalLifecycleOwner (multiplatform),
    // NOT androidx.compose.ui.platform.LocalLifecycleOwner
    val lifecycleOwner = LocalLifecycleOwner.current
    DisposableEffect(lifecycleOwner) {
        val observer = LifecycleEventObserver { _, event ->
            when (event) {
                Lifecycle.Event.ON_START -> onStart()
                Lifecycle.Event.ON_STOP -> onStop()
                else -> Unit
            }
        }
        lifecycleOwner.lifecycle.addObserver(observer)
        onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }
    }
}

LaunchedEffect is acceptable when genuinely needed, but question whether the work belongs in the ViewModel first. Do not use custom CompositionLocals.

Side effects that need a platform API (permissions, share sheet, haptics, opening a URL) never branch on the platform inside a Screen composable. Put them behind an interface provided via Koin or an expect/actual function. LocalContext, LocalConfiguration, and androidx.activity.compose.* (BackHandler, rememberLauncherForActivityResult) do not exist in commonMain.

Lazy Layouts

Add key to lazy list items when there is an obvious unique identifier available. Don't force it if it's unclear which property is unique:

LazyColumn {
    items(
        items = state.notes,
        key = { it.id }  // id is clearly unique
    ) { note ->
        NoteItem(note = note, onClick = { onAction(OnNoteClick(note.id)) })
    }
}

Animations — Recomposition Avoidance

Avoid animations that cause recompositions. Prefer approaches that animate below the recomposition layer:

• graphicsLayer — for alpha, scale, rotation, translation
• Offset lambda — for position changes (offset { ... })
• Canvas — for custom drawing that animates
• animateFloatAsState + graphicsLayer — animate a float, apply in graphicsLayer

// Good — animates without recomposition
val alpha by animateFloatAsState(if (state.isVisible) 1f else 0f)
Box(
    modifier = Modifier.graphicsLayer { this.alpha = alpha }
)

// Bad — causes recomposition on every frame
Box(
    modifier = Modifier.alpha(animatedAlpha)
)

Deferred state reads: When a value drives an animation, pass it as a lambda rather than reading it directly. This defers the state read to the layout/draw phase and avoids recomposition:

// Good — deferred read
fun Modifier.animatedOffset(offsetProvider: () -> IntOffset) =
    offset { offsetProvider() }

// Bad — immediate read causes recomposition
fun Modifier.animatedOffset(offset: IntOffset) =
    offset(x = offset.x.dp, y = offset.y.dp)

TextField

Text input state lives in the ViewModel. Every keystroke dispatches an Action:

// In the Screen composable
TextField(
    value = state.title,
    onValueChange = { onAction(NoteEditorAction.OnTitleChange(it)) }
)

The ViewModel updates state (and optionally persists to SavedStateHandle) in response to the Action — see the kmp-presentation-mvi skill for the full pattern.

Screen Previews

Every Screen composable should have at least one meaningful @Preview that shows a realistic state. Previews live in commonMain next to the screen and are rendered by Android Studio through the Android target:

@Preview
@Composable
private fun NoteListScreenPreview() {
    AppTheme {
        NoteListScreen(
            state = NoteListState(
                notes = listOf(
                    NoteUi("1", "Meeting notes", "Mar 15"),
                    NoteUi("2", "Shopping list", "Mar 14")
                )
            ),
            onAction = {}
        )
    }
}

Wrap previews in the app theme so they reflect real appearance. Use realistic sample data, not empty states (unless previewing the empty state specifically).

For component-level preview conventions (one preview per meaningful state, separate functions), see kmp-compose-components.

For component construction rules (IconButton wrapping, sizing, design system reuse, icons, string resources, previews per state), see kmp-compose-components.