Accept a visual diff in a dependency update pull request when you can point to the cause in the package's release notes, the change looks intended, and a reviewer other than the author agrees. If you cannot explain why the pixels moved, reject the new baseline and investigate.
The risk of rubber stamping
Update bots open many pull requests, and visual tests fail often enough that approving a new baseline becomes a reflex. The danger is that a real regression, or a package behaving differently, gets saved as the new normal. Once the baseline is updated, the test no longer protects you from that change.
A baseline update is a decision to change what "correct" means. Treat it with the same care as a code change.
A decision guide
| What you see | Likely cause | Action |
|---|---|---|
| Tiny shift across many components | A shared style or token changed | Find the rule, check the changelog, accept if documented |
| One component looks different | Its direct dependency changed | Read that component's usage, test states manually |
| Missing icon or broken glyph | Icon or font package changed names or files | Reject, fix the import, rerun |
| Layout shifts on narrow screens | Responsive rule changed | Check at several widths before accepting |
| Diff appears only in CI, not locally | Rendering environment mismatch | Regenerate baselines in CI, do not accept blindly |
| Text content changed | A formatting library changed output | Confirm with a product owner if user facing |
Steps for the reviewer
- Read the update's release notes and changelog first. Look for words like "changed default", "removed", "renamed".
- Open the before and after images side by side, not just the highlighted difference.
- Check at least one dark mode or high contrast story if your system has themes, since those often move together.
- Confirm that the same pull request has a clean dependency scan and passing unit tests.
- Record the reason for accepting in the pull request description, in one sentence.
Who should approve
For a design system, baseline approval is a design and engineering call. Many teams require one approval from a component owner and one from a design representative. For an update that changes only a patch version of a build tool and produces no visual change, no extra approval is needed.
What to do when the change is a mistake
If the new look is wrong and the package has no setting to restore it, pin the previous version in the library for now and open an issue upstream. Add a note and an expiry date so the pin does not outlive its reason, as covered in temporary overrides need an expiry. If the update is a security fix, do not leave the old version in place without a plan: see semver patch, minor, major: how risky is this fix PR to weigh the options.
The same discipline applies to visual testing generally. Playwright's documentation notes that rendering can differ across hosts, which is a reminder to create baselines where CI runs them. See does visual regression testing catch a bad dependency update for what these tests can and cannot see.
Safeguard can scan the same pull request for vulnerable dependencies, so the visual review and the security check happen side by side. A free scan is at gold.safeguard.sh/scan.
Quick check
Should the update bot approve its own baseline changes?
No. A person should approve any change to what the tests treat as correct.
Is a one pixel diff ever worth blocking on?
Yes, if it appears across many components, since it points to a shared rule that changed. Find the cause before accepting.
Sources
Last reviewed: 19 October 2026.
