Kotlin Android

Native Android with Kotlin & Compose

You build production native Android: Kotlin + Jetpack Compose + the UDF layered architecture (UI → domain → data). One rule governs everything: state flows down, events flow up, and there is exactly one source of truth per piece of state. Get that rule right and recomposition, rotation, and testing fall into place; break it and you get a screen that compiles but recomposes every frame, leaks coroutine scopes, blocks the main thread, or drops state on rotation.

This skill exists to stop the agent from reaching for the 2015 playbook — XML layouts, findViewById, AsyncTask, LiveData inside Compose, GlobalScope.launch, MutableState exposed straight out of a ViewModel. Emit a buildable, idiomatic module, not a toy.

Versions floor (2026)

These are floors verified against current docs (2026-06). Re-check the matrix before locking — Compose and AGP move together and a mismatch fails the build.

The architecture in one screen

Three layers. Higher layers depend on lower; never the reverse.

UI layer      Composable (stateless) ── reads ──> UiState
                     │ events up                  ▲ state down
              ViewModel exposes StateFlow<UiState> │
                     │ calls
domain layer  (optional) UseCase — only when logic spans repos or is reused
                     │ calls
data layer    Repository (interface in domain, impl here)
                  ├── Room DAO  → Flow   (single source of truth)
                  └── Retrofit  → suspend (refreshes the source of truth)

• UI is dumb: render UiState, send events. No business logic in a @Composable.
• domain is optional: add use-cases only when a screen needs logic from >1 repository.
• data owns truth: the repository decides; Room is the cache that the UI observes.

Offline-first means Room is the source of truth. The network writes into Room; the UI observes Room's Flow. WorkManager does background sync. The UI never reads the network directly.

State & recomposition

Each rule has a one-line reason.

• Hoist state. A composable that owns mutable state can't be reused or previewed — pass state in, send events out.
• remember survives recomposition; rememberSaveable survives rotation/process death. Use rememberSaveable for anything the user would be annoyed to lose (scroll, input).
• derivedStateOf for computed state — recomputes only when its inputs change, not every recomposition.
• key() / stable keys in LazyColumn — without a stable item key, reorder/insert churns the whole list.
• Business logic never lives in a @Composable — composables run on every recomposition.

// Bad — logic + I/O in the composable; runs on every recomposition.
@Composable
fun ArticlesScreen(repo: ArticleRepository) {
    val articles = runBlocking { repo.fetch() } // blocks UI thread, refetches constantly
    LazyColumn { items(articles) { Text(it.title) } }
}

// Good — stateless UI driven by hoisted state; logic in the ViewModel.
@Composable
fun ArticlesScreen(state: ArticlesUiState, onRetry: () -> Unit) {
    when (state) {
        ArticlesUiState.Loading -> CircularProgressIndicator()
        is ArticlesUiState.Error -> ErrorView(state.message, onRetry)
        is ArticlesUiState.Success ->
            LazyColumn { items(state.articles, key = { it.id }) { Text(it.title) } }
    }
}

ViewModel + UI state

Model the screen as a sealed UiState so impossible states (loading and error) can't exist. Expose it as StateFlow, never a mutable type.

sealed interface ArticlesUiState {
    data object Loading : ArticlesUiState
    data class Success(val articles: List<Article>) : ArticlesUiState
    data class Error(val message: String) : ArticlesUiState
}

@HiltViewModel
class ArticlesViewModel @Inject constructor(
    repository: ArticleRepository,
) : ViewModel() {
    val uiState: StateFlow<ArticlesUiState> =
        repository.observeArticles()
            .map<List<Article>, ArticlesUiState> { ArticlesUiState.Success(it) }
            .catch { emit(ArticlesUiState.Error(it.message ?: "Unknown error")) }
            .stateIn(
                scope = viewModelScope,
                started = SharingStarted.WhileSubscribed(5_000),
                initialValue = ArticlesUiState.Loading,
            )
}

Collect it lifecycle-aware so collection pauses below STARTED and you don't burn work off-screen:

@Composable
fun ArticlesRoute(viewModel: ArticlesViewModel = hiltViewModel()) {
    val state by viewModel.uiState.collectAsStateWithLifecycle()
    ArticlesScreen(state = state,
}

WhileSubscribed(5_000) keeps the flow alive 5s past the last collector so a rotation doesn't restart the upstream pipeline.

Data layer

The repository interface lives in domain; its implementation lives in data. Retrofit uses suspend functions and a @Serializable DTO; Room DAOs return Flow. Errors surface as a sealed result, not raw exceptions thrown into the UI.

interface ArticleRepository {
    fun observeArticles(): Flow<List<Article>>   // from Room — the source of truth
    suspend fun refresh()                         // network -> Room
}

The full wired example — DTO, entity, DAO, Retrofit service, repository impl, mappers, offline-first refresh — is in references/architecture.md. Read it before scaffolding a feature end-to-end.

DI with Hilt

@HiltAndroidApp on the Application, @Module @InstallIn(SingletonComponent::class) for bindings, @HiltViewModel + hiltViewModel() for screens. Prefer constructor injection; reach for @Provides/@Binds only for interfaces and third-party types you don't own.

Classic error: MyRepo cannot be provided without an @Inject constructor. Fix one of: either add @Inject constructor(...) to the concrete class, or @Binds the interface to its implementation inside an installed module. See references/gradle-setup.md for the KSP wiring that makes Hilt generate.

Coroutines & Flow rules

• Never GlobalScope.launch — it outlives every screen and leaks. Use viewModelScope (UI logic) or a repository-scoped scope.
• Structured concurrency: a cancelled parent cancels children — keep work inside a real scope so navigation-away cancels it.
• Inject dispatchers (@IoDispatcher CoroutineDispatcher) instead of hardcoding Dispatchers.IO — otherwise the work isn't testable.
• flowOn to switch a flow's upstream context, not withContext inside a flow { } builder (which is a context-preservation violation).
• Cold Flow for streams, StateFlow for current-value state — don't collect a cold flow when the UI needs the latest value.

Navigation (type-safe)

Since Navigation 2.8, routes are @Serializable types — the compiler checks your args.

@Serializable data object ArticleList
@Serializable data class ArticleDetail(val id: String)

NavHost(navController, startDestination = ArticleList) {
    composable<ArticleList> {
        ArticlesRoute(onOpen = { navController.navigate(ArticleDetail(it)) })
    }
    composable<ArticleDetail> { backStackEntry ->
        val args = backStackEntry.toRoute<ArticleDetail>()
        ArticleDetailRoute(id = args.id)
    }
}

No string routes, no manual arguments = listOf(navArgument(...)), no fragile key parsing.

Build & verify

./gradlew :app:assembleDebug lintDebug testDebugUnitTest

assembleDebug proves it builds, lintDebug catches Android lint, testDebugUnitTest runs JVM unit tests. For a fast, SDK-free static gate over the Kotlin/Gradle you just wrote, run scripts/verify.sh — it greps for banned patterns and missing modern ones without touching the Android SDK, so it works in CI or a bare checkout.

Anti-patterns

When this is the wrong skill

• Shared UI across Android + iOS + desktop from one Kotlin codebase — the moment commonMain, expect/actual, or an iOS target appears, use ../compose-multiplatform/SKILL.md.
• Server-side Kotlin / JVM web backend the app talks to → ../spring-boot/SKILL.md.
• Pure Kotlin/JVM language questions, no Android → ../java/SKILL.md is the nearest JVM-language sibling (there is no standalone kotlin language skill).
• iOS/SwiftUI → swift-ios. Dart cross-platform → ../flutter/SKILL.md. React Native → react-native.
• CI for assembleDebug/tests → github-actions.

References

• references/architecture.md — end-to-end wired feature (UiState + ViewModel + Repository + Room + Retrofit + Hilt), complete file contents.
• references/gradle-setup.md — libs.versions.toml, root + module build.gradle.kts, the Compose Kotlin plugin, Hilt/KSP wiring, and common Gradle/build error fixes.