---
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>/`](../../../DraftTemplates/) 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`](../../../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`](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/`](../../../docs/product-specs/services/cli-reference/). Read [`conventions.md`](../../../docs/product-specs/services/cli-reference/conventions.md) once to learn the flag grammar, exit codes, and `--json` envelope.

**Mandatory reading before writing any scaffold script: [`references/cli-quirks.md`](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](#appendix-a--gui-fallback-workflow). 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:

   ```bash
   .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:

```bash
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`](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:**

```bash
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:**

```bash
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:

```bash
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`:
     ```bash
     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`](references/cli-authoring-loop.md) and [`cli-reference/layer-add-text.md`](../../../docs/product-specs/services/cli-reference/layer-add-text.md) / [`layer-add-image.md`](../../../docs/product-specs/services/cli-reference/layer-add-image.md).

**Enumerate placeholder text layers** (template start):

```bash
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:

```bash
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`](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
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:

```bash
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:

```bash
# 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:

```bash
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`](../../../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).