Elevation

Elevation organizes elements along a visual hierarchy creating a sense of depth in an interface.

Introduction

Elevation represents how "close" or "far" an element feels from the user in a digital context, using a combination of shadows, colors and overlays to create a layering effect, making elements feel distinct, focused or prioritized.

Paste’s elevation system is:

Subtle: Provides just enough visual contrast to create a sense of depth, avoiding excessive visual clutter.
Intentional: Provides clear meaning to guide users through interfaces, improving user efficiency by consistently communicating the level of importance of elements across different pages.
Dynamic: Adapts to different background colors and themes, ensuring consistent depth perception and usability across light, dark, and custom design contexts.

Elevation levels

Paste has a total of 4 levels of elevation. Each elevation level corresponds to a perceived distance within the interface. All components are assigned a level based on their intended distance against the surface behind them.

Level 0

Elements at this level are the baseline for all the other levels and represent the background of the interface.

The majority of elements will be at this level in their resting states. However an element on this level can move to a higher level when interacted with.

For example: a Button might be ‘Level 0’ in its resting state, but ‘Level 1’ when hovered.

Level 1

Elements at this level require subtle differentiation from the surface behind them without adding too much distance. These elements are either presented by default or triggered within the composition but typically do not open on top of other elements.

There are 2 different ways to communicate an element's elevation in level 1:

Use an accent shadow for elements that need to be distinct from the surrounding elements but not highlighted.

mock of side panel component with 'shadow elevation 05' as box shadow

For example: The Side Panel pushes content at Level 0 but is categorized as Level 1, and uses $shadow-elevation-05 because it contains a task that requires user focus while still relying on the background content.

Use a tonal difference when elements need to be highlighted as well as distinct from the background.

a mock of callout component with 'color background body elevation' token as background color that makes it subtly more prominent

For example: a Callout is typically placed inline with the background content and relies on that context for its meaning. However, it uses a slight background change with $color-background-body-elevation to subtly appear more prominent and make its information stand out on top of the default background body color.

Level 2

Elements that rest at this level are distinctly separated from the background and dynamically overlap content layers creating visible distance while still being bound to Level 0 elements.

There are 2 different ways to communicate an element's elevation in level 2:

Use a tonal difference with an accent shadow when an element needs to be highlighted and prominent but does not overlap content by default. Combine this with a soft sharp shadow when the element overlaps other content and extra distance is necessary to make it distinct from the background.

mock of a top bar component that uses 'color background weak elevation' as background color and 'shadow elevation bottom 05' as box shadow

For example: a Topbar's role is not to be at a high hierarchy but to have enough emphasis and differentiation to be easily identified at any point of the experience.

Use a soft and sharp shadow for elements that have temporary prominence or subtly float above the content.

Interactive states like vertical or horizontal scroll can dynamically use a soft, sharp shadow to indicate that there is overflown content.

a mock of popover component that uses 'shadow elevation 10' as box shadow

For example: a Popover uses a subtle, sharp shadow with $shadow-elevation-10 to create the illusion of floating above the content, while still being bound to its trigger button. This adds depth without dominating the interaction.

Level 3

Elements that rest at this level float above all other levels, and tend to contain crucial actions or information that temporarily moves to the top hierarchy of the surface.

Use a large, soft shadow, for elements that are at the top priority and require user focus, but still allow the user to interact with the surrounding content.

For elements that already have their own border, use $shadow-elevation-20. Otherwise, use $shadow-elevation-top-20 to define its edges against the background.

a mock including toast component using 'shadow elevation 20' as box shadow and minimizable dialog using 'color background weaker' token as background color and 'shadow elevation top 20' as box shadow

Use a large soft shadow along with an overlay for elements that completely isolate the interface to draw full focus from the user.

mock of alert dialog component where the overlay is using 'color background overlay' token as background color and 'shadow elevation 20' token as box shadow for dialog

Elevated background color tokens

Subtle tonal shifts are an effective way to communicate hierarchy and prominence for elevated elements without adding visual clutter to the screen.

Paste's elevated background color tokens are derived from a base background color with tonal shifts to indicate elevation. Elevated surfaces darken on light backgrounds and lighten on dark backgrounds, ensuring clarity and consistency across themes.

View our full list of Elevated background color tokens

For levels 1 and 2, when showing elevation through tonal differences, pair elevated background color tokens with their corresponding background color. For example: Use $color-background-body-elevation on top of $color-background-body.

const ElevatedBackgroundColorTokens = () => {
  const TokensTemplate = ({
    backgroundColor,
    backgroundColorElevated,
    hasBorder,
    backgroundColorBase,
    backgroundColorElevation,
  }) => {
    return (
      <Box flexShrink={0} width="170px">
        <Box position="relative">
          <Box
            backgroundColor={backgroundColor}
            borderRadius="borderRadius30"
            height="109px"
            width="100px"
            borderWidth={hasBorder ? "borderWidth10" : "borderWidth0"}
            borderStyle="solid"
            borderColor="colorBorderWeaker"
          />
          <Box
            backgroundColor={backgroundColorElevated}
            borderRadius="borderRadius30"
            height="109px"
            width="100px"
            position="absolute"
            top={23}
            left={23}
          />
        </Box>
        <Box marginTop="space200" fontWeight="fontWeightSemibold">
          <Text as="p" color="colorTextWeak" fontSize="fontSize20">
            Base:
          </Text>
          <Text as="p" marginTop="space30" fontSize="fontSize20">
            {backgroundColorBase}
          </Text>
          <Text as="p" marginTop="space40" color="colorTextWeak" fontSize="fontSize20">
            Elevation:
          </Text>
          <Text as="p" marginTop="space30" fontSize="fontSize20">
            {backgroundColorElevation}
          </Text>
        </Box>
      </Box>
    );
  };
  return (
    <Box display="flex" overflowX="auto" columnGap="space30">
      <TokensTemplate
        backgroundColor="colorBackgroundBody"
        backgroundColorElevated="colorBackgroundBodyElevation"
        backgroundColorBase="$color-background-body"
        backgroundColorElevation="$color-background-body-elevation"
        hasBorder
      />
      <TokensTemplate
        backgroundColor="colorBackground"
        backgroundColorElevated="colorBackgroundElevation"
        backgroundColorBase="$color-background"
        backgroundColorElevation="$color-background-elevation"
      />
      <TokensTemplate
        backgroundColor="colorBackgroundInverse"
        backgroundColorElevated="colorBackgroundInverseElevation"
        backgroundColorBase="$color-background-inverse"
        backgroundColorElevation="$color-background-inverse-elevation"
      />
      <TokensTemplate
        backgroundColor="colorBackgroundInverseStrong"
        backgroundColorElevated="colorBackgroundInverseStrongElevation"
        backgroundColorBase="$color-background-inverse-strong"
        backgroundColorElevation="$color-background-inverse-strong-elevation"
      />
    </Box>
  );
};

render(
  <ElevatedBackgroundColorTokens />
)

Elevated elements across levels that share the same background color as the main page body should use the token $color-background-weaker. This token matches the page body tone in light mode but appears slightly lighter in dark mode to subtly reinforce elevation.

a mock comparing the 'color background weaker token' in light and dark mode used as background color for minimizable dialog

(information)

Different uses of color

Elevation Colors: Subtle tones for prominence and hierarchy, used to separate elements visually from the background.
Semantic Colors: Used to communicate meaning or status, such as success, warning, or error.
Decorative Colors: Reflect the brand identity or give a branded feel to a composition.

Tip: Use elevation colors for hierarchy, semantic colors for purpose, and branded colors for identity and style.

Shadow tokens

Shadows are the most extreme way to display elevation. Overuse of shadows without understanding your page’s visual hierarchy can have a negative effect on the user experience.

View our full list of Elevated shadow tokens

Level 1 shadows are accent shadows that subtly define the edges of a container. They serve as a lightweight alternative to risen shadows at lower elevations.

const ShadowTokensLevel1 = () => {
  return (
    <Box display="flex" fontSize="fontSize30" fontWeight="fontWeightSemibold">
      <Box
        width="50%"
        height="300px"
        display="flex"
        flexDirection="column"
        justifyContent="center"
        paddingLeft="space80"
        borderWidth="borderWidth10"
        borderStyle="solid"
        borderColor="colorBorderWeaker"
        zIndex="zIndex10"
      >
        <Box
          backgroundColor="colorBackgroundWeaker"
          height="100px"
          borderRadius="borderRadius30"
          borderRight="none"
          borderTopRightRadius="borderRadius0"
          borderBottomRightRadius="borderRadius0"
          boxShadow="shadowElevation05"
        />
        <Box display="flex" alignItems="center" columnGap="space20" marginTop="space50">
          <ThemeIcon decorative={true} color="colorTextIcon" />
          <Text as="p" color="colorTextWeak">
            Selected theme
          </Text>
        </Box>
        <Text as="p" marginTop="space30">
          $shadow-elevation-05
        </Text>
      </Box>
      <Box width="50%">
        <Theme.Provider theme="twilio-dark">
          <Box
            backgroundColor="colorBackgroundBody"
            height="300px"
            display="flex"
            flexDirection="column"
            justifyContent="center"
            paddingRight="space80"
            borderWidth="borderWidth10"
            borderLeftWidth="borderWidth0"
            borderStyle="solid"
            borderColor="colorBorderWeaker"
            fontWeight="fontWeightSemibold"
          >
            <Box
              backgroundColor="colorBackgroundWeaker"
              height="100px"
              borderRadius="borderRadius30"
              borderLeft="none"
              borderTopLeftRadius="borderRadius0"
              borderBottomLeftRadius="borderRadius0"
              boxShadow="shadowElevation05"
            />
            <Box display="flex" alignItems="center" columnGap="space20" marginTop="space50" paddingLeft="space80">
              <DarkModeIcon decorative={true} color="colorTextIcon" />
              <Text as="p" color="colorTextWeak">
                Dark mode
              </Text>
            </Box>
            <Text as="p" marginTop="space30" paddingLeft="space80">
              $shadow-elevation-05
            </Text>
          </Box>
        </Theme.Provider>
      </Box>
    </Box>
  );
};

render(
  <ShadowTokensLevel1 />
)

Level 2 shadows are small and sharp and indicate a close distance with the surface behind them. Shadows used in dark backgrounds use a slightly darker hue so the perceived depth is consistent.

const ShadowTokensLevel2 = () => {
  return (
    <Box display="flex" fontSize="fontSize30" fontWeight="fontWeightSemibold">
      <Box
        width="50%"
        height="300px"
        display="flex"
        flexDirection="column"
        justifyContent="center"
        paddingLeft="space80"
        borderWidth="borderWidth10"
        borderStyle="solid"
        borderColor="colorBorderWeaker"
        zIndex="zIndex10"
      >
        <Box
          backgroundColor="colorBackgroundWeaker"
          height="100px"
          borderRadius="borderRadius30"
          borderRight="none"
          borderTopRightRadius="borderRadius0"
          borderBottomRightRadius="borderRadius0"
          boxShadow="shadowElevation10"
        />
          <Box display="flex" alignItems="center" columnGap="space20" marginTop="space50">
            <ThemeIcon decorative={true} color="colorTextIcon" />
            <Text as="p" color="colorTextWeak">
              Selected theme
            </Text>
          </Box>
          <Text as="p" marginTop="space30">
            $shadow-elevation-10
          </Text>
      </Box>
      <Box width="50%">
        <Theme.Provider theme="twilio-dark">
          <Box
            backgroundColor="colorBackgroundBody"
            height="300px"
            display="flex"
            flexDirection="column"
            justifyContent="center"
            paddingRight="space80"
            borderWidth="borderWidth10"
            borderLeftWidth="borderWidth0"
            borderStyle="solid"
            borderColor="colorBorderWeaker"
            fontWeight="fontWeightSemibold"
          >
            <Box
              backgroundColor="colorBackgroundWeaker"
              height="100px"
              borderRadius="borderRadius30"
              borderLeft="none"
              borderTopLeftRadius="borderRadius0"
              borderBottomLeftRadius="borderRadius0"
              boxShadow="shadowElevation10"
            />
            <Box display="flex" alignItems="center" columnGap="space20" marginTop="space50" paddingLeft="space80">
              <DarkModeIcon decorative={true} color="colorTextIcon" />
              <Text as="p" color="colorTextWeak">
                Dark mode
              </Text>
            </Box>
            <Text as="p" marginTop="space30" paddingLeft="space80">
              $shadow-elevation-10
            </Text>
          </Box>
        </Theme.Provider>
      </Box>
    </Box>
  );
};

render(
  <ShadowTokensLevel2 />
)

Level 3 shadows are larger and softer, this indicates a further distance from the surface behind them. Shadows used in dark backgrounds use a slightly darker hue so the perceived depth is consistent.

const ShadowTokensLevel3 = () => {
  return (
    <Box display="flex" fontSize="fontSize30" fontWeight="fontWeightSemibold">
      <Box
        width="50%"
        height="300px"
        display="flex"
        flexDirection="column"
        justifyContent="center"
        paddingLeft="space80"
        borderWidth="borderWidth10"
        borderStyle="solid"
        borderColor="colorBorderWeaker"
        zIndex="zIndex10"
      >
        <Box
          backgroundColor="colorBackgroundWeaker"
          height="100px"
          borderRadius="borderRadius30"
          borderRight="none"
          borderTopRightRadius="borderRadius0"
          borderBottomRightRadius="borderRadius0"
          boxShadow="shadowElevation20"
        />
        <Box display="flex" alignItems="center" columnGap="space20" marginTop="space50">
          <ThemeIcon decorative={true} color="colorTextIcon" />
          <Text as="p" color="colorTextWeak">
            Selected theme
          </Text>
        </Box>
        <Text as="p" marginTop="space30">
          $shadow-elevation-20
        </Text>
      </Box>
      <Box width="50%">
        <Theme.Provider theme="twilio-dark">
          <Box
            backgroundColor="colorBackgroundBody"
            height="300px"
            display="flex"
            flexDirection="column"
            justifyContent="center"
            paddingRight="space80"
            borderWidth="borderWidth10"
            borderLeftWidth="borderWidth0"
            borderStyle="solid"
            borderColor="colorBorderWeaker"
            fontWeight="fontWeightSemibold"
          >
            <Box
              backgroundColor="colorBackgroundWeaker"
              height="100px"
              borderRadius="borderRadius30"
              borderLeft="none"
              borderTopLeftRadius="borderRadius0"
              borderBottomLeftRadius="borderRadius0"
              boxShadow="shadowElevation20"
            />
            <Box display="flex" alignItems="center" columnGap="space20" marginTop="space50" paddingLeft="space80">
              <DarkModeIcon decorative={true} color="colorTextIcon" />
              <Text as="p" color="colorTextWeak">
                Dark mode
              </Text>
            </Box>
            <Text as="p" marginTop="space30" paddingLeft="space80">
              $shadow-elevation-20
            </Text>
          </Box>
        </Theme.Provider>
      </Box>
    </Box>
  );
};

render(
  <ShadowTokensLevel3 />
)