Image Guidelines

Use Good Photos

• Bad photos make everything look unprofessional
• Use high-quality stock photos or hire photographer
• Good free sources: Unsplash, Pexels

Text Needs Consistent Contrast

Problem: Text on images can be illegible

Solutions:

1. Add overlay: Dark semi-transparent layer between image and text
2. Lower image contrast: Reduce saturation and brightness of background
3. Colorize image: Apply color filter to reduce contrast
4. Add text shadow: Subtle shadow makes text readable on varied backgrounds
5. Blur background: Use gaussian blur on area behind text

Everything Has an Intended Size

Icons and graphics:

• SVGs can scale but not infinitely
• Small icons blown up look amateurish
• Design at the size you'll use them

Don't scale up:

• Icons designed at 16-24px shouldn't be used at 48px+
• Screenshots lose quality when enlarged
• Product photos should be high-res

Don't scale down unnecessarily:

• Large graphics scaled way down are wasteful (file size)
• Use appropriate size assets

What to do instead of scaling

Every asset was drawn for a size, and the fix is never to stretch it. Each case has its own move:

• A small icon that must fill a large space: keep the icon at its own size and put it inside a larger colored circle or rounded square. The shape fills the space, the glyph stays crisp, and the tint carries the meaning that a blown-up outline would have lost.
• A screenshot of a full desktop UI: capture a smaller viewport, or crop to the one region the reader needs. Shrinking a whole desktop capture to fit a column turns the interface into unreadable texture. Where even a crop would not read, draw a simplified illustration of the UI instead.
• A logo used as a favicon: redraw a simplified mark at the target size. Letting the browser downscale detailed artwork produces mush at exactly the size people identify the tab by.

// ✅ 16px glyph housed in a 48px tinted circle
<span className="flex size-12 items-center justify-center rounded-full bg-blue-100 text-blue-800">
  <ListIcon className="size-4" />
</span>

// ❌ Same glyph stretched to fill the space
<ListIcon className="size-12" />

Overlapping Images Need a Visible Gap

Two photos that overlap merge into one shape, because nothing marks where the top image ends and the one beneath it starts. The eye reads a single ragged block rather than two layered pictures.

Give the top image a border in the page background color. It reads as empty space rather than a frame, so it guarantees the gap without adding a visible edge:

/* The border matches the surface behind, so it reads as a gap, not a frame. */
.stack img + img {
  border: 4px solid var(--background);
}

Use the token, never a hardcoded value, or the trick inverts the moment the theme changes: a light border against a dark page stops being invisible and becomes exactly the frame you were avoiding. The same applies when the images sit on a card rather than the page, where the border takes the card's color instead.

This is the separation cue for overlapping layers. It is distinct from the hairline in docs/ui/depth-and-surfaces.md, "Outline Images for Depth", which stops one image bleeding into the background behind it. An overlap that also needs an edge takes both: the page-colored border for the gap, the inset hairline for the edge.

Beware User-Uploaded Content

Problems:

• Unpredictable dimensions
• Variable quality
• Can break layouts

Solutions:

Control background:

• Use consistent background color/pattern
• Centers mismatched images

Center-crop:

• Use object-fit: cover
• Crops to fill space
• Best for thumbnails and avatars

Avatars:

• Use fallback (initials) for missing photos
• Makes interface feel more complete

Editorial Diagrams Use the Scribble System

All public editorial graphs, schemas, process diagrams, and decision trees use one AI-generated visual language. This is the source of truth for future generations.

Art direction:

• Warm off-white sketchbook paper with subtle natural grain
• Charcoal-pencil and black-ink scribbles with imperfect doubled outlines
• Rough, clearly directed arrows and hand-drawn note shapes
• Restrained accents in blue, green, purple, and orange
• Large, high-contrast labels with every text block left-aligned
• Generous margins and a landscape 3:2 composition for article use
• No logos, watermarks, gradients, glass effects, photorealism, tiny text, or decorative clutter

Canonical generation prompt:

Use case: infographic-diagram
Asset type: responsive editorial diagram for a Better Design article
Scene/backdrop: warm off-white sketchbook paper with very subtle natural paper grain.
Style/medium: refined charcoal-pencil and black-ink scribble, imperfect doubled outlines, rough arrows, professional editorial notebook aesthetic. Use small muted accent touches in blue, green, purple, and orange.
Composition/framing: landscape 3:2 composition with generous outer margins. Keep EVERY text block LEFT-ALIGNED. Use large readable lettering.
Text (verbatim): <list every required label and sentence in quotation marks>
Constraints: render every quoted phrase exactly once and verbatim; no additional words; no logos; no watermark; no photorealism; no centered body copy; strong readable contrast.
Avoid: polished vector geometry, gradients, glass effects, stock illustration, tiny type, misspellings, decorative clutter.

Add only the diagram-specific structure: clockwise loop, left-to-right path, branching decision, or another truthful relationship. Do not change the shared style lines.

Implementation and review:

• Keep the title, supporting description, and complete ordered content in semantic HTML. The bitmap is the visual explanation, not the only source of meaning.
• Give the image a concise alt description and retain the detailed steps in screen-reader-only markup.
• Inspect every generated asset at full size. Reject misspelled, duplicated, omitted, centered, or invented text.
• Render the image directly in the article body with the shared brand radius applied to the image itself. Do not add an outer card, border, tinted surface, inset padding, or another frame around the generated artwork; rely on spacing and alignment to keep the figure together.
• Store final assets under the relevant packages/web/public directory and reference them through next/image.
• Use responsive image sizing and never make an editorial diagram create page-level horizontal scrolling.

Checklist

• Ensure consistent contrast for text on images
• Use appropriate-sized assets (don't scale up icons)
• Small icons housed in a colored shape, screenshots cropped or captured small, favicons redrawn simplified
• Overlapping images separated by a border in the page background color
• Handle user content gracefully (center-crop, fallbacks)
• Use high-quality photos only
• Match the canonical scribble system for editorial diagrams
• Verify generated diagram text verbatim and keep a semantic HTML equivalent