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.…