Elevation

Our elevation system is used to visually differentiate the hierarchy in our UI. A combination of shadows and background colours is used to convey depth, prominence, and focus.

Best practices

Be mindful to not overuse shadows.

Use shadows only when required to create additional separation against a background or to encourage interaction.

Always make sure your elevation and background choices are accessible.

Do not nest elevated cards inside cards.

If there are two different levels of elevation in an experience, raise the elevation level on the highest-priority item to eliminate confusion and differentiate between surfaces.

Don't use excessively large shadows in compact areas. Reserve for more singular uses, like a Modal.

Gotchas

Why should I use a bg.default for cards and not just a white colour?

The difference becomes obvious when working with multiple themes. The surface colours look alike in the light theme, but in the dark theme the colours change depending on the elevation level. A white colour will just remain white across themes which is not what we want.

Elevation using shadows

To allow for as much creative freedom as possible, the elevation system offers a range of combinations to express prominence and depth.
There are 3 elevation levels:

Default – sits just above the page but inside the normal content flow.

Raised – sits on top of the normal content flow.

Overlay – sits on top of overlay backgrounds and is the highest elevation.

In lighter themes shadows are a great way to make UI elements stand out.

In darker themes, shadows can be very hard to distinguish from the background and therefore the dark theme also convey elevation by changing surface colours.

The surface colours in the dark theme are best understood by imagining that the surfaces are distantly lit from the front — the higher the elevation, the lighter the surface looks.

Default

The default surface colour, bg.default, combined with default shadow, “elevation.default”, are used throughout the system. The most common example being cards.

Pairing the elevation.default shadow with the bg.default colour is optional, since borders can be used to create separation too.

Raised

Raised elevations sit slightly higher than default elevations and is intended for UI elements that open over the main content, usually triggered by the user - e.g. dropdowns and popovers.

Remember to always pair the elevation.raised shadow with the bg.elevation-raised surface colour. This is particularly important in dark mode, where raised surfaces are lighter to help differentiate elevations.

In the dark theme bg.elevation-raised is lighter than the default surface colour to make it easier to distinguish.

Overlay

Overlay is the highest elevation available. It is intended for UI elements placed on top of a backdrop, such as modals and drawers.

Remember to always pair the elevation.overlay shadow with the bg.elevation-overlay surface colour. This is particularly important in dark mode, where overlay surfaces are lighter to help differentiate them from the underlying UI elements.