Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 8 commits into from
Jun 23, 2017
Merged

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

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3d10d24
docs(elevation): Simplify README to follow proposed best practices
lynnmercier Jun 2, 2017
7767862
docs(elevation): Simplify README to follow proposed best practices
lynnmercier Jun 2, 2017
da4d95d
docs(elevation): Simplify README to follow proposed best practices
lynnmercier Jun 2, 2017
921166a
docs(elevation): Simplify README to follow proposed best practices
lynnmercier Jun 2, 2017
a6f5a63
docs(elevation): Simplify README to follow proposed best practices
lynnmercier Jun 2, 2017
2ca992c
Merge branch 'master' into docs/elevation
lynnmercier Jun 22, 2017
9ddac3f
fix typo
lynnmercier Jun 23, 2017
1b5026a
Merge branch 'master' into docs/elevation
lynnmercier Jun 23, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 16 additions & 111 deletions packages/mdc-elevation/README.md
View file
Open in desktop
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. |