docs(elevation): Simplify README to follow proposed best practices (#826)

lynnmercier · lynnmercier · commit 85f3f5cbcae0 · 2017-06-27T16:39:52.000-07:00
diff --git a/packages/mdc-elevation/README.md b/packages/mdc-elevation/README.md
@@ -16,13 +16,7 @@ path: /catalog/elevation/
   </a>
 </div>-->
 
-MDC Elevation provides Sass mixins and CSS classes which are used to provide [shadows and
-elevation](https://material.io/guidelines/what-is-material/elevation-shadows.html) to our material
-components.
-
-The elevation values are mapped out in a "z-space" and range from `0` to `24`.
-Our implementation is based on [Scott Hyndman's work](http://codepen.io/shyndman/full/ojxmdY/),
-which was created in collaboration with the designers on the Material Design team.
+Shadows provide important visual cues about objects’ depth and directional movement. They are the only visual cue indicating the amount of separation between surfaces. An object’s elevation determines the appearance of its shadow. The elevation values are mapped out in a "z-space" and range from `0` to `24`.
 
 > **A note about "z-space"**: Within the spec, elevation is normally referred to as having a `dp`
 > value. In other words, how many "pixels" above the base material is a piece of material elevated.
@@ -50,124 +44,35 @@ npm install --save @material/elevation
 
 ## Usage
 
-### Sass Mixin
-
-MDC Elevation exports an `mdc-elevation` mixin which can be used to set the elevation on a selector.
-It works by assigning the correct elevation value to a selector's `box-shadow` property.
+### Sass Mixins, Variables, and Functions
 
-`mdc-elevation` takes one `$z-value` argument which represents the z-space for that given elevation. For example, [cards](https://material.io/guidelines/components/cards.html) have a resting elevation of `2dp`. Implementing that using MDC Elevation looks like the following:
+| Mixin | Description |
+| ----------------------------------------------- | - |
+| `mdc-elevation($z-value)` | Sets the elevation to the z-space for that given elevation |
+| `mdc-elevation-transition($duration, $easing)` | Applies the correct css rules to transition an element between elevations |
 
-```scss
-@import "@material/elevation/mixins";
-
-.mdc-card {
-  @include mdc-elevation(2);
-  // ...
-}
-```
+| Variable | Description |
+| ------------------------------------------- | - |
+| `mdc-elevation-transition-duration` | Default duration value for elevation transitions |
+| `mdc-elevation-transition-timing-function` | Default easing value for elevation transitions |
 
-It is also quite simple to alias common elevations throughout your application by leveraging this
-mixin to export classes:
-
-```scss
-$elevations: (low, medium-low, medium, medium-high, high);
-
-@for $i from 1 through length($elevations) {
-  $elev: nth($elevations, $i);
-  $z: $i * 2;
-  .my-app-elevation--#{$elev} {
-    @include mdc-elevation($z);
-  }
-}
-```
-
-Note that importing `mdc-elevation/mixins` does not output any CSS.
-
-### CSS Classes
-
-MDC Elevation also includes a CSS file that exports all z values as `mdc-elevation--z<N>` modifier
-classes that can be easily used within HTML.
-
-> NOTE: dist/ dir will be available post-alpha in the distributed npm package.
-
-```html
-<!-- in <head> -->
-<link rel="stylesheet" href="/path/to/mdc-elevation/dist/mdc-elevation.css">
-<!-- ... -->
-<!-- in <body> -->
-<p class="mdc-elevation--z2">Text that floats near the material surface</p>
-<p class="mdc-elevation--z18">Text that floats far away from the material surface</p>
-```
-
-### Handling elevation transitions
-
-MDC Elevation includes utilities for transitioning between elevations.
-
-#### Sass functions/mixins
-
-The `mdc-elevation-transition-rule` function takes an optional duration and optional easing curve and
-spits out a `transition` property value shorthand with `box-shadow` specified as the property, and
-either the supplied or default durations / easings for the transition.
-
-You can also use the `mdc-elevation-transition` mixin - which takes the same arguments as the above
-function - to output a `transition` property with the correct values as well as a `will-change`
-property with `box-shadow` set.
-
-```scss
-@import "@material/animation/variables";
-@import "@material/elevation/mixins";
-
-.my-component {
-  @include mdc-elevation(2);
-  @include mdc-elevation-transition;
-
-  &--fast-transitions {
-    transition: mdc-elevation-transition-rule(180ms);
-  }
-
-  &--default-ease-transitions {
-    transition: mdc-elevation-transition-rule($mdc-elevation-transition-duration, ease);
-  }
-
-  &:focus {
-    @include mdc-elevation(4);
-  }
-
-  &:active {
-    @include mdc-elevation(8);
-  }
-}
-```
-
-If you need more configurability over your transitions, you can easily accomplish this by using
-the `mdc-elevation-transition-rule` function in conjunctions with the exported sass variables that
-mdc-elevation exposes for purposes of transitioning.
+If you need more configurability over your transitions, use the `mdc-elevation-transition-rule` function in conjunction with the exported sass variables.
 
 ```scss
 .my-component-with-custom-transitions {
-  @include mdc-elevation(2);
 
   transition:
     mdc-elevation-transition-rule(),
     /* Configure opacity to use same duration and easing values as elevation */
     opacity $mdc-elevation-transition-duration $mdc-elevation-transition-timing-function;
   opacity: .7;
   will-change: $mdc-elevation-property, opacity;
-
-  &:hover {
-    opacity: 1;
-  }
-
-  &:active {
-    @include mdc-elevation(6);
-  }
 }
 ```
 
-#### CSS Classes
-
-MDC Elevation also exports an `mdc-elevation-transition` CSS class which can be used within HTML.
+### CSS Classes
 
-```html
-<p class="mdc-elevation-transition mdc-elevation--z2">My elevation will change at some point...</p>
-```
+| CSS Class | Description |
+| --------------------------- | - |
+| `mdc-elevation--z<N>` | Sets the elevation to the (N)dp, where 1 <= N <= 24. |
+| `mdc-elevation-transition` | Applies the correct css rules to transition an element between elevations. |
