Ambient depth

Ambient Depth (Mercury)

A premium dark-mode UI needs more than a dark background. It needs atmosphere: soft, blurred color blooms behind the hero content that suggest light sources off-frame. The recipe is small but every part matters.

The recipe

One ambient bloom = a large, translucent ellipse + a heavy layer blur, placed in a parent that does not clip. Two blooms at different hues give multi-light depth (e.g., teal + magenta on a near-black background).

Rules that must hold:

1. Size > frame. The ellipse should be larger than the content it sits behind. A typical 390×844 iPhone frame uses a 500×500 ellipse.
2. Color is a fill with alpha baked into the hex. Use an 8-character hex like #22D3A540 (25% alpha), not a 6-char hex plus opacity: 0.25. The blur effect interacts better with per-fill alpha than with node opacity.
3. Blur is a LAYER_BLUR effect, radius 150–200. Below 120 the bloom looks like a discrete shape. Above 220 it smears into nothing.
4. Parent must have clipsContent: false. Otherwise the bloom hits the parent's rectangular bounds and shows a hard edge — the exact opposite of atmosphere.
5. Z-order matters. The ellipse sits above the background fill but below everything else. Create it early; it needs to be the lowest content child.
6. Do not use icon create. Icons return frames-as-components, not paint surfaces. Use raw create with kind: "ellipse".

Hue pairing for two-light scenes

Pick complementary accent hues from your palette. Typical combinations that read as premium on near-black (#0A0A0B):

• Emerald #22D3A540 + Violet #8B5CF640
• Amber #F59E0B40 + Rose #F43F5E40
• Cyan #06B6D440 + Magenta #EC489940

Place the two ellipses in different quadrants (e.g., top-left and bottom-right). Stagger their sizes slightly so the blooms don't read as symmetric.

Workflow

1. Check the bridge with mcp__mercury__ping.
2. Identify the target frame. If the designer gave an id, use it. Else use mcp__mercury__query op:selection and take the outermost frame.
3. Patch the frame to clipsContent: false via mcp__mercury__patch. (Remember to restore this if the original design required clipping — ask.)
4. Create the ellipse(s) with mcp__mercury__create kind:"ellipse", sized 500×500 (or larger than the frame's smaller dimension), positioned so their center sits near the content they should halo.
5. Apply the fill + blur with mcp__mercury__paint:
   • fills: [{ type: "SOLID", color: "#22D3A540" }]
   • effects: [{ type: "LAYER_BLUR", radius: 180, visible: true }]
6. Push to back. Use mcp__mercury__nodes op:move or rely on creation order — create the ellipse before other foreground elements.
7. Verify visually. Call mcp__mercury__export_node on the parent frame and look at the PNG. If you see hard edges, the parent is still clipping. If the bloom is invisible, the alpha is too low or the blur is too high.

Prefer batching steps 4–6 in a single mcp__mercury__batch call so it's one undo step.

Common mistakes

• Using opacity: 0.25 on the ellipse node instead of alpha in the hex. Node opacity applies after the blur; per-fill alpha applies before. The former looks flatter.
• Forgetting clipsContent: false. The bloom will show a crisp rectangle edge where it hits the frame boundary.
• Putting the ellipse in an auto-layout frame. Auto-layout will pack it and move it. Use a non-auto-layout parent, or set layoutPositioning: "ABSOLUTE" on the ellipse.
• Using icon create for the glow. Icons are components. Use raw create with kind: "ellipse".

When NOT to use this

• Light-mode designs. Ambient depth reads as dirty on white.
• Information-dense screens (tables, dashboards with tight spacing). The bloom competes with content.
• When the designer explicitly wants flat / brutalist / editorial.