Prompt
I'm building a QA workflow for designers and engineers to review visual diffs
Latest observation
Great use case. A solid QA workflow for visual diffs usually needs to solve four things well:
- Capture the right before/after states
- Compare them in a way humans can review quickly
- Route issues to the right people with enough context
- Track decisions so nothing gets lost
Here’s a practical workflow you can use for designers + engineers.
Recommended workflow
1) Trigger a visual snapshot on change
When code or design changes land:
- run screenshot capture against key pages/components
- compare against the approved baseline
- generate diffs with metadata:
- branch / PR
- component/page name
- viewport/device
- browser
- environment
- build hash
2) Auto-group diffs
Don’t present every pixel difference as a separate review item. Group by:
- component
- route/page
- feature
- viewport
- severity
This makes review much faster.
3) Review queue with clear states
A reviewer-friendly status model helps a lot:
- New
- Needs review
- Approved
- Accepted change
- Ignored / false positive
- Needs fix
- Blocked
For designers, “Accepted change” often means “looks good, update baseline.”
For engineers, “Needs fix” should link back to the PR or issue.
4) Review UI should show the right comparisons
Each diff item should include:
- side-by-side baseline vs new
- overlay / onion-skin toggle
- pixel diff heatmap
- zoom/pan
- full-page scroll sync
- DOM/component metadata
- annotations/comments
- link to source code or story
5) Approval workflow
A common pattern:
- Designer reviews UI fidelity
- Engineer reviews implementation and regressions
- Optional product owner signs off on high-risk views
You can support either:
- single approval
- multi-approval
- role-based approval for specific surfaces
6) Baseline update policy
This is important.
Only update baselines when:
- changes are intentional
- reviewer approves
- the change is linked to a PR or design ticket
Avoid “auto-update on pass” unless the team is very disciplined.
7) Exception handling
Have a way to mark diffs as expected due to:
- dynamic content
- timestamps
- ads
- animations
- fonts loading
- environment variance
- A/B tests
- responsive breakpoints
Better still, allow masking or freezing these areas before diffing.
Good data model for review items
A review item could look like this:
{
"id": "diff_123",
"projectId": "proj_01",
"title": "Navbar on homepage changed",
"status": "needs_review",
"severity": "medium",
"surface": "homepage",
"component": "MainNav",
"viewport": {
"width": 1440,
"height": 900,
"device": "desktop"
},
"browser": "Chrome 129",
"baselineId": "base_456",
"candidateId": "cand_789",
"diffMetrics": {
"pixelDiff": 2.1,
"changedRegions": 3
},
"assignee": "designer@company.com",
"labels": ["intentional?", "typography"],
"comments": [],
"createdAt": "2026-10-27T10:00:00Z"
}
Suggested review rules
You can automate triage with rules like:
- Low pixel diff + no structural change → auto-approve or low priority
- Large diff in critical surface → high priority
- Changes in masked regions only → auto-ignore
- Text/layout shifts in header/nav/footer → require designer review
- Component story changes → require engineer + designer review
Useful features for the workflow
For designers
- Figma link or design reference on the diff page
- comment threads
- approve/deny with rationale
- compare against design tokens or spacing rules
For engineers
- PR links
- commit links
- affected test logs
- CI status
- ability to re-run capture for one page/viewport
For the team
- notifications in Slack/Teams
- daily digest of unresolved diffs
- audit trail of approvals
- search by component, label, status, reviewer
Common pitfalls
- Too many false positives
- No masking for dynamic content
- Reviewing only screenshots without context
- No owner assigned
- Baselines drifting without audit trail
- Not capturing multiple breakpoints/browsers
A simple end-to-end flow
- PR opens
- CI captures screenshots
- Diff items created
- Auto-triage prioritizes them
- Designer reviews visual intent
- Engineer reviews technical impact
- Approve or request changes
- Baseline updated only after approval
- Audit record saved
If you want, I can also help you with one of these next:
- a workflow diagram
- a database schema
- a PR/CI integration design
- a review UI wireframe
- a state machine for diff approval