Elevation & Depth

No dedicated token map#

Unlike colors, typography, spacing, and rounded, the @google/design.md 0.3.0 spec does not define an elevation or shadows key in the YAML frontmatter schema. A top-level key named elevation or shadows would be treated as an unknown key by the parser.

The engine classifies the Markdown section heading ## Elevation & Depth (or the alias ## Elevation) as section kind elevation and preserves the prose. The content is available to agents reading the document but does not produce structured tokens in the parsed design system model.

If your design uses shadow values on components, include those as literal Dimension or Color values on the component itself, or describe them in the prose body of this section.

What to put in the prose#

The Elevation & Depth section should answer: how does this design convey visual hierarchy? There are three common strategies:

1. Drop shadows: blur, spread, offset, and color values described in prose so agents know to apply box-shadow.
2. Tonal elevation: elevation expressed through color stops on a surface color (common in Material Design). No explicit shadow CSS; instead, higher-elevation surfaces use a lighter tint of the background.
3. Flat (no elevation): the design uses only borders, background contrast, or white space to separate layers. Agents should not add drop shadows to components.

Being explicit helps agents avoid adding unwanted shadows or missing necessary ones.

Accepted heading aliases#

The engine accepts these headings and maps them all to the elevation section kind:

• ## Elevation & Depth (canonical)
• ## Elevation

German equivalents: ## Tiefe, ## Schatten

Example: drop-shadow design#

---
name: Lifted UI
---

## Elevation & Depth

Visual depth is created through **layered drop shadows**, not tonal shifts.
Three levels of elevation are used:

- **Level 0 (resting):** No shadow. Background surface at `#F5F5F5`.
- **Level 1 (cards, panels):** `box-shadow: 0 1px 3px rgba(0,0,0,0.10), 0 1px 2px rgba(0,0,0,0.06);`
- **Level 2 (modals, drawers):** `box-shadow: 0 10px 25px rgba(0,0,0,0.15), 0 4px 10px rgba(0,0,0,0.08);`

Do not add shadows beyond Level 2. Interactive hover states may shift
from Level 1 to Level 2 as a depth cue.

Example: tonal elevation design#

---
name: Tonal Layers
colors:
  surface-0: "#F2F0ED"
  surface-1: "#FFFFFF"
  surface-2: "#F9F8F6"
---

## Elevation & Depth

Depth is conveyed through **tonal surface shifts**, not shadows.

- **Surface 0** (`#F2F0ED`): Page background. No elevation.
- **Surface 1** (`#FFFFFF`): Cards and primary panels. +1 elevation.
- **Surface 2** (`#F9F8F6`): Modals and overlays. +2 elevation.

No drop shadows are used. Borders (`1px solid rgba(0,0,0,0.08)`) separate
adjacent surfaces at the same level.

Example: flat design#

## Elevation & Depth

This design is intentionally **flat**: no drop shadows are used anywhere.
Visual hierarchy is achieved through:

- Font weight contrast (bold headlines vs. regular body).
- Background color contrast between sections.
- 1px divider lines between panels.

Agents must not add `box-shadow` or `filter: drop-shadow` to any element.

Try it in the tool