# UDS Elevation

## When to use elevation

- Any surface that overlaps or sits on top of another MUST use the `elevation` prop on `<Box>`, `<VStack>`, or `<HStack>`
- This includes cards, modals, popovers, dropdowns, drawers, toasts, sheets, and floating elements

## The elevation scale

- `elevation="0"` — Background or flat surfaces
- `elevation="1"` — Cards, list items, secondary surfaces
- `elevation="2"` — Floating elements like popovers, dropdowns
- `elevation="3"` — Modals, sheets, key actions
- `elevation="4"` — Drawers or toasts
- `elevation="5"` — System overlays

## Always use the shorthand prop

- The `elevation` prop is a shorthand that sets `backgroundColor`, `borderColor`, `borderWidth`, and `dropShadow` together in one prop
- Never use `dropShadow` alone for layered surfaces — it only adds a shadow and misses the required `backgroundColor`, `borderColor`, and `borderWidth` changes
- Never use individual elevation token props (`backgroundColor="elevation-X"`, `borderColor="elevation-X"`, `borderWidth="elevation-X"`, `dropShadow="elevation-X"`) — always use the shorthand `elevation` prop instead
- Individual props override the shorthand if needed: `<Box elevation="2" backgroundColor="primary" />`

## Examples

- Wrong: `<Box dropShadow="md" backgroundColor="primary" borderRadius="lg">` (incomplete elevation)
- Wrong: `<Box backgroundColor="elevation-2" borderColor="elevation-2" borderWidth="elevation-2" dropShadow="elevation-2">` (verbose, use shorthand)
- Correct: `<Box elevation="1" borderRadius="lg">` (single prop sets all 4 properties)
- Correct: `<VStack elevation="2" gap="4" alignItems="stretch" justifyContent="flex-start">Popover content</VStack>`

## More information

- Use `get_documentation` MCP tool with path "core-concepts/elevation" for detailed guidance on applying elevation
