Foundations

Elevation & Shadows

The elevation scale ranges from Level 0 (base) to Level 4, representing five distinct elevation levels. Each level pairs a key and ambient shadow to communicate depth, hierarchy, and interactivity across government service interfaces, from cards at rest to focused modals.

Elevation levels

Five levels provide progressive depth. Each level composes a key shadow with an ambient shadow, and maps to a specific UI context. Values match the Figma shadow tokens exactly.

Level 0

Flat, flush surfaces — content on the page plane, disabled states.

none

Level 1

Cards at rest — subtle lift to separate from the background.

Key: Y: 1, Blur: 2

Ambient: Y: 1, Blur: 2

0px 1px 2px 0px var(--ux4g-elevation-color-1), 0px 1px 2px 0px var(--ux4g-elevation-color-1)

Level 2

Raised cards and dropdowns — hover states and select panels.

Key: Y: 4, Blur: 8

Ambient: Y: 1, Blur: 2

0px 4px 8px 0px var(--ux4g-elevation-color-2), 0px 1px 2px 0px var(--ux4g-elevation-color-1)

Level 3

Popovers and menus — content that floats above the surface.

Key: Y: 8, Blur: 16

Ambient: Y: 4, Blur: 8

0px 8px 16px 0px var(--ux4g-elevation-color-4), 0px 4px 8px 0px var(--ux4g-elevation-color-2)

Level 4

Modals and dialogs — the highest, most focused layer.

Key: Y: 16, Blur: 32

Ambient: Y: 8, Blur: 16

0px 16px 32px 0px var(--ux4g-elevation-color-6), 0px 8px 16px 0px var(--ux4g-elevation-color-4)

Z-Index Scale

A structured 3-tier z-index scale covering base layout stacking, global numeric layers (10–50), and component-specific aliases.

Base Layout Stacking

Surface and layout context layer tokens for structural element stacking.

--ux4g-z-layout-base

Base surface flow (0)

--ux4g-z-layout-raised

Slightly lifted card / header (1)

--ux4g-z-layout-overlay

Low-level overlay (2)

--ux4g-z-layout-top

High-priority layout element (3)

Extended Numeric Scale

Global layer scale spanning sticky elements, navigation, overlays, and floating UI.

--ux4g-z-10

Sticky bars, sub-navs

--ux4g-z-20

Dropdowns, selects, popovers

--ux4g-z-30

Drawers, side-sheets

--ux4g-z-40

Modals, backdrops

--ux4g-z-50

Tooltips, toasts, snackbars

Component Specific Aliases

Semantic component aliases mapped directly to standard component roles.

--ux4g-z-dropdown

Dropdown menus & autocomplete

--ux4g-z-tooltip

Top-level hover tooltips

Usage guidelines

Elevation communicates interactivity and importance. Use it intentionally.

Dos

• Use Level 1 for resting cards to separate them from the background
• Raise to Level 2 on hover/focus for interactive elements
• Reserve Level 3 and Level 4 for popovers, menus, and modals
• Pair elevation with a border for low-contrast themes

Don'ts

• Don't apply Level 4 to inline or resting elements
• Don't stack multiple elevated elements at the same z-level
• Don't use elevation as the only visual differentiator
• Don't use arbitrary z-index values outside the scale

Dark mode adjustments

Shadows are less visible on dark backgrounds. In dark mode the Figma tokens switch to light-tinted key and ambient shadows; pair them with subtle borders for edge definition.

/* Dark mode: key + ambient shadows use light tints */

--ux4g-shadow-l1: 0px 1px 2px 0px rgba(255,255,255,0.08), 0px 1px 2px 0px rgba(255,255,255,0.04);

--ux4g-shadow-l2: 0px 4px 8px 0px rgba(255,255,255,0.12), 0px 1px 2px 0px rgba(255,255,255,0.08);

/* Pair with ux4g-border-neutral-subtle for edge definition */

Code usage

Apply elevation via CSS custom properties or the equivalent utility classes.

Elevation levels

Level 0 → flat / flush

Level 1 → cards at rest

Level 2 → raised cards, dropdowns

Level 3 → popovers, menus

Level 4 → modals, dialogs

CSS custom properties

var(--ux4g-shadow-l1)

var(--ux4g-shadow-l2)

var(--ux4g-shadow-l3)

var(--ux4g-shadow-l4)

var(--ux4g-z-modal): 1060;

← Spacing & Layout Iconography →