Elevated

The problem

In light mode, we use shadow behind white surfaces to signify elevation. In dark mode, we use progressively lighter backgrounds instead.

But traditional components have a fixed background — a dropdown often ends up the same color as the dialog it sits in, and disappears into it.

The solution

Three pieces: tokens, substrate context and the primitive.

• Tokens — eight bg/shadow pairs. Light mode flattens to white after step 2 (shadow alone carries elevation). Dark mode keeps adding white-opacity plus a layered shadow recipe.
• Substrate — each container knows its own level and tells whatever opens inside. A popover on the page and the same popover inside a dialog both end up at the right depth, without anything passed between them.
• Elevated — wrap a panel and its background settles at the level it belongs to. Each layer lifts a single step off the one it sits in — whether you span two levels or all eight.

Installation

pnpm dlx shadcn@latest add https://matos-ui.com/r/elevated.json

Usage

import { Elevated } from '@/components/matos-ui/elevated'
import { SurfaceProvider } from '@/lib/surface-context'

Set a base substrate, then let each panel lift itself relative to it. The offset is what a component adds to whatever it is nested inside — so the same Elevated reads correctly on the page or several layers deep.

<SurfaceProvider value={1}>
  <div className="rounded-2xl bg-surface-1 shadow-surface-1 p-4">
    {/* Dialog: 1 + 4 = surface-5 */}
    <Elevated offset={4} className="rounded-2xl p-4">
      {/* Popover inside the dialog: 5 + 2 = surface-7,
          but a constant popover shadow regardless of depth */}
      <Elevated offset={2} shadowLevel={3} className="rounded-xl p-2">
        Menu
      </Elevated>
    </Elevated>
  </div>
</SurfaceProvider>

Conventional offsets: 2 for a dropdown / popover / select menu, 4 for a dialog / modal.

Reference

Elevated

Renders a div whose background tracks the substrate and re-provides the new level to its descendants. Accepts all native div props.

SurfaceProvider

Sets the substrate level for everything inside. Clamped to 1–8.

useSurface

useSurface(): number — reads the current substrate level from context.