Shadow Tokens

Overview

Shadow tokens define consistent shadow effects used throughout the design system to create depth, establish visual hierarchy, and indicate elevation. They simulate light and shadow to make interfaces feel more tactile and three-dimensional.

Architecture

Shadow tokens are defined in the App group and use an elevation-based system where different shadow intensities indicate varying levels of depth.

How it works:

The system provides progressive elevation:

1. Contextual shadows (shadow.context.*) define semantic shadow styles (none, small, medium, large, inset)
2. Elevation shadows (shadow.elevation.*) create a systematic depth scale
3. Component shadows (shadow.[component].*) assign specific shadows to UI elements
4. State shadows indicate interactivity through shadow changes

Benefits:

• Consistent depth perception across all components
• Clear visual hierarchy through systematic elevation
• Semantic naming clarifies shadow intent
• Easy to adjust shadow intensity globally

Organization

Shadow tokens are organized into three categories:

Contextual Shadows: Semantic shadow styles (none, small, medium, large, inset, state-based).

Elevation Shadows: Systematic depth scale from 10 (minimal) to 40 (maximum).

Component Shadows: Specific shadow effects for individual UI components.

This organization provides both systematic depth and component-specific application.

Contextual Shadows

Contextual shadow tokens provide semantic shadow effects for flexible application.

Basic Shadows

State Shadows

Shadow effects for interactive states:

Shadow Composition

Most shadows use multiple layers to create realistic depth:

{
  "shadow.context.medium": [
    {
      "x": "0",
      "y": "0",
      "blur": "1px",
      "spread": "0",
      "color": "{color.shadow.default}"
    },
    {
      "x": "0",
      "y": "1px",
      "blur": "8px",
      "spread": "2px",
      "color": "{color.shadow.default}"
    }
  ]
}

Layered shadows create more natural, realistic depth than single shadows.

Elevation System

The elevation system provides a systematic depth scale with numbered levels (05-95) across multiple context colors.

Default Context Elevations

Context Color Elevations

Elevation shadows are also available for each context color, following the same level structure:

Where [level] can be: 05, 10, 20, 30, 40, 50, 60, 70, 80, 90, or 95

Elevation Hierarchy

Levels 05-10 (Minimal elevation):

• Extremely subtle depth
• Pressed button states
• Slightly raised cards
• Minimal visual separation

Levels 20-30 (Light elevation):

• Hover states for interactive elements
• Standard cards and panels
• Dropdown triggers on hover
• Active/selected states

Levels 40-50 (Medium elevation):

• Modal dialogs
• Dropdown menus and popovers
• Floating action buttons
• Prominent cards

Levels 60-70 (High elevation):

• Important overlays
• Critical notifications
• Toast notifications
• Top navigation bars

Levels 80-95 (Maximum elevation):

• Highest priority content
• Context menus
• Tooltips over modals
• Exceptional cases requiring maximum depth

Component Shadows

Component-specific shadow tokens assign depth to individual UI elements.

Buttons

Cards & Containers

Dropdowns & Popovers

Navigation

Form Inputs

Tables

Interactive Shadow Patterns

Shadows often change based on interaction state to provide depth feedback.

Standard Elevation Pattern

Floating Element Pattern

Elements that appear above the page:

Usage Guidelines

Choosing the Right Shadow

For flat elements: Use shadow.context.none

For subtle depth: Use shadow.context.small or shadow.elevation.default.10

For standard elevation: Use shadow.elevation.default.20 or shadow.context.medium

For floating elements: Use shadow.elevation.default.40 or shadow.context.large

For pressed states: Use shadow.context.inset or shadow.elevation.default.10

Design Principles

Hierarchy: Higher elevation = more important or interactive

Consistency: Use the same elevation for similar component types

Restraint: Avoid excessive shadows that create visual noise

Direction: Shadows typically cast downward (positive Y offset)

Accessibility

Don't rely on shadows alone: Combine shadows with color, border, or other visual cues

Focus indicators: Use colored shadows for keyboard focus states

Contrast: Ensure shadow colors have sufficient contrast in both light and dark modes

Motion sensitivity: Avoid animating shadows for users with motion sensitivity

Performance

Shadow complexity: Multiple shadow layers can impact rendering performance

Blur radius: Large blur radii are more computationally expensive

Animation: Animating shadows can cause repaints—use transform instead when possible

Mobile devices: Test shadow performance on lower-end devices

Best Practices

Do:

• Use component tokens for specific UI elements
• Use elevation system for systematic depth
• Test shadows in both light and dark modes
• Combine shadows with other visual cues
• Keep blur radius reasonable (< 24px for most cases)

Don't:

• Use arbitrary shadow values—always reference tokens
• Create "floating" interfaces with too many elevated elements
• Use shadows on every element—reserve for emphasis
• Animate shadows when transform would work better
• Forget that shadows affect visual weight

Dark Mode Considerations

Shadows work differently in dark mode:

• Shadow colors should be darker and may need different opacity
• Elevation is less pronounced in dark interfaces
• Consider using borders in addition to shadows in dark mode
• Test shadow visibility against dark backgrounds

Common Patterns

Cards: Use shadow.elevation.default.20 for subtle lift

Dropdowns: Use shadow.elevation.default.40 for clear separation

Hover effects: Transition from no shadow to shadow.elevation.default.20

Pressed buttons: Transition to shadow.elevation.default.10 or shadow.context.inset

Focus indicators: Use colored shadow.context.focus for accessibility