# Elevation

> Elevation is the relative distance between two surfaces along the z-axis.
> –[Material Design](https://material.io/design/environment/elevation.html)

In Atlantis, our web components use elevation to specify position on the z-axis,
with shadows separately responsible for conveying that depth. Our mobile
components combine these two concepts in keeping with Android and iOS patterns.

Generally speaking, the "higher" an element sits in the z-axis, the broader its'
shadow should spread, to reflect diffusion in the distance between the element
and the ground. As an element gets nearer to the ground, or "lower", the
shadow's spread should reduce and the shadow may appear darker.

We also include a *slight* y-axis offset of elevation shadows to imply that the
light source is coming from an angle slightly over the head of a user looking
directly into the screen.

### Low

A low element may have a slight elevation, but is not necessarily something that
will glide across the surface. A basic card on mobile that is not tappable would
be represented as having a "low" elevation.

### Base

This shadow should be used for most instances of shadows to convey that an
element is floating overtop related elements, such as in
[Menu](../Menu/Menu.md) or [Popover](../Popover/Popover.md). An element with a
base elevation is likely interactive, and this level can indicate and invite the
use of gesture controls in a mobile app.

### High

High elements should be elements that float overtop the entire interface,
typically with a fixed position. The "high" elevation indicates that the element
has broken the plane of the view. A good example for web would be
[Toast](../Toast/Toast.md).

## Web

### Z-index elevation

The following table lists Atlantis components that have a z-index specified.

These values can be referenced when you are building a view so that you can
ensure the elements you are using do not unintentionally overlap, if you end up
using z-index on non-Atlantis components.

| Component        | Value |
| :--------------- | :---- |
| Form field label |       |
| Menu             |       |
| Modal            |       |
| Tooltip          |       |
| Toast            |       |

### Shadow elevation

These are the box-shadows rendered to signify elevation on given UI elements;
they map to our low/base/high pattern.

| Name            | Visual |
| :-------------- | :----- |
| `--shadow-low`  |        |
| `--shadow-base` |        |
| `--shadow-high` |        |

## Mobile

For mobile designs, the concept of elevation applies to both shadows and
hierarchy of the element along the z-index. Android accepts a single "elevation"
value, while iOS accepts more granular shadow values similar to CSS.

When using the mobile tokens imported from `@jobber/design`, the shadow tokens
will be resolved to apply to either android or iOS devices automatically.