Unified media-background + overlay macro with automatic z-index

[jackgranatowski]

Problem

There's no recipe for the classic "hero with a real <video> (or <img>) as the background" pattern — where the media is an actual DOM element (not a CSS background-image), an overlay/gradient sits on top of it for legibility, and the section's real content sits above both without the author manually wiring z-index.

Today an author has to hand-assemble three things themselves:

<section style="position: relative">
  ``&lt;video class="sf-overlay" autoplay muted loop src="/hero.mp4"&gt;``</video>
  <div class="sf-overlay" style="background: var(--sf-scrim-gradient)"></div>
  <div style="position: relative; z-index: 1">  <!-- ← this z-index is the manual step -->
    <h1>Hero content</h1>
  </div>
</section>

.sf-overlay (core/layout.css, position: absolute; inset: 0) already solves positioning the video and the gradient div. Nothing solves the third line — stacking real content above them — automatically.

Not the same as .sf-surface-bg (#523 / #559)

.sf-surface-bg (landing via #559) solves a different, CSS-only case: a base color + background-image (photo/gradient/pattern) + an overlay, all composed as two layers of one background-image property on a single element — see the worked example in the discussion above. Because it's pure background-*, there is no separate element and therefore no stacking problem to solve: content in normal flow already paints above a background-image for free.

That composition cannot hold a real <video> element (autoplaying/looping video isn't expressible as a CSS background), and it does nothing for the "auto z-index my content" problem this issue is about. The two issues are complementary, not duplicates:

	.sf-surface-bg (#523/#559)	This issue (#489)
Media type	CSS background-image only	Real <img>/<video> element
Overlay	2nd background-image layer	Separate overlay element (like .sf-overlay)
Content stacking	Automatic (nothing to do — it's just a background)	Manual today — this issue closes that gap

.sf-scrim is the closest existing precedent for "automatic content stacking": it already does position: relative; z-index: 1 on > :not(img, picture, video, svg, canvas) / .sf-scrim__content — but .sf-scrim doesn't position a background media element for you; it assumes you already have one in flow (e.g. an <img> as a normal child, not absolutely positioned as a full-bleed background).

Scope

• A macro/recipe (e.g. .sf-media-bg — naming TBD) that, applied to a container holding a background <img>/<video> element (positioned via .sf-overlay or equivalent) plus a content element:
  • Automatically stacks the content above the media + overlay via z-index (reusing --sf-z-overlay or a dedicated token — no new token group), matching .sf-scrim's existing auto-stack pattern.
  • Supports an optional overlay layer (reuse --sf-scrim-gradient/--sf-scrim-color — don't reinvent overlay tokens).
• Document in docs/macros.md with a full HTML usage example (like the one above, minus the manual z-index).
• Note in the docs how this differs from .sf-surface-bg (CSS-background-only) so users pick the right one.

Acceptance criteria

• Applying the macro to a <video>/<img>-background section auto-stacks real content above it — no manual z-index needed
• Optional overlay/gradient supported, built from existing scrim tokens
• Documented with a worked example, cross-referenced against .sf-surface-bg

[jackgranatowski]

Cross-ref: an internal feature-gap review flagged the same need (media background + overlay + correct stacking as one primitive). Tracking here; related new work on reusable named backgrounds is in #523.

---

Generated by Claude Code

[jackgranatowski]

Resolved — already covered by .sf-bg + .sf-scrim (no new code needed)

On closer investigation this is already implemented, documented, and tested on main. My earlier triage notes on this issue were wrong — they focused on .sf-overlay/.sf-surface-bg and missed the .sf-bg primitive, which is purpose-built for exactly this.

The composition

.sf-bg (core/layout.css:342-380) is an absolutely-positioned cover-media layer. Its parent is auto-promoted to a positioned, isolated stacking context via :where(:has(> .sf-bg)), and the media sits at z-index: -2 — so content stacks above it with zero manual z-index. It composes natively under .sf-scrim, giving the full media → overlay → content order:

<section class="sf-scrim sf-scrim--bottom">
  ``&lt;video class="sf-bg" autoplay muted loop src="/hero.mp4"&gt;``</video>
  <h1 class="sf-scrim__content">Hero content</h1>
</section>

Stacking resolves automatically: media z-index:-2 → scrim gradient 0 → content 1. .sf-scrim's > :not(img, picture, video, svg, canvas) selector deliberately excludes the video so the .sf-bg layer keeps its -2. Works as a bare <img class="sf-bg"> or as a wrapper with a nested > img / > video / > picture.

This satisfies every point of the original scope:

• ✅ Overlay (color/gradient) on top of a background image or video — .sf-scrim
• ✅ Real <img>/<video> element background (not just CSS background-image) — .sf-bg
• ✅ Automatic content stacking, no manual z-index — the :has() promotion + .sf-scrim lift selector
• ✅ Also works for CSS-background-image containers — .sf-scrim alone, or .sf-surface-bg (Named background "surfaces" (image/gradient/overlay/animation presets) #523/Integrate #557 + #558: fluid-width, surface-bg, dist rename, .sf-bg-layer + .sf-theme-* (supersedes #557/#558) #559)

Evidence

• Implementation: core/layout.css:342-380, tokens --sf-bg-inset/-fit/-position/-radius/-z in core/tokens.layout.css:96-100
• Docs: docs/layout.md:33
• Test: tests/macros.spec.js:519 — a describe block literally titled "macro: .sf-scrim composed with .sf-bg (media background + overlay)", asserting content hit-tests on top "with no manual z-index set on content."

Note on the naming

PR #559 renames this primitive .sf-bg → .sf-bg-layer (and --sf-bg-* → --sf-bg-layer-*) to disambiguate it from .sf-surface-bg (the CSS-background composer, #523). Behavior is identical; only the class name changes. After #559 the example above uses class="sf-bg-layer".

Building a separate .sf-media-bg macro would add a third overlapping public API for a result the framework already composes natively — the exact "parallel confusing APIs" pitfall #559 exists to prevent. Closing as completed.

---

Generated by Claude Code