From d13274dceaa41e41ef15dfade5166aeabb981695 Mon Sep 17 00:00:00 2001 From: Jeremy Elbourn Date: Mon, 12 Apr 2021 17:13:20 -0700 Subject: [PATCH] docs(material/theming): rewrite elevation guide This change updates the elevation guide to be more clear, concise, and complete. The changes include: * Drop content about the general concept of elevation, deferring that to the Material Design spec. * Document the `overridable-elevation` mixin * Mention that the elevation CSS classes are emitted by `core-theme`. * Switch to `@use` --- guides/elevation.md | 54 +++++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/guides/elevation.md b/guides/elevation.md index b9578de6cb63..5cea5b933f52 100644 --- a/guides/elevation.md +++ b/guides/elevation.md @@ -1,19 +1,19 @@ -# Setting Element Elevation +# Applying Elevation -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/design/environment/elevation.html) -explains how to best use elevation. +[The Material Design specification][material-elevation] gives guidance on expressing elevation on +UI elements by adding shadows. Angular Material provides CSS classes and Sass mixins for adding +these shadows. -Angular Material provides two ways to control the elevation of elements: predefined CSS classes -and mixins. +[material-elevation]: https://material.io/design/environment/elevation.html -## Predefined CSS classes +## Elevation 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: +The `core-theme` Sass mixin, described in the [theming guide][], emits CSS classes for applying +elevation. These classes follow the pattern `mat-elevation-z#`, where `#` is the elevation number +you want, from 0 to 24. These predefined classes use the CSS `box-shadow` settings defined by the +Material Design specification. + +You can dynamically change elevation on an element by swapping elevation CSS classes. ```html
@@ -21,17 +21,14 @@ achieved by switching elevation classes: -## Mixins - -Elevations can also be added in CSS via the `elevation` mixin, which takes a number 0-24 -indicating the elevation of the element as well as optional arguments for the elevation shadow's -color tone and opacity. +[theming-guide]: https://material.angular.io/guide/theming#applying-a-theme-to-components -Since an elevation shadow consists of multiple shadow components of varying opacities, the -`$opacity` argument of the mixin is considered a factor by which to scale these initial values -rather than an absolute value. +## Elevation Sass mixins -In order to use the mixin, you must import `~@angular/material`: +In addition to the predefined CSS classes, you can apply elevation styles using the `elevation` +Sass mixin. This mixin accepts a `$zValue` and an optional `$color`. The `$zValue` is a number from +0 to 24, representing the semantic elevation of the element, that controls the intensity of the +box-shadow. You can use the `$color` parameter to further customize the shadow appearance. ```scss @use '~@angular/material' as mat; @@ -47,14 +44,23 @@ In order to use the mixin, you must import `~@angular/material`: } ``` -For convenience, you can use the `elevation-transition` mixin to add a transition when the -elevation changes: +### Overridable elevation + +When authoring a component, you may want to specify a default elevation that the component consumer +can override. You can accomplish this by using the `overridable-elevation` Sass mixin. This behaves +identically to the `elevation` mixin, except that the styles only apply when the element does not +have a CSS class matching the pattern `mat-elevation-z#`, as described in +[Elevation CSS classes](#elevation-css-classes) above. + +### Animating elevation + +You can use the `elevation-transition` mixin to add a transition when elevation changes. ```scss @use '~@angular/material' as mat; .my-class { - @include mat.elevation-transition; + @include mat.elevation-transition(); @include mat.elevation(2); &:active {