android-jetpack-compose-expert – Design & UI skill for AI agents

Android Jetpack Compose Expert

Overview

A comprehensive guide for building production-quality Android applications using Jetpack Compose. This skill covers architectural patterns, state management with ViewModels, navigation type-safety, and performance optimization techniques.

When to Use This Skill

• Use when starting a new Android project with Jetpack Compose.
• Use when migrating legacy XML layouts to Compose.
• Use when implementing complex UI state management and side effects.
• Use when optimizing Compose performance (recomposition counts, stability).
• Use when setting up Navigation with type safety.

Step-by-Step Guide

1. Project Setup & Dependencies

Ensure your libs.versions.toml includes the necessary Compose BOM and libraries.

[versions]
composeBom = "2024.02.01"
activityCompose = "1.8.2"

[libraries]
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
androidx-ui = { group = "androidx.compose.ui", name = "ui" }
androidx-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
androidx-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
androidx-material3 = { group = "androidx.compose.material3", name = "material3" }
androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }

2. State Management Pattern (MVI/MVVM)

Use ViewModel with StateFlow to expose UI state. Avoid exposing MutableStateFlow.

// UI State Definition
data class UserUiState(
    val isLoading: Boolean = false,
    val user: User? = null,
    val error: String? = null
)

// ViewModel
class UserViewModel @Inject constructor(
    private val userRepository: UserRepository
) : ViewModel() {

    private val _uiState = MutableStateFlow(UserUiState())
    val uiState: StateFlow<UserUiState> = _uiState.asStateFlow()

    fun loadUser() {
        viewModelScope.launch {
            _uiState.update { it.copy(isLoading = true, error = null) }
            try {
                val user = userRepository.getUser()
                _uiState.update { it.copy(user = user, isLoading = false) }
            } catch (e: kotlinx.coroutines.CancellationException) {
                throw e
            } catch (e: Exception) {
                _uiState.update { it.copy(error = e.message, isLoading = false) }
            }
        }
    }
}

3. Creating the Screen Composable

Consume the state in a "Screen" composable and pass data down to stateless components.

@Composable
fun UserScreen(
    viewModel: UserViewModel = hiltViewModel()
) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    UserContent(
        uiState = uiState,
        onRetry = viewModel::loadUser
    )
}

@Composable
fun UserContent(
    uiState: UserUiState,
    onRetry: () -> Unit
) {
    Scaffold { padding ->
        Box(modifier = Modifier.padding(padding)) {
            when {
                uiState.isLoading -> CircularProgressIndicator()
                uiState.error != null -> ErrorView(uiState.error, onRetry)
                uiState.user != null -> UserProfile(uiState.user)
            }
        }
    }
}

The dependency versions above are historical examples, not a current recommended stack. Type-safe navigation additionally needs compatible Navigation Compose and Kotlin serialization plugin/dependency; lifecycle collection and Hilt need their own dependencies/imports/setup. Fragments require project User/Repository/View components. Trigger initial loading deliberately (for example in ViewModel init or a keyed effect); onRetry alone does not load the first user. Avoid overlapping load jobs and exposing raw server exception messages in UI.

Examples

Example 1: Type-Safe Navigation

Using the new Navigation Compose Type Safety (available in recent versions).

// Define Destinations
@Serializable
object Home

@Serializable
data class Profile(val userId: String)

// Setup NavHost
@Composable
fun AppNavHost(navController: NavHostController) {
    NavHost(navController, startDestination = Home) {
        composable<Home> {
            HomeScreen(onNavigateToProfile = { id ->
                navController.navigate(Profile(userId = id))
            })
        }
        composable<Profile> { backStackEntry ->
            val profile: Profile = backStackEntry.toRoute()
            ProfileScreen(userId = profile.userId)
        }
    }
}

Best Practices

• ✅ Do: Use remember and derivedStateOf to minimize unnecessary calculations during recomposition.
• ✅ Do: Use @Immutable/@Stable only when the type actually honors that contract; do not annotate a mutable collection to hide instability. Prefer immutable data and inspect compiler reports ([Android guidance](https://developer.android.com/develop/ui/compose/performance/stability/fix)).
• ✅ Do: Use LaunchedEffect for one-off side effects (like showing a Snackbar) triggered by state changes.
• ❌ Don't: Perform expensive operations (like sorting a list) directly inside the Composable function body without remember.
• ❌ Don't: Pass ViewModel instances down to child components. Pass only the data (state) and lambda callbacks (events).

Troubleshooting

Problem: Infinite Recomposition loop.

Solution: New object allocation alone is not an infinite loop. Check for a feedback cycle updating observed state inside the composition phase instead of a side-effect or callback. Use Layout Inspector to debug recomposition counts.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.