Og images
Three kinds of image that all do one job: make someone stop on a link and understand the app in a glance. Each is a real capture of the app with a large title, on the brand's field or a bright wallpaper. The UI is the hero. Nothing is drawn but the frame.
Outputs, in launch-assets/og/ of the user's repo:
| File | Size | What |
|---|---|---|
og.png | 1200×630 | The link preview for the home page. |
og-<id>.png | 1200×630 | Optional: one per page of a site, same design, title from that page. |
ph/01-<id>.png … 06 | 1270×760 | Product Hunt gallery, 4 to 6 slides. Slide 1 is the hero. |
x-header.png | 1500×500 | X header with the avatar and phone-crop zones clear. |
meta.html | The <meta> tags to paste into <head>. |
Sizes and safe zones, with sources and dates, are in references/sizes.md.
When to use
- A launch needs a share image, a Product Hunt gallery or an X header.
- The site's current
og:imageis a logo on a flat colour, or there is none. - A release changed the UI, so the previews are re-rendered from fresh captures.
Captures are Mac-style landscape windows or islands; a portrait phone screen is not supported by these cards. Not for: App Store screenshots (a different skill, with different sizes), or anything that needs UI the app does not have. This skill never draws UI.
Setup (once)
Node 20 or newer. Playwright goes into this skill's folder, not the user's repo:
npm install --prefix <skill-folder> [email protected] && npx --prefix <skill-folder> playwright install chromium
If it is missing, render.mjs prints this line and exits 2.
Step 0. Brand
Read launch-assets/brand.json in the user's repo. If it is there, use it. If it is missing, detect each field from the
repo and write the file. Ask the user only for what you could not find, in one message.
{
"appName": "Halo", "oneLiner": "The Dynamic Island for Mac", "platform": "macos",
"colors": { "bg": "#f5f5f7", "ink": "#1d1d1f", "accent": "#0071e3" },
"fonts": { "family": "-apple-system, 'SF Pro Display', sans-serif", "file": null, "google": null },
"iconPath": "site/assets/icon.png",
"screenshotDirs": ["launch-assets/captures"],
"siteUrl": "https://example.com"
}
appName,oneLiner: README title and first line, the site's<title>and<h1>,Info.plist.colors: the site's CSS variables, the asset catalog'sAccentColor, SwiftColordefinitions. Take the light values. Write hex (#0d7f76); convertrgb(),oklch()andhsl()first. Anything the renderer cannot read counts as grey.fonts.family(a CSS stack),fonts.file(a font file the repo ships, a path relative to the repo root, the folder abovelaunch-assets, ornull),fonts.google(such asGeist:wght@400;600, ornull). Use the brand's font only if the repo ships the file; otherwise the system stack or Google Fonts. Never copy a proprietary font into the user's repo.iconPath: the app icon, a square PNG (1024 px is best), relative to the repo root. Look in the site's assets, the asset catalog'sAppIcon, the favicon folder. Required: the icon and name are on every image.siteUrl: wheremeta.htmlpoints the image URLs. Optional; without it the tags carry a placeholder.
Steps
-
Captures. Reuse what exists:
launch-assets/captures/,screenshotDirs, or an earlierlaunch-assets/store-screenshots/shots.json. Take new ones only when none pass the rules below. First look for the app's own way to capture itself: a snapshot, demo or sample-data flag (rg -i "demo|snapshot|screenshot|marketing"in the source, the README andPackage.swift; for exampleMyApp --snapshot <dir>orMYAPP_DEMO=1). Read what a flag does before running it. Never run anything that scans, cleans or writes real user data, and never launch a second copy of an app that keeps live state. If a flag could do either, stop and ask. Otherwise, on a Mac, bring the app to the front in the state to show and runswift <skill-folder>/scripts/capture-window.swift "MyApp" capture.png(the app's largest on-screen window, no shadow, Retina pixels; it skips a notch or menu bar app's panel, which sits on a higher window layer, and says so). iOS:xcrun simctl status_bar booted override --time 9:41 --batteryState charged --batteryLevel 100, thenxcrun simctl io booted screenshot capture.png, thenxcrun simctl status_bar booted clear.Rules for every capture:
- Real UI, focused. The active window: coloured traffic lights, a lit sidebar. A grey, dimmed window is a fail.
- Settled. No counter mid-roll, no spinner, nothing half-drawn.
- Neutral demo data. No personal names, real file, project or account names, no other company's product names (unless the app's own site names that integration). Use the demo mode, never a screenshot of the real thing.
- Light mode if the app has one. Dark captures are for dark-only apps.
- 2x pixels. A card shows a capture at most 1.15x its own pixels (the render fails above that), so a window needs about 1400 px across for a link preview and 2000 px for a gallery slide.
- Real content. No empty wells, no lorem, no truncated text in the part the title talks about.
- One that reads small. The link preview shows the capture at about 600 px wide. Pick the capture whose main point is visible at that size (a big number, a clear list), not a dense settings pane. Crop to the part that matters.
- A SwiftUI
ImageRenderercapture (a notch app's island) comes with opaque yellow placeholders in its corner flares: set"clean": true. For an island floating on the card, add"square": true, which squares the corner flares off to the body's edges. Crop away any empty notch row withcrop.
Done when each capture passes the list. Read every file's size (
sips -g pixelWidth -g pixelHeight) and look at it. -
Write the words.
- Link title: the app's one-liner or the page's own title, in the site's words: 9 words or fewer, sentence
case, no full stop, no dash, no
!. It is the only large text on the card, so shorter is bigger. - Pages: if the repo has a site with several pages, run
node <skill-folder>/scripts/pages.mjs <site-folder>. It prints each page's<title>and<h1>. Pick the pages worth a preview of their own (the guides, the pricing page, the biggest features); skip pages that name another company's product. Take the<h1>or the shorter of the two, drop the site-name suffix and "(2026)" style tags, keep it to 9 words. Never paraphrase. - Slides: if
launch-assets/store-screenshots/shots.jsonexists,"ph": { "fromShots": "../store-screenshots/shots.json" }reuses its headlines, sublines, captures and crops (first 6 shots,"limit"changes that). Otherwise write 4 to 6 slides: slide 1 says what the app is, each later one has one benefit and makes sense alone. Headline 6 words or fewer, an optional subline of one short sentence. - X header title: the one-liner. 6 words or fewer.
- Alt text: one sentence that says what the image shows. It defaults to
<app>: <title>. <subline>; writealton the link when the capture adds something worth saying.
Copy uses the site's own words. Every line is taken from the site or README and shortened; every number, name and claim is on the site. Check each line with
rgagainst the site copy before you keep it. - Link title: the app's one-liner or the page's own title, in the site's words: 9 words or fewer, sentence
case, no full stop, no dash, no
-
Write
launch-assets/og/og.json.{ "brand": "../brand.json", "out": ".", "wallpaper": "auto", "link": { "title": "A Mac cleaner for developers", "capture": "../captures/overview.png", "alt": "Shedi, a Mac cleaner for developers: 43.84 GB found, sorted into safe to clean and check first" }, "pages": [ { "id": "xcode-deriveddata", "title": "Clear Xcode DerivedData", "capture": "../captures/xcode.png" } ], "ph": { "fromShots": "../store-screenshots/shots.json" }, "x": { "title": "A Mac cleaner for developers", "capture": "../captures/overview.png" } }Leave out
pages,phorxto skip that kind. Paths are relative toog.json. A page inherits everything fromlink(capture, crop, layout) and overrides what it names. Options onlink, a page, a slide orx:capture(orcaptures, up to 3, stacked),crop({ x, y, w, h }, 0 to 1 of the capture after transparent margins are trimmed;cropsfor several captures),clean,square,radius,width(capture width as a share of the card),shadow: false,minCoverage.layout: link cards areside(title left, a window rising from the bottom right) orbelow(title centred, a wide capture under it). The default picksbelowfor a capture wider than 2:1,sideotherwise. Slides arefit(the whole capture, nothing cut),bleed(cut by the bottom edge, for a window) orpair(2 or 3 captures stacked). A slide with nolayoutand one plain window capture (noclean) isbleed; anything else isfit.minCoverage: the floor for UI coverage (link 0.3, slide 0.4, header 0.12). A capture that spans 80% of the card width passes without it (a thin island or bar cannot get taller). Do not lower the floor to hide a small capture: show it larger, crop it or pick another.- On a slide in
fromShots, add"slides": [{ "id": "<shot id>", ... }]to override one slide's options.
Background, once for all images:
"wallpaper": "auto"picks the bundled picture whose hue is nearest the brand accent (blue and teal, green, warm, pink) and prints the pick and why. Tell the user the pick and why, and that they can change it ("wallpaper": "snow", or a path to their own bright, calm picture, at least 2400 px wide). A grey accent, or one more than 50 degrees from every picture, gets the brand field instead (the brand's background washed with a little of its accent). Leave the key out for the field. This skill bundles five pictures. -
Render.
node <skill-folder>/scripts/render.mjs launch-assets/og/og.jsonOne output line per PNG:
okorFAIL, size, file weight, the font that actually drew the title, the contrast of the words against the pixels really behind them, the title's size and cap height, the UI coverage and how far the capture and the wallpaper were enlarged.--only link|pages|ph|xrenders one kind (anything else fails). It also writesmeta.html.The guard fails: a size that is not exact, an alpha channel, a file over 5 MB, text contrast under 4.5:1 (there is no scrim; pick a paler wallpaper or darker ink), a title whose cap height is under the minimum (link 40 px, slide 38 px, header 36 px, so it still reads in a 600 px wide preview) or that needs more lines than fit, over-long or dashed (a dash, " - " or "--") or
!copy, a capture enlarged over 1.15x or a wallpaper over 1.2x, UI coverage under the floor unless the capture spans 80% of the card width (measured on the capture's content pixels, not its box, so blank black or white areas do not count), anything outside the X safe area or inside the avatar zone, and a font fallback: the first named family offonts.familymust be the font that drew the title ("Inter, sans-serif"with no file would draw SF Pro: FAIL). A stack that starts with-apple-systemorsystem-uimeans the system font and only fails on a fallback such as Helvetica or Arial. Fix everyFAILinog.jsonand render again. -
QA pass. Required, and done on the files, not on the config.
- Size and alpha:
sips -g pixelWidth -g pixelHeight -g hasAlpha <each file>. Exact sizes from sizes.md,hasAlpha: no. - Look: open every PNG with the Read tool at full size. Then
node <skill-folder>/scripts/preview.mjs launch-assets/ogand open_preview-600.pngand_preview-300.png(every image at 600 and 300 px wide, as a feed shows it), then delete the two files. For each image check:- The title is readable at 300 px and nothing is clipped or alone on a second line.
- The font in the output line is the one you asked for.
- The capture is sharp, shows the point of the title, has no truncated text and no personal data.
- Names: no competitor or other company's name or logo unless the site names that integration; no personal names.
- Words: every line is the site's own wording, shortened; every number is on the site.
- X header: the lower left (x under 420, y over 300) is clear for the profile photo; the content sits in the middle band, away from the top and bottom 70 px. Check it against sizes.md and, if you can, on the real profile.
- Set: the slides read as one family; no two make the same point.
- Fix and render again, then look at that file again.
- Only then report: the file list, the
sipsoutput, and anything you could not verify. Tell the user to copy the PNGs to the site, pastemeta.htmlinto<head>, and refresh the cached preview in each platform's debugger.
- Size and alpha:
Look rules
- Light first. A bright wallpaper or the brand field, ink dark on it. No dark background with neon.
- No glow, no halo. Depth is a 1 px edge and neutral black shadows at low opacity.
- One job per image. One title, one capture (or one pair), at most one subline.
- Large type. The title is what survives a thumbnail. Short copy is what lets it be large.
- Real captures only. The UI is never drawn, redrawn or generated.