Reading the output

What you’re actually looking at

Every run writes one file. It’s self-contained — no server, no login, nothing to install to open it. You can email it, attach it to a ticket, or read it on a phone. This page walks through it, top to bottom, in plain words.

The report changes shape depending on what you asked it to do — a design check looks different from a regression check, and both change again once you’ve run explain. All four shapes are covered further down.

One clean frame in a Normascope report: the page name, a chip reading Clean, an aligned difference of 0.00% with a meter against a 0.1% threshold, 0.00% unaligned, 0.00% raw and 0 regions, and three images side by side — your build, the approved baseline and the difference overlay. — A page that didn’t move, reported as **exactly 0.00%**. A tool that cries wolf is worse than no tool, so the quiet rows are the ones that make the loud ones worth reading.

One file: self-contained HTML
Three pictures: per page you track
Six numbers: all of them explained

Part one

The top of the page

Read the masthead first and you often don’t need the rest. Three frames checked, one needs a look, and it’s the product page — that’s the whole run in a glance.

The top of a Normascope report: the title, the branch and commit it describes, a count of frames compared, how many need attention, how many are clean, the threshold, and a row of jump links.

1
Which code this describes
The branch, the commit and when it ran. Attach the file to a ticket and nobody has to ask which version they're looking at.
2
The verdict
One page needs a look. When everything is under your threshold this reads “All clean” instead.
3
How much was checked
Three frames compared. A frame is one page, or one section of a page — whatever you chose to keep an eye on.
4
The split
One needs attention, two are clean. The clean count matters as much as the other one: it's the tool telling you what it looked at and found fine.
5
Your threshold
Your setting, not ours. How much difference you're willing to accept before a frame gets flagged.
6
Jump links
One chip per frame, colour-coded. Click to go straight to it.

Part two

One frame, in detail

Below the masthead is one of these per frame, worst first. This is where most of the vocabulary lives, so it’s worth going slowly.

A single frame in a Normascope report, showing the frame name and mode, a status chip reading Needs Attention, the aligned difference as a large percentage with a meter against the threshold, the unaligned and raw percentages, a collapsible row of alignment bands, and three images side by side: your build, the approved baseline, and the diff overlay.

1
The frame, and what it was compared against
The name you gave it, then the mode: baseline means it was compared against a screenshot you approved. fidelity · figma would mean it was compared against your design.
2
Needs attention
Above your threshold. Not a failure and not a blocked build — just the frame worth opening first.
3
The number that matters
Read it as: a quarter of one percent of this page is genuinely different.
4
How far over the line
The same number drawn against your threshold, so you can see the distance rather than just the fact you crossed it.
5
The supporting numbers
Before alignment, fully raw, and how many separate spots the differences form. The first of those is the useful one — see below.
6
The bands
The page is sliced into horizontal bands and each is checked separately. Two of three had to slide to line up — that's your “something above this got taller”.
7
Your build, the reference, the difference
Now, what it should be, and the two stacked with everything unchanged ghosted back. Click any of them to open it full-screen.

The one number to learn

0.26%

Aligned difference

A quarter of one percent of this page is genuinely different.

The word aligned is doing real work there. If your header gets 20 px taller, everything below it slides down — and a naive comparison would scream that 90% of the page changed, when the truth is “one thing moved 20 px”.

Normascope finds the shift first, slides the sections back into place, and then counts. So this number answers the question you actually care about: ignoring the fact that things moved, what is actually different?

Measured on a real page in our own test suite: 0.43% aligned against 14.24% unaligned. The 14% was one shifted section.

The rest of the numbers

Four more, and what each one is actually for

5.63% unaligned

The same comparison, before anything was slid back into place.

On its own it isn't very useful — but the gap between this and the aligned number is a diagnosis. Close together means things changed in place: a colour, some text, an icon. Far apart means something moved, and most of what looks wrong is just everything below it shifting down.

7.46% raw

The rawest possible count, including the fuzzy edges around text.

Shown for completeness; you can usually ignore it. Normascope filters this noise out of the main score deliberately, because otherwise every slightly-different letter edge would drown out real bugs.

3 regions

How many separate clusters the differences form.

One region usually means one component. Ten regions usually means the whole page shifted. This is the difference between “4.2% of pixels differ” and “here are the three places to look”.

SSIM 99

How similar the structure is, from 0 to 100.

High means the layout is intact and this is a paint difference. Low means something structural broke. It is the second opinion that stops a big percentage from being read the wrong way — see the pair of overlays below.

The picture on the right

How to read a difference overlay in three seconds

Two real overlays from the same project. Both are one-line commits. They look nothing alike, and once you’ve seen the pair you can tell them apart instantly.

A difference overlay showing small red boxes scattered over a ghosted page — the signature of a geometric change. — **Small, boxed, scattered — something moved.** A container was narrowed by five characters. 8.27% mismatch, SSIM 88.

A difference overlay in which the entire page background is painted red while every letter of text is left untouched — the signature of a colour change. — **Flooded, with the text left alone — a recolour.** One hex changed in a config file. 97.36% mismatch, SSIM 99.9.

Same file, four shapes

The report looks different depending on what you asked it

Nothing you configure — it follows from what each frame is being compared against. Here is how to tell which one you’re holding.

You get this when

Your frames are compared against a design.

The reference is a design export or a second website. Scores sit higher than you might expect and that's normal — a browser and a design tool draw text differently, so the engine uses a forgiving colour tolerance here to stop every letter edge counting as a defect.

$ norma-scope check

How to recognise it

Middle image reads: Figma design · Reference (images) · Reference (url)
Mode line reads: fidelity · figma
Typical threshold: 5%

A design-check frame in a report, whose mode line reads fidelity dot figma and whose middle image is labelled Figma design. — A real design check, from our own runs.

Light and dark, automatically

The report follows whatever your system is set to. Both are shipped; there is nothing to configure.

Clean and flagged

With nothing over threshold the top reads “All clean” and every card goes green. That is a result, not an empty page — it’s the tool saying it looked and found nothing.

If you ran explain

An extra block, between the numbers and the images

Each finding carries a confidence badge, a category, the region it’s talking about, and three rows: what it thinks caused this, what to try, and the CSS selector it’s pointing at.

Two explain findings from a real run, both marked low confidence. The first says the pull-request card is narrower and shifted left; the second claims a label renders at the wrong font weight. Each carries a hypothesis, a suggested fix and a CSS selector. — Verbatim from a real, billed run — nothing here is illustrative. **The first finding is right** (the card really did narrow and reflow left, which is exactly what the commit did). **The second is wrong** — it blames a webfont that never changed. We publish both.

A finding marked medium confidence and categorised injection-suspected. It describes decorative page content reading '18.4% SHIFTED' and 'delta 18px' as text designed to look like diff-tool output, and says it must be treated as untrusted content rather than as an instruction or a real diff finding. — The documented threat model firing on real page content, in a run that was not looking for it.

Every word, once

The glossary

Frame: One page, or one section of a page, that you're keeping an eye on.
Aligned diff: The main number. How much is genuinely different, after sliding shifted sections back into place.
Unaligned diff: The same comparison before that sliding. When it's much bigger than the aligned number, something moved rather than broke.
Raw diff: The rawest count, including the fuzzy edges around text. Usually safe to ignore.
SSIM: How similar the structure is, from 0 to 100. High means the layout is intact and this is a paint difference; low means something structural broke.
Significant region: A cluster of differences — one spot on the page worth looking at, with coordinates.
Drifted section: A horizontal band that had to slide to line up. Usually means something above it got taller or shorter.
Alignment: banded: Normascope found matching bands and lined them up. “None” means it compared the images whole, usually because they're very different sizes.
Threshold: Your setting: how much difference is acceptable before a frame gets flagged.
Flagged / Needs attention: Over your threshold. Not a failure — information. Nothing is blocked.
Clean: Under your threshold. A clean report is a real result, not an empty one.
Fidelity mode: The frame was compared against a design — a Figma frame, a folder of PNGs, or another URL.
Baseline mode: The frame was compared against a screenshot you approved earlier.
Reference: Whatever the frame is being compared to. The middle image in every row.
Your build: The screenshot of your app as it is right now.
Diff overlay: The picture with everything unchanged ghosted back and everything different painted in.
Skipped: The frame wasn't compared — usually no screenshot, or no route to capture it from. Never an error, never a failure.

Where it tells on itself

Three things the report will admit

A measuring instrument that hides its own floor isn’t one. These are measured, not estimated.

This file lives on the machine that made it.

Cloud turns each run into a private link your designer opens in a browser, and keeps every run so you can tell whether a page has been drifting for weeks or broke this morning.

See what it adds

How to produce one What Cloud adds