3.0 KiB
Purpose
Define a consistent lazy-loading experience for images by showing a shimmer placeholder while images download, fading in images on load, and degrading gracefully on failures.
Requirements
Requirement: Shimmer placeholder while images load
Every site image that uses loading="lazy" MUST display an animated shimmer placeholder in its container while the image is downloading.
The shimmer MUST be a translucent gradient sweep animation that matches the site's dark theme.
The shimmer MUST be visible from the moment the page renders until the image finishes loading.
Scenario: Image loads successfully on slow connection
- WHEN a page renders with a lazy-loaded image and the image takes time to download
- THEN the image container displays an animated shimmer placeholder until the image finishes loading
Scenario: Image loads from browser cache
- WHEN a page renders with a lazy-loaded image that is already in the browser cache
- THEN the image displays immediately with no visible shimmer flicker
Requirement: Fade-in transition on image load
When a lazy-loaded image finishes downloading, it MUST fade in smoothly over the shimmer placeholder using a CSS opacity transition.
The fade-in duration MUST be short enough to feel responsive (no longer than 300ms).
Scenario: Image completes loading
- WHEN a lazy-loaded image finishes downloading
- THEN the image fades in over approximately 200-300ms, replacing the shimmer placeholder
Requirement: Graceful degradation on image load failure
If a lazy-loaded image fails to load (network error, 404, etc.), the shimmer animation MUST stop and the placeholder MUST remain visible as a static block.
The page MUST NOT display a broken image icon.
Scenario: Image fails to load
- WHEN a lazy-loaded image triggers an error event (e.g., 404 or network failure)
- THEN the shimmer animation stops and the container displays a static placeholder background instead of a broken image icon
Requirement: Reduced motion support for shimmer
The shimmer animation MUST be suppressed when the user has prefers-reduced-motion: reduce enabled.
When motion is reduced, the placeholder MUST still be visible as a static block (no animation), maintaining the loading indicator without motion.
Scenario: User has reduced motion enabled
- WHEN a user with
prefers-reduced-motion: reduceviews a page with lazy-loaded images - THEN the placeholder is visible as a static block without any sweeping animation
Requirement: No layout shift from shimmer
The shimmer placeholder MUST NOT cause any cumulative layout shift (CLS). The placeholder MUST occupy the exact same dimensions as the image it replaces.
Scenario: Placeholder matches image dimensions
- WHEN a page renders with a shimmer placeholder for a card thumbnail
- THEN the placeholder occupies the same width and height as the image area (e.g., 100% width x 180px height for card thumbnails) with no layout shift when the image loads