Comparing a Live Page Against a Design Mockup with the Visual Diff API

Design QA usually ends the same way: someone opens the shipped page next to the Figma export in another tab and scans back and forth, looking for spacing that is a little off, a font weight that did not carry over, or a section that quietly drifted from the approved layout. It works, but it does not scale past a handful of pages, and it depends entirely on whoever is doing the scanning noticing the right thing.

The Snapshot Site Compare API can do this comparison directly, because before and after do not both have to be live URLs — either side can be a static image instead.

The Key Detail: imageUrl

POST /api/v3/compare normally takes two url fields, one per state. But each side of the comparison — before and after — accepts imageUrl instead: an existing PNG you already have, rather than a fresh capture.

curl --request POST \
  --url https://api.prod.ss.snapshot-site.com/api/v3/compare \
  --header 'Content-Type: application/json' \
  --header 'x-snapshotsiteapi-key: YOUR_API_KEY' \
  --data '{
    "before": {"imageUrl": "https://cdn.example.com/design/pricing-mockup.png"},
    "after": {"url": "https://example.com/pricing", "width": 1440, "fullSize": true, "hideCookie": true},
    "threshold": 0.15
  }'

before here is a PNG exported from your design tool and hosted somewhere reachable by URL. after is the real, live, rendered page. The response comes back exactly like any other compare call — before, after, a diff image, and mismatch metrics — except now "before" is the design intent, not another live capture.

Where This Is Useful

• Pre-launch design QA. Export the final approved mockup, diff it against the staging build, and get a mismatch percentage instead of a manual side-by-side.
• Design system compliance. Compare a page against a canonical reference screenshot to catch drift in spacing, color, or typography over time.
• Archive comparisons. Diff a live page against an older stored screenshot to see how much has changed since a specific point in time, without needing the old page to still be live anywhere.

Setting a Realistic Threshold

A mockup export and a real rendered page will never be pixel-identical, even when the implementation is correct — real content is longer or shorter than placeholder text, fonts render slightly differently than a design tool's preview, and real images replace placeholder blocks. Start with a wider threshold than you would use for a live-vs-live comparison (0.15-0.2 is a reasonable starting point), and tune from there. The full reasoning behind picking that number is in Tuning the threshold Parameter in the Visual Diff API to Avoid False Positives.

Exporting the Mockup Correctly

The comparison is only as good as the reference image. When exporting from a design tool, match the export width to the width you request on the live capture, and export at the same aspect ratio you expect the live full-page capture to produce — a mismatched canvas size between the two images makes the diff far noisier than any real implementation difference would.

Building This Into a Handoff Step

Once a page ships, storing its "as-designed" reference alongside the ticket means any future regression check — whether that is a manual re-review before a redesign, or an automated baseline for Visual Uptime Monitoring — has something concrete to compare against, instead of relying on someone's memory of what the page was supposed to look like.

Turning design QA into a measurable diff instead of a manual scan is a small change to the handoff process, and Snapshot Site runs the comparison the same way whether both sides are live pages or one of them is a static file.