Media Stage

Overview

MediaStage is the bare "media on a background, with content overlaid on top" primitive used by BannerBasic, BannerIntegrated, BannerShowcase, and any custom hero. It owns media positioning, the content slot, the background color, and a built-in ImageContrastOverlay, but leaves border-radius to the call site (apply the .radius-contained utility there).

When backgroundColor is a hex value, MediaStage runs it through colorToSurfaceTone and propagates the result to descendants so text and icons sitting on top stay legible. Non-hex values (CSS vars, light-dark(), rgb(), hsl(), or anything that doesn't parse as hex) short-circuit to the 'light' tone (same caveat as Backdrop). Pass an explicit surfaceTone to override the derived value.

Inheritable props and overlay

MediaStage exposes a set of inheritable props for components that want a brightness-aware surface as their root:

• backgroundImage renders a <Media> behind the content slot. backgroundImageSizes and backgroundImageFit ('cover' or 'contain') tune how it's sized.
• The fallbackBackgroundImageDefault, fallbackBackgroundImageDark, and fallbackBackgroundImageBright trio kicks in when backgroundImage is absent: the resolved surface tone selects which fallback renders, so a single component can ship per-tone artwork.
• overlay accepts an ImageContrastOverlay prop bag and is forwarded to the built-in overlay element (rendered above the media, below the content).
• surfaceTone is the manual override; without it the tone derives from backgroundColor via colorToSurfaceTone (hex only).

Key Business & UX Benefits

• One primitive powers every hero and banner variant, so a brand refresh changes the look in one place instead of touching each banner type.
• Automatic surface-tone derivation keeps headline and CTA text legible when marketing recolors a banner background mid-campaign.
• Clean separation of media, content slot, and chrome lets product teams compose custom heroes without rewriting positioning logic.

Usage

<MediaStage :media="media" background-color="#EFEFEF">
    <TextGroup caption="..." heading="..." subline="..." />
  </MediaStage>

Feature List

API Reference