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.
noneLevel 1
Cards at rest — subtle lift to separate from the background.
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.
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.
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.
0px 16px 32px 0px var(--ux4g-elevation-color-6), 0px 8px 16px 0px var(--ux4g-elevation-color-4)Depth & layering rules
Each UI layer has a defined purpose and stacking order. Never skip layers.
Z-index scale
A fixed scale prevents z-index wars. These numbers represent z-index token values that define the stacking order of UI elements, where higher values are rendered above lower values. Always use tokens instead of arbitrary values.
dropdown
Dropdown menus, select panels
sticky
Sticky headers, fixed navbars
fixed
Fixed positioning elements
offcanvas
Offcanvas menus
modal-backdrop
Modal backdrops
modal
Modal dialogs, lightboxes
popover
Popovers
tooltip
Tooltips
toast
Toast notifications
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 border-border 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;