Screenshots in pull requests: what reviewers actually need
A reviewer reading a front-end pull request has to hold two things in their head: what the code now does, and what the interface now looks like. The diff gives them the first. Only you can give them the second.
Most PR screenshots don't, because they show the new state alone — leaving the reviewer to reconstruct the old one from memory.
Before and after, always
A single "after" screenshot asks the reviewer to remember what the screen looked like previously. For anything they don't work on daily, they can't.
Two images side by side make the change self-evident, and they make unintended changes visible too. A reviewer comparing before and after will notice the button that shifted four pixels, the heading that changed weight, the spacing that collapsed — regressions that no amount of reading the diff would surface.
The most common objection is that capturing "before" means stashing your work and reloading. It does, and it takes about a minute. It is consistently worth it.
Cover the states, not just the happy path
A component has more than one state, and the bug is usually not in the one you screenshotted.
For anything non-trivial, include:
- Empty — no data yet. Frequently the least-designed state and the one users see first.
- Loading — skeletons and spinners, often overlooked entirely.
- Error — what happens when the request fails.
- Overflow — long names, large numbers, text that wraps. This is where layouts break.
You don't need all four on every PR. You need them on any PR where the reviewer would otherwise have to check out the branch and click around, which is the thing you're trying to save them.
Responsive changes need two widths
If the change touches layout, one screenshot at your monitor width proves nothing about the other end of the range.
Narrow and wide, at minimum. Mobile breakpoints are where layout changes break most often and where reviewers are least likely to check manually.
Both themes, if you ship both
Dark mode regressions are notoriously easy to miss because most developers work in one theme and never see the other. If your product has both, a change to colour, borders, or shadows needs a screenshot in each.
Contrast failures in particular tend to appear in only one theme.
Keep them in the description, not buried in comments
Screenshots posted as a follow-up comment get lost in the thread as review progresses. Someone opening the PR three days later reads the description, sees no images, and assumes there were none.
Put them in the PR body and update it as the branch changes. The description is the artefact that survives; comments are conversation.
Recordings for interactions only
The temptation with anything interactive is to record a clip. Sometimes right, often not.
A recording is the correct choice when the transition is the change — an animation, a multi-step flow, a drag interaction. It's the wrong choice for a static layout change, because it forces the reviewer to scrub to find the frame they want, and they can't compare it to a "before" easily.
When you do record, keep it under about ten seconds and crop to the component. Nobody scrubs a forty-second video during code review.
What this is really buying
The reason to do this is not process compliance. It's that reviewers who can see the change approve faster and catch more.
A PR with clear before-and-after images gets reviewed properly in five minutes. A PR with no images either gets a rubber-stamp approval — which catches nothing — or sits for two days while someone finds time to check out the branch. The screenshots are what make a real review cheap enough to actually happen.