Choosing Three Image Variants: thumb, display, and full
The gallery pipeline uses Sharp to produce 720, 1600, and 2560px WebP files. The point is not magic numbers, but matching real UI contexts.
Image optimization gets fuzzy when the first question is "how small can this be?" The better question is "where will this image appear?"
For the gallery I chose three variants:
| Variant | Width | Quality | Use |
|---|---|---|---|
thumb | 720 | 70 | Grid cards and quick previews |
display | 1600 | 76 | Lightbox viewing |
full | 2560 | 82 | Larger inspection and detail |
Why Not Keep One File
A single large image is convenient, but it wastes bandwidth in the grid. A single small image is fast, but it falls apart in the lightbox. The three-variant setup lets each UI surface load the asset it actually needs.
thumb is for speed, display is for comfortable viewing, and full is for people who intentionally ask for a larger version.
Why WebP
WebP is a good fit for photographic content, and browser support is mature. The script uses Sharp to normalize source images into WebP, with smartSubsample enabled so the output stays clean without tuning every file by hand.
It also calls rotate() so EXIF orientation is baked into the pixels before the site ever sees the image.
Blur Placeholders Belong Here Too
The same processing step creates a tiny WebP, at most 24px wide or tall, and stores it as a base64 Data URL. It is small enough to live in YAML, and it gives the page a soft placeholder while the real image loads.
Takeaway
The three variants keep the boundary clear: light by default, sharp when opened, detailed only when requested. Once that boundary exists, upload, caching, and content generation become much easier to reason about.