What an overlap or z-index conflict is #
An overlap conflict is the failure class Loupely Lens identifies when two elements occupy the same visual space and the wrong one is on top, or when an element is appearing behind something it should be in front of. A navigation dropdown gets clipped behind a hero section. A popup appears underneath the page content. Two sections overlap because one is positioned in a way that pulls it out of the normal document flow.
z-index is the CSS property that controls which element sits on top when elements overlap. A higher z-index means closer to the viewer. But z-index doesn’t work the way most people expect, and that’s exactly why these conflicts are hard to diagnose without the right tools.
Why z-index is confusing #
z-index doesn’t operate globally across your entire page. It operates within a Stacking Context, which is a group of elements that share the same stacking order. When a parent element creates a new Stacking Context (which happens automatically when a parent has a position other than static combined with a z-index, or when it uses certain CSS properties like transform or opacity), every child element’s z-index is calculated relative to that context, not to the page as a whole.
This means an element with z-index 9999 inside a Stacking Context that sits below another Stacking Context will still appear behind elements in the other context. The high z-index value is trapped inside a container that the browser renders last.
How Lens diagnoses an overlap conflict #
Lens detects competing elements (elements sharing the same visual space as the one you clicked) and captures the z-index and Stacking Context data for both. The diagnosis identifies which element is creating the unwanted Stacking Context, what CSS property triggered it, and why the expected z-index ordering isn’t working as intended.
The diagnosis output names the specific conflict: “This popup is appearing behind the navigation bar because the navigation’s parent container has position: relative and z-index: 10, which created a Stacking Context. Your popup has a higher z-index number, but it’s inside a different Stacking Context that renders below the navigation’s context.”
What the triage step provides #
Overlap conflicts typically require either removing the unintended Stacking Context from the constraining parent, or moving the element that needs to be on top to a different position in the DOM hierarchy. Lens’s triage routes to the specific property on the specific element that’s creating the problem. When the fix is a CSS property change (removing a transform from a parent element, for example), Lens provides the override. When the fix requires restructuring the HTML, the developer handoff package includes the full Stacking Context chain so a developer has everything needed to resolve it without back-and-forth.