Elevation

Elevation is shadow depth, not paint order. A raised surface casts a larger, softer shadow. ViraUI maps that to a stepped scale you apply with Elevator (or data-elevation*).

z-index is a different contract: who paints on top of whom. The same layer numbers usually line up so something that looks elevated also stacks where you expect, but Elevator never sets z-index. Raising a card's shadow does not move it above a sticky header.

Shadows respect the --effect-shadows gate on your theme: empty or unset means on, initial means off. When the gate is off, elevated surfaces stay flat even if attrs remain. For overlay direction, focus, and portals when you compose modals and popovers, see Base UI.

Shadow and stack share one vocabularyCopy Anchor Link

Use the same stepped numbers for shadow and stacking so depth stays consistent across the product. Treat them as one vocabulary with two controls: elevate for appearance, stack for paint order.

Stay within the built-in scale unless you have an extreme exception. Theme chrome may use very high values on body::after; app UI should not copy that pattern to beat modals.

• Plane content (page backgrounds, cards, flat controls) usually sits at the low end
• Anchored overlays step up above nearby page content
• Fixed chrome belongs above the page but below blocking modals
• Modals, drawers, and global toasts sit at the top of app UI

Match stack placement to how the surface should read. A popover that looks elevated but paints under its trigger is a stack problem, not an Elevator problem.

Applying shadowsCopy Anchor Link

Elevation APIs control shadows only. Most surfaces do not ship with an elevation prop. Wrap a valid element child with Elevator, or call getElevationProps on a host you already own. Reach for raw data-elevation* only when those utilities do not fit. Set z-index separately when paint order must change.

Give this card a subtle shadow that lifts a bit more on hover. Shadows only — don't change stacking order.

TuneCopy Anchor Link

Elevation compose stays on Elevator and stack z-index. What you retune on the theme is whether shadows can run at all, via the --effect-shadows gate (and related shadow tokens when the brand softens or hardens depth).

App Studio in ViraUI Pro is the easiest path: flip that gate and preview depth on a live ViraUI canvas, share the theme with the team, and export CSS that already matches the contract. Drop the export into the app as a custom theme.

Without Studio, paste a prompt into your agent or edit --effect-shadows on a custom theme sheet (or switch a built-in preset). Full gate polarity lives under Effects.

Turn off drop shadows on the theme so elevated surfaces stay flat. Keep stacking order as it is — this is appearance only.