Image Handling

Handling Images and Responsive Banners

This page documents the correct way to handle images, videos, and responsive banners in the site. It focuses on three concepts:

• Intrinsic dimensions – define the layout shape
• Responsive variants – define which file the browser downloads
• Object-fit / object-cover – define how media fills the box

Understanding these three layers makes banners predictable and prevents layout shift.

1. Intrinsic Dimensions (Layout Shape)

Intrinsic dimensions define the aspect ratio of the banner container.

Example:

<div style="aspect-ratio: 1200 / 450">
</div>

This does NOT need to match the actual pixel size of any image or video. It only defines the shape you want rendered.

Key points

• Intrinsic dimensions prevent layout shift (CLS)
• They define the final visible shape of the banner
• They are independent of the actual media files
• Any pair with the same ratio is valid (e.g., 24/9, 2400/900, 1200/450)

2. Responsive Variants (File Selection)

Variants define which file the browser should download at different breakpoints.

Example variant entry:

{
  "size": "md",
  "width": 768,
  "height": 256,
  "mediaQuery": "(min-width: 481px) and (max-width: 768px)"
}

These dimensions are not used for layout. They are only used to build URLs such as:

bill-banner_md_768x256.webp

Key points

• Variants exist only to help the browser choose the correct file
• They do not control the rendered size
• They may be cropped or letterboxed versions of the full image
• They must match the naming convention used by the image pipeline

3. Fallback Images for Video Banners

Video banners use a fallback image when autoplay fails.

The fallback image should always use the largest variant so it looks sharp on desktop.

Example:

{
  "size": "lg",
  "width": 1200,
  "height": 400
}

The fallback image is then:

bill-banner_lg_1200x400.webp

4. How Media Fills the Banner

All media (video or image) uses:

object-fit: cover;

This means:

• The media fills the intrinsic box
• It may crop to maintain its own aspect ratio
• The intrinsic ratio always wins

5. Summary

• Intrinsic dimensions define the shape of the banner
• Variants define which file is downloaded
• object-cover ensures the media fills the box
• The fallback image should always be the largest variant
• The intrinsic ratio should match the intended visual design (e.g., 24/9)

6. Recommended Ratios

Banner Type	Ratio	Notes
Cinematic strip	24/9 (8:3)	Matches old site behaviour
Standard video	16/9	Matches most video exports
Ultra-wide hero	32/9	Very wide, minimal height