CEM D4 Layering — Signed Depth, Planes, and Appearance Shifts

Status: Canonical
Last updated: 2026-09-27 Taxonomy placement: D4. Layering (treats depth + elevation as one consumer concept)

CEM uses layering as the umbrella term for:

• Depth (signed): behind vs in front of the base plane (recess vs lift).
• Elevation (positive): steps above the base plane (raised, floating, overlay, command).
• Planes (rendering): global stacking rules for overlays/modals, independent of local nesting.

Companion specs:

• D0. Color (Emotional Palette) (cem-colors.md) — tonal "dig down" vs "lift up"
• D1. Space & Rhythm (cem-dimension.md) — breathing room coupling
• D3. Shape — Bend (cem-shape.md) — bend roles for overlays/modals
• D5. Stroke & Separation (cem-stroke.md) — contour reinforcement, especially in forced-colors
• D7. Time & Motion (cem-timing.md) — lift/drop transitions and reduced-motion behavior
• Action states (discussion #14) — visual priority order and interaction escalation semantics

Contents

1. What layering means to users
2. Consumer layering vocabulary
3. User-flow journey through layering
4. Design goals
5. Signed ladder and planes
6. Token model
7. Basis tokens and appearance-change principle
8. Semantic endpoints contract
9. Representation channels
10. Scrim
11. Action states and the color ladder
12. Cross-dimension coupling
13. Accessibility and forced-colors requirements
14. Component mapping matrix
15. Implementation guidance
16. Canonical token summary
17. Governance and versioning
18. Migration notes
19. References

1. What layering means to users

Layering communicates relationship and intent before interaction:

• Where am I? (shell vs work)
• What belongs together? (grouping vs separation)
• What can I act on? (affordance prominence)
• What requires my decision? (modal commitment)

In consumer language, layering typically reads as:

• Back layer: context and scaffolding (navigation, filters).
• Work layer: primary reading/doing.
• Interruption/command: transient overlays and modal decisions.

Layering exists to support three outcomes:

1. Orientation — know what is “infrastructure” vs “work.”
2. Separability — see boundaries without reading.
3. Commitment clarity — distinguish “context” from “decision.”

2. Consumer layering vocabulary

2.1 Common terms

• Layer / plane: a named region with stable intent (back, work, overlay).
• Stack / z-order: physical draw order.
• Recessed / inset: visually “dug down” behind the base.
• Raised / floating: visually “lifted” above the base.
• Overlay / popover: transient contextual layer above other content.
• Command / modal: must-respond decision layer.

2.2 Semantic tiers are not a z-index ladder

The tier number communicates priority and meaning (user psychology), not guaranteed draw order. Physical stacking may differ because of clipping, portals, and platform APIs. That physical mismatch does not change the semantic contract.

Normative rules

• MUST NOT use --cem-elevation-* as a z-index value.
• MUST NOT infer semantic tier from physical draw order.
• MUST preserve semantic meaning even when physical stacking differs.
• MUST treat Command as the owner of modality (scrim, focus trap, blocked interaction), even if an Overlay renders above it.
• MUST apply dismissal precedence: dismiss the topmost Overlay first, then the Command layer (if present).

Discriminator rules: Overlay vs Floating

Use these rules when physical appearance could be misread (notably when overlays appear over dialogs).

• Choose Overlay when the UI is a separate transient layer artifact with its own dismissal semantics (appears/disappears without becoming part of layout).
  Typical: menus, popovers, autocomplete lists, date pickers, tooltips.

• Choose Floating when the UI is the same object as in the work context, temporarily lifted for affordance while remaining part of the current task.
  Typical: hover lift, “picked-up” cards, dragged items.

Examples (required interpretation)

• Tooltip over a dialog: Tooltip remains Overlay (contextual helper). Physical topness does not outrank the dialog’s “must respond” semantics; it dismisses first.
• Dragging while a dialog is present: The dragged object remains Floating (same work object lifted). The drag ghost may portal above for clipping, but it MUST NOT be reclassified as Overlay.

2.3 7-tier canonical ladder

CEM defines exactly 7 canonical tiers. The ladder is signed: two recess rungs, one base rung, and four lift rungs.

The ladder is designed to be perceptually distinct and implementable across light/dark/contrast themes.

2.4 Terminology disclaimer

1. One consumer term: “layering” is the shared vocabulary for elevation and recess.
2. Signed meaning: both “dig down” and “lift up” are first-class.
3. Multiple channels: tone, contour, shadow, blur/material, space, and motion are coordinated.
4. Theme resilience: the ladder works in light/dark/forced-colors.
5. Avoid false importance: overlays can render above commands physically, but they must not steal semantic priority.

3. User-flow journey through layering

Layering is experienced as the user moves through a interaction flow.

3.1 Landing (orient)

• The user identifies Back vs Work immediately.
• Recess is used to make scaffolding feel “behind.”
• Back layer gives orientation without competing for attention.
• Base establishes the canvas and reading comfort.

[ Back layer ]   |  [ Work layer ]
(nav/context)    |  (primary content)

3.2 Scanning (compare)

• The user needs separability at speed.
• Work layer regions should be visually grouped (Raised).
• Recess reduces noise in scaffolding regions.

3.3 Interacting (act)

• Floating lift signals “this is the active object.”
• Focus/hover are reinforced without changing the underlying layer role.

3.4 Contextualizing (choose)

• Overlay provides contextual options near the trigger, above the work.
• Overlay must remain dismissible and non-modal.
• If an overlay blocks reading or causes ambiguity, it has become a Command.

3.5 Deciding (commit)

• Command is the highest semantic priority.
• Command forces a decision with scrim and focus trap.
• Any Overlay displayed above a Command remains subordinate and dismisses first.

4. Design goals

• Semantic clarity: layers communicate intent (shell vs work vs command).
• Minimal ladder: seven tiers only; no micro-tiers as defaults.
• Theme resilience: semantics stay constant across light/dark/contrast and density.
• Accessibility: layering must remain readable in forced-colors (contour substitutes for shadow/tone).
• Portability: the model maps to web, native, and component libraries.

5. Signed ladder and planes

Layering is a composition of:

• Semantic tier (the signed ladder rung)
• Plane (the global rendering order / portal)

5.1 Planes

CEM defines five named planes (semantic layer roles). They are typically implemented with portals.

• Back plane — recessed context.
• Base plane — canvas.
• Work plane — primary doing/reading.
• Overlay plane — contextual transient UI.
• Command plane — modal decisions.

Normative rules

• Overlays and commands MUST render in global planes to avoid clipping by scroll containers.
• A component’s semantic tier is independent of its rendering plane.

5.2 Physical stacking exceptions are allowed

A tooltip can render above a dialog while remaining an Overlay-tier element.

This is not a contradiction; it reflects two truths:

• Physical topness is about rendering constraints (portals, clipping, platform APIs).
• Semantic topness is about attention and commitment (what the user must respond to).

6. Token model (basis → endpoints → adapters)

CEM D4 defines three layers of contract.

6.1 Basis tokens (rungs)

Basis tokens are the minimal numeric “rungs.” They encode signed tier meaning.

• --cem-recess-2
• --cem-recess-1
• --cem-elevation-0
• --cem-elevation-1
• --cem-elevation-2
• --cem-elevation-3
• --cem-elevation-4

6.2 Semantic endpoints (product-facing)

Semantic endpoints are what components use. They map to basis rungs.

• --cem-layer-back
• --cem-layer-base
• --cem-layer-work
• --cem-layer-overlay
• --cem-layer-command

6.3 Adapters (appearance channels)

Adapters describe how the rung is rendered:

• tonal shift (color ladder)
• shadow recipe
• contour/stroke reinforcement
• material/blur recipe
• spacing adjustments
• motion/transition recipe

Adapters can vary per theme/density without changing semantics.

6.4 Generator output shape (R-D4-1 resolved)

D4 emits the semantic-aliases shape, not per-channel adapter hooks:

• Basis rungs emit a single canonical channel — a box-shadow recipe (positive recipes for lift, inset recipes for recess, none for the canvas baseline). This is the most universally meaningful single channel that is not z-index (using rungs as z-index is explicitly forbidden — see §2.2).
• Semantic endpoints alias to rungs via var() (--cem-layer-work: var(--cem-elevation-1), etc.).
• Per-channel adapter hooks (--cem-layer-{rung}-tone, -contour, -material, -space, -motion) are theme-stylesheet concerns: tone is owned by D0's .cem-theme-{light,dark,contrast-light,contrast-dark,native} blocks; contour is owned by D5; spacing by D1; motion by D7. D4 does not redeclare them.

D4 also emits the public physical choice-popup stacking integer (§15.1.1), separately from these rung recipes. Theme adapters compose the remaining appearance channels.

6.5 Per-rung perceivable channels (R-D4-2 resolved)

§7.2 requires each rung to differ from its neighbors in at least one perceivable channel (≥2 in dense UIs). D4 emits shadow as the canonical channel; tone is the second channel and is supplied per-theme by cem-colors.html (light/dark/contrast/native blocks). Together those two channels satisfy the rule in normal themes. In forced-colors: active themes, shadows are stripped — D4's forced-colors override collapses all rungs to none, and the tier signal is then carried by D5 contour (--cem-stroke-boundary-strong) and by spatial isolation. Browser-level verification of "≥1 perceivable channel change per rung" is performed in Phase 13.

7. Basis tokens: the canonical signed ladder

7.1 Required rung tokens

The 7-tier ladder rungs are required and must remain stable. Each rung emits as a box-shadow recipe (the canonical single channel — see §6.4). Recess rungs use inset recipes; lift rungs use outset recipes; the canvas base is none. Values are perceptually graded so each step differs visibly from its neighbors.

cem-layering-rungs

7.2 Appearance-change principle

When moving by one rung, at least one of the following must change in a perceivable way (and ideally two in high-density UI):

• Tone (surface/container tone, chroma shift)
• Contour (stroke/outline, especially in forced-colors)
• Shadow (soft separation)
• Material (blur/opacity)
• Space (inset/gap or breathing room)
• Motion (lift/drop transition)

Recess should primarily use tone and contour (shadows are often imperceptible “into” the page).

Lift should primarily use tone + shadow, with contour as a fallback.

8. Semantic endpoints: product-facing contract

Semantic endpoints allow components to express layering without knowing numeric rungs.

8.1 Canonical endpoints

Note: --cem-elevation-2 (Floating) is most often an internal component choice within the Work layer (e.g., a temporary lifted region), not a global plane.

cem-layering-semantic

8.2 Optional endpoints

Optional endpoints are allowed only if they remain stable and scoped, and if they map cleanly to an existing rung without creating new “micro tiers”.

Examples:

• --cem-layer-back-deep → --cem-layer-back + --cem-recess-2
• --cem-layer-work-floating → --cem-layer-work + --cem-elevation-2

cem-layering-semantic-optional

9. Representation channels

Layering cues are multi-channel. No single channel is reliable across all themes.

9.1 Tone and the color ladder

The CEM color ladder is the primary driver of “dig down” vs “lift up.”

Rules

• Recess SHOULD move toward neutral/gray (less chroma/brand energy).
• Lift SHOULD move toward brighter/branded tones (more chroma/energy).
• Tone changes must preserve text contrast; do not “flip” text color unless the rung truly becomes Overlay/Command.

9.2 Shadow

• Shadows MAY be reduced in dark themes; tonal separation must still carry the meaning.
• Recess relies less on shadow; “negative shadow” is generally not readable.
• Shadow should never be the only separator.

9.3 Contour / stroke

• Back and Base SHOULD rely on contour in high-density layouts and forced-colors.
• Back and Base layers SHOULD have minimal contour.
• Work and above SHOULD provide optional contour reinforcement for dense layouts.
• Overlay and Command MUST remain legible if shadows are removed.

9.4 Material / blur

Where supported, material/blur can reinforce overlay separation, but MUST NOT replace tone/contrast requirements.

9.5 Space (inset and gap)

Layers with higher semantic priority SHOULD “earn” breathing room (inset and/or gap) in comfort density modes.

• Recess can be communicated by reduced padding/visual weight, but never by reducing hit targets.

9.6 Motion

Lift/drop transitions MAY reinforce the ladder, but the meaning must remain clear in reduced-motion settings.

• Lift/drop transitions are allowed for state changes (hover, focus) but must not change semantic tier.

10. Scrim

Scrim communicates modality and commitment.

10.1 Scrim usage matrix

10.2 Command owns modality

• Command MUST trap focus (or equivalent modality) and own the scrim.
• Overlay MUST NOT break modality; it may appear above physically, but remains subordinate in semantics and dismissal precedence.
• Dismissal precedence: dismiss the topmost Overlay first, then Command.

11. Action states must align with layering and the color ladder

11.1 Alignment rule: one direction, two dimensions

Layering (signed depth) and action states (visual priority order) must not contradict each other.

• “More urgent / more interactive” states SHOULD NOT be rendered with recess cues.
• “Less available / less interactive” states SHOULD NOT be rendered with lift cues.

11.2 State escalation should not change layer role

State changes (hover, focus, pressed, selected, disabled, readonly) MUST NOT change the layer endpoint. They may adjust rung rendering (tone/contour/shadow) within a bounded range.

Action states must align with layering cues and color ladder direction.

A button becoming hovered does not become an Overlay. State changes should be expressed as micro-shifts within the component’s assigned layer role.

11.3 Recommended state → signed shift mapping (default guidance)

This guidance assumes the component’s base endpoint is correct.

• Default: no signed shift change.
• Hover / focus: +0 → +1 appearance reinforcement (often contour and/or slightly increased tonal separation).
• Pressed: may “press toward base” visually without reducing salience (tactile cue, not hierarchy reversal).
• Selected: treat as a meaning change (often tone), not necessarily as a rung change.
• Readonly / disabled: allow a recess cue (typically −1 via tone/contour) without moving planes.

11.4 Active/pressed tactile rule

Pressed feedback may reduce shadow (a “press in”), but MUST preserve the state’s prominence via tone/contour so the user does not read it as “disabled or background.”

12. Cross-dimension coupling

Layering relies on other dimensions for robustness:

• D0 Color ladder: supplies tonal recipes for recess and lift.
• D5 Stroke: provides contour when tone/shadow are insufficient or unavailable.
• D1 Space: higher-priority layers may gain breathing room in comfort density.
• D7 Motion: transitions can reinforce, never replace, the ladder.

Layering MUST NOT rename or duplicate these dimensions; it only defines coupling invariants.

13. Accessibility and forced-colors requirements

13.1 Depth is not the only signal

Layer meaning must remain readable without shadows and with limited color (e.g., high-contrast themes). Therefore:

• At least one non-shadow signal (tone or contour) MUST remain.
• Focus indicators MUST remain visible across all tiers.

13.2 Forced-colors

In forced-colors:

• Tier meaning SHOULD be expressed primarily via contour and spacing.
• Do not rely on subtle tonal deltas.

In forced-colors: active themes, shadows are stripped by the user agent. D4's generator collapses every rung's shadow recipe to none, and components rely on D5 contour (--cem-stroke-boundary-strong) plus spatial isolation to carry the tier signal.

cem-layering-rungs-forced

cem-layering-rungs-forced is generator-only — no new tokens. The same rung names are redeclared inside @media (forced-colors: active) :root { … }.

14. Component mapping matrix

This matrix maps common component families to layer endpoints and their default rung.

15. Implementation guidance

15.1 Keep semantics separate from z-index

• Use layer endpoints and rung tokens for meaning.
• Use a dedicated z-index policy for stacking mechanics; the theme owns the public choice-popup integer below, independently of elevation.

15.1.1 Public choice-popup stacking

The theme owns the web choice-popup stacking value. This public physical stacking property is independent of semantic elevation: its integer is never a rung or priority tier. Containers and individual component hosts may override it; components consume it without redeclaring a local default.

cem-layering-popup-stacking

The default places the popup above later in-flow positioned content. It does not escape ancestor clipping or stacking contexts, establish a global overlay ladder, or replace top-layer/portal policy. Elevation tokens remain shadow recipes and MUST NOT be used as z-index values. The canonical select adopts this token; frozen legacy choice components retain their bounded private adapter until migration.

15.2 Example CSS pattern (illustrative)

The following demonstrates the mapping shape; it is not a required implementation.

/* Semantic endpoints select a rung; adapters render the rung. */

.cem-layer--work      { --cem-rung: var(--cem-elevation-1); }
.cem-layer--overlay   { --cem-rung: var(--cem-elevation-3); }
.cem-layer--command   { --cem-rung: var(--cem-elevation-4); }

/* Adapter hooks (tone/shadow/contour) are theme-specific. */
.cem-layer {
  background: var(--cem-layer-tone, Canvas);
  box-shadow: var(--cem-layer-shadow, none);
  outline: var(--cem-layer-contour, none);
}

15.3 Dismissal and focus precedence

• Escape closes the topmost Overlay first.
• If no overlays remain, escape closes the Command (if allowed).

16. Canonical token summary

16.1 Required rung tokens

• --cem-recess-2
• --cem-recess-1
• --cem-elevation-0
• --cem-elevation-1
• --cem-elevation-2
• --cem-elevation-3
• --cem-elevation-4

16.2 Required semantic endpoints

• --cem-layer-back
• --cem-layer-base
• --cem-layer-work
• --cem-layer-overlay
• --cem-layer-command

16.3 Optional semantic endpoints (allowed)

• --cem-layer-back-deep → --cem-layer-back + --cem-recess-2
• --cem-layer-work-floating → --cem-layer-work + --cem-elevation-2

17. Governance and versioning

17.1 Breaking (major)

Treat as breaking if you:

• Rename or remove any canonical rung token or endpoint.
• Change the semantic meaning of a rung or endpoint.
• Change the meaning of “Command owns modality” or dismissal precedence.

17.2 Non-breaking (minor/patch)

Treat as minor/patch if you:

• Adjust adapter recipes (tone/shadow/contour) per theme/density while preserving semantics.
• Add optional endpoints with stable consumer meaning (and clear mapping to existing rungs).
• Clarify documentation or add mapping guidance.

18. Migration notes

This spec is the canonical D4 contract for layering (signed depth).

• Legacy elevation tokens may be kept as internal aliases.
• Prefer --cem-elevation-*, --cem-recess-*, and --cem-layer-* as the public CEM contract going forward.

19. Token manifest index

Generator derivation rules:

• cem-layering-rungs, cem-layering-semantic, cem-layering-semantic-optional, cem-layering-popup-stacking → token list (tier in last column).
• cem-layering-rungs-forced → override values emitted inside @media (forced-colors: active) :root { … }; no new tokens.
• D4 emits shadow recipes as the rung value (R-D4-1 resolved). Tone, contour, material, spacing, and motion adapter hooks are owned by their respective dimensions (D0, D5, etc.) and are not redeclared here.
• --cem-elevation-* and --cem-recess-* MUST NOT be used as z-index values (§2.2).

20. References

Internal

• Action states in visual priority order (EPA-WG custom-element-dist discussion #14): https://github.com/EPA-WG/custom-element-dist/discussions/14

External

• Material Design Backdrop (back layer / front layer): https://m2.material.io/components/backdrop
• Material Design 3 — Elevation: https://m3.material.io/styles/elevation
• Android Developers — Material 3 elevation guidance (tonal + shadow): https://developer.android.com/develop/ui/compose/designsystems/material3#elevation
• Fluent 2 Design System — Elevation: https://fluent2.microsoft.design/elevation
• Windows apps — Depth, z-depth, and shadow: https://learn.microsoft.com/en-us/windows/apps/design/layout/depth-shadow
• Apple Human Interface Guidelines — Materials: https://developer.apple.com/design/human-interface-guidelines/materials
• Apple Human Interface Guidelines — Popovers: https://developer.apple.com/design/human-interface-guidelines/popovers
• Atlassian Design System — Elevation (includes z-index guidance): https://atlassian.design/foundations/elevation
• Atlassian Design System — Portal (stacking context): https://atlassian.design/components/portal