Store screenshots

Most people meet an app in search results, where its card shows the icon, name, subtitle, rating and the first three portrait screenshots, each about the width of a thumb. Many install or move on right there (in one app's own analytics, 56 of 73 downloads came without a product page view; no published figure exists for the store as a whole). So the images are judged at thumbnail size first, and the first one to three carry most of the weight. Everything below follows from that.

All paths here are relative to this skill's folder unless they start with store/, which is the app's own folder for launch work (<app repo>/store/).

What you deliver

In store/screenshots/:

• upload/<locale>/01-….png to 0N-….png: the set for each locale, at one accepted iPhone size. Six to eight images; ten is the limit. build.mjs writes straight into this folder, and it is the folder the uploader reads.
• upload/<locale>/proof.png: the set at search-result size. This is what you and the owner look at. (It is not uploaded: only files that start with a digit are.)
• creative/<locale>/search-results.png and header.png: the two creative assets (shown on iOS 27 and later), with safe-area-guide.png beside them.
• build.mjs, screens.mjs, content/<locale>.json: the source, so one screen can be redone later in minutes.

Sizes and Apple's current requirements are in references/specs.md. Read it before choosing the export size or deciding about iPad.

Before drawing anything

1. Read the research. store/research/aso-report.md (from the aso-research skill) says what the app is competing against, which phrase positions it, and what the rivals' first images say. If it does not exist, run that skill first: captions written without it are guesses.
2. Read the app. Open the theme file (colours, radii, spacing, type sizes) and the components of every screen you intend to show. Note the exact strings the app prints and where they live in its translation files.
3. Confirm each screen still exists. Search the code for the feature a screenshot shows. A listing once advertised a "duplicate last week's trip" button that had been removed months before launch; Apple rejects that under 2.3, and users feel lied to.
4. Look at the rivals' first images. node ../aso-research/scripts/store-research.mjs shots <cc> <id> <id> … --out store/research/rivals downloads them; Read the files. Your first image will sit in a list beside these. Note their colours and the line each leads with, so yours differs in both. A stock line that three rivals already use is not a headline.
5. Ask the owner for one capture of the app's main screen, and of any screen you cannot reconstruct from code (maps, camera, charts with real data, native system UI). One request, with the exact list. The capture of the main screen is the check that your redrawn UI is the real one; without it, say in your report that the screens were rebuilt from code and not compared. See ../app-launch/references/owner-inputs.md.

Decide the story

Write a storyboard before rendering: one line per image, with the headline and what is shown.

• Image 1 is a statement with proof. Big words that say what the app is, for whom, in the searcher's own vocabulary, over real pieces of the app's UI. A shopper who sees only this image must know what the app does. Words alone would spend one of three visible slots on no product, and Apple advises against an image that is only a slogan.
• More than half of the set must show the app in use. That is App Review's rule (2.3.3), counted per locale. One statement image in a set of six is fine.
• Images 2 and 3 show the core loop and the one thing rivals do not have. They are the rest of what fits on the search card.
• Each further image is one benefit, in the order a new user would care about. A feature that needs explaining goes last or gets cut.
• Headlines: a benefit in the user's words, about five words, one part highlighted. "Never buy milk twice." beats "Real-time sync". They must be readable in the proof sheet without zooming.
• Claims have to be true and checkable. No awards, user counts or "#1" unless they exist and can be shown; the app's real, current star rating may be used. No prices and no "free" in any image (reviewers treat it as a pricing word). No other platforms, no competitor names. See the rules in references/specs.md.
• Write captions for people. Whether Apple reads caption text for search ranking is contested, and the evidence leans against it. Use the target phrase where it is also the benefit; do not bend a caption to carry keywords.

Published "studies" of what converts (caption position, dark against light, benefit against feature) are vendors' selected case studies; treat these defaults as a starting point and say so if the owner asks for proof. The evidence and its strength are in ../aso-research/references/aso-knowledge-base.md, section 7.

When two directions for image 1 are both defensible, render both and show them side by side; this is the single design decision the owner reliably wants to make. For everything else, decide and move on.

Build

1. Copy assets/example/ to store/screenshots/ (it is a small complete set for an invented app; run it once unchanged to see it work). In build.mjs set the two lines under "settings to change": KIT to the absolute path of this skill's scripts/kit.mjs, and APP_STRINGS to the app's own translation folder, adjusting loadAppStrings to its file format. Delete the example's app-strings/.
2. The renderer: npm init -y && npm i -D playwright-core in that folder (it drives the Edge or Chrome already on the machine; nothing is downloaded). If another project on the machine already has Playwright, PLAYWRIGHT_FROM=<that project's folder> uses it instead.
3. Rewrite screens.mjs for the real app: tokens copied from the theme file, each component rebuilt as its source lays it out at 390 points wide. Words the app prints come through t("key") from its translation files, never retyped, so the translated sets show what the app really shows. Compare against the owner's capture.
4. Rewrite content/en-US.json: headlines and sample data only.
5. Lay out the slides in build.mjs with the kit's pieces (their parameters are listed at the top of kit.mjs): headline, phone (the screen in a frame), sticker (one row or card enlarged and tilted so it reads at thumbnail size; place it where it does not hide the rows that make the point), tag (a short human line such as "Sara · just now"). Mark each slide inUse: true or false.
6. node build.mjs en-US, then look at upload/en-US/proof.png with the Read tool. Everything that carries meaning has to be readable there: if the small chip above a headline cannot be read at that size, it is decoration, so do not put the key phrase in it. Fix and repeat.

build.mjs prints a WARNING when text could not be shrunk to fit, when the app's own layout cut a string off with "…" (shorten the sample data), and when half or fewer of the images show the app in use. Clear every warning.

Sample data is part of the design. Use realistic names, items and amounts for the market, never the owner's test data ("Test2", their own name, their family's). Format money, dates and units exactly as the app does, including oddities like "64.20 USD"; a prettier format than the app's is a false screenshot.

Localize

For each locale, one subagent writes content/<locale>.json and runs the checker until it passes:

node scripts/check-content.mjs store/screenshots/content <locale> --base en-US

Put the length caps in content/limits.json (the example has one). Brief each agent with: the English file, the app's translation file for that language, the localized store listing (store/copy/<locale>.json) so headlines use the same words as the name and subtitle, and these rules:

• Translate the meaning of a headline, not its words; keep one [highlighted] part and the same number of | lines.
• Invent natural sample data for that country: local first names, shop types, products, metric units, local currency.
• Where there is no native speaker on the team, the agent is the native-speaker check. It should say which lines it is unsure about.
• Grammar that depends on the sample data (gender, case) has to agree with it. "lo ha añadido" next to "Mantequilla" is wrong.

Then render and look at every locale's proof sheet. Long languages (German, Dutch, French) overflow in ways the checker cannot see: a label that now covers the headline, a tag pushed off the edge. The warnings catch text that could not be shrunk and strings cut off with "…"; your eyes catch the rest.

If the app prints some values in English regardless of language (stored category names, unit abbreviations), choose sample data that avoids them rather than showing a half-translated screen.

Creative assets

Two extra images per locale, introduced in October 2026 and shown on iOS 27 and later: a 3:2 image that replaces the screenshot strip in search results, and a 21:9 header on the product page. They do not have to show the app in use.

• Render them with node build.mjs <locales> --creative (they are large, so they are not rendered on every run).
• Put every word inside Apple's art safe area (CREATIVE.search.safe, CREATIVE.header.safe in the kit); phones crop the rest. Real UI makes good scenery outside it.
• renderCreative writes the upload files and, separately, safe-area-guide.png with the safe area drawn on a copy. When showing the owner, show the clean files and say the dashed box exists only on the guide. An owner once took the guide for the design and asked for the box to be removed.
• How a phone really crops them is only visible in App Store Connect's Device Preview, which needs the owner's signed-in browser; say so if you have not seen it.

Upload

Uploading is the app-store-connect skill's job: asc.mjs shots for the sets, asc.mjs creative place for the creative assets. Both read the folders build.mjs wrote (store/screenshots/upload/ and store/screenshots/creative/, the defaults in store/asc.json). Only files that start with a digit are uploaded, so drafts and proof sheets can stay beside them.

Things that have gone wrong

• Font names inside a style="…" attribute must use single quotes ('Inter', sans-serif). A double quote ends the attribute, and the text renders tiny in Times.
• Images referenced by file path load only when the page itself is a file; the kit writes each page to html/ and opens it for that reason. Do not switch to page.setContent.
• Playwright's own Chromium is usually not installed; the kit starts Edge or Chrome instead.
• Write files with the Write tool. Shell heredocs mangle backslashes and apostrophes in HTML, JSON and regular expressions.
• A screenshot A/B test with a dozen impressions per arm says nothing. Do not report a winner from it.