Skip to content

Commit 3f5179c

Browse files
hunterstichimhappi
hunterstich
authored and
imhappi
committed
[Motion] Updated motion documentation to include springs.
PiperOrigin-RevId: 708412031
1 parent f29063e commit 3f5179c

File tree

1 file changed

+116
-30
lines changed

1 file changed

+116
-30
lines changed

‎docs/theming/Motion.md‎

Lines changed: 116 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,15 @@ path: /theming/motion/
99

1010
# Motion
1111

12-
Material motion is a system to help create stylized and consistent animations across an app. Provided in the library are semantic easing and duration theme attributes, components that use themed motion for their built-in animations, and a set of transitions for navigational events or custom animations.
13-
14-
Before you can use the motion library, you need to add a dependency on the
15-
Material Components for Android library (version `1.2.0` or later). For more
16-
information, go to the
12+
Material motion is a system to help create stylized and consistent animations
13+
across an app. Provided in the library are semantic easing and duration theme
14+
attributes, semantic spring theme attributes, components that use themed motion
15+
for their built-in animations, and a set of transitions for
16+
navigational events or custom animations.
17+
18+
The easing and duration motion system is available in version `1.6.0` or later.
19+
The physics motion system is available in version `1.13.0` or later. For more
20+
information, see the
1721
[Getting started](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
1822
page.
1923

@@ -22,11 +26,96 @@ page.
2226

2327
## Theming
2428

25-
The Material motion system is backed by a limited number of easing and duration slots. These are the building blocks for creating any Material-styled animation. These slots are implemented as theme attributes, similar to color or shape attributes, and are used by all components in the library to create a unified motion feel.
29+
The Material motion system is backed by a set of easing and duration slots and
30+
a set of spring slots. These are the building blocks for creating any
31+
Material-styled animation. These slots are implemented as theme attributes,
32+
similar to color or shape attributes. They are used by components in the
33+
library to create a unified motion feel and can be used by custom animations
34+
to make motion feel cohesive across an entire app.
35+
36+
### Springs
37+
38+
The spring (or physics) motion system is a set of six opinionated spring
39+
attributes intended to be used with the [Dynamic Animation AndroidX library](https://developer.android.com/develop/ui/views/animations/spring-animation#add-support-library).
40+
A spring attribute is configured as a style made up of a damping and stiffness
41+
value (see [MaterialSpring styleable](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/motion/res/values/attrs.xml)
42+
for available properties and [spring styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/motion/res/values/styles.xml)
43+
for examples). The damping ratio describes how rapidly spring oscillations
44+
decay. Stiffness defines the strength of the spring. Learn more about how
45+
spring animations work [here](https://developer.android.com/develop/ui/views/animations/spring-animation).
46+
47+
The spring system provides springs in three speeds - fast, slow, and default.
48+
A speed is chosen based on the size of the component being animated or the
49+
distance covered. Small component animations like switches should use the fast
50+
spring, full screen animations or transitions should use the slow spring, and
51+
everything in between should use the default spring.
52+
53+
Additionally, for each speed there are two types of springs - spatial and
54+
effects. Spatial springs are used for animations that move something on
55+
screen - like the x & y position of a View. Effects springs are used to animate
56+
properties such as color or opacity where the property's value should not be
57+
overshot (e.g. a background's alpha shouldn't bounce or oscillate above 100%).
58+
59+
This makes for a total of six spring attributes:
60+
61+
Attribute | Default value | Description
62+
-------------- | ------------------------ | ---------------------------------
63+
**?attr/motionSpringFastSpatial** | `damping: 0.9, stiffness: 1400` | Spring for small components like switches and buttons.
64+
**?attr/motionSpringFastEffects** | `damping: 1, stiffness: 3800` | Spring for small component effects like color and opacity.
65+
**?attr/motionSpringSlowSpatial** | `damping: 0.9, stiffness: 300` | Spring for full screen animations.
66+
**?attr/motionSpringSlowEffects** | `damping: 1, stiffness: 800` | Spring for full screen animation effects like color and opacity.
67+
**?attr/motionSpringDefaultSpatial** | `damping: 0.9, stiffness: 700` | Spring for animations that partially cover the screen like a bottom sheet or nav drawer.
68+
**?attr/motionSpringDefaultEffects** | `damping: 1, stiffness: 1600` | Spring for animation effects that partially cover the screen.
69+
70+
When building spring animations, a speed should be chosen based on the
71+
animation's size or distance covered. Then, a spacial or effects type should be
72+
chosen depending on the property being animated. For example, if animating a
73+
button's shape and color when pressed, use two springs: a
74+
`motionSpringFastSpatial` spring to animate the button's shape/size and a
75+
`motionSpringFastEffects` spring to animate the button's color.
76+
77+
Spring attributes can be customized (or "themed") by overriding their value to
78+
your own [MaterialSpring](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/motion/res/values/attrs.xml)
79+
style.
80+
81+
#### Custom animations using the spring motion system
82+
83+
To create a spring animation, you'll need to declare a dependency on the
84+
Dynamic Animation AndroidX library. Follow instructions for including the
85+
library and creating a spring animation
86+
[here](https://developer.android.com/develop/ui/views/animations/spring-animation#add-support-library).
87+
88+
With your configured `SpringAnimation`, use
89+
[MotionUtils.resolveThemeSpring()](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/motion/MotionUtils.java)
90+
to resolve a spring attribute from your theme into a SpringForce object. Then,
91+
use the resolved object to configure your SpringAnimation's SpringForce.
92+
93+
```kt
94+
val defaultSpatialSpring = MotionUtils.resolveThemeSpringForce(
95+
/* context= */ this,
96+
/* attrResId= */ com.google.android.material.R.attr.motionSpringDefaultSpacial
97+
)
98+
SpringAnimation(box, DynamicAnimation.TRANSLATION_Y, 400f).apply {
99+
spring.apply {
100+
dampingRatio = defaultSpacialSpring.dampingRatio
101+
stiffness = defaultSpacialSpring.stiffness
102+
}
103+
start()
104+
}
105+
```
106+
107+
### Curves (easing & duration)
26108

27-
### Easing
109+
Easing (aka interpolator) and duration theme attributes make up the curve
110+
motion system. Easing is a curve which determines how long it takes an object
111+
to start and stop moving. Duration determines the overall time of the animation.
112+
These are paired together to define how motion moves and feels. Learn about
113+
suggested pairings by reading through Material's
114+
[Easing and duration guidance](https://m3.material.io/styles/motion/easing-and-duration/applying-easing-and-duration).
28115

29-
Easing theme attributes define a set of curves that are used as [Interpolators](https://developer.android.com/reference/androidx/core/animation/Interpolator).
116+
Material's curve system includes seven easing attributes
117+
([interpolators](https://developer.android.com/reference/androidx/core/animation/Interpolator))
118+
:
30119

31120
Attribute | Default value | Description
32121
-------------- | ------------------------ | ---------------------------------
@@ -38,7 +127,10 @@ Attribute | Default value | Description
38127
**?attr/motionEasingEmphasizedAccelerateInterpolator** | `cubic-bezier: 0.3, 0, 0.8, 0.15` | Easing used for common, M3-styled animations that exit the screen.
39128
**?attr/motionEasingLinearInterpolator** | `cubic-bezier: 0, 0, 1, 1` | Easing for simple, non-stylized motion.
40129

41-
To customize an easing value, override any of the attributes in your app’s theme to your own interpolator resource.
130+
By default, these attribute values are set to interpolators that feel cohesive
131+
when used together in an app. However, they can be overridden (or "themed") to
132+
reflect your app's unique style by setting their values to your own interpolator
133+
resource from your app's theme.
42134

43135
```xml
44136
<style name="Theme.MyTheme" parent="Theme.Material3.DayNight.NoActionBar">
@@ -49,10 +141,8 @@ To customize an easing value, override any of the attributes in your app’s the
49141

50142
For more information on easing, see [Applying easing and duration](https://m3.material.io/styles/motion/easing-and-duration/applying-easing-and-duration#569498ab-3e78-4e1a-bf59-c3fc7b1a187b).
51143

52-
### Duration
53-
54-
Duration attributes are a set of durations in milliseconds that can be used for
55-
animations.
144+
Material's curve system also includes 16 duration attributes to be paired
145+
with an easing. The duration attributes include:
56146

57147
Attribute | Default value
58148
-------------- | ------------------------
@@ -89,22 +179,14 @@ millisecond integer value.
89179

90180
For more information on duration, see [Applying easing and duration](https://m3.material.io/styles/motion/easing-and-duration/applying-easing-and-duration#569498ab-3e78-4e1a-bf59-c3fc7b1a187b).
91181

92-
### Path
93-
94-
Path attributes are values which control the behavior of animating elements.
95-
96-
Attribute | Default value | Description
97-
-------------- | ------------------------ | ---------------------------------
98-
**?attr/motionPath** | `linear` | An enum that controls the path along which animating elements move.<br/>`linear`: Elements move along a straight path from their current position to their new position. A linear path corresponds to a `null` `PathMotion`.<br/>`arc`: Elements move along a curved/arced path. An arc path corresponds to a `MaterialArcMotion` `PathMotion`.
99-
100-
For more information of motionPath, see
101-
[material.io/design/motion/customization.html#motion-paths](https://material.io/design/motion/customization.html#motion-paths)
102-
103-
### Custom animations using the motion system
182+
#### Custom animations using the curve motion system
104183

105-
When implementing your own animations, use an easing and duration theme attribute so your animations tie in with animations used by Material components, bringing motion consistency across your app.
184+
When implementing your own animations, use an easing and duration theme
185+
attribute so your animations tie in with animations used by Material components,
186+
bringing motion consistency across your app.
106187

107-
When creating animations in xml, set your animation's `interpolator` and `duration` properties to a Material motion theme attribute.
188+
When creating animations in xml, set your animation's `interpolator` and
189+
`duration` properties to a Material motion theme attribute.
108190

109191
```xml
110192
<!-- res/anim/slide_in.xml –>
@@ -120,7 +202,8 @@ When creating animations in xml, set your animation's `interpolator` and `durati
120202
<set/>
121203
```
122204
123-
If creating animations in Java or Kotlin, Material provides a `MotionUtils` class to help facilitate loading `interpolator` and `duration` theme attributes.
205+
If creating animations in Java or Kotlin, Material provides a `MotionUtils`
206+
class to help facilitate loading `interpolator` and `duration` theme attributes.
124207
125208
```kt
126209
val interpolator = MotionUtils.resolveThemeInterpolator(
@@ -138,7 +221,9 @@ val duration = MotionUtils.resolveThemeDuration(
138221
139222
## Transitions
140223
141-
Material provides a set of transition patterns that help users understand and navigate an app. For more information on the patterns and how to choose between them, check out the
224+
Material provides a set of transition patterns that help users understand and
225+
navigate an app. For more information on the patterns and how to choose between
226+
them, check out the
142227
[Material motion transition patterns](https://m3.material.io/styles/motion/transitions/transition-patterns).
143228
144229
Material Components for Android provides support for all four motion patterns
@@ -260,7 +345,8 @@ override fun onCreate(savedInstanceState: Bundle?) {
260345
}
261346
```
262347

263-
Add or replace Fragment B, adding the shared element from your start scene to your Fragment transaction.
348+
Add or replace Fragment B, adding the shared element from your start scene to
349+
your Fragment transaction.
264350

265351
```kt
266352
childFragmentManager

0 commit comments

Comments
 (0)