# Shadows (/foundations/shadows)



<div className="hd-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.

  <ShadowExplorer />

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

  | Elevation         | Micro resolves to | Macro resolves to |
  | ----------------- | ----------------- | ----------------- |
  | `elevation.drop`  | `2xs`             | `xs`              |
  | `elevation.lift`  | `xs`              | `sm`              |
  | `elevation.raise` | `sm`              | `md`              |
  | `elevation.float` | `md`              | `lg`              |

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

  ```tsx
  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 [#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.

  <ShadowContexts />

  ## How a shadow is built [#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.

  <ShadowAnatomy />

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

  <ShadowScale />

  | Family        | Available values                            |
  | ------------- | ------------------------------------------- |
  | Outer shadows | `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`. |
  | Inset shadows | `inset-2xs`, `inset-xs`, `inset-sm`.        |

  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](/foundations/design-system#token-playground) for the full shadow definitions.

  ## Inset shadows [#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.

  <ShadowScale kind="inset" />

  ## Across backgrounds [#across-backgrounds]

  An opaque [background](/foundations/colors) 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.

  <ShadowBackgrounds />

  ## Composition [#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.

  <ShadowClipping />

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

  See [Motion](/foundations/motion) when an elevated element enters or leaves the screen.
</div>