Elevation

Elevation

Elevation creates visual hierarchy through shadow and depth. Standard uses a four-level elevation system built from multi-layer composite shadows — a key light (sharp, directional) paired with an ambient fill (soft, diffused). This dual-layer approach produces more natural, realistic depth than single-layer shadows.

Every shadow in the system adapts automatically to dark mode, where opacities increase to remain visible against dark surfaces.

Elevation Scale

Small
--sh-s
Ground level — subtle lift
Medium
--sh-m
Raised surface — cards, panels
Large
--sh-l
Overlay — dropdowns, menus, toasts
Extra Large
--sh-xl
Modal — dialogs, drawers, nav

Token Reference

Token Light Mode Dark Mode Use Case
--sh-s 0 1px 2px / .06, 0 1px 3px / .04 0 1px 2px / .24, 0 2px 6px / .16 Switch knobs, sliders, preview blocks
--sh-m 0 2px 4px / .04, 0 4px 16px / .06 0 2px 4px / .20, 0 4px 16px / .24 Elevated cards, hover states
--sh-l 0 4px 8px / .04, 0 12px 40px / .08 0 4px 8px / .24, 0 12px 40px / .32 Dropdowns, menus, tooltips, toasts
--sh-xl 0 8px 16px / .06, 0 24px 64px / .12 0 8px 16px / .28, 0 24px 64px / .40 Modals, drawers, floating nav
--sh-ring 0 0 0 3px var(--accent-s) Same (accent adapts) Focus rings on inputs, search bars

Multi-Layer Anatomy

Each elevation level is composed of two shadow layers:

Key Light
Sharp, directional
Small blur, higher opacity
+
Ambient Fill
Soft, diffused
Large blur, lower opacity
=
Composite
Natural depth
Realistic, layered

Elevation Hierarchy

Components map to elevation levels based on their relationship to the page surface:

Level Components Behavior
Ground (--sh-s) Switch knobs, slider thumbs, preview blocks Resting on the surface
Raised (--sh-m) Elevated cards, interactive card hover Lifted above the surface
Overlay (--sh-l) Dropdown menus, context menus, tooltips, toasts, search results Floating above content
Modal (--sh-xl) Modal dialogs, drawers, floating navigation Blocking layer above everything

Border Ring Pattern

Overlay and modal-level elements use an additional 0 0 0 1px inset ring shadow to define their edge against complex backgrounds:

/* Overlay with border ring */
box-shadow: var(--sh-xl), 0 0 0 1px oklch(0% 0 0 / .06);

/* Dark mode — white ring for edge definition */
box-shadow: var(--sh-xl), 0 0 0 1px oklch(100% 0 0 / .04);

Focus Rings

Interactive elements use --sh-ring for consistent focus indication:

.Input:focus {
  border-color: var(--accent);
  box-shadow: var(--sh-ring);
}

The ring uses --accent-s (accent at reduced opacity) and adapts to dark mode automatically.

Dark Mode Behavior

Shadows intensify in dark mode because low-lightness backgrounds absorb subtle shadows. The system handles this automatically — shadow tokens override their opacities in [data-theme="dark"] and prefers-color-scheme: dark contexts.

Light mode: Opacities range from .04 to .12 — barely-there whispers of depth. Dark mode: Opacities range from .16 to .40 — assertive enough to read against dark surfaces.

This isn’t a multiplier — each level is tuned independently for its context.

Usage Guidelines

Do

  • Use --sh-s for small, grounded elements (knobs, thumbs, inline cards)
  • Use --sh-m for elevated surfaces and hover states
  • Use --sh-l for overlays that sit above page content
  • Use --sh-xl for modal-level UI that demands attention
  • Add border rings to overlays on complex backgrounds
  • Transition shadows smoothly: transition: box-shadow var(--dur-n) var(--ease)

Don’t

  • Don’t use raw box-shadow values — always reference tokens
  • Don’t skip elevation levels (e.g., ground → modal with nothing between)
  • Don’t combine multiple elevation tokens on one element
  • Don’t use elevation shadows for decorative glow effects (those are intentional, separate patterns)