imagery

Use this skill whenever a design calls for images — hero/cover backgrounds, feature, gallery, or card images, team photos, product shots — and before every generate_images call.

1. Plan all imagery first. While planning a page or theme, list every image it needs: filename, subject, placement, aspect ratio. Call generate_images BEFORE writing the markup that references them: it returns each image's path, attachment ID, and URL at once and generates the images in the background, so write the markup right away.
2. Pick the destination by where the image is shown: the file that holds its markup decides, not what the image depicts.
   • Content imagery: every image shown by page or post content, including a page's hero or cover, section images, products, team photos, and galleries. Write to <site>/wp-content/uploads/<name>.png. The tool adds every image under wp-content/uploads/ to the media library and reports its attachment ID and URL: use the URL as the src and the ID in the block attrs (e.g. wp:image {"id":<id>,"sizeSlug":"large"}).
   • Theme imagery: only images shown by theme files, meaning a template, a template part such as the header or footer, or style.css. Write to <site>/wp-content/themes/<theme-slug>/assets/images/<name>.png and reference it in markup as /wp-content/themes/<theme-slug>/assets/images/<name>.png. It stays in the theme and never goes into the media library. One call can mix both: each image goes where its path says. A one-page site builds its sections in the page content, so its images, hero included, are content imagery.
3. Batch aggressively. One generate_images call per page (or per site for small sites) with every image in the images array — generation is concurrent server-side. Never one call per image. The site's set from the design steps below is the first batch: use it before generating anything else.
4. Write real alt text. Generated images are content: give every <img> a short, descriptive alt in the markup (what the image shows, for a person who cannot see it). Never leave a spec string or an empty alt on a content image; cover backgrounds keep an empty alt (decorative).

Every image in the images array takes path, subject, pageContext, style, aspectRatio. The call also takes a shared siteContext and imageGrade.

The look is picked on one image and the layout on a set, both from the site-spec skill's design steps:

• The look image: before the look options, one generate_images call with a single image, the site's first-screen scene in landscape, at <site>/wp-content/uploads/<scene>.png, with the call-wide imageGrade left out and a neutral, versatile grade in pageContext ("natural light, true color, moderate contrast"). Pass the path it reports as each look's image. Every look's board shows this same photo under that look's imagery treatment from its DESIGN.md draft, so the user compares looks rather than photo content. A direction that rejects photography (its Imagery line says none, or type-only) passes no image: its board shows a pattern.
• The site's set: once DESIGN.md is written, one generate_images call with 3–4 images in the picked look, with its Imagery section as the call-wide imageGrade and its style if it is not photographic: the first-screen scene again plus distinct supporting subjects (a detail, a place or a person, a product), each in the aspect ratio of the slot it is most likely to fill, at <site>/wp-content/uploads/<name>.png. The set is content imagery: the layout sneak peeks use the paths it reports, and the build starts from its attachment IDs and URLs. When a template or template part needs one of its images, copy that file into the theme's assets/images and reference the copy. Generate more only for slots the set cannot fill, with the same imageGrade. The look image is in the media library too, for a look its treatment reproduced.
• A failed or unavailable image is not a blocker: the board shows a pattern, and a sneak-peek slot a solid color shape.

When generate_images is not available but you have an image tool of your own (such as image_gen), make the same images with it, including the look image and the site's set below: plan them exactly as above, and write what you would pass as siteContext, pageContext, style and imageGrade into each image's prompt, with no text in the image. Then put each file where its destination says:

• Content imagery: copy the files into the site's tmp/ folder and import them in one wp_cli call, media import tmp/<a>.png tmp/<b>.png --porcelain, which prints their attachment IDs in order; post list --post_type=attachment --post__in=<ids> --fields=ID,guid gives their URLs.
• Theme imagery: copy the file to its path in the theme's assets/images.

For the look image, pass the file where your tool saved it as each look's image; import it only if the site uses it.

Generated imagery is for CONTENT — covers, feature/gallery/card images, photographic bands. Never generate decorative assets: no ornaments, flourishes, crests, stamps, icons, or logo marks. They come out off-palette and geometrically wobbly, and small raster icons turn to mush. Decoration comes from theme primitives (separators, borders, spacing, type); feature icons: use none — let type and layout carry the hierarchy.

For wp:cover backgrounds, set the same image URL on BOTH the block's url attribute and the inner <img> src. Wide cover images (landscape/ultrawide) are generated at 2K automatically.

• Safety-filtered image: rewrite that image's subject to avoid the flagged element and call generate_images again for just that image. One retry; if it fails again, treat as a permanent failure.
• Permanent failure: adapt the layout to work without that image (a color/gradient background, a text-led card). NEVER substitute an unrelated image, source an image from a web URL, or leave a reference to a file that does not exist.
• Failures arrive after the call returns, with a later tool result; take_screenshot, inspect_design, and present_design_options wait for the images.