Elevation

Propel ships 7 shadows in three groups: raised for things that lift within the page, overlay for things that float above it, and direction for panels that cast sideways.

Each one is a two-layer shadow: a tight contact layer that grounds the edge, and a wide ambient layer that does the lifting.

<div class="rounded-lg bg-surface-1 shadow-overlay-100">…</div>

Shadow is the smaller half of the depth system. Only 13 component families cast one directly, alongside 4 shared internal surfaces; everything else separates itself with a 1px border and a step on the surface ladder. Reach for the ladder first, and add a shadow only when an element genuinely leaves the layout.

Raised

Overlay

Directional

What the reset removes

--shadow-*: initial clears Tailwind’s scale before Propel declares its own, so every utility below generates no CSS and fails silently. The bare shadow goes with them, since it read --shadow. There is no replacement: a shadow should come from the three groups above, chosen by what the element is rather than by how heavy it should look.

Three things survive. shadow-none is a static utility rather than a token, so it still cancels an inherited shadow. inset-shadow-* and drop-shadow-* are separate namespaces Propel never touches, so Tailwind’s defaults apply unchanged — they carry a generic pure-black tint rather than Propel’s slate ink, and will look subtly foreign beside the tokens above.

Guidelines

A shadow alone does not separate a floating layer from the page; it darkens the edge of something that still shows whatever is behind it. Pair every overlay with a real background, as bg-surface-1 shadow-overlay-100, and never ship the shadow on its own.

Shadows don’t compose. Two elevated surfaces nested inside each other produce overlapping ambient layers that read as a smudge rather than as two levels, so let the outer layer carry the shadow and give the inner one a border.

Elevation says an element sits on a layer above, not that it is interactive. Hover and pressed states belong to the surface and border tokens, and a control that lifts on hover is claiming to float, which almost nothing in Propel does.

Stacking order is a separate concern again. Propel declares no z-index tokens, and a deeper shadow does not put an element in front of anything.

Theme behavior

All seven shadows are declared once, outside every theme selector, so the same ink renders in light, dark, light-contrast, and dark-contrast.

They are tuned for a light canvas, using slate ink rgb(41 47 61) at 2–10% alpha, which is close to invisible against a dark background. That is not a bug to route around with a heavier shadow. In dark themes depth comes from the surface ladder and borders, and the shadow quietly stops contributing.

One shadow breaks the pattern: shadow-direction-right is tinted pure black rather than slate ink, the only one in the system that is. It reads as an inconsistency rather than a decision.