Norma

Norma compares your implementation screenshots against the original Figma designs and generates a visual diff report — automatically, every time you commit. No servers, no LLM, no blocking: just a report you can open and share.

Install

npx norma-scope init

Run this once per project. It walks you through connecting your Figma file and picking which frames to track.

How it works

1. npx norma-scope init — connect your Figma file, select frames to check
2. Screenshot your implementation
3. Drop the screenshots into .bridge/screenshots/
4. git commit
5. .bridge/reports/report.html generates automatically
6. Open it and share with your designer if needed

The pre-commit hook installed by init never blocks a commit — it only generates the report. If your Figma token is missing or invalid, the hook skips the comparison and prints a warning, but your commit still goes through.

Screenshot naming convention

Screenshot filenames are the lowercased, hyphenated version of the matching Figma frame name. init tells you the exact filenames it expects:

Figma frame name     Screenshot filename
────────────────     ───────────────────
"Hero Section"    →  hero-section.png
"Primary Button"  →  primary-button.png
"Nav Bar"         →  nav-bar.png

Taking the screenshot

Norma compares images pixel-for-pixel from the top-left corner — it doesn't understand scrolling or page sections. So your screenshot needs to be a full-page capture at the exact dimensions init showed you (e.g. 1440×10661px), not just what's visible in your browser viewport. A partial screenshot (like just the footer) will get compared against the top of the design and produce a meaningless, huge diff %.

Chrome / Edge (Mac and Windows — same steps, since this is a browser feature, not an OS one):

1. Open the page and resize your browser window to match the frame's width (e.g. 1440px wide)
2. Open DevTools (Cmd+Option+I on Mac, Ctrl+Shift+I on Windows)
3. Open the Command Menu (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows)
4. Type "screenshot" and choose Capture full size screenshot
5. Chrome downloads a PNG of the entire page, full height, no scrolling needed

Firefox (Mac and Windows):

1. Right-click anywhere on the page and choose Take Screenshot (or press Shift+F2, type screenshot --fullpage, then Enter)
2. Choose Save full page

Browser extensions (any browser, if you prefer a permanent toolbar button):

• GoFullPage (Chrome) or FireShot (Firefox) both export a single full-page PNG in one click

Once you have the PNG, drop it into .bridge/screenshots/ with the exact filename init printed for that frame, then git commit as normal.

Running manually

The pre-commit hook runs this for you automatically, but you can also run it by hand any time:

npx norma-scope compare

Add --fresh to bypass Norma's local Figma cache and force a fresh fetch (useful right after you've updated the design):

npx norma-scope compare --fresh

Cleaning up

npx norma-scope clean

Empties .bridge/screenshots/, .bridge/diff/, .bridge/reports/, and .bridge/.cache/. Useful when switching to a different Figma file, or just to clear out old local artifacts — .bridge/config.json is never touched.

Config

init writes .bridge/config.json, which is committed to your repo:

{
  "figmaFileKey": "abc123XYZ",
  "threshold": 5,
  "frames": [
    {
      "label": "Hero Section",
      "screenshot": "hero-section.png",
      "figmaFrameId": "12:34"
    }
  ]
}

threshold is the mismatch percentage above which a component is flagged in the report — it's a visual flag, not a blocker.

Your Figma personal access token is stored in .env.local, which is never committed.

What's not committed

.bridge/screenshots/
.bridge/reports/
.bridge/diff/
.bridge/.cache/
.env.local

Only .bridge/config.json is committed — everything else is local to your machine.

Norma's current version (V1) is screenshot diffing, local and free, with no LLM involved.

See COMMANDS.md for a full command reference and the step-by-step workflow.

License

MIT