Skip to content

Write HTML. Render video. Built for agents.

docs: explain negative z-index stacking contexts (#5201)

Abdullah M. Nazife529fbb015ed
diff --git a/docs/concepts/data-attributes.mdx b/docs/concepts/data-attributes.mdx
index 7ee156218e..e420a9cabc 100644
--- a/docs/concepts/data-attributes.mdx
+++ b/docs/concepts/data-attributes.mdx
@@ -47,6 +47,43 @@ keep an intentional overlap, such as a crossfade, readable in Studio:
</section>
```
+### Keep negative layers inside their parent
+
+A negative `z-index` is valid CSS, but it can put a clip behind an opaque
+ancestor background when its parent does not create a stacking context. For
+example, this backdrop can be covered by the root's background:
+
+```css
+#root {
+ position: relative;
+ background: #0a0a0a;
+}
+#backdrop {
+ position: absolute;
+ inset: 0;
+ background: #f5e6c8;
+ z-index: -1;
+}
+```
+
+Add one property to keep the backdrop above its parent's background and below
+foreground siblings:
+
+```css
+#root {
+ isolation: isolate;
+}
+```
+
+`isolation: isolate` creates a local stacking context. The backdrop becomes
+visible in the browser, `snapshot`, and `render`; siblings at `z-index: 0` or
+above can still cover it. You can also use an earlier background sibling and
+raise foreground elements with non-negative `z-index` values.
+
+`hyperframes lint` reports `negative_z_index` as a warning based on CSS text.
+It can still warn when an ancestor already creates a stacking context, so
+verify the visible result rather than treating every negative value as invalid.
+
## Start relative to another clip
A numeric `data-start` is an absolute time in seconds. A clip ID means “start
diff --git a/docs/reference/html-schema.mdx b/docs/reference/html-schema.mdx
index 5127957bcc..b51e5fafb0 100644
--- a/docs/reference/html-schema.mdx
+++ b/docs/reference/html-schema.mdx
@@ -104,6 +104,14 @@ unbounded animation, and timeline-free compositions need an explicit duration.
front-to-back layering. Two clips on the same track may overlap in time; the
lane is a Studio display row, not a scheduling constraint.
+Negative `z-index` values are valid CSS, but an opaque ancestor background can
+cover the clip if its parent does not create a stacking context. Add
+`isolation: isolate` to that parent to keep the negative layer above the
+parent's background and below its foreground siblings. See the
+[before/after example](/concepts/data-attributes#keep-negative-layers-inside-their-parent).
+The `negative_z_index` lint warning also fires on isolated layers because it
+checks CSS text rather than computed stacking contexts.
+
Video visibility is managed as media and does not require `class="clip"`.
Audio has no visual lifecycle.