Element layers

Every element can carry two extra boxes that cost nothing — no markup, no node in the layers tree, no empty div invented to hold a colour.

They are how a section gets a wash over its photograph, how a heading gets a rule beneath it, how a card gets a flash of colour in one corner. Without them you build all three out of spare boxes, and the page you hand over fills up with elements that exist only to hold a tint.

In CSS they are ::before and ::after. You do not need to know that.

Adding one

Select an element and find Element layers, under Style & depth.

Upper	Over the element’s content
Lower	Behind the element’s content, and over its own background

Both rows are always there, whether the layers exist yet or not. Click one to create it and start styling it; click the ✕ to remove it.

That is what makes each one useful. A picture or a shape goes on Lower, where it sits behind the words and in front of the element’s own fill. A scrim that has to dim everything, words included, goes on Upper.

Depth under Style & depth changes it, so either layer can be moved to either side of the content.

Depth offers your design system’s --z-* scale — below, base, raised, dropdown and the rest — because it has already decided what those mean, and two things at raised and modal stay in the right order when someone changes the scale. Custom is at the end of that list for a number of your own: two layers on one element only have to be ordered relative to each other, and they do not need a name for that.

Custom is also how a value written before the scale existed shows itself. A stacking order of 2 lights Custom with 2 in the field, and the tokens are right there to put it on the scale.

Styling one

Opening a layer points the whole panel at it. A blue strip appears at the top of the panel — above the colours, because the colours are one of the things being retargeted — saying which layer you are in and on which element, with Back to the element on it. The rail is tinted down its whole height, because the whole rail is now the layer’s.

It gets the real controls, not a reduced set: fills, pictures, corners, shadows, opacity, movement, depth, size, pinning. A layer is a box, and everything true of a box is true of it.

It also gets Adjust, which is where a layer earns its keep: Blend set to Screen lifts the photograph underneath instead of covering it, Multiply deepens it.

A layer can carry a picture of its own — Fill › Image, exactly as on an element — with all the same controls: crop, position, repeat, scrolling, and the brightness, contrast, saturation and blur. A tiled texture on a layer set to Multiply, over a photograph on the element beneath, is two pictures and no extra markup. See Adding images.

The one thing not offered there is Back to an image element: a layer holds no children, so there is nowhere for an <img> to go.

Three things are not offered, because a layer cannot have them:

• Layout — it holds no children, so there is no flow to arrange
• Spacing — it is not in the flow, so margins do nothing
• Typography — its content is a pair of empty quotes

Size and place

A layer starts pinned to all four edges of its element, so it covers it exactly.

Pinned to changes that — the nine anchors and the four offsets, the same as free placement. Size is a width and a height, left empty to mean whatever the edges say. There is no Hug or Fill here: hug what, and fill from whom? A layer has no contents and nothing is sharing space with it.

This is not the background image

The background is a property of the element: one picture, behind everything inside it. See Adding images.

A layer is a box in its own right, with its own size, its own place and its own fill, and it can sit over the content instead of under it. The reason to reach for one is usually that the element’s background is already spoken for.

Parallax

Choosing Parallax under a picture’s Scrolling puts that picture on the lower layer and moves it as the page scrolls. That is not an implementation detail being hidden from you — a background cannot move without its element moving, so the picture has to become a box, and a layer is one. See Adding images.

Gradients

A gradient is one thing a layer can be. Drawing one with the gradient tool puts it on a layer, creating it if there is not one there yet — which is why a photograph can fade to dark at the bottom without the photograph being replaced.

Adding a gradient to a layer keeps whatever else you had given it, and clearing the gradient leaves the layer alone unless the gradient was all it was.

What comes out

.hero__box::after {
  content: "";
  position: absolute;
  inset: 0;
  z-index: var(--z-raised);
  pointer-events: none;
  background-color: var(--primary);
  border-radius: var(--radius-l);
}

pointer-events: none is there so a wash over a card does not swallow the click on the card. The stacking order is a token, like everything else.

Knowing you are on one

While a layer is the target, the whole right-hand rail says so: a banner across the top naming the layer and the element it belongs to, a coloured edge down the side, and the rail itself tinted. It has a colour of its own — not the accent every selected thing in the app uses, because that reads as nothing in particular, and this is the one state where every control in the panel means something different from what it usually means.

Back to the element in the banner returns the panel to the element itself.

Depth, and the one value that hides it

A layer sits behind the content and in front of the element’s own fill. That is depth z-base, and it is not the same as “as far back as possible”.

z-below is further back than the element itself. A section is position: relative with no depth of its own, so it is not a stacking context — and a layer set below it paints underneath the section’s own background colour. On a dark section the picture simply vanishes, with nothing in the panel to say where it went. If a layer has disappeared, this is the first thing to check.