Surfaces

Open a dropdown and it should read as floating above the page. Open a popover inside a dialog and it should still read as floating above the dialog. Surfaces is the system that makes that happen automatically, at any depth. Most of the time you never touch it.

How elevation works

Every floating component (Popover, Dropdown, Dialog, Sheet, Drawer, and the rest) sits on a level from 1 to 8. The deeper something is nested, the higher its level. A card sits low, a dialog higher, a popover opened inside that dialog higher still. Each step up gets a lighter surface and a stronger shadow, so every layer reads as lifted above the one behind it.

There are eight levels because a nested case can go surprisingly deep, and the ladder should never run out. Most apps only ever reach for three or four.

One thing is worth knowing up front, because light and dark behave differently:

• Light mode keeps levels 3 and up pure white. The shadow alone does the lifting.
• Dark mode brightens the surface at each level, from oklch(0.205) at level 1 to oklch(0.402) at level 8, so each layer is visibly lighter than the one below.

The two knobs

Every elevated component takes two props:

• level picks the surface color: which rung of the 1 to 8 ladder it sits on.
• shadowLevel picks the shadow weight: how heavily it casts.

They move independently. A wide dialog can sit on a mid surface but throw a heavy shadow; a small popover can sit higher yet cast a lighter one. Drag both and watch what changes:

In light mode the surface stops changing above level 3 (they are all white) while the shadow keeps growing. In dark mode the surface color climbs with every level. That split is the whole idea: light mode leans on shadow, dark mode leans on color. Toggle the site theme to compare.

Using it

Here is the part that matters most: you rarely set either prop. The defaults are tuned for the common case. A popover already sits at the right level; a dialog already sits higher.

The one time you reach for level is when you nest deeper than usual, like opening a popover from inside a dialog:

// Default popover: level and shadow are already set for you.
<Popover>
  <PopoverTrigger>Open</PopoverTrigger>
  <PopoverContent>Default popover</PopoverContent>
</Popover>
 
// Inside a Dialog (which sits at level 5), bump the inner popover up.
<Dialog>
  <DialogContent>
    <Popover>
      <PopoverTrigger>Open inside dialog</PopoverTrigger>
      <PopoverContent level={7}>Pops above the dialog</PopoverContent>
    </Popover>
  </DialogContent>
</Dialog>

Bump level (not shadowLevel) when you nest. shadowLevel stays pinned per component, so a popover keeps reading like a popover no matter how deep it goes.

That is the whole API for most people. Everything below is reference: the raw tokens, four helpers for building your own surfaces, and the knobs for retuning the system. Skip it until you need it.

Reference

The ladder

Eight surface colors, drawn here in your current theme:

◇ is var(--neutral-chroma) and ◆ is var(--neutral-hue); both come from the brand tint.

The named tokens you use elsewhere alias onto the ladder, so tuning the ladder updates all of them:

--background: var(--surface-1);
--card: var(--surface-3); /* Card and Popover share level 3 */
--popover: var(--surface-3);
--sidebar: var(--surface-1);

Shadows

shadowLevel tracks the visual weight of the element, not its surface level. Pick it by size:

• Under ~400px wide: 3
• ~400 to 800px: 5
• Over ~800px or fullscreen: 7
• Never let shadowLevel exceed level by more than 2.

In dark mode the recipe also adds an inset highlight and ring, giving surfaces a lit-from-above edge. In light mode those insets are no-ops and the drop shadow does everything.

Component defaults

You do not need these day to day; they are what each component already uses. Reach in only to match a custom element to a built-in one.

State overlays

Hover and selected backgrounds are translucent overlays, so they lift whatever surface they sit on by a fixed perceptual step, whatever its level:

/* light */
--surface-hover: oklch(0 0 0 / 0.06);
--surface-selected: oklch(0 0 0 / 0.1);
 
/* dark */
--surface-hover: oklch(1 0 0 / 0.06);
--surface-selected: oklch(1 0 0 / 0.1);

<div className="bg-(--surface-hover)">Hovered row</div>
<div className="bg-(--surface-selected)">Active row</div>

Because they are overlays and not fixed colors, hover on a surface-3 row brightens by the same amount as on a surface-7 row. Hover always reads as hover, even deeply nested. The values (6% for hover, 10% for selected) are matched to fluid-functionalism.

Building your own surface

Making a custom floating container? Four helpers in @/registry/default/lib/elevated return Tailwind class strings. Drop them on any element you want elevated. Pick by situation:

solidSurface(level, shadowLevel?)

Returns bg-surface-N, the combined drop and rim shadow, and exposes --popup-surface for descendants. Use it for any floating container without sticky or opaque children near its edges.

import { solidSurface } from "@/registry/default/lib/elevated";
 
function Card({ children }) {
  return <div className={solidSurface(3)}>{children}</div>;
}

elevatedSurface(level, shadowLevel?)

Same look as solidSurface, but it paints the rim on an ::after layer above the content instead of in the box-shadow. Reach for it when sticky or opaque children sit near the edges: with solidSurface the rim lives in the box-shadow, so an opaque child at an edge renders on top and hides it. The two common cases are sticky group labels (Select, Combobox, Autocomplete) and opaque inset footers (Dialog, Sheet, Drawer, where a bg-muted footer would cover the bottom rim).

import { elevatedSurface } from "@/registry/default/lib/elevated";
 
function MenuWithStickyHeader({ children }) {
  return (
    <div className={`relative overflow-clip rounded-xl ${elevatedSurface(3)}`}>
      <div className="sticky top-0 bg-(--popup-surface)">Sticky header</div>
      {children}
    </div>
  );
}

The host must be positioned and have a border-radius so the rim clips correctly.

surfaceClasses(level, shadowLevel?)

The primitive the others build on: just bg-surface-N and the downward drop shadow, no rim. Reach for it directly when the surface defines its own edge some other way (a real CSS border, a single-edge rim).

import { surfaceClasses } from "@/registry/default/lib/elevated";
 
function PlainSurface({ children }) {
  return <div className={surfaceClasses(3)}>{children}</div>;
}

flushSurface(level, innerEdge)

For viewport-flush containers: the default Sheet and Drawer variants that slide in pinned against a screen edge. Three of their four edges sit at the viewport boundary, so solidSurface's always-downward shadow and four-edge rim point the wrong way. flushSurface instead casts the drop shadow toward the inner, content-facing edge, and paints a single-edge rim on that same edge. Pass the content-facing edge directly, or derive it from the attach side with INNER_EDGE_FROM_ATTACH_SIDE (right → left, bottom → top, and so on).

import {
  flushSurface,
  INNER_EDGE_FROM_ATTACH_SIDE,
} from "@/registry/default/lib/elevated";
 
// Right-flush sheet: shadow and rim on the left (inner) edge.
function RightSheet({ children }) {
  return (
    <div className={`fixed inset-y-0 right-0 ${flushSurface(5, "left")}`}>
      {children}
    </div>
  );
}
 
// Or derive the edge from the attach side:
// flushSurface(5, INNER_EDGE_FROM_ATTACH_SIDE[side])

Customizing the system

Brand tint

Two variables at the top of :root tint every neutral in the system, so you can retune the whole thing from one place:

--neutral-hue: 275; /* hue angle 0–360. Cool purple-blue. */
--neutral-chroma: 0.004; /* tint strength for mid-tone neutrals */
--neutral-chroma-low: 0.002; /* tint strength near the lightness extremes */

Change --neutral-hue to rotate the entire palette without touching individual tokens:

• 0 to 90: warm (red, orange, amber, yellow). Try ~70 for amber.
• 90 to 180: green.
• 180 to 270: cool (cyan, blue). The primary lives at 250.
• 270 to 330: cool purple and violet. The neutral tint sits at 275.
• 330 to 360: pink and magenta, heading back toward warm.

--neutral-chroma around 0.005 to 0.01 is the visibility floor; we sit just under at 0.004 for a quieter feel.

Tracking the level from descendants

When you set level, the helpers expose --popup-surface on that element. Children can match the surface color without hardcoding a level:

// Arrow that matches whatever level the popup is at.
<svg className="fill-(--popup-surface,var(--popover))" />
 
// Sticky label inside a Select that blends with the popup.
<div className="sticky top-0 bg-(--popup-surface)">Group label</div>

The var(--popover) fallback keeps things working if the variable is not set in some context.

Design decisions

Surfaces is inspired by fluidfunctionalism.com/elevated, adapted to a prop-based API instead of a context, with a few deliberate divergences from a strict "tint everything on the ladder" reading.

Token reference

Every token lives on :root and is exposed as a Tailwind utility through @theme inline. Tune any of them in your globals.css to customize the system without touching the components.

/* Substrate */
--surface-1 .. --surface-8       /* surface colors */
--surface-shadow-1 .. -8         /* drop-shadow recipes → shadow-surface-N */
--surface-rim-1 .. -8            /* inset rim recipes → shadow-surface-rim-N */
 
/* State */
--surface-hover                  /* +6% perceived brightness overlay */
--surface-selected               /* +10% perceived brightness overlay */
--input                          /* opaque form-field bg = surface-3 */
--input-elevated                 /* stronger overlay for elevated fields and Switch */
--surface-rim-color              /* single-edge rim color (flush sheets) */
--popup-surface                  /* set by the helpers, read by descendants */
 
/* Tint controls */
--neutral-hue                    /* one knob: rotates the whole tint */
--neutral-chroma                 /* tint strength for mid-tone neutrals */
--neutral-chroma-low             /* tint strength near the gamut extremes */
 
/* Aliases */
--background  →  var(--surface-1)
--card        →  var(--surface-3)
--popover     →  var(--surface-3)
--sidebar     →  var(--surface-1)