Table of contents
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
ADR 0046: Progressive Media Loading with Structural Skeletons
Status: proposed Date: 2026-06-07
Context
Memories is a media-heavy application. The primary interaction — browsing a photo timeline — demands fast visual feedback. Users tolerate brief loading states, but only when those states communicate something useful. A blank screen or generic spinner erodes trust. A wall of identical gray rectangles is slightly better but still disorienting: the user cannot preview the structure of what is coming.
After the UX Overhaul (spec 006), two loading deficiencies became apparent:
-
No progressive image loading. Media tiles went from skeleton placeholder directly to full quality. On slow connections, this created a visible "pop-in" jump. The previous implementation had used blurred 512px thumbnails as intermediate placeholders, and this was lost in the redesign. Spec 013 and ADR 0045 address the component-level fix (
ProgressiveImage.sveltewith blur→HQ dual-layer crossfade). -
Generic skeletons that ignore data structure. The timeline skeleton rendered three identical gray bars regardless of how many days or items the API would return. Search, Explore, and Albums pages used similar generic patterns. This causes layout shift when real data arrives and gives users no preview of the content's actual shape.
The backend already produces both derived asset sizes per media item (thumbnail at 512×512 and
preview at 2048×2048), and API responses include both URLs. The infrastructure for progressive
loading exists; the frontend must use it consistently.
Decision
Memories adopts two complementary loading strategies as permanent UX principles. This ADR establishes the strategy and design rules; ADR 0045 establishes the component implementation for the blur→HQ image swap.
1. Low-Quality Image Placeholders (LQIP) as First-Class Loading Strategy
Every image in the application loads in two stages:
| Stage | Asset | Timing | Visual |
|---|---|---|---|
| Immediate | Blurred 512px thumbnail (thumbnailUrl) |
Shown as soon as tile enters viewport | Soft, recognizable preview |
| Deferred | Sharp 2048px preview (previewUrl) |
Swapped in when browser finishes decode | Crisp final image |
Rules:
- The blurred thumbnail must be displayed whenever
thumbnailUrlis available, regardless ofpreviewStatus. A blurry photo is always better than a gray box. - The HQ swap uses an opacity crossfade, not a hard cut. Duration: 200–300ms.
prefers-reduced-motion: reducedisables the crossfade; HQ replaces thumbnail instantly.- Both layers use identical
object-cover/ fixed aspect ratio to prevent layout shift (CLS = 0). - Lazy loading (
loading="lazy",decoding="async") applies to both<img>elements. - The
ProgressiveImage.sveltecomponent (ADR 0045) encapsulates this pattern. Pages provide URLs and readiness state; the component handles layers, transitions, and accessibility.
Scope of application:
| Context | Thumbnail source | Notes |
|---|---|---|
| Timeline media grid | item.thumbnailUrl |
Core path, most frequent |
| Media detail viewer | detail.thumbnailUrl or tile's pre-loaded thumbnail |
Opens instantly if tile was visible |
| Explore — People | Face thumbnail endpoint (/api/media/{id}/faces/{faceId}/thumbnail) |
Different URL pattern, same component |
| Explore — Albums, Places, Plants | coverAsset.thumbnailUrl |
Album cover progressive load |
| Album detail grid | item.thumbnailUrl |
Same as timeline via MediaGrid |
| Search results | item.thumbnailUrl |
Inherits MediaGrid behavior |
2. Structurally-Accurate Skeletons
Skeleton UI must mirror the actual data structure that will replace it. Generic placeholders that bear no resemblance to the final layout are not acceptable.
Design principles:
- Correct count. If the API will return 5 day sections, show 5 skeleton sections. If a day has 12 items, show 12 skeleton tiles (capped at a viewport budget to avoid excessive DOM nodes).
- Correct shape. Day sections show a heading skeleton (eyebrow bar + title bar + count badge) followed by a tile grid. Card views show card-shaped skeletons (image area + text lines). Detail views show metadata-field skeletons matching the actual field layout.
- Correct proportions. Tile skeletons use the same aspect ratio as real tiles (4/3 for media, 1/1 for face thumbnails). Grid skeletons use the same column breakpoints as the real grid.
- Progressive fill. Once data arrives, loaded items replace their skeleton counterpart immediately (showing blurred thumbnail), while remaining items stay as skeletons until their data loads. This means a partially-loaded view shows a mix of real thumbnails and skeleton tiles.
View-specific skeleton designs:
Timeline (TimelineSkeleton.svelte)
- Input:
days[]array fromTimelineDaysPageAPI (each withkey,label,eyebrow,itemCount). - Structure: per-day section with eyebrow bar + title bar + count badge, then responsive tile grid (3/4/6/8 columns by breakpoint).
- Tile cap: maximum 20 tiles total across all days, distributed proportionally by
itemCount. Last day absorbs rounding remainder. - Fallback: when
daysis empty (API not yet responded), show 3 generic day sections with 8–12 tiles each.
Explore page
- Each section (People, Places, Albums, Plants) renders its own skeleton matching its card shape.
- People: circular avatar skeleton + name bar + count bar.
- Places/Albums/Plants: square card skeleton + title bar + subtitle bar.
- Section headers: eyebrow text bar + heading bar.
- Real implementations already follow this pattern (
explore/+page.sveltelines 219–252).
Media detail viewer
- Layout skeleton: centered image placeholder (60% width, rounded) + metadata sidebar.
- Metadata fields: 6–8 horizontal bars of varying widths matching the field layout (title, date, camera, location, tags, people, etc.).
- Real implementation follows this pattern (
MediaDetailViewer.sveltelines 1048–1065).
Search results
- Filter chips: 3 small pill-shaped bars.
- Results grid: responsive tile grid matching MediaGrid column breakpoints.
- When no results: empty state, not skeleton.
Map view
- Grid of square thumbnails (1/1 aspect ratio) in a 3-column layout.
3. Interaction Between LQIP and Skeletons
The two strategies compose. A typical page load follows this sequence:
1. Navigation triggers data fetch.
2. Skeleton renders immediately (structural, data-aware).
3. API response arrives → skeleton partially replaced by blurred thumbnails.
4. Thumbnail images decode → blurred previews visible within ~100ms of tile paint.
5. HQ preview images decode → crossfade from blur to sharp over 200–300ms.
Steps 2–4 happen within the first second on most connections. Step 5 completes within 2–5s depending on image size and connection speed. At no point does the user see a generic spinner or experience unexplained layout shift.
Alternatives Considered
| Option | Summary | Benefits | Costs / Risks |
|---|---|---|---|
| A: Full-resolution only (no LQIP) | Show skeleton until full-quality image loads | Simpler implementation | Long blank periods on slow connections; visible pop-in; high CLS |
| B: Generic skeletons (no structural awareness) | Single spinner or uniform gray blocks | Minimal development effort | No structural preview; layout shift on data arrival; disorienting |
| C: Placeholder color averaging | Extract dominant color from EXIF/thumbnail, show solid color block | Better than gray | Requires backend pre-processing; no structural information; blurred thumbnail is strictly superior |
| D: Skeleton-free progressive load | Skip skeleton, show blurred thumbnail immediately when available | Fastest visual feedback | No structural preview during initial fetch; first paint is unpredictable shape |
Option D is the closest runner-up and is partially adopted: pages that already have cached thumbnail URLs (e.g., tile click → detail view) skip the skeleton and show the cached blurred thumbnail instantly. But for initial page loads where no thumbnail URLs exist yet, a structural skeleton remains necessary.
Consequences
- Reduced perceived load time. Users see recognizable content structure within 200ms and blurred image previews within 1s, even on slow connections.
- Zero layout shift. Fixed aspect ratios on both skeleton tiles and progressive image layers eliminate CLS as a loading concern.
- Consistent pattern across the app.
ProgressiveImage.svelte(ADR 0045) provides one component for the blur→HQ swap. Skeleton designs follow documented per-view rules. New pages inherit the pattern without reinventing it. - Skeleton maintenance cost. Each view's skeleton must be updated when the view's data structure changes. This is a conscious trade-off: accurate skeletons provide real UX value, but they couple skeleton markup to API response shape.
- No backend changes required. The backend already serves both
thumbnailUrlandpreviewUrl. No new endpoints, no new derived assets, no new worker capabilities. - Slight memory overhead. Two images loaded per visible tile (512px blur + 2048px sharp). The blurred thumbnail is small (~30–80KB JPEG) and evicts naturally under memory pressure.
Revisit Triggers
Revisit this ADR if:
- Thumbnail generation moves to a different pipeline or changes resolution/format (currently 512×512 JPEG);
- The backend stops serving
thumbnailUrlseparately frompreviewUrl; - A new view type (e.g., immersive slideshow, VR gallery) requires a fundamentally different loading strategy;
- Browser
fetchpriorityorPriority HintsAPI adoption makes manual preload ordering obsolete; - AVIF/WebP adoption changes the progressive decoding characteristics significantly enough to alter crossfade timing.
References
- ADR 0045: ProgressiveImage Shared Component Pattern — the component-level implementation of the blur→HQ dual-layer swap.
- Spec 013: Progressive Image Loading (
specs/013-progressive-image-loading/spec.md) — the implementation spec covering R1–R6 requirements and AC1–AC8 acceptance criteria. - Spec 006: UX Overhaul (
specs/006-ux-overhaul/spec.md) — the redesign that introduced the current skeleton-based loading and identified the progressive loading regression. TimelineSkeleton.svelte:apps/web/src/lib/components/skeleton/TimelineSkeleton.svelte— the first structurally-aware skeleton, acceptingdays[]with proportional tile distribution.ProgressiveImage.svelte:apps/web/src/lib/components/ProgressiveImage.svelte— shared blur→HQ component per ADR 0045.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference