MediaBand

MediaBand owns the "decorative graphic behind content" recipe as one primitive: a clipped positioned parent (z-index: 1), a decorative layer at z-index: 0, content at z-index: 2, and an optional seam-fade at z-index: 4. Consumers stop hand-rolling a position: relative wrapper per page.

<MediaBand graphic={<BackgroundPattern />}>…</MediaBand>

<BackgroundPattern variant="dot-grid" />

<Frame ratio="16-9">{media}</Frame>

Use it for

• A page band whose background carries an illustration, pattern, or graphic that must sit behind real content
• Section seams where one band should dissolve into the next instead of butting against a hard edge
• Any surface where a decorative layer needs to bleed past the band's box without introducing a scroll container

Not for content-bearing media — the decorative layer is aria-hidden and non-interactive. A media element the reader is meant to see and act on belongs in the content slot, or in Frame.

Import

import { MediaBand } from '@brikdesigns/bds';

The stacking contract

overflow: clip — not hidden — clips decorative bleed without making the band a scroll container. A focused child inside a scroll container can scroll into view and shift the layout.

Graphic: slot or token

The decorative layer renders either way. Fill the graphic slot with JSX, or leave it empty and set --bds-media-band-graphic — the latter is the per-client swap path, changing the graphic from a theme with no JSX change.

// Slot
<MediaBand as="section" graphic={<BackgroundPattern fade />}>
  <SectionHeader title="How we work" />
</MediaBand>

/* Token — same component, graphic swapped per client */
.theme-acme .workflow-band {
  --bds-media-band-graphic: url('/acme/workflow.svg');
}

Seam fade

seam takes 'none' (default), 'top', 'bottom', or 'both'. Set --bds-media-band-seam-to to the neighbouring section's surface: the gradient runs from that color at the band edge to --bds-media-band-seam-from inward.

<MediaBand as="section" seam="both">…</MediaBand>

Depth without blend modes

Depth comes from gradients and token-driven scrims, never mix-blend-mode. A blend mode resolves against whatever happens to sit underneath, so it reads differently in the light and dark themes and cannot be swapped per client. Every depth value here is a token a theme can override.

Accessibility

• The decorative layer renders aria-hidden="true" with pointer-events: none, so it stays out of the accessibility tree and the tab order.
• Static by construction (no animation, no JS-driven motion) — the band needs no prefers-reduced-motion handling and its graphic renders at rest. Animated content a consumer slots into graphic owns its own reduced-motion behaviour.

API

Plus all standard HTML attributes for the rendered element.

CSS Override API

Related

• Storybook playground
• BackgroundPattern — the usual occupant of the decorative slot