Content & design for Animation (docs) page

---
type: documentation
title: Animation
resources:
  links:
    name: "Debugging Chrome Animations"
    source: http://valhead.com/2015/01/06/quick-tip-chrome-animation-controls/
---

## Animation Guidelines

The overarching metaphor for our animation comes from the IBM Design Language metaphor *elegant machine motion*. Elegant machine motion consists of very quick movements with strong easing at the beginning and/or end of the animation, plus subtle offsets.

## Properties

Properties are the elements of an object that will change over time. The properties you can animate within CSS are listed below. We recommend using the most performant properties first. If the desired effect cannot be achieved, use the general list of properties as a fallback.

**Most Performant Properties**

* Position: `transform: translate(npx,npx);`
* Scale: `transform: scale(n);`
* Rotation: `transform: rotate(ndeg);`
* Opacity: `opacity: 0...1;`

For more information about why these properties are performant, see [this blog post.](http://www.html5rocks.com/en/tutorials/speed/high-performance-animations/)

General list of animatable properties:
- `background-color`
- `border-width`
- `clip`
- `font-size`
- `left`
- `margin`
- `min-height`
- `outline-color`
- `padding`
- `text-shadow`
- `visibility`
- `z-index`
- `background-position`
- `border-spacing`
- `color`
- `font-weight`
- `letter-spacing`
- `max-height`
- `min-width`
- `outline-offset`
- `right`
- `top`
- `width`
- `border-color`
- `bottom`
- `crop`
- `height`
- `line-height`
- `max-width`
- `opacity`
- `outline-width`
- `text-indent`
- `vertical-align`
- `word-spacing`

A great example of all the animatable properties can be seen [here.](http://leaverou.github.io/animatable/)

### Single Property Animations

When animating only a single property, you should follow the guidelines below. 

![Single-Attribute](images/motion/examples/Single_Attribute-1.gif)

```scss
//box class
.single-attribute {
  animation: single-attribute 1s $ibm-bouncein;
}

//keyframes for animation
@keyframes single-attribute {
  0% {
    transform: scale(0);
  }
  100% {
    transform: scale(1);
  }
}

Easing Curves Use bounces eases to add the snap in factor that is lost if you don’t use two properties. These bounces are snappy bounces, not physics-based bounces.

Use of Easing Curves:
- Entrances = $bounce-in (Fast to Slow)
- Exits = $bounce-out (Slow to Fast)
- Interactive Elements = $bounce-in-out

Multiple Property Animations

Multiple property animations are animations where multiple properties are being animated together. With multiple property animations, there are two directions you can take: Direction 1 - Start one property alone, then animate the additional properties, or Direction 2 - Both properties start at the same time, then one property ends before the other. Don’t start AND stop multiple properties at the same time; choose one or the other.

Direction 1 Start one property alone, then animate the additional properties.

Direction-1

//box class
.animation-a {
  animation: animation-a 1s $ibm-snapin;
  transform-origin: 0% 100%;
}

//keyframes for animation
@keyframes animation-a {
  0% {
    transform: scale(0 , 0);
  }
  50% {
    transform: scale(.5 , 0);
  }
  100% {
    transform: scale(1 , 1);
  }
}

Direction 2 Both properties start at the same time, then one property ends before the other.

Direction-2

//box class
.animation-b {
  animation: animation-b 1s $ibm-snapin;
  transform-origin: 0% 100%;
}

//keyframes for animation
@keyframes animation-b {
  0% {
    transform: scale(0 , 0);
  }
  30% {
    transform: scale(.2 , 0);
  }
  80% {
    transform: scaleY(.5);
  }
  100% {
    transform: scale(1 , 1);
  }
}

Easing Curves

Use of Easing Curves:
- Entrances = $snap-in (Fast to Slow)
- Exits = $snap-out (Slow to Fast)
- Interactive Elements = $snap-in-out

Singular vs. Sequence of Actions

Within user interfaces, there are instances when only one element moves, as well as instances when multiple elements create a sequence of actions. The guidelines for both kinds of instances are listed below.

Singular Action

A singular action animation occurs when only one element on the screen is animated, and there are no other complementary elements.

Singular action shows a box animating scaling horizontally then vertically

Sequence of Actions

A sequence of actions animation occurs when there are multiple animated elements. This is typically a primary action, followed by a secondary action that complements the primary.

Secondary action shows a box animating scaling horizontally then vertically with text animating up following the hertical scale

In the example above, the text animations and delay enhance the animation by following the lead of the primary action, which in this case is the scaling of the box.

Things to consider with Sequence of Actions

Choreography: Elements should coordinate within the determined hierarchy.
Delays: Delays need to be consistent and should have the same rate across similar content.

Animation Library Implementation

All of the animations live within an animation map. It looks a bit like this:

$animations: (
  'fade-in': (
    0%: (
      opacity: 0
    ),
    100%: (
      opacity: 1
    )
  ),
  'slide-in--left' : (
    0%: (
      transform: translateY(-100%)
    ),
    100%: (
      transform: translateY(0)
    )
  ),
  'slide-in--right' : (
    0%: (
      transform: translateY(100%)
    ),
    100%: (
      transform: translateY(0)
    )
  )
);

This is the format of the map, with everything between <> being a string:

$animations: (
  '<animation name>': (
    <keyframe%>: (
      <property>: <value>;
    ),
    <keyframe%>: (
      <property>: <value>;
    )
  )
);

In order for you to use these animations in your product, we have implemented an animate Sass mixin. All you need to do is include the animation on the element, by using the following syntax: @include animate(<animation name>, <duration>, <timing function>). If you do not specify the duration and timing function, we have included the default values of 2s and ease-in.

For example, you can implement @include animate('fade-in'); or @include animate(fade-in, 3s, snapin);.

The current animations provided are:

Entrance Animations

fade-in
fade-in--up
fade-in--down
fade-in--left
fade-in--right
slide-in--up
slide-in--down
slide-in--left
slide-in--right

Exit Animations

fade-out
fade-out--up
fade-out--down
fade-out--left
fade-out--right
slide-out--up
slide-out--down
slide-out--left
slide-out--right

Timing Functions

The current timing functions provided are:

ease-in
ease-out
bounce-out
bounce-in
bounce-in-out
snap-in
snap-out
snap-in-out

A timing functions is a mathematical equations that creates a bezier curve, which is a line that defines the acceleration pattern on a graph. Bezier curves are often translated to keywords like: ease-in, ease-out, and ease-in-out. They are also referred to as “Motion Curves” or “Curves.”

IBM-Watson / design-guide