Product Visuals

Product Visuals

Compose product marketing stills from real app screenshots inside official Apple device bezels. Background is a separate layer and can be swapped without re-framing the screens.

Capability contract

• Outcome: a 16:9 (or requested) PNG with iPhone / MacBook frames and pixel-accurate UI
• Preconditions: iPhone screenshot and/or real app/browser window screenshot; network access to fetch Apple resources and public wallpaper when needed
• Boundaries: do not invent or redraw UI; do not implement app-store-set / og-card / changelog-card in this version (route only)

Iron rules

1. Never send product screenshots through an image model. Frames and composite are local code.
2. Never commit or vendor Apple Design Resource PNGs/DMGs. Fetch them under ~/.cache/product-visuals/.
3. Clip the screenshot to the interior screen mask, not the hole's bounding box (bbox corners sit outside the rounded device).
4. Zero RGB on fully transparent bezel pixels and premultiply before LANCZOS resize.
5. Shadows are padded contact shadows under the chassis. Do not blur the full bezel canvas — that stamps a rectangular plate.
6. Never use the user's live desktop, personal wallpaper, notifications, bookmarks, or unrelated windows unless they explicitly request it.
7. For a web product on Mac, screenshot a real local Safari window with its native shadow (screencapture -l <CGWindowID>). --mac accepts that window only; the compositor supplies the wallpaper and Menu Bar and never adds a second window shadow. Do not paste a webpage screenshot into someone else's Safari chrome. Do not redraw Safari.
8. For iPhone, capture the simulator framebuffer with xcrun simctl io <udid> screenshot. Never screenshot the Simulator.app window. Never crop a screen out of an already-framed mockup.

Recipes

Default composition for dual-device-hero: 4800×2700, opaque device group centered on the canvas, MacBook Pro 14 Space Black slightly left of that group, iPhone 17 Pro Silver overlapping lower right.

Workflow

[1] Pick recipe from the request (default dual-device-hero)
[2] Collect --phone (simctl framebuffer PNG) and --mac (real Mac window PNG with native shadow)
[3] Export the official Menu Bar SVG from Apple's macOS UI Kit and cache it with scripts/cache-macos-menu-bar.sh
[4] Let compose.py build the Mac screen as wallpaper -> official Menu Bar -> --mac window
[5] bash scripts/fetch-bezels.sh
[6] Derive background from the app's 调性 (see Background)
[7] uv run scripts/compose.py dual-device-hero --phone … --mac … --bg … --out …
[8] Open the PNG. Confirm UI is readable, no corner overflow, no rectangular plates around devices, background reads as the same product

HERE="<path-to-this-skill>"
bash "$HERE/scripts/fetch-bezels.sh"
bash "$HERE/scripts/cache-macos-menu-bar.sh" "$MENU_BAR_SVG"
uv run "$HERE/scripts/compose.py" dual-device-hero \
  --phone "$PHONE" --mac "$MAC" --bg "$BG" --out "$OUT"

Swap background only — same screenshots, new --bg:

uv run "$HERE/scripts/compose.py" dual-device-hero \
  --phone "$PHONE" --mac "$MAC" --bg "$BG" --out "$OUT"

--iphone-color silver|deep-blue|cosmic-orange and --mac-color space-black|silver select cached official bezels.

Background

The plate is the product's 调性, not a stock cinematic studio. Derive it from the screens (and DESIGN.md / tokens if the app repo is known). Do not rebuild device frames to change it.

Yohaku example: 余白, warm parchment #f9f8f5 / dark desk #141414, 梅 #c56473 ≤5% — paper and ink, not blue volumetric cinema.

Generated atmospheres must stay empty. If a model draws a laptop or phone, discard and regenerate.

--bg-dim 0.88 darkens a too-bright plate. Default is 1.0 (unchanged).

macOS web presentation

When the Mac screen presents a website, read references/macos-web-scene.md before composing it. The --mac input is only the real Safari window capture. The compositor builds the privacy-safe desktop scene from separate wallpaper, Menu Bar, and window layers.

iPhone capture

--phone is the device framebuffer, not a photo of Simulator.app.

UDID=$(xcrun simctl list devices booted | awk -F '[()]' '/Booted/{print $2; exit}')
xcrun simctl io "$UDID" screenshot phone.png

Accept: a rectangle at the device's native screenshot size (iPhone 17 Pro: 1206×2622). The status bar and iOS's black island pill are framebuffer pixels; the official bezel supplies the hardware island and camera.

Reject and recapture:

• Simulator.app window (screencapture, axe of the window, a display screenshot that includes chassis chrome)
• A crop from an already-framed mockup (camera already in the island, rounded device corners in the PNG)
• Any size other than the booted device's native screenshot pixels

The workflow's "real window capture" is Mac only.

Inputs

Reject a --mac capture that includes wallpaper, a desktop corner, the display notch, Dock, notifications, or unrelated windows. Recapture only the target window.

Verification

Before claiming done:

• Open --phone before composing: rectangle at native size, no silver chassis, no camera lens in the island.
• Open the PNG. Read actual UI text on both screens — it must match the source screenshots.
• Check iPhone top-left and both bottom corners: no screenshot rectangle leaking past the silver frame.
• Check the Dynamic Island: one hardware island with the camera. A second black pill beside or below it means --phone was not a framebuffer shot, or the island was not covered by the bezel.
• Check around both devices: no darker rectangular plate, no second shadow card on the Mac.
• Check the MacBook display corner against the official bezel: the screen content reaches the official interior mask and has no second inset rounded corner from a desktop screenshot.
• Check the pair as a group: left/right gaps around the opaque chassis should match. A left-heavy Mac with empty canvas on the right means the layout used PNG origin instead of the opaque union.
• Background shares the product's palette and material. A blue cinematic void behind a parchment/ink app is wrong.
• For a web product, confirm the browser is genuine Safari, fills roughly 84–90% of the desktop width, and contains no private browser or desktop data.
• Confirm Safari has one native rounded border and one native soft shadow. A second hard or concentric arc means the compositor added or reconstructed a shadow; it must not do so.
• Confirm the Menu Bar is the unmodified official UI Kit export: Apple glyph, outlined typography, status icons, spacing, and date/time must remain coherent.
• If only the background should change, the framed screens must be identical to the previous export.

Common mistakes