Surfaces

Context-aware elevation system for consistent depth and hierarchy.

Elemnts UI’s Surfaces use a smart elevation system to ensure your UI layers always look distinct and intentional. Instead of manually picking colors like bg-card or bg-modal, Elemnts automatically adjusts backgrounds and shadows based on where a component sits in your layout.

This solves the annoying problem of elevation collapse—where nested elements blend into their containers and disappear visually.

How It Works

Relative Elevation (Deltas)

No fixed levels like "Level 3" or "Level 5". With Elemnts, you define how much higher a component should sit relative to its parent using a delta value.

Term	Definition
Substrate	The current background level (1–8), establishing the base for elevation.
Delta	The relative lift applied to a component above its parent (e.g., `delta={1}`).

For example:

Parent Level	Delta	Resulting Level
1 (Page)	1	2
5 (Dialog)	1	6

This keeps your UI consistent, no matter how deeply nested it is.

The Eight Levels

Elemnts uses eight elevation levels, each with its own background and shadow:

Level	Purpose	Shadow Intensity
1	Base page (background)	None
2–8	Cards, modals, tooltips, etc.	Increases

In Dark Mode, higher levels subtly lighten their backgrounds using color-mix with white. This mimics how light behaves in real life, making depth visible even in pure black environments where traditional shadows fail.

Key Components

Elevated

The building block of the system. Wrap any component to lift it relative to its parent.

import { Elevated, Text } from "@elemnts-ui/react";

<Elevated delta={1}>
  <Text>I’m one level higher than my parent!</Text>
</Elevated>

Surface

A ready-to-use panel or card with built-in slots for headers, content, and footers. By default, it includes a border and shadow, but you can disable this for a flat look while still maintaining the elevation context.

import { Surface, Text } from "@elemnts-ui/react";

<Surface delta={1} p="6">
  <Surface.Header>
    <Surface.Title>Card Title</Surface.Title>
  </Surface.Header>
  <Surface.Content>
    <Text>Main content goes here.</Text>
  </Surface.Content>
</Surface>

Behind the Scenes

Elemnts’s system relies on CSS variables and data attributes to handle styling:

data-elevation: The absolute level (parent level + delta).
data-elevation-shadow: The level used for shadows (usually matches data-elevation).
--elevation: A CSS variable storing the current level.

Dark Mode Magic

In dark mode, Elemnts doesn’t just add shadows—it simulates light by lightening backgrounds as levels increase:

/* Simplified Dark Mode Logic */
surface-1: neutral.100;
surface-2: color-mix(in oklab, neutral.100, 4% white);
surface-3: color-mix(in oklab, neutral.100, 8% white);

This ensures depth is always visible, even in the darkest themes.

Try It Out

See how elevation works in a deeply nested hierarchy—each layer stays distinct without extra configuration.

<Elevated delta={0}>
  <Elevated delta={1}>
    <Elevated delta={1}>
      <Elevated delta={1}>
        {/* Each layer lifts relative to the one before it */}
      </Elevated>
    </Elevated>
  </Elevated>
</Elevated>