## 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