Elevation Token Systems

Elevation token systems establish consistent depth representation through shadow values and layering indices. Elevation communicates hierarchy, helps users understand interface structure, and provides visual cues about interactive elements. Without systematic elevation tokens, shadow usage becomes inconsistent and layering conflicts emerge as interfaces grow.

What Are Elevation Token Systems

Elevation token systems are collections of tokens that define how elements appear at different visual depths. This typically includes shadow tokens that create the appearance of depth and z-index tokens that control actual stacking order.

Shadow tokens define the visual representation of elevation through offset, blur, spread, and color values. Z-index tokens define the numeric stacking order for positioned elements. Together, these tokens create a coherent elevation model.

How Elevation Token Systems Work

Shadow token scales typically progress from subtle to prominent:

{
  "elevation": {
    "shadow": {
      "none": { "value": "none" },
      "sm": { "value": "0 1px 2px 0 rgba(0, 0, 0, 0.05)" },
      "md": { "value": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)" },
      "lg": { "value": "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)" },
      "xl": { "value": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)" }
    }
  }
}

Multiple shadow layers (as in md, lg, xl above) create more realistic depth by combining a larger diffuse shadow with a tighter contact shadow.

Z-index tokens establish a scale for stacking contexts:

{
  "elevation": {
    "zIndex": {
      "base": { "value": "0" },
      "dropdown": { "value": "1000" },
      "sticky": { "value": "1100" },
      "fixed": { "value": "1200" },
      "modalBackdrop": { "value": "1300" },
      "modal": { "value": "1400" },
      "popover": { "value": "1500" },
      "tooltip": { "value": "1600" }
    }
  }
}

Semantic elevation tokens can combine shadow and z-index:

{
  "elevation": {
    "raised": {
      "shadow": { "value": "{elevation.shadow.md}" },
      "zIndex": { "value": "{elevation.zIndex.base}" }
    },
    "overlay": {
      "shadow": { "value": "{elevation.shadow.xl}" },
      "zIndex": { "value": "{elevation.zIndex.modal}" }
    }
  }
}

Key Considerations

• Shadow intensity should match the elevation level semantically
• Z-index values need gaps for insertion without restructuring
• Dark mode requires different shadow approaches
• Performance can suffer with complex shadow stacks
• Mobile platforms may use different elevation models
• Accessibility should not rely solely on shadow to convey information
• Print styles may need shadow removal
• Shadow tokens should consider the shadow color’s relationship to backgrounds

Common Questions

How should dark mode elevation differ?

Shadows become nearly invisible against dark backgrounds, requiring alternative dark mode elevation strategies.

Surface lightening uses progressively lighter surface colors for higher elevations. Material Design popularized this approach:

{
  "elevation": {
    "surface": {
      "base": {
        "light": { "value": "#ffffff" },
        "dark": { "value": "#121212" }
      },
      "raised": {
        "light": { "value": "#ffffff" },
        "dark": { "value": "#1e1e1e" }
      },
      "overlay": {
        "light": { "value": "#ffffff" },
        "dark": { "value": "#2c2c2c" }
      }
    }
  }
}

In light mode, elevation comes from shadows with consistent surface colors. In dark mode, elevation comes from surface color variation with minimal or no shadows.

Subtle borders can reinforce elevation in dark mode:

.card {
  background: var(--elevation-surface-raised);
  box-shadow: var(--elevation-shadow-md);
  border: 1px solid var(--color-border-subtle);
}

The border provides edge definition when shadows are less visible.

Ambient glow uses light-colored shadows in dark mode for a different aesthetic:

{
  "elevation": {
    "shadow": {
      "md": {
        "light": { "value": "0 4px 6px rgba(0, 0, 0, 0.1)" },
        "dark": { "value": "0 4px 6px rgba(255, 255, 255, 0.05)" }
      }
    }
  }
}

This approach maintains shadow-based elevation while adapting for dark contexts.

How should z-index conflicts be prevented?

Z-index conflicts occur when elements compete for stacking position without a coordinated system. Token-based z-index management prevents most conflicts.

Centralized definition ensures all stacking levels are defined in one place with clear relationships. No component should invent z-index values.

Semantic naming clarifies intended use. A token named zIndex.modal clearly indicates its purpose, preventing misuse for other contexts.

Adequate gaps between values (typically 100) allow insertion of new levels without restructuring:

dropdown: 1000
  (room for 1001-1099)
sticky: 1100
  (room for 1101-1199)
fixed: 1200

Stacking context understanding is essential. CSS stacking contexts isolate z-index values, so a z-index of 9999 within a lower stacking context still appears behind a z-index of 1 in a higher context. Tokens alone cannot solve stacking context issues.

Documentation should explain both the token values and the stacking context model. Developers need to understand how stacking contexts interact with token values.

How do elevation tokens translate to mobile platforms?

iOS and Android have their own elevation conventions.

iOS traditionally uses subtle shadows and blurs. UIKit shadow properties and SwiftUI shadow modifiers can consume elevation tokens:

.shadow(
  color: Color.black.opacity(0.1),
  radius: Tokens.Elevation.shadowMdBlur,
  x: 0,
  y: Tokens.Elevation.shadowMdOffsetY
)

Android uses elevation as a first-class concept. Elevation values determine both shadow appearance and stacking:

Card(elevation = Tokens.Elevation.md.dp) {
  // content
}

Android’s elevation is a single dimension value, not a complex shadow specification. Token transforms must convert complex shadow definitions to single elevation values for Android.

Cross-platform consistency may mean accepting platform-native shadow rendering rather than pixel-perfect matching. Each platform’s graphics system renders shadows differently even with identical parameters.

Summary

Elevation token systems create consistent depth representation through shadow values and z-index scales. Shadow tokens progress from subtle to prominent with multi-layer definitions for realism. Z-index tokens establish coordinated stacking levels. Dark mode requires alternative approaches like surface lightening. Centralized z-index definition with adequate gaps prevents stacking conflicts. Cross-platform implementation adapts to each platform’s elevation model while maintaining conceptual consistency.