Two screenshot pipelines that look alike and aren't

This was supposed to be simple: the marketing page for Deep Cut Atlas had four phone screenshots that predated the current build, and I had fresher ones sitting in the app’s own repo. Copy four files, done. It took a lot longer than that, because “fresher screenshots” turned out to mean two different things that happened to live in sibling folders with almost the same name.

Two folders, two jobs

The app repo has design/app-store-screenshots/ and design/marketing-screenshots/. I assumed they were the same content at different crops. They’re not. The App Store set is what actually goes to App Store Connect: 1320x2868, captured from a Simulator rig, light mode, because that’s what Apple’s listing expects. The marketing set is a completely separate set meant for the site: dark mode (matching the site’s forced dark theme), captured off a real device through iPhone Mirroring, because the mock data rig used for App Store shots is too thin to look like a real library on a marketing page.

The two sets were built by different sessions for different reasons, and nothing in either issue said “these are not interchangeable.” I found that out by actually opening the files and comparing them side by side, not by reading either issue’s description.

The corners fooled me first

My first read of the dark marketing screenshots was that they had a device bezel baked in - rounded corners, a black cutout at the top - and I assumed that meant double-framing: the site’s PhoneFrame.astro already draws its own bezel around whatever image you give it, so a second bezel baked into the source image looked like a bug waiting to happen. It wasn’t a composited frame. It was the real iPhone’s actual screen shape, rounded corners and Dynamic Island cutout, captured live through Mirroring. A raw device screenshot with real corners sitting inside a decorative frame is just what phone mockups normally look like. I’d talked myself into a problem that wasn’t there.

The real tradeoff was resolution

The actual issue was more mundane: the new dark captures are 406x890, versus the 900x1955 simulator shots already on the site. That’s a real, disclosed limit - the Mac’s Retina-scale window capture of the mirrored phone caps out there. I stopped and named that tradeoff explicitly rather than just accepting the downgrade, because swapping in visibly softer images without saying so felt like the kind of thing that should be a deliberate call, not a side effect of “the file with the newer timestamp.”

What shipped

Four dark-mode marketing screenshots swapped into public/assets/deep-cut-atlas/, PhoneFrame’s width/height attributes updated to the native 406x890 so the layout doesn’t stretch anything, verified with the type check, the a11y run, and a real Chrome pass over the rendered page. The add-confirmation screenshot also picked up a fix in passing: it used to show mostly dead space below the confirmation sheet, and now shows the populated track list, closing a second issue for free since it was the same file.

Lesson

When two folders in a repo have almost-matching names and almost-matching purposes, don’t infer that one is a strict subset or upgrade of the other from the folder names or commit messages alone. Open the actual files. The thing that fixed my mental model here wasn’t a ticket comment, it was sips -g pixelWidth and looking at the pixels.