Elevation

Layers

The UI is built from three surface layers that create depth through subtle lightness differences. In light mode, each layer gets progressively lighter as it rises toward the viewer. In dark mode, the same — each layer lightens away from pure black, matching how physical objects catch more light as they come closer.

Background

The most recessed layer. This is the page canvas behind everything else.

Surface

Cards, panels, sidebars, and other contained regions sit on top of the background. Applies a default shadow and inset highlight to reinforce the lift.

Elevated

Popovers, modals, dropdown menus, and other floating elements. Uses reduced opacity and backdrop-blur for a frosted glass effect.

Shadow & highlight scale

Shadows are pure depth: progressively softer ambient layers with no built-in outline. Every level is paired with an inset highlight of the same scale, simulating a top-lit edge. Both surface and elevated accept any shadow level as an override.

Each level also carries a dormant 1px contact ring at the silhouette, enabled by the edge-contact utility — see Edges below. surface and elevated enable it by default, so the examples here show the ring; a bare shadow-* on its own does not draw one.

Shadow specification

Highlight specification

Dark mode

Shadows are less visible against dark backgrounds. The system compensates with a higher shadow intensity multiplier in dark mode, scaling each layer's opacity. Combined with surface lightening and inset highlights, this maintains a clear sense of depth across both modes.

Edges

Edges come in named roles, each a utility:

• edge-contact — the contact line: a 1px dark ring of shade at the silhouette, grounding the element against the page. It renders as the leading layer of whichever shadow-* level the element carries, at that level's strength, and draws nothing without a shadow. Opt-in by design: chrome that draws its own definition line (inputs, buttons) skips it so the two lines never double up.
• edge-rim — the rim light, described below.
• edge-control — the indicator seat, described below.

Raised chrome carries a 1px inner hairline of highlight on all four edges — the rim light. surface and elevated include it automatically; the standalone edge-rim utility applies the same hairline to chrome that has its own background and shadow recipe. The hairline paints above the element's content, so full-bleed imagery inside a card cannot cover it.

Elements that attach to a surface's edge (such as popover arrows) use the surface-edge-attach utility to paint above the hairline, letting their fill obscure it where they join.

Filled indicator surfaces — switches, checkboxes, slider fills, date badges, avatars — carry a 1px inner hairline of indicator-highlight via the edge-control utility, seating the fill crisply against any backdrop without a mode split.

Edges over imagery

Semantic edge tokens tint with the surrounding colour context, which is wrong for content sitting on photography or wallpaper washes. Two fixed tokens cover those cases: frame is a dark hairline in light mode that flips to a light one in dark mode, for framing avatars, flags and imagery panels. frame-highlight stays white in both modes, for window chrome and glass edges that should read as catching light regardless of mode.

Semantic colors