The docs call for a 16:9 hero, or the OG template is 1200×630. The file in the PR is a 4:3 laptop screenshot. The layout letterboxes it, or a later object-fit: cover chops off the toolbar you meant to show. Nobody looked at the ratio before the file landed in git.
I’ve started treating the required aspect ratio as a first check, not as something the CSS can paper over. Resize and compression are later steps. If the frame is wrong, you are encoding the wrong crop.
This is not the same job as “make the image fewer pixels.” A 2400×1800 capture scaled down is still 4:3. The layout asked for 16:9.
When an in-tab ratio change is enough
Good fit:
- README heroes, OG images, changelog screenshots, store listing frames with a published size
- A capture that is almost right and needs a crop or a contain-with-canvas to the target ratio
- You want to see cover vs contain before you commit the file
Poor fit:
- Product photos that have a real art-direction crop in Figma
- Screenshots that must show a specific control that would be cut off by cover
- Images already produced by the design team’s export preset
If the content does not fit the ratio without losing the bug, change the layout requirement, or attach a tight crop plus a wider shot. Do not stretch the pixels.
A simple evidence-image ratio policy
- Know the target ratio before you capture (docs template, OG size, component preview)
- Prefer a capture that already matches, then a crop, then a contain-on-canvas
- Do not stretch a 4:3 screenshot into 16:9
- Look at the result at 1x around text and UI chrome
A contain-on-canvas (letterbox) is honest when you must keep the whole frame. A cover crop is fine when the empty desktop margins are what you are removing.
Set the ratio in the tab, then attach the file
You want a local tool that can set 16:9, 1:1, 4:3, or a custom size, with cover or contain, and download the result. No mandatory upload of a screenshot that might include customer data.
When the file is already on disk and you are in the browser, an in-tab ratio tool is enough. Uwarp’s aspect ratio changer does cover, contain, or stretch for common ratios in the browser, so you can judge the crop without sending the file to a server. Handy for README and OG stills. If the team already has a Figma export or a docs image pipeline with a fixed frame, use that for anything that ships in the product.
Caveats: stretch will distort type and circular avatars. Cover will hide whatever sits in the chopped edge — usually the top bar or the status line you cared about. If the screenshot is evidence of a layout bug, crop so the bug stays in frame, even if that means a different ratio and a note in the PR.
If you also need a smaller file, set the ratio first, then compress. A compressed 4:3 hero is still the wrong shape.
Reject / send back
Reject
- A 4:3 screenshot dropped into a 16:9 hero slot with
object-fit: coveras the only fix - Stretching the capture to make the numbers match
- Uploading a screen that might show production data to a random online cropper
- Committing both the original and three experimental crops “just in case”
Accept
- A hero or OG image that already matches the required ratio
- A contain-on-canvas still when the whole frame must stay visible
- A design-export that came from the real template, not a hurried resize