Resize a screenshot in the tab when the README hero is oversized

The README hero looks sharp on your 2× laptop display. GitHub (or your docs host) shows it about 800px wide. The file you committed is a 3200×2000 PNG from a retina capture. Every clone pays for pixels nobody renders.

I’ve started treating oversized README screenshots as a packaging bug, not a design flex. If the image displays at ~800px, committing a 3000px source is optional — and usually accidental.

How heroes get fat

Common paths:

• OS screenshot at native retina resolution
• Design export at “2× for safety”
• Drag from Slack / Notion without checking dimensions
• “We’ll compress later” that never happens

Markdown doesn’t downsample for your repo weight. The viewer might, but git clone and PR diffs still move the bytes.

A simple size policy for docs images

Boring rules beat debate:

• Display width — pick a target (e.g. 1200px wide max for README heroes, 800px for inline steps)
• Format — PNG for UI chrome with sharp text; JPEG/WebP for photo-like shots
• Alpha — keep PNG when transparency matters; don’t flatten by accident
• Name — readme-hero.png, not Screen Shot 2026-11-09 at 9.41.03 PM.png

If the screenshot is also used in a marketing site with a real image pipeline, store the master there and link a resized derivative from the README.

Check dimensions in ten seconds

Before the PR:

# macOS
sips -g pixelWidth -g pixelHeight docs/images/readme-hero.png

# or ImageMagick
identify -format "%wx%h\n" docs/images/readme-hero.png

If width is past your policy (say 1600px for a hero shown near 800–1200px), resize first. Reviewers shouldn’t need a binary diff to notice a 4× capture.

Resize before commit (not after the complaint)

You want:

1. Exact pixel target or percent downscale
2. Aspect ratio locked (unless you intentionally crop elsewhere)
3. Transparency preserved for UI PNGs
4. A preview of output dimensions before download
5. No mandatory upload of an unreleased product UI to a stranger’s server

When you’re already in the browser and the file is on disk, an in-tab resizer is enough. Uwarp’s image resize tool scales PNG/JPEG (and similar) by pixels or percent, keeps PNG alpha, previews dimensions, and downloads locally — handy for the README one-off. For batches every release, use sips, ImageMagick, or sharp in a docs script instead of clicking through by hand.

Caveats: heavy upscales won’t invent detail; prefer downscaling screenshots. Very large sources may hit browser limits. Cropping to a new aspect ratio is a different job than scaling — don’t stretch a 16:9 capture into a square hero and call it done.

README markdown that matches the file

After resizing:

![Pricing page — filtered empty state](./docs/images/readme-hero.png)

Avoid huge HTML width hacks as a substitute for resizing the file. Width attributes can help layout; they don’t shrink the blob in git.

If your host supports it, pair with WebP as in the PNG→WebP workflow — but dimension discipline alone fixes most README weight problems.

Reject / send back (in docs PRs)

Reject

• Multi‑megapixel screenshots for a hero displayed under ~1000px
• Screen Shot … filenames in docs/
• Stretched aspect ratios to “fill the banner”
• Uploading unreleased UI to a random online compressor when a local/tab path exists

Accept

• Hero near the display width (with modest 1.5×–2× headroom if you care about crispness on dense screens)
• Predictable names under docs/images/
• Alt text that states what the screen shows
• Masters stored outside the README path when design will reopen them

Tiny habit

Before you drop a fresh capture into the README, check the pixel dimensions once. If it’s more than ~2× the width the page will show, downscale in the tab (or CLI), keep a master elsewhere if you need it, and commit the derivative. Smaller clones. Faster PR diffs. Same information in the hero.