norma-scope 0.1.2 → 0.2.0

package/README.md

@@ -33,6 +33,26 @@ Figma frame name     Screenshot filename
 "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](https://chromewebstore.google.com/detail/gofullpage-full-page-scr/fdpohaocaechififmbbbbbknoalclacl) (Chrome) or [FireShot](https://addons.mozilla.org/en-US/firefox/addon/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:
@@ -47,6 +67,14 @@ Add `--fresh` to bypass Norma's local Figma cache and force a fresh fetch (usefu
 npx norma-scope compare --fresh
 ```
 
+## Cleaning up
+
+```bash
+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:
@@ -81,12 +109,9 @@ Your Figma personal access token is stored in `.env.local`, which is never commi
 
 Only `.bridge/config.json` is committed — everything else is local to your machine.
 
-## Coming soon
-
-Norma's current version (V1) is screenshot diffing, local and free, with no LLM involved. Two upgrades are planned:
+Norma's current version (V1) is screenshot diffing, local and free, with no LLM involved.
 
-- **V2 (pro)** — LLM code scan that points to the exact lines of code causing a visual mismatch
-- **V3 (team)** — runs on every PR via GitHub Action, posts the report as a PR comment, plus a team dashboard and report history
+See [COMMANDS.md](COMMANDS.md) for a full command reference and the step-by-step workflow.
 
 ## License
 

package/dist/cache.js

@@ -1,24 +1,61 @@
 import { readFile, writeFile, mkdir, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { fetchFramePng } from "./figma.js";
+import { fetchFramesPng } from "./figma.js";
 const CACHE_DIR = path.join(".bridge", ".cache");
 const TTL_MS = 10 * 60 * 1000; // 10 minutes
 function cachePathFor(frameId) {
     const safeId = frameId.replace(/[^a-zA-Z0-9]/g, "_");
     return path.join(CACHE_DIR, `${safeId}.png`);
 }
+async function isCacheFresh(cachePath) {
+    if (!existsSync(cachePath)) {
+        return false;
+    }
+    const stats = await stat(cachePath);
+    return Date.now() - stats.mtimeMs < TTL_MS;
+}
 export async function getFramePng(fileKey, frameId, token, options = {}) {
-    const cachePath = cachePathFor(frameId);
-    if (!options.fresh && existsSync(cachePath)) {
-        const stats = await stat(cachePath);
-        const age = Date.now() - stats.mtimeMs;
-        if (age < TTL_MS) {
-            return readFile(cachePath);
-        }
+    const result = await getFramesPng(fileKey, [frameId], token, options);
+    const png = result.pngs.get(frameId);
+    if (!png) {
+        throw new Error(result.fetchError ?? `No image returned for frame ${frameId}`);
     }
-    const png = await fetchFramePng(fileKey, frameId, token);
-    await mkdir(CACHE_DIR, { recursive: true });
-    await writeFile(cachePath, png);
     return png;
 }
+export async function getFramesPng(fileKey, frameIds, token, options = {}) {
+    const pngs = new Map();
+    const staleFrameIds = new Set();
+    const toFetch = [];
+    for (const frameId of frameIds) {
+        const cachePath = cachePathFor(frameId);
+        if (!options.fresh && (await isCacheFresh(cachePath))) {
+            pngs.set(frameId, await readFile(cachePath));
+        }
+        else {
+            toFetch.push(frameId);
+        }
+    }
+    let fetchError = null;
+    if (toFetch.length > 0) {
+        try {
+            const fetched = await fetchFramesPng(fileKey, toFetch, token);
+            await mkdir(CACHE_DIR, { recursive: true });
+            for (const [frameId, png] of fetched) {
+                pngs.set(frameId, png);
+                await writeFile(cachePathFor(frameId), png);
+            }
+        }
+        catch (err) {
+            fetchError = err.message;
+            for (const frameId of toFetch) {
+                const cachePath = cachePathFor(frameId);
+                if (existsSync(cachePath)) {
+                    pngs.set(frameId, await readFile(cachePath));
+                    staleFrameIds.add(frameId);
+                }
+            }
+        }
+    }
+    return { pngs, staleFrameIds, fetchError };
+}

package/dist/clean.js

@@ -0,0 +1,31 @@
+import { rm, mkdir, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+const BRIDGE_DIR = ".bridge";
+const CLEAN_TARGETS = [
+    { dir: path.join(BRIDGE_DIR, "screenshots"), label: "screenshots" },
+    { dir: path.join(BRIDGE_DIR, "diff"), label: "diff images" },
+    { dir: path.join(BRIDGE_DIR, "reports"), label: "reports" },
+    { dir: path.join(BRIDGE_DIR, ".cache"), label: "Figma cache" },
+];
+export async function runClean() {
+    if (!existsSync(BRIDGE_DIR)) {
+        console.log("Norma: no .bridge directory found — nothing to clean.");
+        return;
+    }
+    console.log("Norma — Clean");
+    console.log("══════════════════════════════════════════════");
+    for (const target of CLEAN_TARGETS) {
+        let fileCount = 0;
+        if (existsSync(target.dir)) {
+            const entries = await readdir(target.dir);
+            fileCount = entries.length;
+            await rm(target.dir, { recursive: true, force: true });
+        }
+        await mkdir(target.dir, { recursive: true });
+        console.log(`  ${target.label.padEnd(14)} →  ${fileCount} file(s) removed`);
+    }
+    console.log("");
+    console.log("  .bridge/config.json was left untouched.");
+    console.log("══════════════════════════════════════════════");
+}

package/dist/compare.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { getFramePng } from "./cache.js";
+import { getFramesPng } from "./cache.js";
 import { runDiff } from "./diff.js";
 import { generateReport } from "./report.js";
 const BRIDGE_DIR = ".bridge";
@@ -18,6 +18,25 @@ function readEnvToken() {
     const match = content.match(/^FIGMA_TOKEN=(.*)$/m);
     return match ? match[1].trim() : null;
 }
+function parseConfig(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return null;
+    }
+    const candidate = parsed;
+    if (typeof candidate.figmaFileKey !== "string" ||
+        typeof candidate.threshold !== "number" ||
+        !Array.isArray(candidate.frames)) {
+        return null;
+    }
+    return candidate;
+}
 export async function runCompare(options = {}) {
     if (!existsSync(CONFIG_PATH)) {
         console.log("Norma: no .bridge/config.json found — run `npx norma-scope init` first.");
@@ -28,30 +47,46 @@ export async function runCompare(options = {}) {
         console.log("Norma: ⚠ .env.local missing or FIGMA_TOKEN not set — skipping comparison.");
         return;
     }
-    const config = JSON.parse(await readFile(CONFIG_PATH, "utf-8"));
+    const config = parseConfig(await readFile(CONFIG_PATH, "utf-8"));
+    if (!config) {
+        console.log("Norma: ⚠ .bridge/config.json is malformed — skipping comparison. Run `npx norma-scope init` to regenerate it.");
+        return;
+    }
     const results = [];
     const lines = [];
+    const framesWithScreenshots = config.frames.filter((frame) => existsSync(path.join(SCREENSHOTS_DIR, frame.screenshot)));
+    let figmaPngs = new Map();
+    let staleFrameIds = new Set();
+    let batchFetchError = null;
+    if (framesWithScreenshots.length > 0) {
+        const result = await getFramesPng(config.figmaFileKey, framesWithScreenshots.map((f) => f.figmaFrameId), token, { fresh: options.fresh });
+        figmaPngs = result.pngs;
+        staleFrameIds = result.staleFrameIds;
+        if (result.fetchError) {
+            batchFetchError = result.fetchError.includes("429")
+                ? "rate limited by Figma — try again in a few minutes (Norma caches results for 10 min, so this should resolve on its own)"
+                : result.fetchError;
+        }
+    }
     for (const frame of config.frames) {
         const screenshotPath = path.join(SCREENSHOTS_DIR, frame.screenshot);
         if (!existsSync(screenshotPath)) {
             lines.push(`  ${frame.screenshot.padEnd(22)} →  ⚠ skipped (no screenshot found)`);
             continue;
         }
-        let figmaPng;
-        try {
-            figmaPng = await getFramePng(config.figmaFileKey, frame.figmaFrameId, token, {
-                fresh: options.fresh,
-            });
-        }
-        catch (err) {
-            lines.push(`  ${frame.screenshot.padEnd(22)} →  ⚠ skipped (Figma fetch failed: ${err.message})`);
+        const figmaPng = figmaPngs.get(frame.figmaFrameId);
+        if (!figmaPng) {
+            const reason = batchFetchError ?? `no image returned for frame ${frame.figmaFrameId}`;
+            lines.push(`  ${frame.screenshot.padEnd(22)} →  ⚠ skipped (Figma fetch failed: ${reason})`);
             continue;
         }
         const diffPath = path.join(DIFF_DIR, frame.screenshot.replace(/\.png$/, "-diff.png"));
         let mismatchPercent;
+        let dimensionMismatch;
         try {
             const result = await runDiff(screenshotPath, figmaPng, diffPath);
             mismatchPercent = result.mismatchPercent;
+            dimensionMismatch = result.dimensionMismatch;
         }
         catch (err) {
             lines.push(`  ${frame.screenshot.padEnd(22)} →  ⚠ skipped (diff failed: ${err.message})`);
@@ -68,6 +103,12 @@ export async function runCompare(options = {}) {
             ? `⚠ above threshold (${config.threshold}%)`
             : "✓";
         lines.push(`  ${frame.screenshot.padEnd(22)} →  ${mismatchPercent.toFixed(1).padStart(5)}%  ${flag}`);
+        if (dimensionMismatch) {
+            lines.push(`  ${"".padEnd(22)}    ⚠ image dimensions differ significantly — check screenshot export scale`);
+        }
+        if (staleFrameIds.has(frame.figmaFrameId)) {
+            lines.push(`  ${"".padEnd(22)}    ⚠ Figma fetch failed — using a cached design image older than 10 min`);
+        }
     }
     console.log("Norma");
     console.log("══════════════════════════════════════════════");

package/dist/diff.js

@@ -1,6 +1,12 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { PNG } from "pngjs";
 import pixelmatch from "pixelmatch";
+const DIMENSION_MISMATCH_THRESHOLD = 0.15;
+function isDimensionMismatch(aWidth, aHeight, bWidth, bHeight) {
+    const widthDiff = Math.abs(aWidth - bWidth) / Math.max(aWidth, bWidth);
+    const heightDiff = Math.abs(aHeight - bHeight) / Math.max(aHeight, bHeight);
+    return widthDiff > DIMENSION_MISMATCH_THRESHOLD || heightDiff > DIMENSION_MISMATCH_THRESHOLD;
+}
 function resizeToCanvas(png, width, height) {
     if (png.width === width && png.height === height) {
         return png;
@@ -13,6 +19,7 @@ export async function runDiff(screenshotPath, figmaPngBuffer, outputPath) {
     const screenshotBuffer = await readFile(screenshotPath);
     const screenshotPng = PNG.sync.read(screenshotBuffer);
     const figmaPng = PNG.sync.read(figmaPngBuffer);
+    const dimensionMismatch = isDimensionMismatch(screenshotPng.width, screenshotPng.height, figmaPng.width, figmaPng.height);
     const width = Math.max(screenshotPng.width, figmaPng.width);
     const height = Math.max(screenshotPng.height, figmaPng.height);
     const a = resizeToCanvas(screenshotPng, width, height);
@@ -21,5 +28,5 @@ export async function runDiff(screenshotPath, figmaPngBuffer, outputPath) {
     const mismatchedPixels = pixelmatch(a.data, b.data, diff.data, width, height, { threshold: 0.1 });
     const mismatchPercent = (mismatchedPixels / (width * height)) * 100;
     await writeFile(outputPath, PNG.sync.write(diff));
-    return { mismatchPercent };
+    return { mismatchPercent, dimensionMismatch };
 }

package/dist/figma.js

@@ -12,26 +12,52 @@ export async function fetchFrameList(fileKey, token) {
         const pageChildren = page.children ?? [];
         for (const node of pageChildren) {
             if (node.type === "FRAME") {
-                frames.push({ id: node.id, name: node.name });
+                frames.push({
+                    id: node.id,
+                    name: node.name,
+                    width: node.absoluteBoundingBox ? Math.round(node.absoluteBoundingBox.width) : null,
+                    height: node.absoluteBoundingBox ? Math.round(node.absoluteBoundingBox.height) : null,
+                });
             }
         }
     }
     return frames;
 }
 export async function fetchFramePng(fileKey, frameId, token) {
-    const res = await fetch(`${FIGMA_API_BASE}/images/${fileKey}?ids=${encodeURIComponent(frameId)}&format=png`, { headers: { "X-Figma-Token": token } });
+    const result = await fetchFramesPng(fileKey, [frameId], token);
+    const png = result.get(frameId);
+    if (!png) {
+        throw new Error(`No image returned for frame ${frameId}`);
+    }
+    return png;
+}
+export async function fetchFramesPng(fileKey, frameIds, token) {
+    if (frameIds.length === 0) {
+        return new Map();
+    }
+    const idsParam = frameIds.map(encodeURIComponent).join(",");
+    const res = await fetch(`${FIGMA_API_BASE}/images/${fileKey}?ids=${idsParam}&format=png`, { headers: { "X-Figma-Token": token } });
     if (!res.ok) {
-        throw new Error(`Figma API error exporting frame ${frameId}: ${res.status} ${res.statusText}`);
+        throw new Error(`Figma API error exporting frames ${frameIds.join(", ")}: ${res.status} ${res.statusText}`);
     }
     const data = (await res.json());
-    const imageUrl = data.images[frameId];
-    if (!imageUrl) {
-        throw new Error(`No image returned for frame ${frameId}`);
-    }
-    const imgRes = await fetch(imageUrl);
-    if (!imgRes.ok) {
-        throw new Error(`Failed to download exported PNG: ${imgRes.status} ${imgRes.statusText}`);
+    const entries = await Promise.all(frameIds.map(async (frameId) => {
+        const imageUrl = data.images[frameId];
+        if (!imageUrl) {
+            return null;
+        }
+        const imgRes = await fetch(imageUrl);
+        if (!imgRes.ok) {
+            return null;
+        }
+        const arrayBuffer = await imgRes.arrayBuffer();
+        return [frameId, Buffer.from(arrayBuffer)];
+    }));
+    const result = new Map();
+    for (const entry of entries) {
+        if (entry) {
+            result.set(entry[0], entry[1]);
+        }
     }
-    const arrayBuffer = await imgRes.arrayBuffer();
-    return Buffer.from(arrayBuffer);
+    return result;
 }

package/dist/index.js

@@ -1,5 +1,6 @@
 import { runInit } from "./init.js";
 import { runCompare } from "./compare.js";
+import { runClean } from "./clean.js";
 const HELP = `
 Norma
 
@@ -10,6 +11,7 @@ Commands:
   init             Set up Norma in this project
   compare          Compare local screenshots against Figma designs
   compare --fresh  Bypass the Figma cache and force a fresh fetch
+  clean            Remove local screenshots, diffs, reports, and cache
 `;
 async function main() {
     const command = process.argv[2];
@@ -20,6 +22,9 @@ async function main() {
         case "compare":
             await runCompare({ fresh: process.argv.includes("--fresh") });
             break;
+        case "clean":
+            await runClean();
+            break;
         default:
             console.log(HELP);
             break;

package/dist/init.js

@@ -1,5 +1,5 @@
 import { createInterface } from "node:readline/promises";
-import { mkdir, writeFile, readFile, appendFile, chmod } from "node:fs/promises";
+import { mkdir, writeFile, readFile, appendFile, chmod, copyFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fetchFrameList } from "./figma.js";
@@ -47,16 +47,25 @@ async function updateGitignore() {
         await appendFile(gitignorePath, `${prefix}${missing.join("\n")}\n`);
     }
 }
-async function installPreCommitHook() {
+export async function installPreCommitHook() {
     const hooksDir = ".git/hooks";
     if (!existsSync(hooksDir)) {
         console.log("  ⚠ No .git/hooks directory found — skipping pre-commit hook install.");
-        return;
+        return { backedUpTo: null };
     }
     const hookPath = path.join(hooksDir, "pre-commit");
-    const hookContent = "#!/bin/sh\nnpx norma-scope compare\n";
+    const hookContent = "#!/bin/sh\nnpx norma-scope compare\nexit 0\n";
+    let backedUpTo = null;
+    if (existsSync(hookPath)) {
+        const existing = await readFile(hookPath, "utf-8");
+        if (!existing.includes("npx norma-scope compare")) {
+            backedUpTo = `${hookPath}.pre-norma-backup`;
+            await copyFile(hookPath, backedUpTo);
+        }
+    }
     await writeFile(hookPath, hookContent, { mode: 0o755 });
     await chmod(hookPath, 0o755);
+    return { backedUpTo };
 }
 export async function runInit() {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -77,7 +86,8 @@ export async function runInit() {
         }
         console.log("Which frames do you want to check? (comma-separated numbers)\n");
         frames.forEach((frame, i) => {
-            console.log(`  ${i + 1}   ${frame.name}`);
+            const dims = frame.width && frame.height ? `  (${frame.width}×${frame.height}px)` : "";
+            console.log(`  ${i + 1}   ${frame.name}${dims}`);
         });
         const selection = await rl.question("\n> ");
         const indices = selection
@@ -106,25 +116,36 @@ export async function runInit() {
             await writeFile(".env.local", `FIGMA_TOKEN=${trimmedToken}\n`);
         }
         await updateGitignore();
-        await installPreCommitHook();
+        const { backedUpTo } = await installPreCommitHook();
         console.log("\n✓ Config written to .bridge/config.json");
         console.log("✓ .bridge/screenshots/ folder created");
         console.log("✓ .bridge/reports/ folder created");
         console.log("✓ .bridge/diff/ folder created");
         console.log("✓ .gitignore updated");
-        console.log("✓ Pre-commit hook installed");
+        if (backedUpTo) {
+            console.log(`✓ Pre-commit hook installed (your existing hook was backed up to ${backedUpTo})`);
+        }
+        else {
+            console.log("✓ Pre-commit hook installed");
+        }
         console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
         console.log("You're ready. Here's what to do next:\n");
         console.log("  Screenshot your implementation for each component");
         console.log("  and drop the files here: .bridge/screenshots/\n");
         console.log("  Expected filenames:");
-        for (const frame of config.frames) {
-            console.log(`    ${frame.screenshot}`);
-        }
+        config.frames.forEach((frame, i) => {
+            const source = selectedFrames[i];
+            const dims = source.width && source.height ? `  — capture at ${source.width}×${source.height}px` : "";
+            console.log(`    ${frame.screenshot}${dims}`);
+        });
         console.log("\n  Then just git commit as normal.");
         console.log("  The report generates automatically.");
         console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
     }
+    catch (err) {
+        console.log(`\n✗ Setup failed: ${err.message}`);
+        process.exitCode = 1;
+    }
     finally {
         rl.close();
     }

package/dist/report.js

@@ -14,12 +14,28 @@ function escapeHtml(str) {
     return str
         .replace(/&/g, "&")
         .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;");
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
 }
 async function toBase64(filePath) {
     const buffer = await readFile(filePath);
     return buffer.toString("base64");
 }
+function frame(src, alt, dotClass, caption) {
+    return `
+          <figure class="shot-frame">
+            <div class="shot-chrome">
+              <span class="shot-dot ${dotClass}"></span>
+              <span class="shot-chrome-line short"></span>
+              <span class="shot-chrome-line"></span>
+            </div>
+            <div class="shot-body">
+              <img src="${src}" loading="lazy" onclick="openLightbox('${src}')" alt="${alt}" />
+            </div>
+            <figcaption>${caption}</figcaption>
+          </figure>`;
+}
 export async function generateReport(results, threshold, outputPath) {
     const { branch, commit } = getGitInfo();
     const generated = new Date().toLocaleString("en-GB", {
@@ -40,28 +56,17 @@ export async function generateReport(results, threshold, outputPath) {
         const buildSrc = `data:image/png;base64,${buildB64}`;
         const figmaSrc = `data:image/png;base64,${figmaB64}`;
         const diffSrc = `data:image/png;base64,${diffB64}`;
+        const label = escapeHtml(r.label);
         return `
-      <section class="component ${isFlagged ? "flagged" : "clean"}">
+      <section class="component">
         <div class="component-header">
-          <div class="component-title">
-            <span class="status-dot"></span>
-            <h2>${escapeHtml(r.label)}</h2>
-          </div>
-          <span class="component-status">${r.mismatchPercent.toFixed(1)}% diff</span>
+          <h2>${label}</h2>
+          <span class="component-status ${isFlagged ? "flagged" : "clean"}">${isFlagged ? "⚠ " : ""}${r.mismatchPercent.toFixed(1)}% diff</span>
         </div>
         <div class="component-images">
-          <figure class="image-col">
-            <img src="${buildSrc}" loading="lazy" onclick="openLightbox('${buildSrc}')" alt="${escapeHtml(r.label)} — your build" />
-            <figcaption>Your build</figcaption>
-          </figure>
-          <figure class="image-col">
-            <img src="${figmaSrc}" loading="lazy" onclick="openLightbox('${figmaSrc}')" alt="${escapeHtml(r.label)} — Figma design" />
-            <figcaption>Figma design</figcaption>
-          </figure>
-          <figure class="image-col">
-            <img src="${diffSrc}" loading="lazy" onclick="openLightbox('${diffSrc}')" alt="${escapeHtml(r.label)} — diff overlay" />
-            <figcaption>Diff overlay</figcaption>
-          </figure>
+${frame(buildSrc, `${label} — your build`, "dot-build", "Your build")}
+${frame(figmaSrc, `${label} — Figma design`, "dot-build", "Figma design")}
+${frame(diffSrc, `${label} — diff overlay`, "dot-diff", "Diff overlay")}
         </div>
       </section>`;
     }));
@@ -74,139 +79,126 @@ export async function generateReport(results, threshold, outputPath) {
 <style>
   :root {
     --clay: #A8736E;
-    --clay-dark: #7E5854;
-    --clay-tint: #F5EBE9;
     --ink: #1C1B1A;
     --ink-soft: #6B6664;
     --line: #E7E1DF;
-    --bg: #FAF7F6;
+    --page-bg: #EDE7E1;
     --card: #FFFFFF;
-    --danger: #C2452F;
-    --danger-tint: #FBEAE6;
+    --frame-bg: #F7F5F3;
+    --chrome-bg: #F0EDEA;
+    --danger: #B6611F;
     --success: #3E7D52;
-    --success-tint: #E8F3EB;
   }
   * { box-sizing: border-box; }
   body {
     font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, sans-serif;
-    background: var(--bg);
+    background: var(--page-bg);
     color: var(--ink);
     margin: 0;
-    padding: 0 0 64px;
+    padding: 48px 24px;
     -webkit-font-smoothing: antialiased;
   }
-  .topbar {
-    background: var(--ink);
-    color: #fff;
-    padding: 28px 40px;
-  }
-  .topbar .wordmark {
-    font-size: 22px;
-    font-weight: 700;
-    color: var(--clay);
-    letter-spacing: -0.01em;
-    margin: 0 0 10px;
+  .card {
+    max-width: 1080px;
+    margin: 0 auto;
+    background: var(--card);
+    border-radius: 24px;
+    box-shadow: 0 24px 60px rgba(28,27,26,0.10);
+    overflow: hidden;
   }
-  .meta-row {
+  header {
     display: flex;
-    flex-wrap: wrap;
-    gap: 10px;
-  }
-  .meta-pill {
-    background: rgba(255,255,255,0.08);
-    border: 1px solid rgba(255,255,255,0.12);
-    color: rgba(255,255,255,0.85);
-    font-size: 12px;
-    padding: 5px 12px;
-    border-radius: 999px;
-    font-variant-numeric: tabular-nums;
-  }
-  main { max-width: 980px; margin: 0 auto; padding: 36px 40px 0; }
-  .summary {
-    display: grid;
-    grid-template-columns: repeat(3, 1fr);
-    gap: 16px;
-    margin: 0 0 36px;
+    justify-content: space-between;
+    align-items: flex-start;
+    padding: 32px 40px;
+    border-bottom: 1px solid var(--line);
   }
-  .stat-card {
-    background: var(--card);
-    border: 1px solid var(--line);
-    border-radius: 14px;
-    padding: 20px 22px;
-    box-shadow: 0 1px 2px rgba(28,27,26,0.04), 0 8px 24px rgba(28,27,26,0.06);
+  header h1 { font-size: 26px; font-weight: 700; margin: 0 0 8px; }
+  .report-meta {
+    font-family: "SF Mono", ui-monospace, Menlo, monospace;
+    font-size: 13px;
+    color: var(--ink-soft);
   }
-  .stat-card .stat-number { font-size: 30px; font-weight: 700; line-height: 1; }
-  .stat-card .stat-label { font-size: 13px; color: var(--ink-soft); margin-top: 6px; }
-  .stat-card.attention .stat-number { color: var(--danger); }
-  .stat-card.clean .stat-number { color: var(--success); }
-  .component {
-    background: var(--card);
-    border: 1px solid var(--line);
-    border-radius: 14px;
-    margin-bottom: 18px;
-    overflow: hidden;
-    box-shadow: 0 1px 2px rgba(28,27,26,0.04), 0 8px 24px rgba(28,27,26,0.05);
+  .wordmark { font-size: 14px; font-weight: 700; color: var(--clay); letter-spacing: -0.01em; }
+  .summary-bar {
+    display: flex;
+    gap: 28px;
+    flex-wrap: wrap;
+    padding: 20px 40px;
+    border-bottom: 1px solid var(--line);
+    font-size: 15px;
   }
+  .summary-bar b { font-weight: 700; }
+  .summary-bar .attention b { color: var(--danger); }
+  .summary-bar .clean b { color: var(--success); }
+  .components { padding: 8px 40px 40px; }
+  .component { padding: 28px 0; border-bottom: 1px solid var(--line); }
+  .component:last-child { border-bottom: none; }
   .component-header {
     display: flex;
     justify-content: space-between;
     align-items: center;
-    padding: 16px 20px;
-    border-bottom: 1px solid var(--line);
-  }
-  .component-title { display: flex; align-items: center; gap: 10px; }
-  .component-title h2 { font-size: 15px; font-weight: 600; margin: 0; }
-  .status-dot { width: 9px; height: 9px; border-radius: 50%; flex-shrink: 0; }
-  .component.flagged .status-dot { background: var(--danger); }
-  .component.clean .status-dot { background: var(--success); }
-  .component-status {
-    font-size: 12px;
-    font-weight: 600;
-    padding: 5px 12px;
-    border-radius: 999px;
-    font-variant-numeric: tabular-nums;
+    margin-bottom: 18px;
   }
-  .component.flagged .component-status { color: var(--danger); background: var(--danger-tint); }
-  .component.clean .component-status { color: var(--success); background: var(--success-tint); }
+  .component-header h2 { font-size: 19px; font-weight: 700; margin: 0; }
+  .component-status { font-size: 13px; font-weight: 600; }
+  .component-status.flagged { color: var(--danger); }
+  .component-status.clean { color: var(--success); }
   .component-images {
     display: grid;
     grid-template-columns: 1fr 1fr 1fr;
-    gap: 1px;
-    background: var(--line);
+    gap: 20px;
   }
-  .image-col {
-    background: var(--card);
-    padding: 16px;
-    margin: 0;
-    text-align: center;
+  .shot-frame { margin: 0; }
+  .shot-chrome {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    height: 28px;
+    padding: 0 12px;
+    background: var(--chrome-bg);
+    border: 1px solid var(--line);
+    border-bottom: none;
+    border-radius: 10px 10px 0 0;
   }
-  .image-col img {
+  .shot-dot { width: 7px; height: 7px; border-radius: 50%; flex-shrink: 0; }
+  .dot-build { background: var(--clay); }
+  .dot-diff { background: #B9B3AE; }
+  .shot-chrome-line { height: 4px; border-radius: 2px; background: #DCD6D1; }
+  .shot-chrome-line.short { width: 18px; }
+  .shot-chrome-line:not(.short) { width: 40px; margin-left: auto; }
+  .shot-body {
+    background: var(--frame-bg);
+    border: 1px solid var(--line);
+    border-top: none;
+    border-radius: 0 0 10px 10px;
+    padding: 14px;
+  }
+  .shot-body img {
     width: 100%;
-    height: 280px;
+    height: 240px;
     object-fit: contain;
     object-position: top center;
-    background: var(--bg);
-    border-radius: 8px;
-    border: 1px solid var(--line);
     cursor: zoom-in;
-    transition: opacity 0.15s ease;
     display: block;
+    transition: opacity 0.15s ease;
   }
-  .image-col img:hover { opacity: 0.85; }
-  .image-col figcaption {
-    margin-top: 10px;
+  .shot-body img:hover { opacity: 0.85; }
+  .shot-frame figcaption {
+    margin-top: 12px;
+    text-align: center;
     font-size: 11px;
-    color: var(--ink-soft);
-    text-transform: uppercase;
+    font-weight: 700;
     letter-spacing: 0.06em;
-    font-weight: 600;
+    text-transform: uppercase;
+    color: var(--ink-soft);
   }
   footer {
-    margin-top: 40px;
     text-align: center;
     color: var(--ink-soft);
     font-size: 12px;
     line-height: 1.7;
+    padding: 28px 40px 8px;
   }
   #lightbox {
     display: none;
@@ -227,41 +219,33 @@ export async function generateReport(results, threshold, outputPath) {
     box-shadow: 0 20px 60px rgba(0,0,0,0.4);
   }
   @media (max-width: 720px) {
-    .summary { grid-template-columns: 1fr; }
     .component-images { grid-template-columns: 1fr; }
+    header { flex-direction: column; gap: 16px; }
   }
 </style>
 </head>
 <body>
-<div class="topbar">
-  <p class="wordmark">norma</p>
-  <div class="meta-row">
-    <span class="meta-pill">Branch: ${escapeHtml(branch)}</span>
-    <span class="meta-pill">Commit: ${escapeHtml(commit)}</span>
-    <span class="meta-pill">${escapeHtml(generated)}</span>
-  </div>
-</div>
-<main>
-  <div class="summary">
-    <div class="stat-card">
-      <div class="stat-number">${results.length}</div>
-      <div class="stat-label">Components checked</div>
-    </div>
-    <div class="stat-card attention">
-      <div class="stat-number">${needsAttention.length}</div>
-      <div class="stat-label">Need attention</div>
-    </div>
-    <div class="stat-card clean">
-      <div class="stat-number">${clean.length}</div>
-      <div class="stat-label">Clean</div>
+<div class="card">
+  <header>
+    <div>
+      <h1>Report</h1>
+      <p class="report-meta">Branch: ${escapeHtml(branch)} &middot; Commit: ${escapeHtml(commit)} &middot; ${escapeHtml(generated)}</p>
     </div>
+    <span class="wordmark">norma</span>
+  </header>
+  <div class="summary-bar">
+    <span>${results.length} components checked</span>
+    <span class="attention"><b>${needsAttention.length}</b> needs attention</span>
+    <span class="clean"><b>${clean.length}</b> clean</span>
+  </div>
+  <div class="components">
+    ${rows.join("\n")}
   </div>
-  ${rows.join("\n")}
   <footer>
     <p>Generated by Norma</p>
     <p>To fix: update your implementation, re-screenshot, commit again.</p>
   </footer>
-</main>
+</div>
 <div id="lightbox" onclick="closeLightbox()">
   <img id="lightbox-img" src="" alt="Full size preview" />
 </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "norma-scope",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Compare your implementation screenshots against Figma designs with a zero-friction, local pre-commit report.",
   "type": "module",
   "bin": {