55 lines
3.0 KiB
Markdown
55 lines
3.0 KiB
Markdown
## 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: reduce` views 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
|