blog-hero-images git:20261005.0cb9d7fA

Immutable. This exact content never changes and is served at /api/v1/blob/9197003d334a3d4c.

---
name: blog-hero-images
description: Art-direct and generate DanLevy.net blog hero images plus compositionally matched square thumbnails. Use for analyzing a target post, exploring 3-5 varied visual concepts, generating wide and square image families, or updating post image frontmatter.
---

# Blog hero images

Create an image family that explains the post's idea at a glance. Treat the wide hero and square thumbnail as two compositions of the same concept, not an arbitrary crop and not unrelated artwork.

Default to Paper atelier as an editorial medium, with mature paper cut-outs, collage, printmaking, or tactile photography. It is not a fixed ivory/blue/terracotta palette or an architectural-model template. Let the article determine subject, color, scale, lighting, and composition. A batch must feel like distinct artworks from one thoughtful publication, not product shots from one catalog. Compatible object photography remains welcome. Read the refined composition, dark-mode, and acceptance guidance in `references/visual-language.md`.

Use the requested image generation tool, or the best available one, for raster generation. If the user named a tool or model, use it. Otherwise pick the strongest image generator available in the current environment, and say which one you chose before generating. Read `references/visual-language.md` before writing prompts. Read the target `index.mdx` in full and inspect its existing images before generating anything.

## Workflow

1. Resolve the target post directory. Keep every project-bound image beside its `index.mdx`.
2. Read the post and write a private art-direction brief containing:
   - the one-sentence thesis
   - 3-7 concrete nouns or mechanisms in the post
   - 2-4 tensions, failures, or surprising reversals
   - visual cliches to avoid
   - any layout, palette, or subject constraints from existing assets
3. Inspect 2-4 relevant post image families. Prefer recent posts with similar subject matter or rhetorical shape. View contact sheets or individual images with whatever image-viewing tool the environment provides. Do not imitate one image closely.
4. Develop 3-5 candidate concepts before generation. Default to five when the user asks for a range. Each candidate must use a different metaphor or physical mechanism; changing color or rearranging the same objects does not count. Vary image-making modes where useful: photographed sculpture, cut photographic collage, torn-paper abstraction, ink/print textures, or an editorial scene. Do not force most candidates into the same studio photograph.
5. For each candidate, record a short concept name, the connection to the thesis, the image-generation prompt, and square-composition notes. Avoid a long pitch deck.
6. Generate each wide candidate with a separate image-generation call. Do not ask the model for a contact sheet. Generate art without baked-in title text, logos, watermarks, fake UI copy, or illegible labels.
7. Inspect every output. Reject candidates with generic AI imagery, accidental text, broken causal logic, weak focal hierarchy, or a subject that cannot survive a square composition. If fewer than three credible candidates remain, generate replacements.
8. Present the viable candidates with filenames and a concise recommendation. If the user has not chosen a winner, stop before creating finals unless they explicitly authorized autonomous selection.
9. For the selected concept, generate a fresh square image using the wide image as a reference. Preserve the central metaphor, materials, palette, lighting, and recognizable objects. Recompose for 1:1. Do not merely center-crop unless the source already has a crop-safe composition.
10. Save final sources beside the post as `wide.<source-ext>` and `square.<source-ext>`. Add `desktop-social.<source-ext>` when the post uses `social_image` or the user requests it. Target 1600x900, 800x800, and 1200x630 respectively when the generation path supports those dimensions.
11. Convert only the target post directory with `bun run webp-images -- <post-directory>`. The command removes successfully converted source files.
12. Inspect the final wide and square files. Check that both read at small sizes, have no accidental text, and still communicate the same idea.
13. Update frontmatter only when requested or when creating the full asset set for a post:

```yaml
social_image: ./desktop-social.webp
cover_full_width: ./wide.webp
cover_mobile: ./square.webp
cover_icon: ./square.webp
```

14. Run `bun run content:check` after changing frontmatter. Report the final paths, selected concept, generation prompts, and whether the square was regenerated or cropped.

## Prompt construction

Write prompts as production briefs. Include:

- editorial purpose and target article idea
- central physical scene or metaphor
- objects and their relationships
- composition and focal point
- material, lighting, palette, and image-making mode
- crop or negative-space needs
- explicit exclusions

Use this skeleton only as needed:

```text
Editorial hero image for a technical essay about [thesis].
Depict [physical metaphor and relationship between objects].
Composition: [focal point, camera/framing, negative space, crop safety].
Visual language: refined editorial object photography, [specific tactile materials], warm neutral background, directional window or studio light, restrained palette with one purposeful accent.
The image should feel intelligent, tactile, and slightly wry rather than futuristic or corporate.
No words, labels, logos, watermarks, code text, floating holograms, glowing brains, or generic AI circuitry.
```

For the square derivative, name the wide image as a style and concept reference, then specify the recomposition:

```text
Create a square companion to the referenced wide hero. Preserve [metaphor, objects, materials, palette, lighting]. Recompose the scene around one strong central silhouette for a 1:1 thumbnail. Simplify peripheral detail rather than shrinking the wide composition. Do not add new narrative elements. No text or logos.
```

## Candidate diversity

The user rejected the first eight Paper atelier proposals as too conforming.
Their shared ivory stock, blue/rust accents, shallow three-quarter camera, and
folded engineering mechanisms created an assembly-line look. Do not repeat it.

For a batch of five or more, use at least three distinct palettes and three
composition/image-making modes. Change subject scale and density too. Judge
variety by looking at the whole contact sheet; separate prompts alone do not
prove diversity. A recurring cut edge or tactile quality is sufficient continuity.
Avoid making every technical subject into a gate, aperture, keyed slot, or tray.


Choose 3-5 lanes that fit the post. Do not force every lane into every job:

- tactile machine or test bench
- miniature physical system or logistics world
- editorial still life with evidence or operational residue
- restrained diagrammatic or print-like abstraction
- failure scene with an obvious physical consequence
- familiar non-technical system that mirrors the technical mechanism

At least one candidate should be simple enough to recognize at 200px. At least one may be stranger or riskier. Reject concepts whose explanation is more interesting than the resulting picture.

## File handling

- Keep exploratory files descriptive: `hero-candidate-01-<concept>.webp`.
- Never overwrite an existing final without explicit permission. Use `wide-v2.webp` and `square-v2.webp` when needed.
- Keep source generations until selection is complete. Remove nothing the user did not ask to remove.
- Prefer a regenerated square. Use ImageMagick cropping only for already crop-safe art or when the user explicitly wants a derived crop.

## Acceptance checks

- Read the visual mechanism at 200px and again at 96px. Remove peripheral props if the causal relationship disappears.
- Inspect wide and square on ivory (`#faf7f1`) and warm charcoal (`#211f1c`). Preserve edge separation and readable shadows; never fix contrast by tinting the entire image or laying a gradient over it.
- Check the wide image in a shallow 2.25:1 editorial feature as well as 16:9. Keep essential objects away from edges and preserve breathing room. Regenerate or change object positioning if the layout crop breaks the metaphor.
- Reject baked-in slogans, labels on props, fake handwritten notes, ornamental equations, incidental brand marks, and invented evidence. Let HTML titles and captions carry the language.
- Record `cover_alt` describing the actual objects and their relationship. Use `cover_credit` for real attribution when applicable; do not invent a photographer or quote.