Skip to content

Motion

Part of the agent-authored prototype specification.

Text nodes accept contentTransition: "numeric" | "crossfade" | "none" (default none). Non-none requires prototype_content_transition_v1. Numeric changes roll only changed characters up for an increase and down for a decrease; formatting is stripped to digits, the first decimal point and a leading minus. Missing or equal numeric values crossfade; identical text stays still. Spans crossfade as a whole. Roll uses a spring (Android damping 0.8, stiffness 380; iOS duration 0.35 s, bounce 0.15); fades take 200 ms. Accessibility and observe expose the new text immediately. Android reduced motion uses fades and motion off snaps; iOS content transitions snap under reduced motion or motion off.

scrollTransition: {axis, edge: {scale?, alpha?, rotation?}} on a descendant of a scroll, pager, carousel or repeat interpolates from the authored edge values to identity at the viewport center. Its axis is horizontal or vertical. The scrollLinked: {source, range: [start, end], alpha?, scale?, offsetY?, offsetX?, blur?} uses the offset in dp of a scroll with that id in the same stack screen. The input endpoints increase; each output is a pair that may increase or decrease. Values interpolate linearly and clamp outside the input range. At least one output is required. Alpha is clamped to 0–1 and blur to a nonnegative radius. Android blur requires Android 12 or later.

Both fields require prototype_scroll_motion_v1; each counts as one binding, with at most 16 bindings after component and repeat expansion. These are drawing transforms: layout slots, hit targets and reported bounds stay fixed. The reduced profile keeps alpha and drops scale, rotation, offsets and blur; none retains all scroll-driven outputs because they follow position, not time.

Prototype state changes animate by default (#10442). A node with visibleWhen fades and expands in and fades and shrinks out; a pager page change driven by setPage animates the scroll instead of jumping. Spec-level motion: "none" opts out and keeps every change instant. Motion is also off when the system animator duration scale is 0 (adb shell settings put global animator_duration_scale 0), so observe screenshots are settled with no extra waits; other scales are honored by Compose’s animation clock. The runtime observes the scale while the prototype is shown. Setting it to 0 after the prototype is up makes the next visibility or page change instant, and turning motion off mid-scroll snaps the pager to its target page. Only nodes with visibleWhen get an animation wrapper.

box, row and column containers animate their size when their children appear, disappear or change (animateContentSize), gated by the same motion-enabled check, so a sibling slides into the freed space instead of jumping.

A non-stack node’s optional transition picks the visibleWhen enter/exit: none (instant), fade, expand (grow/shrink) or slide (vertical slide with a fade). Absent keeps the default fade + expand. It has no effect on nodes without visibleWhen, or when motion is off; a show reports the advisory transition-without-visible-when accessibility finding for that case.

A style pressScale (0.5–1) shrinks a tappable node while it is pressed. With motion on it animates with a short spring; with motion: "none" or animator scale 0 it snaps, so a screenshot taken mid-press is still deterministic.

Expressive and layout motion (prototype_motion_v3)

motion: "expressive" selects Material 3 expressive springs. Standard remains the default.

Change Expressive spring
Visibility size, offset, scale; container size; press scale Default spatial
Visibility alpha; press alpha; animated color and alpha Default effects

Node animate also tweens border.color, border.width, cornerRadius, elevation, shadowColor, padding, and dp width/height. Its duration and easing apply as before; easing: "spring" uses the expressive spring when expressive motion is selected. Text, font, gradient and fill/wrap/token swaps remain instant.

Node press: {scale?, alpha?} requires at least one field: scale 0.85–1, alpha 0.5–1. It requires tap/long-press/double-tap actions or an inherently pressable control (button, iconButton, fab, chip, listItem, switch, checkbox, radioGroup, segmentedButton, select or menu). press.scale overrides style.pressScale. Feedback changes drawing only, keeping the 48dp minimum touch target and reported bounds. Component gestures remain owned by their controls.

With motion: "none" or animator scale 0, style changes and control state visuals are instant, and clickable nodes and Material controls draw no ripple. Material boolean controls are keyed by their final state while off to avoid starting their internal animations; slider position is immediate and its thumb uses a resting interaction source. Reduced motion still snaps spatial changes and preserves fades and colors.

Window and modal motion

Android prototype_window_motion_v1 gates authored window.transition and repeat.stagger. Window transitions are auto (default), none, fade, slide, or scale. Auto slides a sheet from its placement edge, fades and scales a floating surface from 0.92 to 1, and fades fullscreen content. Exit mirrors enter. Same-id shows update the existing window when motion is off or the incoming transition is none, preserving focus and keyboard attachment. With full or reduced motion and an animated transition, replacement attaches a new window while the outgoing window exits; focus transfers to the new window. Changes to display, layer or surface id also require a new window regardless of motion.

Root Compose content animates for 300 ms; removal is scheduled through the host settle timer at 400 ms, independent of animation frames. Exiting windows become non-touchable immediately. Outgoing windows retain their hierarchy motion metadata and shared image/font assets until detach; service teardown drains these exits immediately. Dismissal events and sequence allocation retain their existing timing at exit start. Agent shows animate; device-persistence boot restoration does not. Idle TTL, last-client disconnect and service teardown remove windows immediately to keep teardown bounded.

Bottom sheets slide from the bottom, dialogs and menus fade and scale, and snackbars fade and slide. Scrims fade with their surfaces. Panels remain composed through exit, including when removed from the authored tree; a patch reopening a panel cancels its exit and re-enters. The SheetDismiss and modal button actions commit at exit start, so runtime state and emitted action events change immediately. Retained visual content finishes exiting afterward with input disabled and its semantics cleared.

A dragged sheet follows the pointer directly and springs to the selected detent on release. Reduced motion uses fades without translation, scaling or detent springs. Off motion snaps and keeps the settled rendering unchanged. Window and modal transitions and detent settles participate in the motion-active signal, following the conventions of

15114 (see Motion-active signal). The surface reports itself through

ReportPrototypeMotion while an exit or settle runs, so observe never captures it mid-flight.

repeat.stagger is an integer 0–100 ms per instance, in item order. Only template children with visibleWhen receive it. It adds to container stagger and transition delay through the existing enter-delay machinery, with each total capped at 600 ms; exits are not delayed.

iOS accepts the structural contract but does not advertise prototype_window_motion_v1, so host preflight refuses either authored field.

Attention loops (prototype_loops_v1)

(Android only, requires prototype_loops_v1) Any node accepts attentionLoop: {effect: "pulse" | "spin", periodMs: 400–4000, iterations?: 1–20 | "infinite"}. The period and finite count are integers; omitted iterations means infinite. Pulse scales 1 → 1.08 → 1 per period; spin turns 0 → 360 degrees. Drawing changes without changing layout, reported bounds or touch targets. A pulse node must omit style.scale; a spin node must omit style.rotation, including every styleWhen style. At most eight expanded nodes may carry loops, including repeat instances; shimmer does not consume that limit. Finite loops settle at identity and contribute to settling motion while running. Infinite loops and shimmer contribute only to the intentional loop count. Reduced motion, motion none and animator scale 0 leave loops at rest. On Android each observe metadata read renews a 1500 ms capture hold. During it, attention loops draw identity and shimmer draws no band, so captures within the hold are identical when the rest of the scene is unchanged.

The runtime renews its capture hold in the controller’s window-metadata read path, alongside prototypeMotion. The hold uses an injected monotonic clock and a 1500 ms deadline; repeated reads extend it. Compose reads the deadline during drawing and invalidates the loop layer on renewal. Animation time continues through a hold, so a finite loop still completes on schedule. The first expanded node beyond MAX_PROTOTYPE_LOOPS = 8 fails at <node path>.attentionLoop with Loop node limit exceeded. Conflicting rest transforms fail at the same path.

One-shot keyframes

Every node may carry keyframes: {trigger, durationMs, tracks}, gated by prototype_keyframes_v1. The trigger is exactly one declared state {key: "liked"} or a data pointer {data: "/liked"} relative to the data object. A value change plays once; mounting does not play, and a change during playback restarts from zero.

durationMs is an integer from 100 to 3000. Tracks contain one to seven of scale, scaleX, scaleY, rotation (degrees), offsetX, offsetY (dp), and alpha. Each is 2–8 [fraction, value] points or {points, curve?}; fractions increase strictly from 0 to 1. Curves are linear, standard (default, cubic Bezier 0.2,0,0,1), and spring. Scale values are positive and alpha stays in 0–1. Both ends equal rest: 1 for scale and alpha, 0 for rotation and offsets. The first node beyond the expanded 16-node budget fails at its .keyframes, including component and repeat instances.

One Compose Animatable drives draw-time layers, composing scale/alpha multiplicatively and rotation/offsets additively with style motion. Tracks do not change layout or authored semantics. Reduced motion drops spatial tracks and retains alpha; off disables playback. Finite playback contributes to the motion-active signal. The pure spring sampler uses a normalized damped ease derived from damping ratio 0.8 and stiffness 380, with exact endpoints. On iOS, the runtime runs one linear KeyframeAnimator phase per track and applies the same sampler as Android, so all three curves match across platforms. A trigger.key is a plain declared state key, not a per-row bound key, so every repeat instance plays on the same trigger. Per-row triggers need a bound-key form and are not part of v1.

Motion profiles (#15115, prototype_reduced_motion_v1)

Motion runs in one of three profiles, decided identically on both platforms from the spec’s motion and the system setting:

Profile Chosen when Behaviour
full Neither of the rows below applies. Every animation described in this section.
reduced motion: "reduced", or on iOS system Reduce Motion. Spatial animations (slide, expand and shrink, scale, container size, pressScale, swipe-row and stack slides, shared element morphs) become crossfades or snap. Loops (shimmer, indeterminate progress) rest. Color and alpha still animate.
off motion: "none", or on Android animator duration scale 0 or transition animation scale 0 (read from Settings.Global). Everything is instant.

none wins over reduced, and a system off wins over both. Android has no system reduced setting, so there reduced comes from the spec alone; both scales are observed while the prototype is shown. On iOS the system Reduce Motion setting (and UIAccessibility.prefersCrossFadeTransitions) selects reduced rather than off, so a Reduce Motion run shows crossfades; motion: "none" is still fully instant. motion: "reduced" needs prototype_reduced_motion_v1, which the host checks before showing.

Shared element morphs (#15115, prototype_shared_element_v1)

sharedKey names two visibleWhen nodes as one element, so swapping them morphs the first into the second (a list row into a detail card, a thumbnail into a viewer):

{
  "state": { "open": false },
  "root": {
    "type": "box",
    "children": [
      {
        "type": "row",
        "sharedKey": "album",
        "visibleWhen": { "key": "open", "equals": false },
        "onTap": [{ "type": "setState", "key": "open", "value": true }],
        "children": [{ "type": "text", "text": "Album" }]
      },
      {
        "type": "card",
        "sharedKey": "album",
        "visibleWhen": { "key": "open", "equals": true },
        "onTap": [{ "type": "setState", "key": "open", "value": false }],
        "children": [{ "type": "text", "text": "Album" }]
      }
    ]
  }
}

A literal key referenced as a zoom source labels exactly one node and is exempt from the visibleWhen requirement and visibility-pair counting.

Rules, enforced by every validator with exact paths: sharedKey retains the state-key grammar and aliases shared: {key, as: "bounds"}. The object form requires prototype_shared_element_v2; plain sharedKey requires prototype_shared_element_v1. A node cannot set both. Visibility morph nodes must have visibleWhen. Literal v2 keys allow hyphens in addition to the state-key characters, with a 64-character resolved limit. Literal visibility morph keys pair exactly two nodes. Inside repeat children, a key template must reference the field named by repeat.key, without index or other-field placeholders. Each instance must resolve a distinct key; at most two nodes can use each resolved key. Unmatched repeat items remain ordinary cards. A spec has at most 16 resolved keys for visibility morphs, including unmatched feed items. Pairs cannot nest, disagree on as, or cross a dialog or bottomSheet boundary (including two separate modals). Shared elements across pager pages and stack screens are not supported.

Under full, Android applies sharedElement for as: "element" (identical content, only the target draws) and sharedBounds for as: "bounds" (changing content, both sides crossfade), in one SharedTransitionLayout. On iOS the runtime uses matchedGeometryEffect(properties: .frame) in one namespace; bounds also crossfades the two sides. The morph counts in the motion-active signal. Under reduced both kinds crossfade in place; under off they swap instantly. A pair visible at the same time keeps ordinary visibility behavior. Shape interpolation still needs animate on cornerRadius; image content scale snaps.

A feed card expanding into a detail column uses the same spec on Android and iOS. Here the one feed item binds story-{item.id} to story-one; tapping it swaps the pair. More feed items may have unmatched keys until their corresponding detail is shown.

{
  "window": { "placement": { "type": "fullscreen" } },
  "state": { "open": false },
  "root": {
    "type": "box",
    "children": [
      {
        "type": "column",
        "repeat": { "items": [{ "id": "one" }], "as": "item", "key": "id" },
        "children": [
          {
            "type": "card",
            "shared": { "key": "story-{item.id}", "as": "bounds" },
            "visibleWhen": { "key": "open", "equals": false },
            "onTap": [{ "type": "setState", "key": "open", "value": true }],
            "style": { "width": { "dp": 160 }, "height": { "dp": 80 } },
            "children": [{ "type": "text", "text": "Story {item.id}" }]
          }
        ]
      },
      {
        "type": "column",
        "shared": { "key": "story-one", "as": "bounds" },
        "visibleWhen": { "key": "open", "equals": true },
        "onTap": [{ "type": "setState", "key": "open", "value": false }],
        "style": { "width": { "dp": 320 }, "height": { "dp": 400 } },
        "children": [{ "type": "text", "text": "Story one: the full detail" }]
      }
    ]
  }
}

Motion-active signal (#15114)

Fades and scales change no node, so two identical hierarchy reads do not prove a prototype has stopped moving. The prototype window’s entry in a hierarchy capture carries prototypeMotion: {active, loops} next to prototypePlacement (prototype_window_metadata_v1; older APKs omit it and hosts read absence as settled). The active field counts the animations that will finish: visibleWhen and retained-visibility transitions, animate style animations, pressScale, container size changes, swipe-row settles and pager scrolls. The loops field counts intentional infinite animations (today only the shimmer) and hosts ignore it. Both observe(waitFor: stable) and the launcher/SystemUI quiet-tree wait do not settle while active is positive and stay bounded by their usual timeout. The count is zero after a single frame under motion: "none" or animator scale 0.