Jetpack Compose Expert Skill
Non-opinionated, practical guidance for writing correct, performant Jetpack Compose code. Focuses on real pitfalls developers encounter daily, backed by analysis of the actual androidx/androidx source code (branch: androidx-main).
Workflow
When helping with Compose code, follow this checklist:
1. Understand the request
- What Compose layer is involved? (Runtime, UI, Foundation, Material3, Navigation)
- Is this a state problem, layout problem, performance problem, or architecture question?
2. Consult the right reference
Read the relevant reference file(s) from references/ before answering:
| Topic | Reference File |
|---|---|
@State, remember, mutableStateOf, state hoisting, derivedStateOf, snapshotFlow | references/state-management.md |
| Structuring composables, slots, extraction, preview | references/view-composition.md |
Modifier ordering, custom modifiers, Modifier.Node | references/modifiers.md |
LaunchedEffect, DisposableEffect, SideEffect, rememberCoroutineScope | references/side-effects.md |
CompositionLocal, LocalContext, LocalDensity, custom locals | references/composition-locals.md |
LazyColumn, LazyRow, LazyGrid, Pager, keys, content types | references/lists-scrolling.md |
NavHost, type-safe routes, deep links, shared element transitions | references/navigation.md |
animate*AsState, AnimatedVisibility, Crossfade, transitions | references/animation.md |
MaterialTheme, ColorScheme, dynamic color, Typography, shapes | references/theming-material3.md |
| Recomposition skipping, stability, baseline profiles, benchmarking | references/performance.md |
| Semantics, content descriptions, traversal order, testing | references/accessibility.md |
| Removed/replaced APIs, migration paths from older Compose versions | references/deprecated-patterns.md |
Styles API (experimental): Style {}, MutableStyleState, Modifier.styleable() | references/styles-experimental.md |
3. Apply and verify
- Write code that follows the patterns in the reference
- Flag any anti-patterns you see in the user's existing code
- Suggest the minimal correct solution — don't over-engineer
4. Cite the source
When referencing Compose internals, point to the exact source file:
// See: compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/Composer.ktKey Principles
- Compose thinks in three phases: Composition → Layout → Drawing. State reads in each phase only trigger work for that phase and later ones.
- Recomposition is frequent and cheap — but only if you help the compiler skip unchanged scopes. Use stable types, avoid allocations in composable bodies.
- Modifier order matters.
Modifier.padding(16.dp).background(Color.Red)is visually different fromModifier.background(Color.Red).padding(16.dp). - State should live as low as possible and be hoisted only as high as needed. Don't put everything in a ViewModel just because you can.
- Side effects exist to bridge Compose's declarative world with imperative APIs. Use the right one for the job — misusing them causes bugs that are hard to trace.
Source Code Receipts
Beyond the guidance docs, this skill bundles the actual source code from androidx/androidx (branch: androidx-main). When you need to verify how something works internally, or the user asks "show me the actual implementation", read the raw source from references/source-code/:
| Module | Source Reference | Key Files Inside |
|---|---|---|
| Runtime | references/source-code/runtime-source.md | Composer.kt, Recomposer.kt, State.kt, Effects.kt, CompositionLocal.kt, Remember.kt, SlotTable.kt, Snapshot.kt |
| UI | references/source-code/ui-source.md | AndroidCompositionLocals.android.kt, Modifier.kt, Layout.kt, LayoutNode.kt, ModifierNodeElement.kt, DrawModifier.kt |
| Foundation | references/source-code/foundation-source.md | LazyList.kt, LazyGrid.kt, BasicTextField.kt, Clickable.kt, Scrollable.kt, Pager.kt |
| Material3 | references/source-code/material3-source.md | MaterialTheme.kt, ColorScheme.kt, Button.kt, Scaffold.kt, TextField.kt, NavigationBar.kt |
| Navigation | references/source-code/navigation-source.md | NavHost.kt, ComposeNavigator.kt, NavGraphBuilder.kt, DialogNavigator.kt |
Two-layer approach
- Start with guidance — read the topic-specific reference (e.g.,
references/state-management.md) - Go deeper with source — if the user wants receipts or you need to verify, read from
references/source-code/
Source tree map
compose/
├── runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/
├── ui/ui/src/androidMain/kotlin/androidx/compose/ui/platform/
├── ui/ui/src/commonMain/kotlin/androidx/compose/ui/
├── foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/
├── material3/material3/src/commonMain/kotlin/androidx/compose/material3/
└── navigation/navigation-compose/src/commonMain/kotlin/androidx/navigation/compose/