$3d
Non-opinionated, practical guidance for writing correct, performant Compose code —
across Android, Desktop, iOS, and Web. Covers Jetpack Compose and Compose Multiplatform.
Backed by analysis of actual source code from androidx/androidx and
JetBrains/compose-multiplatform-core.
When helping with Compose code, follow this checklist:
references/design-to-compose.mdreferences/animation.md for recipesRead 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 |
| Figma/screenshot decomposition, design tokens, spacing, modifier ordering | references/design-to-compose.md |
| Production crash patterns, defensive coding, state/performance rules | references/production-crash-playbook.md |
Compose Multiplatform, expect/actual, resources (Res.*), migration | references/multiplatform.md |
| Desktop (Window, Tray, MenuBar), iOS (UIKitView), Web (ComposeViewport) | references/platform-specifics.md |
When referencing Compose internals, point to the exact source file:
// See: compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/Composer.kt
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 from Modifier.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.
Compose Multiplatform shares the runtime but not the platform. UI code in
commonMain is portable. Platform-specific APIs (LocalContext, BackHandler,
Window) require expect/actual or conditional source sets.
Beyond the guidance docs, this skill bundles the actual source code from
androidx/androidx (branch: androidx-main) and JetBrains/compose-multiplatform-core
(branch: jb-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 |
| CMP | references/source-code/cmp-source.md | Window.kt, ComposeUIViewController.kt, UIKitView.kt, ComposeViewport.kt, ResourceReader.kt |
references/state-management.md)references/source-code/androidx/androidx (branch: androidx-main)
├── compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/
├── compose/ui/ui/src/androidMain/kotlin/androidx/compose/ui/platform/
├── compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/
├── compose/foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/
├── compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/
└── compose/navigation/navigation-compose/src/commonMain/kotlin/androidx/navigation/compose/
compose-multiplatform-core (branch: jb-main)
├── compose/ui/ui/src/desktopMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/iosMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/webMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/skikoMain/kotlin/androidx/compose/ui/
└── compose/foundation/foundation/src/skikoMain/kotlin/androidx/compose/foundation/
compose-multiplatform (resources library)
└── components/resources/library/src/commonMain/