AThevon/genjutsu / skills/_jutsu/compose-graphics
compose-graphics
VerifiedAdvanced Compose visuals - Material 3 Expressive motion physics, AGSL shaders (Android 13+), Canvas/DrawScope generative, graphicsLayer effects.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.0 KB |
| references/agsl-recipes.md | markdown | 11.5 KB |
| references/canvas-generative.md | markdown | 8.9 KB |
| references/m3-expressive-deep.md | markdown | 10.6 KB |
references/m3-expressive-deep.md
View on GitHub# Material 3 Expressive: Deep-Dive
M3 Expressive is the 2025 Material 3 evolution. Springs replace fixed-duration tweens for spatial properties; shape morphing replaces step transitions; choreography becomes the unit of motion design rather than the individual easing curve. Use it where attention should anchor: hero moments, key actions, brand-defining surfaces. Default the rest to Standard.
---
## MotionScheme Tokens
The theme exposes six animation specs through `MaterialTheme.motionScheme`. They split along two axes.
### Spatial vs Effects
| Domain | Token family | Implementation |
|---|---|---|
| **Spatial** - position, size, scale | `*SpatialSpec()` | Spring-based. Inertia, overshoot, settle. |
| **Effects** - opacity, color, elevation | `*EffectsSpec()` | Also spring-based, but critically damped (`dampingRatio = 1.0`) and much stiffer. Predictable, no overshoot. |
> Why split? A bouncing alpha looks broken (opacity overshoots into negative or above 1). A tweened position looks robotic (no inertia). The split codifies what works and what doesn't.
### Speed Variants
Springs have no duration; these are the actual `dampingRatio` / `stiffness` values behind each token (material3 1.4.0, `StandardMotionTokens` / `ExpressiveMotionTokens`):
| Speed | Spatial - standard | Spatial - expressive | Effects (both schemes) |
|---|---|---|---|
| Fast | `0.9 / 1400` | `0.6 / 800` | `1.0 / 3800` |
| Default | `0.9 / 700` | `0.8 / 380` | `1.0 / 1600` |
| Slow | `0.9 / 300` | `0.8 / 200` | `1.0 / 800` |
Read the columns: expressive spatial is *softer and looser* than standard (lower stiffness, lower damping = visible overshoot), while the effects springs are identical across both schemes and critically damped.
### When to Override
Rare. Reach for the tokens 95% of the time - they encode Material's calibrated spring stiffness, damping, and visibilityThreshold values. Only override when:
- The brand demands a unique signature spring (extra-bouncy hero, e.g. a game).
- You're animating a non-Material surface (custom canvas).
- A11y testing surfaces a specific issue (e.g. a token spring is too long for vestibular comfort).
In those cases, build a custom spring once and reuse it through a small abstraction. Don't sprinkle ad-hoc `spring(stiffness = ..., dampingRatio = ...)` calls across the app.
---
## Choreography Patterns
Choreography is sequencing multiple element animations into a single perceived motion. Three patterns cover most hero moments.
### Sequential Reveal
Cards or list items stagger in. The eye reads left-to-right, top-to-bottom. Stagger 50ms per item.
```kotlin
items.forEachIndexed { index, item ->
val visible by produceState(false, index) {
delay(index * 50L)
value = true
}
AnimatedVisibility(
visible = visible,
enter = slideInVertically(
animationSpec = MaterialTheme.motionScheme.defaultSpatialSpec()
) + fadeIn(animationSpec = MaterialTheme.motionScheme.defaultEffectsSpec())
) {
Card(item)
}
}
```
### Hero-First
The focal element animates first. Supporting elements follow 100-150ms later. Establishes hierarchy.
```kotlin
val heroVisible by produceState(false) { value = true }
val supportingVisible by produceState(false) { delay(150); value = true }
Column {
AnimatedVisibility(heroVisible, /* hero springs */) { HeroCard() }
AnimatedVisibility(supportingVisible, /* supporting springs */) { Metadata() }
}
```
### Coordinated Exit
All elements exit on the same `slowEffectsSpec()`. No staggering on exit - it slows perceived dismissal and feels sluggish.
```kotlin
AnimatedVisibility(
visible = sheetVisible,
enter = /* staggered enter */,
exit = fadeOut(animationSpec = MaterialTheme.motionScheme.slowEffectsSpec())
) { /* ... */ }
```
> **Enter is choreography. Exit is uniform.** Never stagger on exit unless you have a very specific narrative reason.
---
## Code Example: Hero Card with Full Choreography
Tap a card. Shape morphs (Circle to Cookie4Sided), color transitions (primary to primaryContainer), elevation springs up, content fades in 100ms after the morph starts.
```kotlin
@Composable
fun ExpressiveHeroCard(item: Item) {
var expanded by remember { mutableStateOf(false) }
val transition = updateTransition(expanded, label = "hero")
val morphProgress by transition.animateFloat(
transitionSpec = { MaterialTheme.motionScheme.slowSpatialSpec() },
label = "morph"
) { if (it) 1f else 0f }
val color by transition.animateColor(
transitionSpec = { MaterialTheme.motionScheme.defaultEffectsSpec() },
label = "color"
) {
if (it) MaterialTheme.colorScheme.primaryContainer
else MaterialTheme.colorScheme.primary
}
val elevation by transition.animateDp(
transitionSpec = { MaterialTheme.motionScheme.defaultSpatialSpec() },
label = "elevation"
) { if (it) 12.dp else 2.dp }
val contentAlpha by transition.animateFloat(
transitionSpec = {
tween(
durationMillis = 250,
delayMillis = 100,
easing = FastOutSlowInEasing
)
},
label = "alpha"
) { if (it) 1f else 0f }
val morph = remember { Morph(MaterialShapes.Circle, MaterialShapes.Cookie4Sided) }
Box(
modifier = Modifier
.size(200.dp)
.shadow(elevation, shape = RoundedCornerShape(16.dp))
// MorphShape scales the normalized 0..1 morph path to the draw size -
// see ../SKILL.md "Shape Morphing" for the class.
.clip(MorphShape(morph, morphProgress))
.background(color)
.clickable { expanded = !expanded }
) {
Box(modifier = Modifier.alpha(contentAlpha)) {
Text(item.title, modifier = Modifier.padding(24.dp))
}
}
}
```
What ships in this 30-line composable: spatial spring on size and elevation, tweened color and content fade, content reveal delayed 100ms after the shape begins morphing. The hierarchy is preserved: shape leads, color and elevation join immediately, content waits its turn.
---
## Shape Morphing Patterns
`androidx.graphics.shapes:graphics-shapes` (stable 1.1.0) is the geometry engine: `RoundedPolygon`, `CornerRounding`, `Morph`. The named Material shapes below are a *separate* thing - `androidx.compose.material3.MaterialShapes`, still `@ExperimentalMaterial3ExpressiveApi`, shipping only in the `androidx.compose.material3:material3:1.5.0` pre-releases, alpha or beta (absent from stable 1.4.0). Import them from material3, not from graphics-shapes.
### Predefined Shapes
```kotlin
MaterialShapes.Circle
MaterialShapes.Square
MaterialShapes.Triangle
MaterialShapes.Pentagon
MaterialShapes.Cookie4Sided
MaterialShapes.Cookie6Sided
MaterialShapes.Cookie9Sided
MaterialShapes.Cookie12Sided
MaterialShapes.Heart
MaterialShapes.Sunny
MaterialShapes.Pill
```
These are tuned for smooth morphing. They share consistent vertex counts after subdivision, which means `Morph` can interpolate without artifacts.
### Morph
```kotlin
import androidx.compose.material3.toPath // Compose Path overload; the graphics-shapes
// one returns android.graphics.Path
import androidx.graphics.shapes.Morph
val morph = remember { Morph(MaterialShapes.Circle, MaterialShapes.Cookie4Sided) }
val path: Path = morph.toPath(progress) // progress in 0..1, path normalized to a 0..1 box
```
Combine with springs for organic feel:
```kotlin
val progress by animateFloatAsState(
targetValue = if (active) 1f else 0f,
animationSpec = MaterialTheme.motionScheme.slowSpatialSpec(),
label = "morph"
)
```
> **Always use the spring tokens with morphing.** A linear morph feels mechanical; a spring morph feels alive.
### Custom Shapes
If `MaterialShapes` doesn't cover your need, use `RoundedPolygon` directly:
```kotlin
val custom = remember {
RoundedPolygon(
numVertices = 5,
radius = 1f,
rounding = CornerRounding(0.2f, smoothing = 0.5f)
)
}
val morph = remember { Morph(MaterialShapes.Circle, custom) }
```
Vertex counts must align between the two shapes for smooth morphing. The library subdivides automatically when they don't match, but the result is choppier.
---
## Anti-Patterns Specific to Expressive
### 1. Expressive on Every Button
```kotlin
// BAD - every micro-interaction overshoots, UI feels chaotic
MaterialTheme(motionScheme = MotionScheme.expressive()) {
Scaffold {
Button(onClick = ...) { Text("Action") }
IconButton(onClick = ...) { /* icon */ }
// Every press now overshoots
}
}
// GOOD - Standard for chrome, Expressive scoped to hero
MaterialTheme(motionScheme = MotionScheme.standard()) {
Scaffold {
// Hero region overrides locally
MaterialTheme(motionScheme = MotionScheme.expressive()) {
HeroCard()
}
// Buttons elsewhere stay calm
}
}
```
### 2. Expressive on Sub-100ms Interactions
Overshoot is wasted on a 100ms toggle - the eye doesn't perceive it. Use Standard or a flat tween.
```kotlin
// BAD - bouncy 80ms toggle, the bounce is invisible
val color by animateColorAsState(
targetValue = if (on) Color.Green else Color.Gray,
animationSpec = MaterialTheme.motionScheme.fastSpatialSpec() // wrong domain too
)
// GOOD - effects spec for color, fast and flat
val color by animateColorAsState(
targetValue = if (on) Color.Green else Color.Gray,
animationSpec = MaterialTheme.motionScheme.fastEffectsSpec()
)
```
### 3. Mixing Spatial Spec on Effects (and vice versa)
```kotlin
// BAD - bouncy alpha overshoots into invalid range, looks broken
val alpha by animateFloatAsState(
targetValue = if (visible) 1f else 0f,
animationSpec = MaterialTheme.motionScheme.defaultSpatialSpec()
)
// GOOD - effects spec for alpha
val alpha by animateFloatAsState(
targetValue = if (visible) 1f else 0f,
animationSpec = MaterialTheme.motionScheme.defaultEffectsSpec()
)
```
### 4. Stagger on Exit
```kotlin
// BAD - staggered exit slows dismissal, feels sluggish
items.forEachIndexed { i, item ->
AnimatedVisibility(
visible = visible,
exit = fadeOut(animationSpec = tween(delayMillis = i * 50))
) { Card(item) }
}
// GOOD - unified exit
items.forEach { item ->
AnimatedVisibility(
visible = visible,
exit = fadeOut(animationSpec = MaterialTheme.motionScheme.slowEffectsSpec())
) { Card(item) }
}
```
---
## Sources
- [Material 3 Expressive blog](https://m3.material.io/blog/m3-expressive-motion-theming)
- [Material 3 Motion specs](https://m3.material.io/styles/motion/overview/specs)
- [androidx.graphics.shapes release notes](https://developer.android.com/jetpack/androidx/releases/graphics-shapes)
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 |