imagery

Assess and improve image usage so photography, illustrations, screenshots, icons, and uploaded media feel intentional, readable, and well-contained.

MANDATORY PREPARATION

Users start this workflow with /imagery. Once this skill is active, load $frontend-design — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow that protocol before proceeding — if no design context exists yet, you MUST load $setup first. Additionally gather: what role imagery plays here (brand, explanation, proof, decoration, content).

Consult the color and contrast reference when images create readability problems, need overlays, or should be harmonized with the palette. Consult the semantic color when imagery intersects with status, alerts, meaning, or tinted contextual surfaces rather than pure atmosphere. Consult the image treatment as the canonical shared source for overlays, screenshot sizing, icon scaling, media containment, and background bleed prevention. Consult the surface separation when images or media need cleaner separation from surrounding surfaces.

---

Assess Imagery Problems

Analyze where visual media is helping or hurting:

1. Photo quality and appropriateness:

   • Are the images high quality enough to support the intended brand?
   • Do they feel generic, mismatched, or obviously placeholder?

2. Text on images:

   • Is text readable over background images?
   • Are contrast problems caused by the image rather than the typography?

3. Screenshots and icons:

   • Are screenshots scaled so small they become illegible?
   • Are tiny icons being enlarged beyond their intended visual size?
   • Are detailed icons being reduced until they turn mushy?

4. User-uploaded content:

   • Are user images breaking the layout with chaotic aspect ratios?
   • Are backgrounds bleeding into the interface?

5. Harmony:

   • Do photography, illustration, screenshots, and icons feel like part of the same product?

If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.

CRITICAL: Bad imagery can ruin an otherwise good design. Images should support hierarchy and communication, not create readability problems or visual chaos.

Plan Imagery Improvements

Create a plan around:

• Role: Is the image there for atmosphere, explanation, product proof, or user content?
• Containment: How should images be cropped, scaled, and framed?
• Readability: What needs to happen so overlaid text remains readable?
• Visual consistency: How should photos, illustrations, screenshots, and icons relate stylistically?

Improve Imagery Systematically

Use Appropriate Photos

• Use photos that genuinely match the product quality and audience expectations
• Avoid placeholder-quality imagery that drags the interface down
• Match the emotional tone of the product — playful, editorial, professional, etc.

Improve Text Contrast on Images

• Add overlays when the image dynamics are too extreme
• Lower image contrast when the text needs more consistent support
• Colorize images when that helps them harmonize with the brand palette
• Use a subtle text shadow only when it improves local readability without turning into an obvious effect

Screenshot Usage Rules

• Don’t scale full-app screenshots down until the interface becomes unreadable
• Prefer tighter crops, partial screenshots, or smaller-source-layout captures when detail matters
• If the goal is structure rather than detail, simplify the screenshot instead of cramming everything into tiny space

Icon Scaling Rules

• Don’t blow small icons up far beyond the size they were drawn for
• Don’t shrink detailed icons until they become fuzzy or overly dense
• If you need larger visual presence, consider placing a smaller icon inside a larger shaped container instead

User-Uploaded Media Containment

• Force uploaded images into deliberate containers with consistent aspect ratios
• Use cover-style cropping when preserving raw dimensions would damage the layout
• Accept that containment matters more than preserving every edge of the original upload

Bleed Prevention

• When images blend into the page background, add a subtle inner shadow or inner border
• Prefer understated containment; a loud border often fights the image itself

Illustration / Photo Harmony

• Keep illustration style consistent across the product
• Make sure illustrations and photography don’t feel like they come from unrelated brands
• If mixing photos and illustrations, unify them through palette, framing, or usage context

NEVER:

• Put unreadable text on a busy image and blame the type
• Use screenshots so small users want to zoom in with their eyeballs
• Enlarge tiny icons until they feel chunky and amateurish
• Let user-uploaded images dictate layout shape
• Mix photographic, illustrative, and icon styles with no unifying logic

Verify Imagery Quality

• Readability: Is text on imagery consistently legible?
• Containment: Do uploaded and editorial images stay within the layout gracefully?
• Scale: Are screenshots and icons shown at sensible sizes?
• Harmony: Do all visual media feel like part of one system?
• Appropriateness: Does the imagery match the product’s quality and personality?

Remember: Imagery should support the design’s message and hierarchy. When it starts fighting the UI, the image treatment needs work.