Skip to content

aldefy/compose-skill / skills/compose-expert

compose-expert

Unverified

Compose and Compose Multiplatform expert for UI development across Android, Desktop, iOS, and Web. Use whenever the user mentions Compose APIs (@Composable, remember, LaunchedEffect, NavHost, MaterialTheme, LazyColumn, Modifier, recomposition), Compose Multiplatform (commonMain, expect/actual, Res.*, ComposeUIViewController, UIKitView, ComposeViewport), Android TV (tv-material, D-pad, focus, Carousel), Material 3 motion, atomic design systems, design-to-code workflows, Paging 3, or navigation. Activates Review Mode on GitHub PR URLs and review phrases ("review this PR", "what's wrong with this"). Auto-detects Compose projects on session_start. Backed by actual androidx/androidx and JetBrains/compose-multiplatform-core source receipts. See "## When this skill applies" in SKILL.md for the full trigger surface.

FileKindSize
SKILL.mdskill md24.8 KB
agents/openai.yamlconfig278 B
references/accessibility.mdmarkdown11.2 KB
references/adaptive-layout-input.mdmarkdown5.2 KB
references/agentic-ui-a2ui.mdmarkdown4.7 KB
references/agsl-shaders.mdmarkdown11.5 KB
references/animation.mdmarkdown41.7 KB
references/appfunctions.mdmarkdown5.8 KB
references/appstate.mdmarkdown3.9 KB
references/atomic-design.mdmarkdown10.7 KB
references/auto-init.mdmarkdown1.6 KB
references/car-compose.mdmarkdown6.7 KB
references/composition-locals.mdmarkdown6.9 KB
references/deprecated-patterns.mdmarkdown8.3 KB
references/design-to-compose.mdmarkdown23.5 KB
references/graphics-modern.mdmarkdown2.6 KB
references/ink.mdmarkdown5.1 KB
references/lists-scrolling.mdmarkdown14.5 KB
references/material3-motion.mdmarkdown14.9 KB
references/media3-compose.mdmarkdown1.7 KB
references/ml-kit-agentic.mdmarkdown5.5 KB
references/modifiers.mdmarkdown13.6 KB
references/multiplatform.mdmarkdown21.1 KB
references/navigation-migration.mdmarkdown14.6 KB
references/navigation.mdmarkdown11.0 KB
references/official-android-skills.mdmarkdown2.7 KB
references/paging-mvi-testing.mdmarkdown6.4 KB
references/paging-offline.mdmarkdown6.4 KB
references/paging.mdmarkdown11.1 KB
references/performance.mdmarkdown22.7 KB
references/platform-specifics.mdmarkdown20.2 KB
references/pr-review.mdmarkdown14.1 KB
references/production-crash-playbook.mdmarkdown25.3 KB
references/remote-compose.mdmarkdown3.7 KB
references/side-effects.mdmarkdown13.0 KB
references/source-code/cmp-source.mdmarkdown17.8 KB
references/source-code/foundation-source.mdmarkdown560.9 KB
references/source-code/material3-source.mdmarkdown836.1 KB
references/source-code/navigation-source.mdmarkdown118.8 KB
references/source-code/runtime-source.mdmarkdown449.0 KB
references/source-code/ui-source.mdmarkdown313.1 KB
references/state-management.mdmarkdown17.6 KB
references/styles-experimental.mdmarkdown14.5 KB
references/text-editing.mdmarkdown3.8 KB
references/theming-material3.mdmarkdown13.0 KB
references/tv-compose.mdmarkdown30.2 KB
references/view-composition.mdmarkdown20.0 KB
references/wear-compose.mdmarkdown2.0 KB
references/xr-compose.mdmarkdown5.1 KB

references/material3-motion.md

View on GitHub
# Material 3 Motion

Source: `compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/MotionTokens.kt`
and `compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/MotionScheme.kt`
in `androidx/androidx` (branch: `androidx-main`)

> **`MotionTokens` is `internal` to material3** (`internal object MotionTokens`), so app code cannot
> reference it. The public API is `MaterialTheme.motionScheme` / `MotionScheme`. The token values
> below are reference data (what M3 components use); to reuse one, copy the number or easing curve
> into your own constants.

CMP compatibility: `MotionScheme` is in `androidx.compose.material3`, available on all CMP targets
(Android, Desktop, iOS, Web) since M3 1.2.0. No platform guards needed.

---

## 1. Two APIs, One System

M3 provides two ways to apply motion:

| API | When to Use |
|-----|------------|
| **`MotionScheme`** (preferred) | Inside components that should adapt to the app's motion scheme — the theme controls whether spring-based or tween-based specs are used |
| **Your own constants + `tween()`** (values copied from the token tables) | When you need explicit `tween()` / `keyframes {}` control and the component is not theme-motion-aware |

Use `MotionScheme` for new components. Use your own constants (copied token values) when the caller explicitly provides `AnimationSpec` parameters or when working with `AnimatedVisibility`, `Crossfade`, or shared elements.

---

## 2. MotionScheme API (Preferred for Components)

`MotionScheme` is part of `MaterialTheme` alongside `colorScheme`, `typography`, and `shapes`.

```kotlin
// Access via MaterialTheme
val motionScheme = MaterialTheme.motionScheme

// Two built-in schemes
MaterialTheme(motionScheme = MotionScheme.standard())    // utilitarian UI
MaterialTheme(motionScheme = MotionScheme.expressive())  // prominent UI (M3 recommended default)
```

### Spec Functions

| Function | Use Case |
|----------|---------|
| `defaultSpatialSpec<T>()` | Layout changes, position/size transitions (spatial) |
| `fastSpatialSpec<T>()` | Quick spatial transitions |
| `slowSpatialSpec<T>()` | Deliberate spatial transitions |
| `defaultEffectsSpec<T>()` | Opacity, color, non-spatial changes |
| `fastEffectsSpec<T>()` | Quick opacity/color transitions |
| `slowEffectsSpec<T>()` | Deliberate opacity/color transitions |

```kotlin
@Composable
fun AnimatedCard(expanded: Boolean) {
    val motionScheme = MaterialTheme.motionScheme

    // Size change = spatial
    val size by animateDpAsState(
        targetValue = if (expanded) 200.dp else 100.dp,
        animationSpec = motionScheme.defaultSpatialSpec(),
        label = "card-size"
    )

    // Color change = effects
    val color by animateColorAsState(
        targetValue = if (expanded) MaterialTheme.colorScheme.primaryContainer
                      else MaterialTheme.colorScheme.surface,
        animationSpec = motionScheme.defaultEffectsSpec(),
        label = "card-color"
    )
}
```

> **Key difference from `tween()`**: `MotionScheme` specs are spring-based by default in
> `expressive()`. The actual spec type (spring vs. tween) is controlled by the theme, not
> the component. This means motion adapts to the app's motion scheme without code changes.

---

## 3. Duration Tokens

Use when explicit `tween()` control is needed. All values sourced from `MotionTokens.kt`
(generated from Material Design spec v0_103). Durations are `Float` — use `.toInt()` for
`tween(durationMillis = ...)`.

| Token | Value (ms) | Use Case |
|-------|-----------|---------|
| `MotionTokens.DurationShort1` | 50ms | Micro interactions — ripple spread, checkbox tick |
| `MotionTokens.DurationShort2` | 100ms | Small element appear/disappear |
| `MotionTokens.DurationShort3` | 150ms | Icon transitions, selection indicators |
| `MotionTokens.DurationShort4` | 200ms | Tooltip appear, chip selection |
| `MotionTokens.DurationMedium1` | 250ms | FAB expand, card state change |
| `MotionTokens.DurationMedium2` | 300ms | **Most common** — dialog, bottom sheet, nav drawer |
| `MotionTokens.DurationMedium3` | 350ms | Expanded component transitions |
| `MotionTokens.DurationMedium4` | 400ms | Page-level panel transitions |
| `MotionTokens.DurationLong1` | 450ms | Complex layout changes |
| `MotionTokens.DurationLong2` | 500ms | Shared element enter |
| `MotionTokens.DurationLong3` | 550ms | Shared element — large content |
| `MotionTokens.DurationLong4` | 600ms | Full container morphs |
| `MotionTokens.DurationExtraLong1` | 700ms | Full-screen transitions only |
| `MotionTokens.DurationExtraLong2` | 800ms | Full-screen transitions only |
| `MotionTokens.DurationExtraLong3` | 900ms | Full-screen transitions only |
| `MotionTokens.DurationExtraLong4` | 1000ms | Full-screen transitions only |

---

## 4. Easing Tokens

All values sourced from `MotionTokens.kt`. Access via `MotionTokens.Easing*CubicBezier`.

| Token | CubicBezierEasing(x1, y1, x2, y2) | Direction | Use Case |
|-------|------------------------------------|-----------|---------|
| `MotionTokens.EasingEmphasizedDecelerateCubicBezier` | `(0.05f, 0.7f, 0.1f, 1.0f)` | Entering | Element arriving on screen — fast start, gentle settle |
| `MotionTokens.EasingEmphasizedAccelerateCubicBezier` | `(0.3f, 0.0f, 0.8f, 0.15f)` | Exiting | Element leaving screen — slow start, fast exit |
| `MotionTokens.EasingEmphasizedCubicBezier` | `(0.2f, 0.0f, 0.0f, 1.0f)` | Both | Default for most M3 component transitions |
| `MotionTokens.EasingStandardDecelerateCubicBezier` | `(0.0f, 0.0f, 0.0f, 1.0f)` | Entering | Simple enter — less expressive than Emphasized |
| `MotionTokens.EasingStandardAccelerateCubicBezier` | `(0.3f, 0.0f, 1.0f, 1.0f)` | Exiting | Simple exit |
| `MotionTokens.EasingStandardCubicBezier` | `(0.2f, 0.0f, 0.0f, 1.0f)` | Both | Simple state changes |
| `MotionTokens.EasingLinearCubicBezier` | `(0.0f, 0.0f, 1.0f, 1.0f)` | — | Looping / repeating animations only |
| `MotionTokens.EasingLegacyCubicBezier` | `(0.4f, 0.0f, 0.2f, 1.0f)` | — | `FastOutSlowInEasing` equivalent — do not use in new code |
| `MotionTokens.EasingLegacyAccelerateCubicBezier` | `(0.4f, 0.0f, 1.0f, 1.0f)` | — | `FastOutLinearInEasing` equivalent — do not use in new code |
| `MotionTokens.EasingLegacyDecelerateCubicBezier` | `(0.0f, 0.0f, 0.2f, 1.0f)` | — | `LinearOutSlowInEasing` equivalent — do not use in new code |

> **Enter/exit rule (always):** Enter = Decelerate easing (fast start, gentle settle).
> Exit = Accelerate easing (slow start, quick departure). Never use the same easing for both.
> The `Legacy*` tokens are equivalent to the pre-M3 named constants — do not use them in new code.

---

## 5. Using Tokens in Compose Animation APIs

### animate*AsState (prefer MotionScheme)

```kotlin
// Color — effects spec
val color by animateColorAsState(
    targetValue = if (selected) MaterialTheme.colorScheme.primary
                  else MaterialTheme.colorScheme.surface,
    animationSpec = MaterialTheme.motionScheme.defaultEffectsSpec(),
    label = "selection-color"
)

// If explicit tween is required:
val color by animateColorAsState(
    targetValue = targetColor,
    animationSpec = tween(
        durationMillis = MotionTokens.DurationShort4.toInt(),   // 200ms
        easing = MotionTokens.EasingStandardCubicBezier         // state change, not enter/exit
    ),
    label = "color"
)
```

### AnimatedVisibility (asymmetric enter/exit)

Enter and exit must use different durations and easing — exit is always faster.

```kotlin
AnimatedVisibility(
    visible = visible,
    enter = fadeIn(
        animationSpec = tween(
            durationMillis = MotionTokens.DurationMedium2.toInt(),      // 300ms
            easing = MotionTokens.EasingEmphasizedDecelerateCubicBezier // entering
        )
    ) + slideInVertically(
        animationSpec = tween(
            durationMillis = MotionTokens.DurationMedium2.toInt(),
            easing = MotionTokens.EasingEmphasizedDecelerateCubicBezier
        ),
        initialOffsetY = { it / 4 }
    ),
    exit = fadeOut(
        animationSpec = tween(
            durationMillis = MotionTokens.DurationShort4.toInt(),       // 200ms — exit is faster
            easing = MotionTokens.EasingEmphasizedAccelerateCubicBezier // exiting
        )
    ) + slideOutVertically(
        animationSpec = tween(
            durationMillis = MotionTokens.DurationShort4.toInt(),
            easing = MotionTokens.EasingEmphasizedAccelerateCubicBezier
        ),
        targetOffsetY = { it / 4 }
    )
) {
    content()
}
```

### updateTransition (multi-property, shared spec)

```kotlin
val transition = updateTransition(targetState = expanded, label = "card")

val elevation by transition.animateDp(
    transitionSpec = {
        tween(
            durationMillis = MotionTokens.DurationMedium1.toInt(),  // 250ms
            easing = MotionTokens.EasingEmphasizedCubicBezier
        )
    },
    label = "elevation"
) { isExpanded -> if (isExpanded) 8.dp else 0.dp }

val cornerRadius by transition.animateDp(
    transitionSpec = {
        tween(
            durationMillis = MotionTokens.DurationMedium1.toInt(),
            easing = MotionTokens.EasingEmphasizedCubicBezier
        )
    },
    label = "corner-radius"
) { isExpanded -> if (isExpanded) 0.dp else 12.dp }
```

### Shared element transitions

Shared elements cross screen boundaries — use Long range.

```kotlin
Modifier.sharedElement(
    state = rememberSharedContentState(key = "hero-${item.id}"),
    animatedVisibilityScope = animatedVisibilityScope,
    boundsTransform = { _, _ ->
        tween(
            durationMillis = MotionTokens.DurationLong2.toInt(),    // 500ms
            easing = MotionTokens.EasingEmphasizedCubicBezier
        )
    }
)
```

---

## 6. Decision Tree

Pick the right duration by working through these questions in order:

1. **Micro interaction?** (ripple, checkbox tick, toggle thumb snap)
   → `DurationShort1` (50ms) or `DurationShort2` (100ms)

2. **Component state change?** (button press feedback, chip select, icon swap, tab indicator)
   → `DurationShort3` (150ms) or `DurationShort4` (200ms)

3. **Container change?** (card expand, FAB extend/shrink, menu open, tooltip)
   → `DurationMedium1` (250ms) or `DurationMedium2` (300ms) ← most common

4. **Screen-level element?** (dialog enter, bottom sheet slide, search bar expand, nav drawer)
   → `DurationMedium3` (350ms) or `DurationMedium4` (400ms)

5. **Shared element / hero transition?** (image or card expands from list to detail screen)
   → `DurationLong1` (450ms) or `DurationLong2` (500ms)

6. **Full-screen complex morph?** (entire screen layout changes)
   → `DurationLong3`–`DurationExtraLong1` (550ms–700ms)

**Easing rule (always apply):**
- Element arriving → `EasingEmphasizedDecelerateCubicBezier`
- Element departing → `EasingEmphasizedAccelerateCubicBezier`
- Element changing state (stays on screen) → `EasingEmphasizedCubicBezier`
- Looping/infinite → `EasingLinearCubicBezier`
- Prefer `MotionScheme` specs over manual easing for theme-aware components

---

## 7. Review Flags

Patterns to catch in code review. See also `references/pr-review.md` Category 3.

| Pattern in Code | Flag | Fix |
|----------------|------|-----|
| `tween(50)` | Hardcoded duration | `MotionTokens.DurationShort1.toInt()` |
| `tween(100)` | Hardcoded duration | `MotionTokens.DurationShort2.toInt()` |
| `tween(150)` | Hardcoded duration | `MotionTokens.DurationShort3.toInt()` |
| `tween(200)` | Hardcoded duration | `MotionTokens.DurationShort4.toInt()` |
| `tween(250)` | Hardcoded duration | `MotionTokens.DurationMedium1.toInt()` |
| `tween(300)` | Hardcoded duration | `MotionTokens.DurationMedium2.toInt()` |
| `tween(350)` | Hardcoded duration | `MotionTokens.DurationMedium3.toInt()` |
| `tween(400)` | Hardcoded duration | `MotionTokens.DurationMedium4.toInt()` |
| `tween(N)` with any integer literal | Hardcoded duration | Nearest `MotionTokens.Duration*` token |
| `FastOutSlowInEasing` | Pre-M3 easing | `MotionTokens.EasingEmphasizedCubicBezier` |
| `LinearOutSlowInEasing` | Pre-M3 easing | `MotionTokens.EasingEmphasizedDecelerateCubicBezier` |
| `FastOutLinearInEasing` | Pre-M3 easing | `MotionTokens.EasingEmphasizedAccelerateCubicBezier` |
| `animateColorAsState(target)` no `animationSpec` | Missing spec | `MaterialTheme.motionScheme.defaultEffectsSpec()` |
| Same easing on both `enter` and `exit` | Wrong pairing | Decelerate for enter, Accelerate for exit |
| Duration > 600ms on non-shared-element | Too slow | Reduce to `DurationLong1`–`DurationLong2` |
| New component uses explicit `tween()` instead of `MotionScheme` | Not theme-aware | Use `MaterialTheme.motionScheme.defaultSpatialSpec()` / `defaultEffectsSpec()` |

---

## 8. Expressive motion

`MotionScheme.expressive()` is the M3 recommended default and is what
`MaterialExpressiveTheme` installs. Choosing it changes the *character* of every
`MotionScheme`-driven animation in the app — the spec functions above resolve to
bouncier, more energetic springs than `standard()`. You do not change call sites;
the scheme changes underneath them.

```kotlin
// Set once at the root — every defaultSpatialSpec()/defaultEffectsSpec() reader
// downstream now animates with the expressive character.
MaterialTheme(motionScheme = MotionScheme.expressive()) { /* app */ }
// (MaterialExpressiveTheme does this for you — see references/theming-material3.md)
```

### Spatial vs effects under the expressive scheme

The spatial/effects split still holds, and it matters *more* under expressive
because the spatial springs are the ones with visible overshoot:

- **Spatial** (`defaultSpatialSpec`, `fastSpatialSpec`, `slowSpatialSpec`) —
  position/size/layout. Under `expressive()` these carry the signature bounce.
  Use them for movement.
- **Effects** (`defaultEffectsSpec`, …) — opacity/color. Kept near-critically
  damped even under expressive, because bouncing alpha reads as a glitch. Use
  them for fades and color, never for the "springy" feel.

**Rule:** springiness belongs on spatial changes, not on effects. Animating a
color/alpha with a *spatial* spec is the most common expressive-motion mistake —
it makes fades wobble.

### The expressive components animate through this scheme

The expressive components in `references/theming-material3.md` (`ButtonGroup`,
`FloatingActionButtonMenu`, `LoadingIndicator`, etc.) read their motion from the
theme's `motionScheme`. That is *why* they must sit under `MaterialExpressiveTheme`
— placed under a plain `MaterialTheme(motionScheme = MotionScheme.standard())`
they still function but lose the expressive motion they were designed around.

> **Stability:** the components are `@ExperimentalMaterial3ExpressiveApi`; the
> `MotionScheme` API itself is the stable, verified surface you should lean on.

### Review flag

| Pattern in Code | Flag | Fix |
|----------------|------|-----|
| Effects/alpha animated with `defaultSpatialSpec()` under `expressive()` | Wobbling fade | Use `defaultEffectsSpec()` for opacity/color |
| Expressive components under `MaterialTheme` (not `MaterialExpressiveTheme`) | Loses expressive motion | Host under `MaterialExpressiveTheme` |
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall