imagery

name	imagery
description	Use when working with photos, icons, screenshots, or user-uploaded images. Covers picking quality photography, getting consistent text contrast over hero images, respecting an image's intended size (don't scale icons up, don't scale screenshots down), and defending layouts against unpredictable user-uploaded content.

Imagery

When to use this skill

• A page hero, marketing section, or product card has photography.
• Text needs to sit legibly on top of a photo.
• A landing page has small SVG icons being scaled up to fill features sections.
• A "screenshot" of the app is being shrunk to fit a marketing layout.
• The product accepts user-uploaded avatars, photos, or banners.

Core stance

Images either elevate a UI or destroy it. Treat photos as first-class assets (high-quality only), respect the size each image was drawn for, and don't trust user uploads to be reasonable.

Principles

1. Use professional or high-quality stock; never placeholders-then-snapshots. Bad photos drag down everything else, even if the layout, type, and color are perfect. Two viable paths:

• Hire a photographer for product-specific shots.
• Use a quality stock source (Unsplash, Pexels, etc.) for generic needs.

Don't design with stand-in images planning to "swap in real ones later" — designs assembled around bad photos get re-broken when good photos arrive.

2. Text over photos needs consistent contrast. Photos are dynamic — bright in some regions, dark in others. White text becomes invisible in light areas; dark text disappears in dark areas. The fix is to reduce the photo's range so contrast becomes uniform. Pick from these techniques (combine if needed):

• Semi-transparent overlay. A black overlay (rgba(0,0,0,0.55)) tones down light areas; a white overlay does the opposite. Simplest fix.
• Lower the image's contrast directly. Reduces the dynamic range without dimming everything; pair with a small brightness bump to compensate.
• Colorize the image. Lower contrast → desaturate → fill with a brand color in multiply blend mode. Useful when you also want the image to integrate with the palette.
• Text shadow as glow. Big blur radius, no offset, semi-transparent — creates a halo behind text that lifts it from busy backgrounds. Pair with a slight overall contrast reduction.

3. Every image has an intended size; respect it both ways.

• Don't scale icons up. A 16–24px icon blown to 48px looks chunky and undetailed because it lacks the strokes and shapes a 48px icon would have. If you only have small icons and need a larger feel, wrap them in a tinted circle/square — keeps the icon at native size while filling the space.
• Don't scale screenshots down. A full-resolution app screenshot shrunk to 30% has unreadable text and feels noisy. Better options:
  • Take the screenshot at a smaller device size (mobile, tablet) and use that.
  • Crop to a meaningful detail and show a partial UI.
  • Draw a simplified illustration of the UI — boxes and lines instead of real text.
• Don't shrink complex logos to favicon size. Browsers render the result as mush. Redraw a simplified logo at the target size.

4. User-uploaded content is hostile by default. You don't control aspect ratio, color, or quality. Two protections to apply:

• Lock shape and size. Render uploads as background images (background-size: cover) inside fixed-size containers. Crop the rest. Avatars, thumbnails, hero banners — any place layout matters.
• Prevent background bleed. When an uploaded image's edges color-match your background, the image visually melts into the page. Don't fix this with a colored border (clashes with photo content). Use a subtle inner box-shadow (box-shadow: inset 0 0 0 1px rgba(0,0,0,0.1)) or a semi-transparent inner border. The eye reads it as a defined edge without color conflict.

Quick reference

• Photo overlays for text legibility: rgba(0,0,0,0.55) for white text, rgba(255,255,255,0.55) for dark text.
• Icon at the wrong size? Wrap, don't scale.
• Screenshot too detailed for the slot? Use a tablet/mobile shot, crop to a region, or simplify-illustrate.
• User-uploaded image container: fixed dimensions + background-size: cover.
• Image-on-similar-bg edge fix: inset 0 0 0 1px rgba(0,0,0,0.1), not a hard border.

Attribution

Heuristics distilled from Refactoring UI by Adam Wathan & Steve Schoger (https://refactoringui.com). Independent skill package; not affiliated with or endorsed by the authors.