lazy-loading done

openspec/changes/archive/2026-02-10-lazy-loading/specs/image-lazy-loading/spec.md

@@ -0,0 +1,50 @@
+## ADDED 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 × 180px height for card thumbnails) with no layout shift when the image loads