Elevation

Surface hierarchy #

Elevation indicates that an object sits above another surface. Keep ordinary reading content flat. Use a restrained shadow when a popover, menu or dialog needs separation; pair it with a clear surface and boundary. A stronger shadow does not make an action more important.

Level, appearance and paint order #

Keep three decisions separate: a semantic elevation describes a surface relationship; a color, edge or shadow depicts it; CSS stacking determines which pixels are painted in front. None of those decisions grants keyboard focus, blocks background interaction or establishes modal behavior.

Material uses six relative levels. Their reference distances are density-independent platform units, not CSS z-index values or blur radii. MobTranslate exports shadow and layer tokens, not Material elevation-level tokens or a dp conversion. Do not rename --shadow-md to level 2 and assume equivalence.

Tonal surfaces and visible edges #

Use surface fill, an edge and relative placement to communicate grouping without covering every panel in shadows. Surface color roles are a separate choice from elevation levels: a surface-container role does not automatically assign a physical height. Keep text paired with the foreground for its selected surface.

For this library, card/card-foreground and popover/popover-foreground are explicit foreground pairs. Muted/muted-foreground provides supporting treatment; placing an essential long passage there still requires readable text and hierarchy. The lab lets you compare those real pairs against the page background with or without shadow. It does not certify arbitrary combinations.

When a visible boundary is necessary to identify a control, verify the actual boundary against adjacent colors and the applicable non-text contrast requirement. A subtle shadow or different fill alone is not proof. Retain labels, focus indicators and grouping when shadows disappear in forced-colors mode.

Resting elevation and interaction changes #

Start with the component's existing resting appearance. An overlay should have an intentional relationship to its trigger and underlying content; a selected row can remain flat and use a separate selection indicator. Do not raise every selected element or make a larger shadow the only evidence of selection.

Choose hover, focus, pressed and dragged treatments deliberately and consistently within a family. Pointer hover does not replace keyboard focus, and touch has no persistent hover contract. A lifted draggable item must keep its name, position information, drop/cancel behavior and keyboard alternative. Restore resting appearance when the interaction ends.

Material describes interaction-driven elevation changes, often one relative level. Existing MobTranslate components use their own state styles; this guide does not silently install Material hover levels. If a product introduces a lift, document its shadow/edge/fill change, reduced-motion behavior, clipping bounds and tests together. Never defer the underlying action until an animation ends.

Protection, overlap and scrims #

A floating surface over a busy image may need a stronger edge, opaque fill or restrained shadow. Check the actual content under the surface, including scrolling and translated text. Do not solve poor text contrast by adding a distant shadow around the panel.

A scrim sits beneath a temporary foreground surface and changes the apparent background. Material's reference scrim opacity is 32%; that is not this library's modal token contract. Use the current Dialog or Drawer implementation and verify its actual background, nested layers and focus policy before changing opacity.

Visual dimming does not make background content inert or create a modal dialog. Pair the scrim with the component's focus containment, accessible name, deliberate dismissal, background interaction policy and focus return. Nonmodal popovers should not inherit modal behavior merely because they have a shadow.

Actual shadow specifications #

Light shadows use warm tinted ink. Dark overrides are stronger black shadows. The CSS catalogue is authoritative; a shadow must be judged on its actual background. There is no --shadow-none token: use box-shadow: none for a flat surface.

Live surface lab #

Layer order and portals #

Shadow controls appearance; z-index controls stacking inside a stacking context. Transforms, opacity and isolation can create new contexts. A large z-index on a child cannot escape a lower ancestor context.

• Use the library portal behavior for overlays rather than stacking a popup inside an overflow-hidden card.
• A locally themed trigger does not automatically theme a popup portalled elsewhere. Place theme scope where both can inherit it.
• Respect top-layer behavior for native dialog and popover elements. Their order is not governed solely by ordinary z-index.

Implementation #

.floating-surface {
  background: var(--color-popover);
  color: var(--color-popover-foreground);
  border: 1px solid var(--color-border);
  box-shadow: var(--shadow-lg);
  border-radius: var(--radius-lg);
}
@media (forced-colors: active) {
  .floating-surface { box-shadow: none; border-color: CanvasText; }
}

Failure cases #

• Avoid stacking several shadows around nested cards; use grouping and dividers instead.
• Do not use shadow alone to identify an input or button boundary.
• Do not assign toast or tooltip layers to every popup. Layer tokens express responsibilities.
• A visually elevated dialog still needs a name, dismissal policy, focus management and background interaction control.

Verification #

• Compare the live surface in light, dark and forced-colors modes.
• Open overlays inside scrolling containers and verify they are neither clipped nor detached from their trigger.
• Open nested overlays and check keyboard focus, dismissal and layer order.
• Scroll sticky regions while tabbing; focused controls must remain visible rather than hidden below a header.

Related guidance #