generate-consistent-og-images

name

generate-consistent-og-images

description

How to generate share-imagery (OpenGraph banners, portraits, squares, tall WhatsApp/iMessage cards) for any Lossless site or splash page so the resulting images form a coherent visual family. Use whenever a site, splash, plugin page, or fundraise deck needs an OG image generated or refreshed; whenever the user says "make an og image", "generate a banner", "we need a share image", "regenerate banners across formats", "the unfurl looks stale"; whenever scaffolding a new Astro Knots site that doesn't yet have an `og:image` or a `DESIGN.md`; whenever per-page or per-component custom illustrative imagery is needed even if it deliberately departs from the OG-image canon. Encodes the pattern of (1) check / create a DESIGN.md following the Google Stitch open spec, (2) check / add an `imagery:` recipe block to that DESIGN.md, (3) call Ideogram v3 generate with every field locked except `prompt` and `aspect_ratio`, (4) save with the canonical naming convention, (5) treat WhatsApp + iMessage chat-preview as the primary share surface and other socials as secondary. The skill never sees an API key in source — `IDEOGRAM_API_KEY` lives in `~/.secrets` and is inherited from the shell, same pattern as the `crawl-fetch-ingest` skill.

Generate Consistent OG Images

Two variables per request: aspect ratio and a one-sentence prompt. Everything else — brand reference image, color palette, style type, negative prompt, seed, rendering speed, magic-prompt flag — is locked at the project's DESIGN.md level so every image in a set looks like it belongs in the same family.

When to use this skill

• A site, splash page, plugin page, or fundraise deck needs an OG image generated for the first time
• An existing OG image needs to be refreshed (rebrand, stale visual, new feature launch)
• A new format is needed alongside an existing one (e.g. you have banner but now need banner_tall for WhatsApp / iMessage)
• The user asks for "an image for this page" or "an image for this component" that may or may not follow the OG canon
• Scaffolding a new Astro Knots site that doesn't yet have a DESIGN.md at all
• "The link unfurl looks wrong" — the OG image is missing, off-brand, or in the wrong format

Philosophy (Lossless OG preference)

The Lossless Group optimizes share imagery for mobile chat previews — iMessage and WhatsApp first — and treats LinkedIn / Twitter / Bluesky / Slack as concentric rings around that target.

In practice this means:

• Tall aspect ratios get production attention, not just landscape banners. 3x4 (WhatsApp / iMessage default) and 2x3 (extra-tall) variants are first-class assets, not afterthoughts.
• Subject lives in the lower portion of the frame by default so the top half stays clean for the receiver's preview crop (chat platforms aggressively top-crop tall images).
• The 1200×630 OG-canonical banner is one format among several, not the only target. Other social-specific banners (LinkedIn portrait, Twitter Card) are still produced when needed, but never at the expense of a polished tall variant.

This shapes the aspect-ratio enum below and the naming convention.

Prerequisites

IDEOGRAM_API_KEY in ~/.secrets

Same pattern as the crawl-fetch-ingest skill: keys never live in source.

# ~/.secrets (chmod 600)
export IDEOGRAM_API_KEY="..."

# ~/.zshenv adds one line (already in place if other Lossless skills work)
[ -f ~/.secrets ] && source ~/.secrets

No MCP server is required. Ideogram's v3 endpoint accepts a direct HTTPS request with Api-Key header. Bash + curl is enough. If a future MCP wrapper is preferred, register it the same way the firecrawl/tavily wrappers are registered in crawl-fetch-ingest's setup.md — but it's not necessary for this skill.

A target project with a known visual identity

The skill assumes the project has some established aesthetic. If it doesn't — brand-new site, no design decisions yet — that conversation has to happen before image generation. Use the astro-knots skill or pair with the user on a Brand & Style first pass before invoking this one.

The flow

Five steps, in order. Steps 1–2 are setup the first time the skill runs against a project; steps 3–5 are the per-image work that repeats.

Step 1 — Check (or create) DESIGN.md

Look for DESIGN.md at the project root.

• If present: verify it has YAML frontmatter and the standard Google Stitch spec sections (Brand & Style, Colors, Typography, Layout, Elevation & Depth, Shapes, Components).
• If absent: hand off to the maintain-design-md skill to bootstrap one. That skill owns the canonical authoring flow, the spec mapping, and the scaffold template (templates/design-md-scaffold.md). Once a first-pass DESIGN.md exists, return here to add the imagery: extension and proceed.

The skill cannot proceed to image generation without a DESIGN.md because the imagery recipe (next step) references its color palette tokens.

Step 2 — Check (or add) the imagery: block to DESIGN.md

The imagery: block is outside the Google Stitch spec's standard token groups, but spec-compliant consumers preserve unknown top-level keys (per the spec's "Consumer Behavior for Unknown Content" table). It's safe to keep there as the single source of truth.

The canonical block lives at templates/imagery-block.yaml in this skill. Open that file, adapt three things to the target project, paste into the project's DESIGN.md frontmatter (after components:, before the closing ---):

Field	What to adapt
style_reference.path	The project's canonical hero/banner image. If the project has none yet, generate a one-off using a quick prompt + the project's colors: palette, save it, and use that as the reference for all subsequent runs.
color_palette.members	Map from the project's colors: tokens to Ideogram's color_hex + color_weight shape. Weight the surface background highest (0.4–0.5) and brand accents lower.
defaults.seed	Pick a fixed seed for the project. Any integer is fine; bump only when the canon shifts.

Everything else in templates/imagery-block.yaml — style_type: AUTO, magic_prompt: OFF, rendering_speed: QUALITY, the aspect_ratios enum, the negative_prompt set, the prompt constraints — is project-agnostic and should be copied verbatim. The whole point of locking those is that they don't vary across projects either.

API constraint worth knowing: style_type: AUTO is required whenever style_reference_images is uploaded. The v3 endpoint rejects DESIGN / REALISTIC / FICTION in that combination with the error "Please use AUTO or GENERAL style type with style_codes, style_reference_images or style_preset." The reference image carries the aesthetic; AUTO lets it through.

The matching prose section (## Imagery) belongs in the body of DESIGN.md immediately before ## Do's and Don'ts. The reference implementation in content-farm/splash/DESIGN.md is the canonical example.

Step 3 — Construct the request

Read the project's DESIGN.md imagery: block. The Ideogram request is built by:

1. Taking every field from imagery.defaults as-is.
2. Taking imagery.color_palette as-is.
3. Uploading the file at imagery.style_reference.path as style_reference_images.
4. Taking imagery.negative_prompt as-is.
5. Picking one entry from imagery.aspect_ratios for aspect_ratio — based on the user's stated target format (see § "The aspect-ratio enum" below).
6. Authoring one prompt for the prompt field — see § "Prompt convention" below.

No other field varies. If the user asks to vary something else (e.g., "use a brighter palette"), that's a DESIGN.md change, not a per-request override.

Step 4 — Call Ideogram v3 generate

The canonical curl call lives at templates/ideogram-request.sh. Substitute {prompt} and {aspect_ratio} and run. The script reads IDEOGRAM_API_KEY from the environment (~/.secrets).

POST https://api.ideogram.ai/v1/ideogram-v3/generate
Content-Type: multipart/form-data
Api-Key: $IDEOGRAM_API_KEY

The response carries a url for each generated image. Images expire on the Ideogram side; download immediately to the target project's public/ (or equivalent static asset directory).

Step 5 — Save with the canonical naming convention

ogimage__{Site-Name}--{Format-Or-Variant}.{ext}

• Site-Name — the project's canonical name in PascalCase or Hyphen-Joined-PascalCase: Content-Farm, Reach-Edu-Hub, Calmstorm-Decks, Perplexed.
• Format-Or-Variant — one of: Default, Banner, BannerTall, BannerTallMax, Portrait, PortraitTall, Square. Default aliases whichever format is the canonical share image (typically Banner).
• Extension: prefer .jpg per the open-graph-share-seo-geo skill's JPEG-over-WebP rule. Convert from Ideogram's PNG output with ffmpeg -i in.png -q:v 2 out.jpg (quality 2 is near-lossless and lands ~95 KB at 1200×630).

Example set for content-farm:

public/ogimage__Content-Farm--Default.jpg          # the canonical banner (also serves as style_reference)
public/ogimage__Content-Farm--Banner.jpg           # alias of Default
public/ogimage__Content-Farm--BannerTall.jpg       # WhatsApp / iMessage default tall
public/ogimage__Content-Farm--BannerTallMax.jpg    # dramatic-tall variant
public/ogimage__Content-Farm--Portrait.jpg         # LinkedIn portrait / IG feed
public/ogimage__Content-Farm--PortraitTall.jpg     # Stories / Reels / TikTok
public/ogimage__Content-Farm--Square.jpg           # avatars, square unfurls

If the image is destined for a CDN (per the open-graph-share-seo-geo skill's "host the OG image remotely" rule), upload there as well; the same file naming travels.

The aspect-ratio enum

Format key	Ideogram aspect_ratio	When to use
banner	16x9	Default share — OpenGraph, Twitter / X, Slack, generic
banner_tall	3x4	WhatsApp & iMessage chat-preview cards (the Lossless default tall)
banner_tall_max	2x3	Dramatic-tall variant; use when the subject genuinely benefits from height
portrait	4x5	LinkedIn portrait, Instagram feed post
portrait_tall	9x16	Instagram Stories, Reels, TikTok
square	1x1	Avatars, square OG fallbacks, Discord embeds

The keys live in imagery.aspect_ratios of the project's DESIGN.md; the values may differ if a project has a different target mix, but the format names stay the same across projects so cross-site automation can talk in one vocabulary.

Prompt convention

The prompt is the only free-text channel in the request. Two ingredients per prompt, nothing else:

1. Subject — what the image depicts. One short noun phrase. "Isometric sprout growing from a stack of paper-cut tiles", "Three nested transparent cubes drifting above a horizon line", "A spool of thread unwinding into a typeset block of characters".

2. Composition — empty space as a first-class subject. This is the rule that matters most for share imagery (where SVG overlay text needs clean room). Lead the prompt with the empty region — declare it explicitly, give it concrete content (a "dark gradient sky", a "muted atmospheric backdrop"). Then state what fills the bottom region. The model treats both clauses as renderings the sky is just as describable as the quill — and the subject can't grow into the overlay zone because the sky is already there.

   Bad framing (subject-first; produces 85%-tall subjects that swallow the overlay zone):

   "An isometric quill pen with paper-leaf feathers, growing from a stack of paper-cut card tiles, in the lower third of the frame, top two-thirds open."

   Good framing (empty-region-first, two clauses, explicit numeric split):

   "Top 1/3 of frame is empty negative space, dark gradient sky. Bottom 2/3 contains an isometric quill pen with paper-leaf feathers, growing from a stack of paper-cut card tiles."

   Three rules that survive aspect-ratio changes:

   • Lead with the empty region, not the subject. The first sentence describes what's empty and what content fills that emptiness (a sky, a backdrop, a gradient).
   • Use explicit numeric proportions ("top 1/3 / bottom 2/3"), never soft terms ("lower portion", "below the horizon").
   • Reinforce in negative_prompt with the specific failure mode you observe (e.g. subject in top half). The negative prompt isn't a substitute for the positive empty-region declaration — it's a belt alongside the positive suspenders.

   The underlying principle: empty space won't be left as residue. It has to be declared, named, and given content — otherwise the subject expands to fill the canvas. This was discovered empirically over iter1 → iter2 → iter3 on the Perplexed OG set; iter1 and iter2 used subject-first framing and produced subjects at 75-85% canvas height; iter3 used empty-region-first framing and produced subjects at 40-65% canvas height with the upper region genuinely empty.

Target ≤220 characters total. Past that, hard composition asks start losing to subject elaboration.

Forbidden in the prompt (already encoded via locked channels, never repeat):

• Brand names (Lossless, Content Farm, plugin names)
• Color words (cyan, dark, warm)
• Aesthetic adjectives (vibrant-minimal, build-in-public, monospace)
• Texture descriptors (paper-cut, isometric, atmospheric) — unless the subject genuinely requires them and the style reference image already establishes them as canon

Composition templates that survive aspect-ratio shifts cleanly. Note the two-clause structure — empty-region declaration first (with concrete content), subject placement second:

• Top 1/3 of frame is empty negative space, dark gradient sky. Bottom 2/3 contains {subject}.
• Left 1/3 of frame is empty negative space, soft atmospheric backdrop. Right 2/3 contains {subject}.
• Top half of frame is empty atmospheric gradient. Bottom half contains {subject}, centered horizontally.
• Top-right 2/3 of frame is empty negative space, dark muted sky. Bottom-left 1/3 contains {subject}.

When to break the rules (per-page / per-component custom imagery)

The locked recipe is for share imagery — the assets a third party sees when a link is unfurled. The user / team may also need:

• A hero illustration for a specific page or section
• An icon-like image for a component card
• A decorative asset embedded in long-form content
• A presentation slide background

These are legitimate departures from OG-image canon. They may use different palette weights, different aspect ratios, different style references, even a different style_type. When the user asks for one of these:

1. Confirm out loud that this is a display asset, not a share asset. ("Just so I have this right — this image is meant to live inside the page as illustration, not be the page's OG share preview. Is that correct?")
2. Author a prompt that's free of OG-image constraints — the "subject in lower third" rule doesn't apply when there's no SVG overlay to leave space for.
3. Pick the aspect ratio that fits the layout slot, even if it's not in the aspect_ratios enum (use Ideogram's resolution field instead of aspect_ratio for pixel-exact sizing).
4. Save outside the ogimage__ naming convention. illustration__Section-Name--Variant.jpg, hero__Page-Name.jpg, or whatever the project's local convention is — but never use the ogimage__ prefix, since that name implies the canonical recipe was followed.

The point: don't pollute the OG-image set with one-off custom imagery, and don't constrain one-off custom imagery with OG-image rules.

Two short worked examples

Example A — refreshing the splash's WhatsApp tall variant

User says: "Regenerate the WhatsApp tall card for content-farm."

# 1. Project: content-farm/splash. DESIGN.md exists, imagery: block exists.
#    No setup work needed.

# 2. Pick aspect ratio: banner_tall (3x4)
# 3. Author one-sentence prompt with subject + composition:
PROMPT="Top 1/3 of frame is empty negative space, dark gradient sky. Bottom 2/3 contains an isometric sprout growing from a stack of paper-cut tiles."

# 4. Call Ideogram (see templates/ideogram-request.sh):
bash templates/ideogram-request.sh "$PROMPT" 3x4

# 5. Download response[0].url, convert PNG → JPEG, save as:
#    public/ogimage__Content-Farm--BannerTall.jpg

Example B — bootstrapping a brand-new splash

User says: "I just scaffolded reach-edu-hub. Generate the OG banner."

# 1. Check for DESIGN.md at reach-edu-hub/ → absent
# 2. Pair with the user to author DESIGN.md from the spec:
#    - Frontmatter token groups (colors, typography, rounded, spacing, components)
#    - Eight prose sections in spec order
#    Reference: github.com/google-labs-code/design.md and
#               content-farm/splash/DESIGN.md as a shape example
# 3. No style_reference exists yet. Generate a one-off with only color_palette
#    + style_type=AUTO to seed the canon, save as the reference, then add
#    the imagery: block pointing at it.
# 4. Now run the canonical recipe across banner, banner_tall, portrait, square.

Preservation discipline — never replace prior runs

Ideogram generations are non-deterministic in composition (even with seed + every other parameter locked) and expensive in attention to curate. When we land a "good" image after multiple iterations, the prior candidates and the prior canonical pick are historical record worth keeping — they justify the final pick, document what was tried, and give a baseline if a future run drifts.

Two preservation layers:

Layer 1 — raw candidates auto-archive per run

The templates/ideogram-request.sh script writes each run into a fresh timestamped directory:

<project>/.ideogram-candidates/<subject>-<aspect>-<YYYYMMDD-HHMMSS>/
  candidate-0.png
  candidate-1.png
  candidate-2.png
  candidate-3.png
  response.json     ← Ideogram's echo: actual prompt, seed used, resolution, expired URL

The dot-prefixed parent directory (.ideogram-candidates/) sits outside the project's static-asset directory (public/, static/, etc.) so Astro / 11ty / Next / any static-site framework doesn't deploy 1.4MB PNGs to production. Per-run subdirs are timestamped → never overwritten across runs. Two BannerTall passes done an hour apart produce two distinct subdirectories.

Decide per project whether to .gitignore .ideogram-candidates/. Pro keeping in git: auditable history of every gen pass. Con: PNGs bloat repo size. Lossless default: keep in git unless the repo is shared with non-team contributors who'd be confused by the byte size.

Layer 2 — canonical JPEGs archive on replacement

The canonical-named files (ogimage__{Site}--{Format}.jpg) live in public/ because the splash needs them at deploy time. When you re-run the recipe and pick a NEW winner for the same format, don't overwrite the existing canonical file directly. Instead:

1. Move the current ogimage__{Site}--{Format}.jpg to <project>/.ogimage-archive/ogimage__{Site}--{Format}--{YYYY-MM-DD}.jpg (creating the archive directory if needed — also dot-prefixed, also outside public/).
2. Write the new pick to the canonical path.

# Pseudo-recipe — the actual ffmpeg step lives in your conversion script:
ARCHIVE="<project>/.ogimage-archive"
mkdir -p "$ARCHIVE"
if [[ -f "public/ogimage__Perplexed--BannerTall.jpg" ]]; then
  mv "public/ogimage__Perplexed--BannerTall.jpg" \
     "$ARCHIVE/ogimage__Perplexed--BannerTall--$(date +%Y-%m-%d).jpg"
fi
ffmpeg -y -i "<new-pick>.png" -q:v 2 "public/ogimage__Perplexed--BannerTall.jpg"

The unfurler URL stays stable (it's still …/ogimage__Perplexed--BannerTall.jpg); only the bytes behind it change. Old bytes survive in .ogimage-archive/ with a date stamp so you can A/B which version unfurled how.

Why both layers matter

• Raw candidates answer "what else did we generate that day?"
• Canonical archives answer "what did the splash actually serve last quarter?"

Without Layer 1, repeat runs erase candidates we considered. Without Layer 2, the splash's deployed history becomes irrecoverable as soon as you generate v2.

Anti-patterns

• Putting brand or palette words in the Ideogram prompt — that's what the locked channels are for. Repeating them in the prompt only dilutes attention budget for subject + composition.
• Varying magic_prompt across requests in a set — single biggest source of "why don't these match." If on for one, on for all (and expect more drift).
• Varying the seed across requests in a set — same logic. Different seeds = different interpretations of identical parameters. Fix the seed at the project level; only override when iterating one prompt at a time.
• Subject-first framing for overlay-bearing imagery. Saying "subject in the lower third" alone is not strong enough — the subject grows up into the overlay zone regardless. Lead the prompt with the empty region as its own renderable thing, give it concrete content (a "dark gradient sky"), and put the subject in the second clause. Reinforce in negative_prompt with the failure mode (subject in top half). Empty space won't be left as residue; it has to be declared, named, and given content. See the "Composition" subsection above for the full rule and the iter1→iter3 evidence that drove the refinement.
• Long negative prompts — each token competes with the positive prompt. Stay close to the seven-token canonical list in the template.
• Treating the 1200×630 OG banner as the only deliverable — Lossless ships WhatsApp / iMessage first. Always produce banner_tall alongside banner.
• Naming a one-off custom illustration with the ogimage__ prefix — that prefix means "the canonical recipe was followed." Custom imagery uses a different prefix; see § "When to break the rules".
• Authoring a new DESIGN.md by copying Content Farm's tokens — the shape of content-farm/splash/DESIGN.md is canonical (frontmatter groups, eight prose sections in order). The values (palette, fonts, sizes) belong to Content Farm and must be re-authored for each new project.
• Overwriting canonical OG JPEGs in place when re-running. See § "Preservation discipline" — archive the old one with a date suffix before writing the new one. The unfurler URL stays stable; the byte history is preserved.
• Putting raw candidates inside public/. Static-site frameworks deploy everything under public/ verbatim. ~16 MB of PNG candidates ships to GitHub Pages otherwise. Keep raw candidates at — dot-prefixed, outside .

See also

• templates/imagery-block.yaml in this skill — the canonical imagery: recipe block, ready to drop into a new DESIGN.md
• templates/ideogram-request.sh in this skill — the canonical curl invocation
• content-farm/splash/DESIGN.md — the canonical full-example of a Lossless DESIGN.md with both the standard Stitch sections and the imagery: recipe
• maintain-design-md skill — owns Step 1 of this flow when no DESIGN.md exists, plus the maintenance discipline (drift audits, when code changes should bounce back into the doc)
• open-graph-share-seo-geo skill — sibling skill on the delivery side: where to host the file, what HTTP headers it needs, JPEG-over-WebP rule, the og:image:type invariant, cache-busting recipes
• crawl-fetch-ingest skill — the precedent for the ~/.secrets pattern this skill borrows
• astro-knots skill — when scaffolding a new site that needs a DESIGN.md from scratch
• Google Stitch DESIGN.md spec — https://github.com/google-labs-code/design.md
• Ideogram v3 generate API — https://developer.ideogram.ai/ideogram-api/api-overview