Shadows

Use a shadow when it helps distinguish an element from the content behind it. Keep the default elevation of a library component, and use semantic elevation tokens when building related custom elements.

Change the elevation and switch between micro and macro to compare the live tokens. The lifted drawing makes the relationship visible; a shadow token itself does not move or resize an element.

Semantic elevation

The preset defines four elevation names, each with a micro and macro variant. Micro uses a smaller shadow; macro uses a larger one. Choose between them based on the element's size and context.

Use the complete name, such as elevation.raise.macro, with boxShadow:

import { css } from "@hashintel/ds-helpers/css";

export const floatingPanel = css({
  backgroundColor: "bgSolid.surface",
  borderWidth: "1px",
  borderColor: "bd.subtle",
  borderRadius: "lg",
  boxShadow: "elevation.raise.macro",
});

Shadows in context

Think about what overlaps, how large it is, and how close it should feel to the content beneath it. These are illustrative compositions, not overrides for the library components' default styles.

How a shadow is built

Many base shadows combine two layers: a tight contact shadow and a softer ambient shadow. Here is md taken apart. Both layers use black at 10% opacity; their offsets, blur, and spread differ.

In a box-shadow value, the first two lengths set the horizontal and vertical offset, followed by blur and spread. A negative spread pulls the shadow inward before blurring, keeping a larger shadow from becoming too heavy.

Base shadows

Base tokens remain available for cases where the semantic scale does not express the required treatment. Each tile below uses the same surface size so you can compare the shadows directly.

Use boxShadow: "sm" in a Panda style object, or token.var("shadows.sm") when reading the CSS variable through the token helper. Inspect the token playground for the full shadow definitions.

Inset shadows

An inset shadow sits inside a surface. Use it sparingly to suggest a recessed area, such as a custom input well. It should not replace a visible control boundary or a focus indicator.

Across backgrounds

An opaque background keeps underlying content from showing through. A border can preserve the panel's edge when its shadow is hard to see, especially in dark mode.

Turn the edge off to see how much separation it contributes. In dark mode, prefer a clear surface and a restrained border over a stronger, darker shadow. The examples below keep the shadow identical.

Composition

• Start with the lowest elevation that separates the element from its surroundings.
• Use spacing and borders to group content within a page. Reserve stronger shadows for meaningful overlap.
• Avoid adding a second shadow around a component that already supplies one.
• Check the result on light, dark, and colored backgrounds, including where two floating elements overlap.

A shadow changes appearance; it does not change stacking order. Keep overlay positioning, clipping, and focus behavior in the overlay component. Prefer Dialog, Popover, or Menu to a custom floating container for those interactions.

See Motion when an elevated element enters or leaves the screen.