compose-animation

Compose Animation — M3 Expressive Motion System

M3 Expressive (2025) replaced fixed-duration easing with physics-based springs. These rules cover the complete animation toolkit — from micro-interactions to screen transitions.

The M3 Expressive motion philosophy

// M3 Expressive motion tokens — import from design-system skill's DesignTokens.kt

// Physics-based springs for SPATIAL motion (position, size, scale)
// → Never use tween() for elements that move — spring feels natural
val spatialEnter = spring<Float>(
    dampingRatio = Spring.DampingRatioLowBouncy,   // slight bounce
    stiffness    = Spring.StiffnessMediumLow        // smooth, not jerky
)

// Tween with M3 easing for EFFECTS (opacity, color, blur)
// → Effects have no mass — tween with easing curve is correct
val effectsIn  = tween<Float>(Duration.medium2, easing = AppEasing.EmphasizedDecel)
val effectsOut = tween<Float>(Duration.short4,  easing = AppEasing.EmphasizedAccel)

// Rule: if it moves → spring. If it fades/colors → tween with M3 easing.

Rule 1: AnimatedVisibility — M3 Expressive enter/exit

// ✅ Standard show/hide with M3 Expressive physics
AnimatedVisibility(
    visible = isVisible,
    enter = slideInVertically(
        initialOffsetY = { -it / 4 },
        animationSpec  = spring(Spring.DampingRatioLowBouncy, Spring.StiffnessMediumLow)
    ) + fadeIn(tween(Duration.medium2, easing = AppEasing.EmphasizedDecel)),
    exit = slideOutVertically(
        targetOffsetY = { -it / 4 },
        animationSpec = tween(Duration.short4, easing = AppEasing.EmphasizedAccel)
    ) + fadeOut(tween(Duration.short4))
) { Content() }

// ✅ Common patterns
// Slide from bottom (FAB, snackbar, floating panels)
val enterFromBottom = slideInVertically(
    initialOffsetY = { it },
    animationSpec = spring(Spring.DampingRatioMediumBouncy, Spring.StiffnessMedium)
) + fadeIn(tween(Duration.medium2))
val exitToBottom = slideOutVertically(
    targetOffsetY = { it },
    animationSpec = tween(Duration.short4, easing = AppEasing.EmphasizedAccel)
) + fadeOut(tween(Duration.short4))

// Scale pop (context menus, badges, chips)
val popIn  = scaleIn(initialScale = 0.7f,
    animationSpec = spring(Spring.DampingRatioLowBouncy, Spring.StiffnessHigh)
) + fadeIn(tween(Duration.short4))
val popOut = scaleOut(targetScale = 0.7f,
    animationSpec = tween(Duration.short3, easing = AppEasing.EmphasizedAccel)
) + fadeOut(tween(Duration.short3))

// Expand/collapse (accordion, show more)
val expandDown = expandVertically(
    expandFrom    = Alignment.Top,
    animationSpec = spring(Spring.DampingRatioNoBouncy, Spring.StiffnessMediumLow)
) + fadeIn(tween(Duration.medium1))
val collapseUp = shrinkVertically(
    shrinkTowards = Alignment.Top,
    animationSpec = tween(Duration.short4, easing = AppEasing.EmphasizedAccel)
) + fadeOut(tween(Duration.short4))