Iwiseman: Created page with "= 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. In..."

2026-04-17T02:06:15Z

Created page with "= 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. In..."

New page

= 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:

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

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:

<syntaxhighlight lang="json">
{
"size": "md",
"width": 768,
"height": 256,
"mediaQuery": "(min-width: 481px) and (max-width: 768px)"
}
</syntaxhighlight>

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

<syntaxhighlight lang="text">
bill-banner_md_768x256.webp
</syntaxhighlight>

=== 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:

<syntaxhighlight lang="json">
{
"size": "lg",
"width": 1200,
"height": 400
}
</syntaxhighlight>

The fallback image is then:

<syntaxhighlight lang="text">
bill-banner_lg_1200x400.webp
</syntaxhighlight>

== 4. How Media Fills the Banner ==

All media (video or image) uses:

<syntaxhighlight lang="css">
object-fit: cover;
</syntaxhighlight>

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 ==

{| class="wikitable"
! 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
|}

Image Handling - Revision history