Images

sizes - ratios - workflow - best practice

Note: Ratios and sizes are still being reviewed. Content below will continue to be updated as standards are refined.

Ratio Calculator

Width (px) Height (px) Ratio

Shape preview (not to scale)

Banner and Hero Ratio Standards

Type	Desktop Ratio	Smaller-Screen Ratio	Use
Primary Banner	3:1	2:1	Page-top banners, intro bands, marketing banners
Primary Hero	2:1	16:9	Main hero areas that need more impact without taking over the page
Alternate Hero	5:2	16:9	When you want a little more height but still a controlled footprint
Cinematic Banner	21:9	3:1 or 2:1	Special use only
Media / Video	16:9	16:9	Embedded media, posters, and standard widescreen content

Responsive Ratio Usage

Pattern	Example	Use
Base only	`class="ratio ratio-3-2"`	Same ratio at all sizes
Change at small	`class="ratio ratio-1-1 sm:ratio-3-2"`	Square first, wider after small breakpoint
Change at medium	`class="ratio ratio-16-9 md:ratio-2-1"`	Smaller-screen media, larger-screen hero
Change at large	`class="ratio ratio-2-1 lg:ratio-3-1"`	Smaller-screen banner, desktop wide banner
Natural at large	`class="ratio ratio-4-3 lg:ratio-auto"`	Crop on smaller screens, natural ratio later

How to Use Image and Background Classes

Content image pattern

Use semantic <img> or <picture> when the image communicates meaning. The ratio wrapper controls the crop area, and the image fills that area.

<div class="ratio ratio-3-2">
  <picture>
    <source srcset="images/sample/main-demo-3-2-800x533.webp" type="image/webp">
    <img src="images/sample/main-demo-3-2-800x533.jpg" alt="Describe the image">
  </picture>
</div>

Decorative background pattern

Use background-image utilities when the image is decorative or part of layout styling. In the CSS, bg-img already gives you no-repeat, center, and cover as a starting point.

<div class="cb-imagebox ratio ratio-2-1 bg-img"
     style="background-image:url('images/sample/banner-demo-3-1-1200x400.jpg');">
</div>

Image and Background Utility Reference

Class	Purpose	Common Use
`.ratio`	Creates a ratio wrapper for media	Images, video, iframe, and picture-based crops
`.ratio-auto`	Returns to natural aspect ratio	Responsive overrides at larger breakpoints
`.bg-img`	Applies default background-image behavior	Reusable decorative image blocks
`.bg-cover`	Fills the box and crops as needed	Heroes, banners, decorative image blocks
`.bg-contain`	Shows the full image inside the box	Logos, diagrams, images that must not crop
`.bg-auto`	Uses the image’s natural background size	Special cases where scaling is not needed
`.bg-fill`	Stretches image to fill both axes	Rare; only when distortion is acceptable
`.bg-100-auto`	Sets width to 100% and height to auto	Width-led decorative scaling
`.bg-auto-100`	Sets height to 100% and width to auto	Height-led decorative scaling
`.bg-center`	Centers image crop	Most common default
`.bg-top-center`	Keeps crop higher in frame	Faces or subjects near top
`.bg-center-right`	Shifts crop toward right side	Subject positioned right
`.bg-no-repeat`	Prevents tiling	Most single-image backgrounds
`.bg-repeat`	Repeats the image	Patterns and textures
`.bg-repeat-x`	Repeats on the x axis only	Horizontal textures or decorative strips
`.bg-repeat-y`	Repeats on the y axis only	Vertical textures or side treatments
`.bg-fixed`	Uses fixed background attachment	Intentional visual effect only
`.bg-scroll`	Uses normal scrolling background attachment	Default scroll behavior
`.cb-imagebox`	Background-image demo/container block	Decorative image examples

Image Tag vs. Background Image

Feature	Using <img> / <picture>	Using background-image
Semantics	Semantic and recognized by assistive technologies	Presentation only; not read as content
Alt text	Supports meaningful `alt` text or empty decorative alt	No semantic image description available
Responsive handling	Supports `srcset`, `sizes`, and `<picture>`	Relies on CSS and media-query handling only
Best use	Content images, editorial media, photos that communicate meaning	Textures, decorative banners, and purely visual layout treatments

Best Practices for Image Sizing

Principle	Best Practice
Responsive sizes	Use images that match layout needs instead of oversized originals everywhere.
Avoid fixed sizes	Use fluid width and ratio wrappers instead of forcing fixed heights.
Correct resolution	Export multiple widths for larger layouts when image detail matters.
Compression	Use WebP first, with JPEG fallback when needed.
Zoom and scaling	Test at 200% browser zoom and on smaller screens.
Alt text	Use meaningful alt text for content images and empty alt for decorative images.
Text in images	Avoid when possible. Use real HTML text for accessibility and scaling.

Common Sizing Options by Use Case

Use Case	Recommended Widths	Suggested Ratios	Notes
Primary banner	1280, 1536, 2000	3:1 desktop, 2:1 smaller screens	Best for short banners and marketing banners.
Primary hero	1280, 1536, 2000	2:1 desktop, 16:9 smaller screens	Main hero system with a more controlled smaller-screen height.
Alternate hero	1280, 1536, 2000	5:2 desktop, 16:9 smaller screens	Use when slightly more image depth is needed.
Cinematic banner	1536, 2000	21:9	Use intentionally and sparingly.
Media / video image	768, 1280, 1600	16:9	Best for embedded media, video posters, and widescreen content.
Content image	560, 768, 1280	3:2, 4:3, 1:1	Use semantic image elements and let layout width control display size.
Card image	320, 480, 560, 768	1:1, 4:3, 16:9	Use predictable wrappers for consistency across repeated cards.