Docs
Paper

Paper

Paper is a Flex with pre-configured padding, borderRadius, bgColor and deep (depth shadow). Use it when you want a "sheet" with a shadow without having to declare those defaults on every use.

Since it extends Flex, all factory props are available and any default can be overridden via props.

The split between the two is semantic, and it is meant to be read in the code: Flex declares structure (rows, columns, gaps — the invisible skeleton), Paper declares a content surface (a visible sheet the user looks at). Paper carries every Flex prop plus the two things only a content surface earns — background and shadow. If you catch yourself giving a Flex a bgColor, that node stopped being structure: make it a Paper.

When to use

✅ Use when…🚫 Avoid when…
  • To make content stand out from the background (dashboard cards, panels, inline modals).
  • When you need a consistent shadow across components — Paper has 8 levels of deep mapped in the theme.
  • For containers without a shadow. Use Flex directly.
  • For cards with structured media/title/actions. Use Card — it already composes those parts.

Depth

Paper (and Flex) support 8 levels of deep, from -1 to 6.

deep = -1
deep = 0
deep = 1
deep = 2 (default)
deep = 3
deep = 4
deep = 5
deep = 6
<Paper bgColor="neutral.5" p="small" gap="medium">
  <Paper deep={-1} />
  <Paper deep={0} />
  <Paper deep={1} />
  <Paper deep={2} />
  <Paper deep={3} />
  <Paper deep={4} />
  <Paper deep={5} />
  <Paper deep={6} />
</Paper>

Changing the shadow color

deepColor accepts any semantic theme color:

loading

This component's API is the system's layout props (spacing, color, flex/grid, size, border).

Avoid stacking several high deep values close together — it creates visual noise instead of a clear hierarchy.

See also

  • Storybook story: Components / Paper
  • Base container: Flex.

Theming — surface ladder

Paper sits on the surface ladder: its default ground is surface.paper (bgColor="surface.paper"), its shadow follows the polarity (lighter in light, heavier and black-anchored in dark). The roles are mode-aware by construction — paper is lighter than the canvas in both light and dark — and every ink inside resolves against this ground through the ground channel. Override a role per polarity with createTheme({ colors: { ladder: … } }); see Dark Mode Engine.

GridCard