docs(elevation): add guide for elevation helpers (#8172)

* docs(elevation): add guide for elevation helpers

- Credit to @M-a-c for intitial version

* Remove extra newlines

* Address comments

Author: willshowell

guides/elevation.md

@@ -0,0 +1,50 @@
+Angular Material's elevation classes and mixins allow you to add separation between elements along
+the z-axis. All material design elements have resting elevations. In addition, some elements may
+change their elevation in response to user interaction. The
+[Material Design spec](https://material.io/guidelines/material-design/elevation-shadows.html)
+explains how to best use elevation.
+
+Angular Material provides two ways to control the elevation of elements: predefined CSS classes
+and mixins.
+
+### Predefined CSS classes
+
+The easiest way to add elevation to an element is to simply add one of the predefined CSS classes
+`mat-elevation-z#` where `#` is the elevation number you want, 0-24. Dynamic elevation can be
+achieved by switching elevation classes:
+
+```html
+<div [class.mat-elevation-z2]="!isActive" [class.mat-elevation-z8]="isActive"></div>
+```
+
+<!-- example(elevation-overview) -->
+
+### Mixins
+
+Elevations can also be added in CSS via the `mat-elevation` mixin, which takes a number 0-24
+indicating the elevation of the element. In order to use the mixin, you must import
+`~@angular/material/theming`:
+
+```scss
+@import '~@angular/material/theming';
+
+.my-class {
+  @include mat-elevation(2);
+}
+```
+
+For convenience, you can use the `mat-elevation-transition` mixin to add a transition when the
+elevation changes:
+
+```scss
+@import '~@angular/material/theming';
+
+.my-class {
+  @include mat-elevation-transition;
+  @include mat-elevation(2);
+
+  &:active {
+    @include mat-elevation(8);
+  }
+}
+```

src/material-examples/elevation-overview/elevation-overview-example.css

@@ -0,0 +1,4 @@
+.example-container {
+  padding: 16px;
+  margin-bottom: 16px;
+}

src/material-examples/elevation-overview/elevation-overview-example.html

@@ -0,0 +1,7 @@
+<div class="example-container"
+    [class.mat-elevation-z2]="!isActive"
+    [class.mat-elevation-z8]="isActive">
+  Example
+</div>
+
+<button mat-button (click)="isActive = !isActive">Toggle Elevation</button>

src/material-examples/elevation-overview/elevation-overview-example.ts

@@ -0,0 +1,13 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title Elevation CSS classes
+ */
+@Component({
+  selector: 'elevation-overview-example',
+  styleUrls: ['elevation-overview-example.css'],
+  templateUrl: 'elevation-overview-example.html',
+})
+export class ElevationOverviewExample {
+  isActive = false;
+}

src/material-examples/example-module.ts

@@ -45,6 +45,7 @@ import {DialogContentExampleDialog,DialogContentExample} from './dialog-content/
 import {DialogDataExampleDialog,DialogDataExample} from './dialog-data/dialog-data-example';
 import {DialogElementsExampleDialog,DialogElementsExample} from './dialog-elements/dialog-elements-example';
 import {DialogOverviewExampleDialog,DialogOverviewExample} from './dialog-overview/dialog-overview-example';
+import {ElevationOverviewExample} from './elevation-overview/elevation-overview-example';
 import {ExpansionOverviewExample} from './expansion-overview/expansion-overview-example';
 import {ExpansionStepsExample} from './expansion-steps/expansion-steps-example';
 import {MyTelInput,FormFieldCustomControlExample} from './form-field-custom-control/form-field-custom-control-example';
@@ -312,6 +313,12 @@ export const EXAMPLE_COMPONENTS = {
     additionalFiles: ["dialog-overview-example-dialog.html"],
     selectorName: 'DialogOverviewExample, DialogOverviewExampleDialog'
   },
+  'elevation-overview': {
+    title: 'Elevation CSS classes',
+    component: ElevationOverviewExample,
+    additionalFiles: null,
+    selectorName: null
+  },
   'expansion-overview': {
     title: 'Basic expansion panel',
     component: ExpansionOverviewExample,
@@ -785,6 +792,7 @@ export const EXAMPLE_LIST = [
   DialogDataExampleDialog,DialogDataExample,
   DialogElementsExampleDialog,DialogElementsExample,
   DialogOverviewExampleDialog,DialogOverviewExample,
+  ElevationOverviewExample,
   ExpansionOverviewExample,
   ExpansionStepsExample,
   MyTelInput,FormFieldCustomControlExample,