Skip to content

Commit

Permalink
docs(elevation): Simplify README to follow proposed best practices (#826
Browse files Browse the repository at this point in the history 
)
  • Loading branch information
@lynnmercier
lynnmercier authored Jun 23, 2017
1 parent 01decc3 commit 82cd7b6
Showing 1 changed file with 16 additions and 111 deletions.
127 changes: 16 additions & 111 deletions packages/mdc-elevation/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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. |

0 comments on commit 82cd7b6

Please sign in to comment.