Depth → Tokens

Use a combination of shadows and layering to create a sense of realism and hierarchy in the interface, guiding merchants' attention and indicating interactivity.

Primitive shadow tokens

The primitive shadow tokens scale offers a versatile range of shadows that can be applied to components, providing a fundamental foundation for creating visual cues of depth in the UI. These tokens are categorized into three sets:

Token scales

Elevation tokens: These tokens visually represent a shadow being cast on a surface below the element, effectively simulating a sense of elevation.
Inset tokens: Demonstrate an inner shadow creating the impression of an embedded element.
Bevel tokens: provide a dimensional appearance to an element, enhancing its perceived shape and structure.

shadow-300 and shadow-bevel-100 tokens applied to a tooltip and a
shadow-inset-200 token applied to a pressed icon
button.

Token structure

Each of these sets is declared with the shadow token group name. In addition, the scales offer comprehensive ranges in increments of 100, and the base value is set at 100.

shadow-100 and shadow-bevel-100 tokens applied to cards and a shadow-600
token applied to a search
overlay.

Component specific tokens

Components such as buttons require component-specific shadows to visually exhibit their unique tactility. To achieve this button styling, component-specific shadow tokens are assigned to each variant of the button. These tokens reside in a separate token collection and should only be utilized for the specific component they are named after.

A shadow-button token applied to a default button and a
shadow-button-primary-critical token applied to a critical
button.

A shadow-button-inset token applied to a pressed default button and a
shadow-button-primary-critical-inset token applied to a pressed critical
button.

Token pairing

When combining the bevel token with elevation tokens, builders can achieve a desired visual distinction that is necessary to create contrast between an elevated surface and its background. The bevel token adds dimensionality to the element, while elevation tokens provide a drop shadow effect that creates the perception of distance. To implement this pairing, assign the bevel token as a pseudo class with absolute positioning and set the mix-blend-mode CSS property to luminosity to create the desired effect.

position: relative;
box-shadow: $boxShadow;
border-radius: $borderRadius;
border: $border;

&::before {
content: $content;
position: absolute;
top: 0;
left: 0;
right: 0;
bottom: 0;
z-index: $zIndex;
box-shadow: var(--p-shadow-bevel-100);
border-radius: $borderRadius;
pointer-events: none;
mix-blend-mode: luminosity;
}

Polaris component shadows

Components use specific shadow tokens. The following table can be a useful resource.

Polaris Components	Shadow tokens
Account connection Card Data table Empty states Fullscreen bar Index table Media card Resource list Setting toggle Top bar	--p-shadow-100 --p-shadow-bevel-100
Banner Callout card	--p-shadow-200 --p-shadow-bevel-100
Action list Option list Color picker Date picker Popover Tooltip	--p-shadow-300 --p-shadow-bevel-100
Toast	--p-shadow-400 --p-shadow-bevel-100
Modal	--p-shadow-600 --p-shadow-bevel-100
Search	--p-shadow-600