lighthouse fixes

openspec/changes/archive/2026-02-10-lighthouse-fixes/specs/responsive-image-delivery/spec.md

@@ -0,0 +1,29 @@
+## ADDED 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