create-screenshot-file

name

create-screenshot-file

description

Compose a `.screenshot` document for an app's App Store listing using the `sscc` CLI — deconstruct any reference listing, build a per-panel design plan that names every visual ingredient (devices, off-frame bleed directions, decorative arrows / badges / shapes, generated backgrounds, multi-device arrangements), generate every asset the plan demands, then script the compositions, render PNGs to audit that every panel reads in one second, and export at ASC-required sizes. Use when the user asks to create App Store screenshots, build a screenshot file, recreate a competitor's listing, design an App Store page, or ship marketing screenshots for any Apple app. The deliverable is a saved `.screenshot` file plus audited + exported PNGs. Pairs with `screenshot-format` (the document schema) and `template-author` (only when the final output is a reusable bundled template rather than a one-off file).

Create a .screenshot file

Core principle

Screenshots are advertisements, not documentation. Each panel sells one idea — a feeling, an outcome, or a pain point you kill. If you're showing UI to explain UI, start over.

The App Store reader gives a listing about one second before they scroll. Design every headline, pose, and color choice for that one second.

How this skill is structured

The workflow has three editorial gates that run before any composition is built:

1. Discovery — the questions you must have answers to.
2. Deconstruction + Design plan — a per-panel description of every visual ingredient (devices, bleed directions, decorative assets, backgrounds, palette, headline placement). Plan ambitiously; ignore tool limits. This is the gate the original workflow lacked and the most common cause of bland or unfaithful listings.
3. Copy approval — every headline + caption locked before layout work starts.

Then two production phases:

4. Asset generation — image-generate every background, decorative shape, arrow, badge the plan calls for. Assets exist on disk before the scaffold runs.
5. Composition + audit + export — sscc scripts, render the audit set, iterate, export at ASC sizes.

Skipping any of the three gates wastes the rest. The plan is the cheapest place to iterate; never let the first iteration of the design happen inside sscc.

Working directory convention

Every listing lives under DraftTemplates/<slug>/ at the repo root — never in tmp/ (which is gitignored and exists for the template-author skill's downloaded App Store screenshots). The directory is tracked in git so the design plan, generated wallpapers, scaffold script, and .screenshot bundle survive between sessions and remain reviewable.

Pick a <slug> up-front before generating any artifact. It's kebab-case and descriptive of the visual style or reference, not the source app being marketed. Examples: acorn-8-style/, playful-blocks/, cobalt-stack/. Multiple draft listings can share one style root if you're iterating.

Per-listing layout (mandatory shape — see DraftTemplates/README.md for the full reference):

DraftTemplates/<slug>/
├── README.md                     # status header + one-paragraph intent
├── design-plan.md                # the per-panel ingredient plan
├── deconstruction/               # if recreating a reference: per-platform notes
├── refs/                         # downloaded reference screenshots (input)
├── assets/                       # generated backgrounds, decorative shapes
├── captures/<platform>/          # placeholder captures, swapped for real ones later
├── scaffold.sh                   # idempotent rebuild of the bundle from the plan
├── <ListingName>.screenshot/     # the saved bundle (a macOS package)
└── audit/                        # freshly rendered PNGs (safe to delete + re-render)

Throughout the rest of this skill, every path written as DraftTemplates/<slug>/... should be read as "in the listing's working directory you set up at Step 1".

Two non-negotiables for the production phase

• sscc exit 0 is not proof of side-effect. Several Phase 0 commands accept flags they then silently drop (most famously layer add background --source). After every batch of mutations, run the verify script (Step 8.5) — bash references/verify.sh DraftTemplates/<slug> jq's the platform JSON files, runs the headline-fit math, and exits non-zero with a checklist of failures. Step 9 is blocked until verify exits 0. Read references/cli-quirks.md once before writing your scaffold so you know which calls to avoid.
• You don't get to declare "done" until you've sampled the result yourself. Render the audit cleanly (rm -rf $AUDIT && sscc export ...), open at least one PNG per platform, and confirm the wallpapers / devices / text the plan demanded are visibly there. Telling the user "Opened it for you" without sampling is how a fully-broken bundle ships looking like a successful one.

Scope

This skill covers the editorial + planning + composition + visual audit workflow for one .screenshot document, driven by the sscc command-line interface. It does not cover:

• The .screenshot format itself — see screenshot-format.
• Authoring reusable bundled start-screen templates — see template-author (use that instead when the user wants the output checked into ScreenShotComposer/Templates/).
• Recreating a specific competitor's listing as a reusable template — see template-author/workflows/from-app-store.md. (Recreating a listing as a one-off .screenshot file uses this skill plus that workflow's screenshot-fetcher script.)

The output is a saved .screenshot file (wherever the user keeps their documents) plus a folder of rendered PNGs at every ASC-required size, visually audited panel-by-panel before hand-off.

Tooling — CLI first, plus image generation

Authoring happens through the sscc CLI for everything that touches the .screenshot file, plus the agent's image-generation tool for any background or decorative asset the plan calls for.

sscc command families used in this skill:

Family	Commands	Used in
Catalogs (discovery)	sscc catalog templates / bezels / presets / fonts	Step 5
Schema (introspection)	sscc schema layer --kind text|image	Step 7 (when editing field-by-field)
File lifecycle	sscc new, sscc show, sscc validate	Steps 6, 7, 8
Composition lifecycle	sscc composition add / set	Steps 6, 7
Layer lifecycle	sscc layer add text / image / background, sscc layer set	Step 7
Render / export	sscc export	Steps 8, 10

Full per-command reference lives in docs/product-specs/services/cli-reference/. Read conventions.md once to learn the flag grammar, exit codes, and --json envelope.

Mandatory reading before writing any scaffold script: references/cli-quirks.md. sscc is shipping in phases; several subcommands accept flags they then silently drop (no error, no warning, no JSON change). Skipping this file means re-discovering each trap by shipping a broken bundle. The most common one: layer add background --source is a no-op — you must use layer set --source on the auto-created background layer instead.

Operational notes:

• Every mutating command accepts --json and returns a stable envelope. Parse that, not human output.
• Every command is atomic: either the file is updated cleanly or it is untouched. No partial writes.
• UUIDs are the addressing primitive. Never match by title.
• Image sizing is --frame only. There is no --scale flag (the legacy imageScale field is deprecated; see CW-89). To make an image bigger, pass a bigger frame.
• For negative origins (edge bleed past the left or top), use the --frame=-200,300,800,1200 form (with an = sign) so swift-argument-parser doesn't interpret the leading - as a flag.
• When the CLI is not yet available in the local build, fall through to the GUI path in Appendix A. The skill shape is identical; only the commands change.

When to use this skill

• "Create App Store screenshots for my app."
• "Build a screenshot file for <app>."
• "Design the App Store page for my iPhone / iPad / Mac app."
• "Make marketing screenshots I can upload to App Store Connect."
• "Recreate this App Store listing for my app." (reference URL provided)
• "Refresh my listing — here are the new captures."

Workflow

Step 1 — Ask the user these questions

Do not author anything until you have answers. Ask everything up-front; don't interleave "can I start?" between questions.

Required:

1. App name and one-line positioning. "What's the app, and what's the one sentence someone should walk away remembering?"
2. Target platforms. "Which platforms does the app ship on — Mac, iPhone, iPad, or a combination?"
3. Feature priorities. "Top 3–5 features in priority order — the #1 is the hero promise; the rest become Feature panels."
4. Brand palette and typography. "Primary color, accent color, preferred text color, and either a font name or a vibe (e.g. humanist sans / geometric / serif)."
5. Style direction OR reference listing. "Either describe the vibe (warm / moody / clean / bold / editorial / minimalist), or share an apps.apple.com URL of a listing whose design you want this to feel like." A reference listing unlocks the deep deconstruction in Step 2; a vibe-only direction makes you invent every ingredient from scratch (still possible, just denser planning).
6. Panel count. "How many screenshots? Apple allows up to 10 per locale. 5–6 is typical; 3 is an aggressive minimum."
7. Start shape. "Start from one of ScreenShotComposer's bundled templates (you'll swap the copy + captures) or start blank (you pick every plate, bezel, and layout)?"

Optional (only ask if the answer isn't obvious from context):

8. Ecosystem surfaces. "Watch, widgets, AppIntents, share sheet, Shortcuts, Siri — any you want to highlight?"
9. Trust signal. "Any reviews, awards, featured-by-Apple moments, or proof points for a trust panel?"

Never ask — always assume:

• Captures are placeholders during the design pass. Do not ask the user for raw captures. Generate platform-sized placeholder PNGs (solid fills or simple gradients matching the panel's plate palette) at scaffold time and drop them into captures/<platform>/<NN>-<slug>.png. Real captures get swapped in by the user later via sscc layer set --source <real.png> once they like the layout. This keeps the iteration loop tight — design first, real-capture last.

Derived — decide yourself, never ask:

• Bezel per platform. Pick the newest shipping device in the bezel catalog matching the raw captures' aspect ratio. Confirm with sscc catalog bezels --json in Step 5.
• Panel pose rotation. Cycle across centered / tilted pair / multi-device / edge bleed (device sized larger than the plate so it crops past one or more edges — 4 sides + 4 corners) / text-led so no two adjacent panels repeat. See references/message-hierarchy.md for the full pose vocabulary, default-per-slot table, when-to-use rules for edge bleed, and CLI frame syntax for bleeding past plate bounds.
• Background style. Flat / 2-stop gradient / image-fill — one of the three. Decide per panel during the design plan in Step 2; only invoke image generation in Step 6 once the plan calls for it.
• Dark vs light mix. 1–2 inverted panels for visual rhythm if the panel count is ≥ 5.
• Typography treatment. Weight, tracking, line height — derive from the style direction.

Step 2 — Deconstruct any reference listing, then write the design plan

This is the gate the original workflow lacked. Do not scaffold a document, do not generate any asset, do not pick palette colors before this step has produced an approved plan.

Read references/design-plan.md end-to-end. It defines the per-panel ingredient checklist, the deconstruction file shape, the design-plan template, the asset manifest, and the multi-device + decoration patterns.

The two paths:

Step 2a — Reference-driven (a URL or screenshots were provided)

1. Fetch every panel for every Apple platform the source app ships on:

   .cursor/skills/template-author/scripts/download-app-store-screenshots.sh \
     <url-or-id> DraftTemplates/<slug>/refs
   

   The script writes per-platform subfolders of full-resolution PNGs (it rewrites /643x0w.png to /0x0w.png). For non-App-Store references (a hand-shared screenshot, a Figma export), drop them into DraftTemplates/<slug>/refs/source/ numbered.

2. Open every PNG and deconstruct it using the per-panel ingredient checklist in design-plan.md § "Visual deconstruction". One markdown file per source panel at DraftTemplates/<slug>/deconstruction/<platform>-<NN>-<slug>.md. Fill every row of the table — explicit "none" is informative. Pay particular attention to:

   • Off-frame placement. Which devices bleed past which edges, in which direction. This is the most-missed ingredient.
   • Per-platform asymmetry. The Mac panel often shows two devices; the iPhone version of the same panel shows one. Don't assume parity.
   • Decorative assets. Hand-drawn arrows pointing from headline to device, callout pills anchored to UI elements, mascots, star clusters, sparkles, badges. Every non-device, non-text PNG.
   • Background structure. Flat / gradient / mesh / image. Sample 2–4 hexes per panel.
   • Headline placement, weight, color, and size as a fraction of plate height.

Step 2b — Vibe-driven (style direction only, no reference)

If the user gave a style direction without a reference URL, name one or two well-known reference listings in the same vibe (Mela / Things / Linear for moody-editorial; Bear / Highlights for playful; Raycast / Notion for outcome-first dev tools) and use those as anchor references for the deconstruction step above. You don't have to copy them — naming references makes color, weight, and pose decisions defensible.

Step 2c — Write the design plan

Produce DraftTemplates/<slug>/design-plan.md using the template in design-plan.md § "Design plan template". One section per panel × platform. Every section must specify:

• The pose (from the rotation vocabulary).
• Plate background kind + colors.
• Per-device bezel ID, frame, and bleed direction.
• Capture file path per platform.
• Headline + caption placement (quadrant, frame, color, font-size, weight).
• Decorative assets with their position, z-order, source PNG file, and prompt sketch.
• Light/shadow direction.
• Contrast/inversion notes.

End the plan with the asset manifest (from design-plan.md § "Section 2 — bottom of file"): one explicit table for user-provided captures, one for backgrounds to generate, one for decorative assets to generate, one for bezel IDs, one for fonts.

Step 2d — Plan presentation gate

Show the design plan to the user. They get to reorder panels, swap pose rotations, drop or add decorative assets, adjust palette, replace generated backgrounds with specific images they want to provide instead.

Mark the design plan as approved: true at the top of the file before proceeding to Step 3. Re-show the plan after every revision. Do not generate assets, do not write copy options, do not scaffold until the plan is approved.

Plan ambitiously. When you draft the plan, describe what you actually want — not what's easy to scaffold, not what the catalog ships with, not what the renderer obviously supports. "Hand-drawn coral arrow pointing from headline to device screen, ~-10° rotation" is a valid plan ingredient. The realization step (Step 6: image generation) figures out how to get the PNG. Constraint thinking belongs after the plan, not during it.

Step 3 — Write copy first

Read references/headline-craft.md. For every panel × platform, draft 3 headline options using the three approaches (Paint a moment / State an outcome / Kill a pain). Apply the Iron Rules: one idea, 1–2 syllable words, 3–5 words per line, intentional line breaks.

Per-platform copy: Mac and iPad usually share copy; iPhone often needs a tightened (2–3 word) variant for thumbnail readability — call this out per panel in the table.

Write all options to DraftTemplates/<slug>/copy.md as a single markdown table per panel (Option / Approach / Headline / Caption columns). Present to the user.

Do not proceed to Step 4 until the user has picked one option per panel and marked the approved choices. Bad copy ruins good layout.

Once approved, fold the chosen headlines + captions back into the design plan's per-panel sections (the Approved headline: and Approved caption: rows).

Step 4 — Discover the catalog

Before writing anything to disk, enumerate the live catalog so all subsequent flag values are grounded in what actually exists:

sscc catalog templates --json > DraftTemplates/<slug>/catalog-templates.json
sscc catalog bezels    --json > DraftTemplates/<slug>/catalog-bezels.json
sscc catalog presets   --json > DraftTemplates/<slug>/catalog-presets.json
sscc catalog fonts     --json > DraftTemplates/<slug>/catalog-fonts.json

Pick:

• Template ID (if Step 1's "start shape" was template) — the one closest to the style direction.
• Bezel IDs per platform — from catalog-bezels.json, matching the capture aspect ratios. The plan already named the bezels; this step verifies they exist in the live catalog.
• Preset tokens per platform — the ASC-largest for each bucket (see references/cli-authoring-loop.md).
• Font PostScript names — if the style direction called for a specific typeface; otherwise default to the system font.

Cross-check against the design plan's asset manifest. If the plan named a bezel that's not in the catalog, stop and either pick the closest available bezel and note the substitution in the plan, or escalate to the user. Do not silently substitute.

Step 5 — (merged into Step 4)

This step number is reserved to keep parity with the previous workflow numbering. The merged operation lives in Step 4.

Step 6 — Generate every asset the plan calls for

Read the asset manifest at the bottom of the design plan. For every row in the "Backgrounds to generate" and "Decorative assets to generate" tables, run the agent's image-generation tool with the prompt sketch in the row.

For background-image prompts and the visual-language catalog (minimalist arches, sunrise gradients, painterly landscapes, mesh gradients, geometric grids, grain, paper-cut, editorial photography), read ../../template-author/references/background-image-generation.md §§ "Visual-language catalog" and "Prompt writing tips". The same prompt grammar applies whether the asset is a full-bleed plate background or a transparent decoration.

Conventions for this skill (where assets land on disk):

DraftTemplates/<slug>/assets/
  bg-<panel-or-shared>-<short-slug>.png        # plate-fill backgrounds
  arrow-<short-slug>.png                       # decorations
  badge-<short-slug>.png
  halo-<short-slug>.png
  …

Asset rules:

• Backgrounds: one PNG per panel that needs an image fill, sized at 2× the largest plate aspect (≥ 2560 × 2796) so it crops cleanly to all platforms. Center the visual interest in a calm middle band.
• Decorations: square or aspect-matched transparent PNGs at 2× the intended frame size. Bake any rotation into the PNG (the renderer doesn't rotate image layers as of CW-XX).
• Forbid in every prompt: people, text (unless explicitly desired), brand logos, watermarks, devices.
• Pin colors with hex codes that match the palette section of the design plan. Don't say "warm" — say #F4ECE2.
• Optimize before scaffold: pngquant --quality 70-90 -o assets/bg-X.opt.png assets/bg-X.png && mv assets/bg-X.opt.png assets/bg-X.png — keep individual files under 800 KB so the resulting .screenshot package isn't bloated.

After generation, inspect every PNG before scaffolding. If the asset doesn't match the plan, regenerate it with a tighter prompt — fixing it post-scaffold means re-running the populate step.

Generate the placeholder captures. The asset manifest's "Placeholder captures" table lists one PNG per panel × per device-bearing platform. Create each as a solid-fill PNG at the plate dimensions (magick -size <W>x<H> xc:'<#hex>' captures/<platform>/<NN>-<slug>.png), with the hex matching the panel's plate palette so the in-bezel content harmonizes with the wallpaper. These exist purely so the layout can be audited; the user swaps them for real captures later via sscc layer set --source <real.png>. Placeholder captures are expected and never block scaffolding.

Step 7 — Create the document

Read references/cli-authoring-loop.md for the full command sequence. The short version:

Template start:

FILE=./Listing.screenshot
sscc new "$FILE" --template <TEMPLATE_ID> --platforms mac,iphone,ipad --emit-id

The template lands with placeholder copy (literal strings like "Your tagline here"). Expect to rewrite every text layer in Step 8.

Blank start:

sscc new "$FILE" --platforms mac,iphone,ipad
# One composition per panel, per platform:
for i in 01 02 03 04 05 06; do
  sscc composition add "$FILE" --platform mac    --title "$i · ${MESSAGE[$i]}" --emit-id
  sscc composition add "$FILE" --platform iphone --title "$i · ${MESSAGE[$i]}" --emit-id
  sscc composition add "$FILE" --platform ipad   --title "$i · ${MESSAGE[$i]}" --emit-id
done

Capture every emitted composition UUID into a DraftTemplates/<slug>/ids.json file keyed by <platform>.<panel-number>. Step 8 will edit those compositions by UUID; losing the mapping means re-discovering it via sscc show.

Verify the scaffold:

sscc validate "$FILE" --strict
sscc info     "$FILE" --json | jq '.data.compositions | map_values(length)'

Step 8 — Populate every panel from the design plan

One loop per panel, per platform. For each composition (addressed by its UUID from Step 7), the loop reads the corresponding section of the design plan and translates each ingredient into a CLI call. The plan-to-CLI mapping table in design-plan.md § 6 is the canonical reference.

Order matters — image layers draw in the order they were added. Add them bottom-up:

1. Plate background:
   • Flat: sscc composition set "$FILE" --id "$COMP" --plate-color "#HEX"
   • Gradient: sscc composition set "$FILE" --id "$COMP" --plate-gradient "#A,#B,180deg"
   • Image-fill: do NOT use sscc layer add background --source — that flag is silently dropped (Phase 0 stub). Each composition is born with one empty background layer. Look up its UUID from <bundle>/<platform>.json and attach the source via sscc layer set:

     BG_ID=$(jq -r --arg cid "$COMP" \
       '.compositions[] | select(.id==$cid) | .layers[] | select(.kind=="background") | .id' \
       "$FILE/$PLATFORM.json")
     sscc layer set "$FILE" --id "$BG_ID" --source assets/bg-X.png
     

2. Decorative assets that sit BEHIND the device (halo glows, soft drop shadows, background motifs). Each as sscc layer add image --composition "$COMP" --source assets/X.png --frame X,Y,W,H — omit --bezel.
3. Devices (in z-order — back-most first). For template starts, swap captures with sscc layer set --id <image-layer-uuid> --source <capture.png>. For blank starts, sscc layer add image --composition $COMP --source <capture.png> --bezel <BEZEL_ID> --frame X,Y,W,H per device per the plan's per-device frame table.
4. Decorative assets that sit IN FRONT of the device (arrows pointing at UI, callout pills anchored to a button, sparkles around a feature word). Same sscc layer add image pattern, no bezel.
5. Headline + caption text layers — sscc layer add text --composition $COMP --content "..." --font-size N --font-weight bold --color "#HEX" --frame X,Y,W,H per the plan's text-placement rows.

For the exact flag vocabulary — text styles, colors, shadows, alignment, frame syntax — read references/cli-authoring-loop.md and cli-reference/layer-add-text.md / layer-add-image.md.

Enumerate placeholder text layers (template start):

sscc show "$FILE" --json | jq '
  .data.compositions | to_entries[] | .key as $plat |
  .value[] | .id as $comp |
  .layers[] | select(.kind == "text") | { platform: $plat, composition: $comp, layer: .id, text: .textContent }
'

Save this to DraftTemplates/<slug>/text-layer-map.json. Use it to drive the sscc layer set --content loop.

Validate after every batch of edits:

sscc validate "$FILE" --strict

Step 8.5 — Verify (run BEFORE rendering)

sscc validate only proves the file is well-formed JSON. It does not prove the bundle contains what the plan called for, and it does not prove the bundle will render correctly. Several Phase 0 CLI commands silently drop flags (see references/cli-quirks.md); several text frames look fine in the JSON but clip the headline once rendered.

Catch every detectable failure here, in seconds, before burning render time on a broken bundle.

Run the verify script

bash .cursor/skills/create-screenshot-file/references/verify.sh DraftTemplates/<slug>
# Add --allow-flat-plates if your design plan intentionally uses flat or gradient plates on some panels

The script runs three classes of checks against the bundle JSON for every platform and exits non-zero with a checklist of failures.

Class	Catches	Source
A. Bundle content	Quirk 1 (silent --source drop), Quirk 2 (duplicate bg layers), empty text layers, missing image bezels	jq queries on <bundle>/<platform>.json
B. Plan-derivable invariants	Headlines that will clip past their frame: fontSizePoints × line-count × 1.2 > (plateFrame.maxY − minY)	jq math, no rendering needed
C. Asset embedding	Plan-side PNGs in assets/ or captures/ that didn't make it into the bundle	find over both directories

Hard gate

Step 9 (sscc export) is BLOCKED until verify.sh exits 0. A failed verify is a populate-step bug, not a render bug — fix it with sscc layer set (re-attach a missing --source, grow a clipped frame, reduce a font size, rewrite a 3-line headline to 2 lines), re-run verify, then proceed.

Known limitation

The verify script counts explicit \n line breaks. It cannot detect width-induced wrap — a single-line headline that's too wide for its frame at the given font size, forcing the renderer to wrap it onto a second (or third) line that then overflows vertically. Width-induced wrap requires actual text measurement and is only catchable after the first render. Mitigation: in Step 9, eyeball one PNG per platform and confirm every headline rendered with the line count the plan called for; if a 2-line plan rendered as 3 lines, narrow the typography (smaller font, wider frame, or shorter copy) and re-verify.

Step 9 — Render the audit set

This is the moment the work becomes inspectable. Before hand-off, before any further copy fiddling, render every panel and look at every PNG.

Always start the audit cycle with a clean folder. Stale PNGs from earlier scaffold passes will lie to you — a previous run may have rendered correctly before a refactor broke the populate step, and reading those cached PNGs makes the new bug invisible:

AUDIT=DraftTemplates/<slug>/audit
rm -rf "$AUDIT"
sscc export "$FILE" --output "$AUDIT" --opaque --naming title-slug --json > "$AUDIT/manifest.json"

Output shape:

• $AUDIT/mac-01-hero.png, $AUDIT/iphone-01-hero.png, etc. — one PNG per composition.
• $AUDIT/manifest.json — file paths, pixel sizes, byte counts, and per-file SHA-256.

Spot-check freshness before reading any PNG: every file in $AUDIT/ should have an mtime newer than $FILE's mtime. If you re-render and a PNG mtime hasn't moved, the export silently skipped that composition (or you read the wrong folder).

Open every PNG and read it as the App Store reader would. Then run three audits in this order:

1. Width-wrap eyeball (the one thing Step 8.5's verify script can't catch). For every panel, count the rendered headline's lines. If the plan said 2 lines and the PNG shows 3, the frame is too narrow at the given font size and the renderer auto-wrapped — narrow the typography, re-run Step 8.5, and re-render. This is your only chance to catch text-measurement failures before the audit set is "done."
2. Plan-fidelity audit — for every rendered PNG, verify each ingredient in the design plan appears as the plan described it. Pose, devices, bleed direction, decorative assets, headline placement, palette. If a generated arrow sits 200 points off where the plan put it, fix the frame; don't re-plan.
3. references/qa-checklist.md gate — the message-quality / visual-quality / contrast / thumbnail-legibility checks, against the freshly rendered PNGs not the source document.

Audit signals that indicate a real problem:

• data.warnings[] contains FONT_FALLBACK — a layer referenced a font that is not installed. The rendered PNG is wrong. Install the font or rewrite the text layer to use a system font via sscc layer set --font-post-script-name none.
• data.warnings[] contains HOSTING_FALLBACK — informational; the output is identical, the renderer just took the NSHostingView path. Safe to ignore.
• Text clipping — the headline cuts at a frame edge. Loosen the --frame or tighten the copy.
• Bezel / capture aspect mismatch — the raster letterboxes inside the bezel. Either pick a different bezel (sscc catalog bezels --json | jq ...) or resize the source to the bezel's screenshotWidth × screenshotHeight.
• Decorative asset misplacement — the generated arrow / badge / shape is at the wrong frame, wrong z-order, or visible behind something it should be in front of. Fix the --frame or re-add the layer in the correct order.
• Generated asset doesn't match the plan — the prompt didn't constrain enough. Re-generate the asset (Step 6), don't try to fix it in the composition.
• Contrast failure at thumbnail size — hold the PNG at arm's length or downscale to ~400 px wide. If the headline disappears, the text color or background needs adjustment.

Step 10 — Iterate

Every issue the audit surfaces becomes either:

• A sscc layer set / sscc composition set for layout fixes.
• A regeneration in Step 6 for asset fixes.
• A copy edit in copy.md (rare — copy was approved before scaffolding).

…followed by a narrowed re-render so you don't rebuild the whole listing for a one-panel fix:

# Example: tightened the Mac hero headline and made the plate darker.
sscc layer set       "$FILE" --id "$MAC_HERO_HEADLINE_ID" --content "Your day,\non one screen."
sscc composition set "$FILE" --id "$MAC_HERO_COMP_ID"     --plate-color "#0E1117"

sscc export "$FILE" --output "$AUDIT" \
  --composition "$MAC_HERO_COMP_ID" \
  --opaque --overwrite

Repeat the audit → edit → re-render loop until every panel passes both audits in Step 9.

Step 11 — Final export

Once the audit set is clean, produce the ASC-upload-ready PNGs. These are the same sscc export --opaque calls you ran in Step 9, just written into a shipping directory and, when the listing requires multiple ASC sizes, replayed at each preset override:

SHIP=DraftTemplates/<slug>/ship

# Largest-required sizes (always emit these):
sscc export "$FILE" --output "$SHIP/largest" --opaque --naming title-slug --json \
  > "$SHIP/largest/manifest.json"

# Additional ASC slots (only if the listing requires them):
sscc export "$FILE" --output "$SHIP/iphone-6.5" --platform iphone --at-preset 1284x2778 --opaque
sscc export "$FILE" --output "$SHIP/ipad-12.9" --platform ipad   --at-preset 2048x2732 --opaque
sscc export "$FILE" --output "$SHIP/mac-2560"  --platform mac    --at-preset 2560x1600 --opaque

--at-preset is a render-time override — the .screenshot document on disk keeps its original presets. Smaller sizes reuse the same layouts; no per-size re-authoring.

Cross-check the manifest.json from Step 9 and Step 11 — same SHA-256 per panel at matching presets means the exported bytes match what you audited.

Step 12 — QA gate

Read references/qa-checklist.md. Run every check against both the PNGs in $SHIP/ and the .screenshot document. Any "no" is a blocker — fix and re-run Step 10 / Step 11.

Hand-off

When you present the finished work:

1. Briefly explain the narrative arc across the panels (which panel is the hook, which is the differentiator, which is the trust signal, which closes).
2. Call out any panel that uses a contrast treatment or breaks pose rotation on purpose.
3. Flag any assumptions you made about feature priority, bezel choice, skipped platforms, or design-plan ingredients that the user revised after Step 2d.
4. Link to:
   • The saved .screenshot file.
   • DraftTemplates/<slug>/design-plan.md — the source-of-truth plan the listing realizes.
   • DraftTemplates/<slug>/assets/ — the generated assets, in case the user wants to swap or refine them.
   • $SHIP/ (or the final-export directory).
   • $AUDIT/manifest.json (for reproducibility — same SHA-256 on re-render means no drift).

Common mistakes

Mistake	Fix
Skipping the design-plan gate (Step 2) — jumping from copy to scaffold without enumerating per-panel visual ingredients	Plan first, every panel, every ingredient. The plan is the cheapest place to iterate. Re-read references/design-plan.md before scaffolding.
Letting tool limits shape the plan — "we can't really do an arrow, so let's drop it"	Plan ambitiously. Image-generate the arrow as a transparent PNG and add it as a no-bezel image layer. The CLI's primitives realize anything you can describe as a bitmap.
Describing reference listings impressionistically — "warm and modern" instead of #F4ECE2 plate, two soft sage arches bottom-left, bottom-right corner bleed on the device	Use the per-panel ingredient checklist in design-plan.md § "Visual deconstruction". Hex codes, bleed directions, asset counts.
Missing per-platform asymmetry in the deconstruction (Mac shows two devices, iPhone shows one)	design-plan.md § 1.4 — deconstruct every platform separately. Don't assume parity.
Generating assets one-at-a-time inline during scaffolding	Step 6 batches all asset generation from the manifest at the bottom of the design plan. One generation pass, one inspection pass, then scaffold.
Asset prompts without color hexes / "transparent background" / forbids	Image models drift without explicit constraints. Pin every color with #HEX. Always say "transparent background" for decorations. Always forbid people, text, devices, brand logos.
Panels that sell two ideas at once	Split them. "Fast capture and shared budgets" → panel A "Capture in one tap." + panel B "Share the budget."
Showing the app's UI as the message	UI is the proof, not the story. Headline names the outcome; the device frame is visual evidence.
Every panel uses the same centered-device pose	Rotate poses per references/message-hierarchy.md. No two adjacent panels repeat. Edge-bleed poses (device cropped past one or more plate edges, 4 sides + 4 corners) are the cheapest break from "always centered" without changing devices or counts.
All devices fully framed and centered → listing reads flat	Promote one or two panels to edge bleed — the Sketch / Apple-Marketing trick. Frame the image layer larger than the plate so it crops past an edge. Avoid on the Hero. See references/message-hierarchy.md § "Edge-bleed pose".
Forgot to add multi-device or decoration to the plan, then rediscovered it during scaffolding	The plan is the gate. Every device, every PNG, every shape gets a row before scaffold. Step 2d is non-negotiable.
Tried to rotate a decorative arrow with a CLI flag	Image layers don't rotate (as of CW-XX). Bake the rotation into the PNG at image-gen time — the prompt should specify the angle.
Headlines too long at thumbnail size	Apply the "one second at arm's length" test. Drop a word, or rewrite with a different approach.
Wrong bezel for the platform bucket	Pick from sscc catalog bezels --json; never freehand-crop a raw capture.
Export size doesn't match an ASC slot	sscc export --at-preset <TOKEN> for each additional ASC size. Tokens come from sscc catalog presets --json.
Skipping the copy-first gate	Layout time is expensive and compositions are hard to rebalance after the fact. Always approve copy in DraftTemplates/<slug>/copy.md before touching sscc new.
Skipping the render-audit gate	Step 9 is non-negotiable. A composition that looks right in the source JSON can still render with a clipped headline, a broken bezel aspect, a misplaced decorative asset, or a font fallback. Never ship PNGs you have not visually inspected.
Generating backgrounds when a gradient would do	Flat or 2-stop gradient is the default. Only generate a bespoke background when the design plan calls for an image fill.
Panels in the wrong platform bucket	Each bucket exports at its own ASC sizes. Validate with sscc info --json before exporting.
Trying to resize images with a --scale flag	There is no --scale flag. Size images by adjusting their --frame W,H. See the "Tooling" note above (CW-89).
Re-running full exports for a one-panel fix	Use sscc export --composition <UUID> to render just the panel you edited. Much faster for iteration loops.
Losing composition UUIDs between steps	Capture every --emit-id output into DraftTemplates/<slug>/ids.json at create time. Never match compositions by title.
Font fallback in the render manifest	If data.warnings[].code == "FONT_FALLBACK" appears, the PNG shipped with the wrong typeface. Install the font or switch to a system font before Step 11.
Negative --frame origin parsed as a flag	Use --frame=-200,300,800,1200 (with =) so swift-argument-parser doesn't treat the leading - as a flag boundary.
Used <br/> for line breaks in --content — the literal <br/> characters render as text in the PNG	The CLI's text layer accepts \n only (see sscc layer add text --help: "Use \n for line breaks"). Pass \n literally in the bash double-quoted string (--content "Beautiful\nApp Store\nscreenshots."); bash leaves it untouched and the CLI converts it to a real newline. Never <br/> or <br />.
Multi-line headline overflows its frame and gets clipped by the device — a 3-line headline at 180pt in a 540pt frame is ~648pt tall; the bottom line crops past the frame and renders behind the device	Per platform, set font-size × line-count × 1.2 ≤ frame.height. If a panel's headline is 3 lines, either reduce font-size for that platform (we used 140pt on iPad to fit 3 lines in 540pt), grow frame.height, or rewrite to 2 lines. Catch this at audit time by checking every headline ends with the panel's full text — if the last word is missing, the frame is too small.
Skipped Step 8.5 verify and rendered first — went straight from populate to sscc export, then discovered the bug visually	bash references/verify.sh DraftTemplates/<slug> is a five-second pre-render gate. It catches every silent-CLI-drop, every empty text layer, and every headline that exceeds its frame's height. Visual audits are for things JSON can't tell you (color drift, decorative-asset placement, width-induced wrap); they are not for things jq can.
Trusted the post-render visual audit to catch headline overflow — read the rendered PNG and noticed the last word missing	The math is plan-derivable: fontSizePoints × line-count × 1.2 ≤ (plateFrame.maxY − minY). Step 8.5's verify script runs this for every text layer in every platform; you should never discover a height-overflow from a PNG. (Width-induced wrap is the one case that does need eyeballs — see Step 9 audit #1.)
sscc layer add background --source <path> silently drops the source — the --source flag is accepted but never written to the JSON; renders fall back to the plate fill color, so every panel looks like a solid background. Compounds with: sscc composition add already auto-creates an empty background layer per composition, so an add background would also create a duplicate.	Skip layer add background entirely. Each composition starts with an empty background layer; read its UUID from <bundle>/<platform>.json (.compositions[] | select(.id==$cid) | .layers[] | select(.kind=="background") | .id) and attach the wallpaper with sscc layer set --id <bg_id> --source <path> (this command writes correctly). Verify post-scaffold with jq '[.compositions[].layers[] | select(.kind=="background") | select(.image.assetPath != null)] | length' per platform — must equal the composition count.

Appendix A — GUI fallback workflow

When the sscc CLI is not yet available in the local build (it is planned; see docs/product-specs/services/cli.md), or the user prefers to work in the UI, the composition step in Steps 7 / 8 can be done interactively:

1. bin/launch-mac — launch the app.
2. File ▸ New — pick the bundled template from the start-screen chooser, or start blank.
3. For each target platform bucket, add compositions equal to the panel count via the dashed Add Screenshot placeholder (CW-82).
4. Per composition: set the plate background, drop in the bezel + capture, drop in any decorative PNGs from assets/, write the headline + caption with the Format ▸ Text inspector, and save.
5. File ▸ Export — set the export size menu per bucket to the ASC largest-required size (Mac 2880×1800, iPhone 1320×2868, iPad 2064×2752) and export into the audit / ship directories by hand.

The editorial discipline is unchanged — design plan still approved before any composition, copy still approved before layout, poses still rotated, QA checklist still mandatory. Only the composition tool changes. When the CLI ships, the skill's primary path is the one in Steps 4–11 above; the GUI path stays available as a fallback and for human-driven final tweaks.

Files in this skill

• SKILL.md — this file.
• references/design-plan.md — central reference: visual deconstruction framework, per-panel design-plan template, multi-device + decoration patterns, asset manifest, plan-to-CLI mapping. Read before Step 2.
• references/message-hierarchy.md — generic narrative arc framework, pose rotation rules, edge-bleed pose definitions.
• references/headline-craft.md — Iron Rules, three approaches, bad-to-better examples, one-second test.
• references/cli-authoring-loop.md — sscc command recipes for create → populate → render → iterate, including multi-device + decoration layer recipes.
• references/cli-quirks.md — every known silent-flag-drop and Phase 0 stub in the CLI, with detection commands and workarounds. Read before writing your scaffold.
• references/verify.sh — Step 8.5's pre-render verify script. Runs bundle-content + plan-derivable + asset-embedding checks; exits non-zero with a checklist of failures. Step 9 is blocked until this exits 0.
• references/qa-checklist.md — the Step 12 gate (source document + rendered PNGs + plan fidelity).