/* ─── Overlap — pull utilities + the content z-index scale ─────────────
   Wave S spatial vocabulary. Boundary-breaking is the cheapest premium signal
   there is: one element that refuses to stay inside its section. Every band
   sitting neatly in its own box is what makes a page read as a stack of
   rectangles no matter how good the individual sections are.

   Pulling is a two-part move and BOTH parts are needed. A negative margin
   alone puts the element in the right place and then paints it underneath the
   neighbour's background, so the effect silently disappears. That is why
   every .hzo-pull-* here also opens a positioning context and raises the
   element. It is one class, not a recipe you have to remember.

     <section class="hzo-section hzo-section--dark">…</section>
     <section class="hzo-section">
       <div class="hzo-container">
         <div class="hzo-card hzo-pull-2">…</div>   <!-- rises into the dark band -->
       </div>
     </section>

   ── The scale ───────────────────────────────────────────────────────────
     .hzo-pull-1   48px   a nudge — a card breaking its section line
     .hzo-pull-2   64px   the default overlap; a panel straddling two surfaces
     .hzo-pull-3   80px   a hero card sitting deep in the band above
     .hzo-pull-4  120px   the statement move; use once per page at most
   Push variants pull the NEXT sibling up into THIS element instead:
     .hzo-push-1 … .hzo-push-4  (negative margin-bottom, same steps)

   RESPONSIVE BEHAVIOUR: below 768px every step clamps to --pull-1. A 120px
   overlap on a 375px screen is not a composition, it is two things on top of
   each other. The clamp lives in the CLASS, not in the token — tokens are not
   responsive, and a --pull-4 read from an inline style would hard-code 120px
   at every width.

   ── The content z-index scale ───────────────────────────────────────────
   The existing --z-100…700 / --z-header / --z-modal ladder governs CHROME
   (sticky bars, drawers, modals, toasts) and starts at 10. Content layering
   inside a section needs a vocabulary an order of magnitude below that, and
   it was missing — which is why component CSS reaches for bare `z-index: 1`.

     --z-behind  -1   decorative fill BEHIND the section's own content
     --z-base     0   the content plane
     --z-above    1   the element that must sit on top of its neighbours

   Utilities: .hzo-z-behind / .hzo-z-base / .hzo-z-above. Each opens a
   positioning context, because a z-index on a static element does nothing —
   the second-most-common silent no-op in this system after a bare modifier.

   ⚠ .hzo-z-behind needs a stacking context on the ancestor or it will slide
   behind the SECTION's background too, not just behind its content. Put
   .hzo-isolate on the section that owns the decoration.

   ⚠ AN ANCESTOR WITH overflow: hidden CLIPS EVERY PULL. If an overlap does
   not appear, that is the first thing to check — .hzo-media-band and several
   card variants set it deliberately. `overflow: clip` on the page root is
   safe (see _base/bleed.css); overflow on the section between the two is not.
   ────────────────────────────────────────────────────────────────────────── */

.hzo-pull-1, .hzo-pull-2, .hzo-pull-3, .hzo-pull-4,
.hzo-push-1, .hzo-push-2, .hzo-push-3, .hzo-push-4 {
    position: relative;
    z-index: var(--z-above, 1);
}

.hzo-pull-1 { margin-top: calc(-1 * var(--pull-1, 48px)); }
.hzo-pull-2,
.hzo-pull-3,
.hzo-pull-4 { margin-top: calc(-1 * var(--pull-1, 48px)); }  /* mobile clamp */
.hzo-push-1 { margin-bottom: calc(-1 * var(--pull-1, 48px)); }
.hzo-push-2,
.hzo-push-3,
.hzo-push-4 { margin-bottom: calc(-1 * var(--pull-1, 48px)); }  /* mobile clamp */

@media (min-width: 768px) {
    .hzo-pull-2 { margin-top: calc(-1 * var(--pull-2, 64px)); }
    .hzo-pull-3 { margin-top: calc(-1 * var(--pull-3, 80px)); }
    .hzo-pull-4 { margin-top: calc(-1 * var(--pull-4, 120px)); }
    .hzo-push-2 { margin-bottom: calc(-1 * var(--pull-2, 64px)); }
    .hzo-push-3 { margin-bottom: calc(-1 * var(--pull-3, 80px)); }
    .hzo-push-4 { margin-bottom: calc(-1 * var(--pull-4, 120px)); }
}

/* Content-layer utilities. Each opens a positioning context so the z-index
   is not a no-op. */
.hzo-z-behind { position: relative; z-index: var(--z-behind, -1); }
.hzo-z-base   { position: relative; z-index: var(--z-base, 0); }
.hzo-z-above  { position: relative; z-index: var(--z-above, 1); }

/* Stacking-context opener — the partner to .hzo-z-behind, and the correct
   answer whenever a section's decoration must not escape into the page's
   global stacking order. */
.hzo-isolate { isolation: isolate; }