AThevon/genjutsu / skills/_jutsu/compose-motion
compose-motion
VerifiedJetpack Compose animation foundations - animate*AsState, AnimatedVisibility, Crossfade, updateTransition, SharedTransitionLayout, gestures.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.6 KB |
| references/gestures-compose.md | markdown | 9.7 KB |
| references/recomposition-and-anim.md | markdown | 8.2 KB |
| references/shared-transitions.md | markdown | 11.8 KB |
references/recomposition-and-anim.md
View on GitHub# Recomposition and Animation
Recomposition is your friend until it's not. Animations change state every frame; if a frame's worth of state change recomposes a tree of 200 nodes, you ship a slideshow. This file covers when animations cause unnecessary recompositions and how to detect / fix them.
---
## Why Recomposition Matters for Animation
Compose recomposes any composable function that reads `MutableState` whose value changed. Animations change state every frame (16.67ms at 60fps, 8.33ms at 120fps). If a frame-rate state read happens at the composition phase, every reader recomposes every frame and you have jank.
The fix is to confine the state read to a phase that doesn't trigger recomposition:
- **Composition phase:** reading state here recomposes the function.
- **Layout phase:** reading state here re-runs measure/place but not composition.
- **Draw phase:** reading state here re-runs only drawing - the cheapest of the three.
The lambda-based modifiers (`Modifier.offset { ... }`, `Modifier.graphicsLayer { ... }`, `Modifier.drawBehind { ... }`) defer their state reads to layout or draw. The non-lambda variants read in composition and trigger recomposition.
---
## Diff: State Read in Composition vs Layout/Draw
```kotlin
// BAD - Modifier.offset(x) reads animatedX in composition.
// Every frame: full composition for this Box.
val animatedX by animateFloatAsState(targetX, label = "x")
Box(Modifier.offset(x = animatedX.dp))
```
```kotlin
// GOOD - lambda defers read to placement (layout phase).
// Composition runs once; placement re-runs each frame.
val animatedX by animateFloatAsState(targetX, label = "x")
Box(Modifier.offset { IntOffset(animatedX.roundToInt(), 0) })
```
Same idea for transforms:
```kotlin
// BAD
Box(Modifier.scale(animatedScale))
```
```kotlin
// GOOD - graphicsLayer reads in draw phase
Box(Modifier.graphicsLayer { scaleX = animatedScale; scaleY = animatedScale })
```
`graphicsLayer { ... }` is the right choice for any transform-only animation (translate, scale, rotate, alpha): composite-only, no layout pass, GPU-accelerated.
---
## `derivedStateOf` for Derived Values
When you compute a `Boolean` (or any cheap value) from a frequently-changing `State`, wrap it in `derivedStateOf` so readers only recompose when the derived value flips, not every time the source changes.
```kotlin
val lazyListState = rememberLazyListState()
// BAD - recomposes on every scroll position change (every pixel)
val isScrolled = lazyListState.firstVisibleItemIndex > 0 ||
lazyListState.firstVisibleItemScrollOffset > 0
// GOOD - recomposes only when the boolean actually flips
val isScrolled by remember {
derivedStateOf {
lazyListState.firstVisibleItemIndex > 0 ||
lazyListState.firstVisibleItemScrollOffset > 0
}
}
if (isScrolled) Shadow()
```
Rule of thumb: if the predicate result changes far less often than its inputs, use `derivedStateOf`. If the predicate is expensive AND deterministic in its inputs, also use it (caches the result until inputs change).
---
## `key()` in Lists with Animation
```kotlin
// BAD - no keys; on insert/remove/reorder, items animate the WRONG slot
LazyColumn {
items(list) { item ->
AnimatedVisibility(item.expanded) { Row(item) }
}
}
```
```kotlin
// GOOD - stable keys + Modifier.animateItem for reorder/insert/remove anim
LazyColumn {
items(list, key = { it.id }) { item ->
Row(modifier = Modifier.animateItem()) {
AnimatedVisibility(item.expanded) { ItemRow(item) }
}
}
}
```
Without keys, Compose matches items by position - reorder the list, and item 0's visibility state slides into position 5's row. `Modifier.animateItem()` (Compose 1.7+, replaces the deprecated `Modifier.animateItemPlacement`) animates appearance, removal, and movement automatically when keys are stable.
---
## Layout Inspector (Recomposition Counts)
Android Studio's Layout Inspector exposes "Show recomposition counts" - it draws each composable with a counter and a "skipped" counter.
What to look for:
- A **static** component (header, footer, button you didn't touch) recomposing on every list scroll = somewhere up the tree, a state read leaks to the parent. Hoist the read.
- A node that recomposes 60 times per second during an animation = the animation state is being read at composition phase. Switch to lambda-based modifiers (`offset { }`, `graphicsLayer { }`).
- Skipped count high relative to recompositions = recomposition is happening but Compose is correctly detecting unchanged inputs and skipping the body. That's healthy.
Open it via Tools -> Layout Inspector while running on a connected device. Compose nodes show in the same tree as Android views.
---
## Watching recompositions happen (dev only)
**There is no `Modifier.recomposeHighlighter()` in any androidx artifact.** It is a copy-paste sample from the [android/snippets](https://github.com/android/snippets/blob/main/compose/recomposehighlighter/src/main/java/com/example/android/compose/recomposehighlighter/RecomposeHighlighter.kt) repo (a `ModifierNodeElement` + `DrawModifierNode` you vendor into your own debug source set). Do not `import` it - it will not resolve.
Use the shipped tooling instead:
1. **Layout Inspector recomposition counts** (the default answer). Run on a device, open Layout Inspector, and in the Component Tree turn on **Show Recomposition Counts** from the **View Options** menu. Two columns appear per node: compositions and skips. **Reset** at the top of the Component Tree zeroes them so you can attribute counts to one interaction. Requires API 29+ and Compose 1.2+.
2. **Recomposition highlighting** - the same Layout Inspector draws a gradient overlay on the image pane that fades out, so the hottest composables are visible spatially. This is the shipped equivalent of the snippet above.
3. **Composition tracing** for a system trace that names your composable functions - the right tool once you know *where* and need to know *how long*.
4. **Compose compiler reports** (`-P plugin:androidx.compose.compiler.plugins.kotlin:reportsDestination=...`) to find unstable parameters that defeat skipping in the first place.
If you do vendor the snippet, keep it in `debug/` so it cannot reach a release build.
---
## Macrobenchmark for Frame Timing
`androidx.benchmark:benchmark-macro` runs your app on a device or emulator and measures real frame timings via `FrameTimingMetric`.
```kotlin
@RunWith(AndroidJUnit4::class)
class ScrollBenchmark {
@get:Rule val benchmarkRule = MacrobenchmarkRule()
@Test fun scrollHomeFeed() = benchmarkRule.measureRepeated(
packageName = "com.example.app",
metrics = listOf(FrameTimingMetric()),
iterations = 10,
startupMode = StartupMode.WARM,
) {
startActivityAndWait()
val list = device.findObject(By.res("home-feed"))
list.fling(Direction.DOWN)
device.waitForIdle()
}
}
```
Targets:
- **60Hz device:** p50 < 16.67ms, p99 < 30ms.
- **120Hz / ProMotion:** p50 < 8.33ms, p99 < 16ms.
- A single dropped frame is fine. A pattern of dropped frames during scroll = a fix needed.
---
## Baseline Profiles
Compose recomposition logic itself goes through JIT before AOT compilation kicks in - first launch and first scroll are the worst. Baseline Profiles bake hot paths into AOT at install time.
```kotlin
@RunWith(AndroidJUnit4::class)
class GenerateBaselineProfile {
@get:Rule val rule = BaselineProfileRule()
@Test fun generate() = rule.collect(packageName = "com.example.app") {
startActivityAndWait()
val list = device.findObject(By.res("home-feed"))
list.fling(Direction.DOWN)
device.waitForIdle()
}
}
```
Run via the AGP `:app:generateBaselineProfile` task; commit the generated `baseline-prof.txt`. Typical wins: 20-40% reduction in jank on cold-start scrolls. Combine with Macrobenchmark to measure delta.
---
## Sources
- [Compose performance docs](https://developer.android.com/develop/ui/compose/performance)
- [Stability and recomposition](https://developer.android.com/develop/ui/compose/performance/stability)
- [Macrobenchmark](https://developer.android.com/topic/performance/benchmarking/macrobenchmark-overview)
- [Baseline Profiles](https://developer.android.com/topic/performance/baselineprofiles/overview)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |