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.

Elevation functions

The design system includes a concept of elevation, which refers to how far an element appears to be raised above the canvas. Elevation affects both the surface colour and the size of the shadow cast by the element. This documentation explains how elevation is handled across light and dark modes and how to use shadow functions to achieve the correct elevation in your designs.

Understanding elevation

Elevation is a key aspect of our design system, influencing not just the shadow of an element but also its surface colour. As an element’s elevation increases, its shadow grows larger, and the surface colour may also change to reflect its raised position. This approach ensures a consistent look and feel across different themes and modes.

Using the shadow functions in sass

To apply shadows based on elevation, use the ds-shadow($name) function. This function accepts the name of the shadow type and returns the corresponding CSS variable.

Shadow values

elevation

0 2px 2px 0 rgba(21,39,45,0.08), 0 4px 8px 0 rgba(21,39,45,0.08)

elevation / default

The default shadow used throughout the system. The most common example being cards.

0 2px 4px 0 rgba(21,39,45,0.08), 0 6px 8px 0 rgba(21,39,45,0.12)

elevation / default-hover

Default hover state shadow, used in combination with the default shadow, to improve the visual feedback for interactive surfaces.

0 2px 2px 0 rgba(0,46,54,0.08)

elevation / default-press

Default press state shadow, used in combination with the default shadow, to improve the visual feedback for interactive surfaces.

0 4px 6px -2px rgba(21,39,45,0.08), 0 12px 16px -2px rgba(21,39,45,0.12)

elevation / raised

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

0 8px 12px -4px rgba(21,39,45,0.08), 0 20px 24px -4px rgba(21,39,45,0.12)

elevation / overlay

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

Example source (SCSS)

.c-card {
    box-shadow: ds-shadow("default");
}

Example output (CSS)

.c-card {
    box-shadow: var(--ds-shadow-default);
}

Combining elevation with surface colours

When applying elevation, it’s important to pair shadows with the appropriate surface colours to maintain visual consistency across different modes (light and dark).

Elevation / layers

Default elevation example (SCSS)

.c-card {
    background-color: ds-color("bg", "default");
    box-shadow: ds-shadow("default");
}

Raised elevation example (SCSS)

.c-card {
    background-color: ds-color("bg", "elevation-raised");
    box-shadow: ds-shadow("raised");
}

Overlay elevation example (SCSS)

.c-card {
    background-color: ds-color("bg", "elevation-overlay");
    box-shadow: ds-shadow("overlay");
}