astro-website/openspec/specs/responsive-image-delivery/spec.md

Purpose

Define responsive image delivery requirements that reduce layout shift and improve deterministic performance outcomes for Lighthouse.

Requirements

Requirement: Card thumbnails have explicit dimensions

All card thumbnail images MUST include explicit width and height attributes matching the rendered aspect ratio.

Scenario: Thumbnail dimensions are present

• WHEN a crawler or browser loads a listing surface with content cards
• THEN each card thumbnail <img> includes width and height attributes

Requirement: Above-the-fold imagery is optimized

The site MUST ensure above-the-fold images are optimized for performance:

• avoid unnecessarily large image payloads for the requested viewport
• prefer modern image formats when first-party controlled
• avoid layout shift caused by late image dimension discovery

Scenario: Above-the-fold images do not cause layout shift

• WHEN a user loads the home page on a mobile viewport
• THEN the hero/top content area does not shift vertically due to image loading

Requirement: Third-party image variability is controlled for the Lighthouse gate

If a gated page depends on third-party images (e.g., external thumbnails), the gate MUST either:

• ensure those images do not block reaching 100s by design (e.g., not above-the-fold, lazy-loaded), or
• provide a first-party controlled alternative for gated pages.

Scenario: Gated pages avoid third-party image volatility

• WHEN Lighthouse runs against the gated URL set
• THEN third-party image delivery does not prevent meeting the required scores