Elevation
Elevation organizes elements along a visual hierarchy creating a sense of depth in an interface.
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.
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.
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.
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.

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

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.

- 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.

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.

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

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 tokensFor 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"><BoxbackgroundColor={backgroundColor}borderRadius="borderRadius30"height="109px"width="100px"borderWidth={hasBorder ? "borderWidth10" : "borderWidth0"}borderStyle="solid"borderColor="colorBorderWeaker"/><BoxbackgroundColor={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"><TokensTemplatebackgroundColor="colorBackgroundBody"backgroundColorElevated="colorBackgroundBodyElevation"backgroundColorBase="$color-background-body"backgroundColorElevation="$color-background-body-elevation"hasBorder/><TokensTemplatebackgroundColor="colorBackground"backgroundColorElevated="colorBackgroundElevation"backgroundColorBase="$color-background"backgroundColorElevation="$color-background-elevation"/><TokensTemplatebackgroundColor="colorBackgroundInverse"backgroundColorElevated="colorBackgroundInverseElevation"backgroundColorBase="$color-background-inverse"backgroundColorElevation="$color-background-inverse-elevation"/><TokensTemplatebackgroundColor="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.

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.
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 tokensLevel 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"><Boxwidth="50%"height="300px"display="flex"flexDirection="column"justifyContent="center"paddingLeft="space80"borderWidth="borderWidth10"borderStyle="solid"borderColor="colorBorderWeaker"zIndex="zIndex10"><BoxbackgroundColor="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"><BoxbackgroundColor="colorBackgroundBody"height="300px"display="flex"flexDirection="column"justifyContent="center"paddingRight="space80"borderWidth="borderWidth10"borderLeftWidth="borderWidth0"borderStyle="solid"borderColor="colorBorderWeaker"fontWeight="fontWeightSemibold"><BoxbackgroundColor="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"><Boxwidth="50%"height="300px"display="flex"flexDirection="column"justifyContent="center"paddingLeft="space80"borderWidth="borderWidth10"borderStyle="solid"borderColor="colorBorderWeaker"zIndex="zIndex10"><BoxbackgroundColor="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"><BoxbackgroundColor="colorBackgroundBody"height="300px"display="flex"flexDirection="column"justifyContent="center"paddingRight="space80"borderWidth="borderWidth10"borderLeftWidth="borderWidth0"borderStyle="solid"borderColor="colorBorderWeaker"fontWeight="fontWeightSemibold"><BoxbackgroundColor="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"><Boxwidth="50%"height="300px"display="flex"flexDirection="column"justifyContent="center"paddingLeft="space80"borderWidth="borderWidth10"borderStyle="solid"borderColor="colorBorderWeaker"zIndex="zIndex10"><BoxbackgroundColor="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"><BoxbackgroundColor="colorBackgroundBody"height="300px"display="flex"flexDirection="column"justifyContent="center"paddingRight="space80"borderWidth="borderWidth10"borderLeftWidth="borderWidth0"borderStyle="solid"borderColor="colorBorderWeaker"fontWeight="fontWeightSemibold"><BoxbackgroundColor="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 />)