argusqa-os 9.5.0 → 9.5.3

package/README.md

@@ -52,7 +52,7 @@ Then ask Claude (or any MCP client):
 Run argus_audit on http://localhost:3000
 ```
 
-**Six tools are exposed:**
+**Seven tools are exposed:**
 
 | Tool | What it does |
 | --- | --- |
@@ -62,6 +62,7 @@ Run argus_audit on http://localhost:3000
 | `argus_last_report` | Return the last saved JSON report without re-running a scan |
 | `argus_watch_snapshot` | Snapshot the currently open Chrome tab without navigating — raw console + network capture |
 | `argus_get_context` | Capture everything broken on the open tab, formatted as a diagnostic context for Claude to diagnose and suggest fixes |
+| `argus_design_audit` | Full Figma design-to-implementation fidelity audit — 13 finding types across color, typography, spacing, per-corner radius, position drift, stroke, shadow (color+spread), opacity, gap, and text. Selector fallback: `[data-testid]` → `[aria-label]` → `#id` → `.class` |
 
 > **Requires**: Node.js ≥ 20.19, Chrome (desktop or headless), and the `chrome-devtools-mcp` server registered alongside Argus (shown above).
 
@@ -79,7 +80,7 @@ The `landing/` directory contains the product landing page (React + Vite + Tailw
 
 | 🔴 Critical / 🟡 Warning / 🔵 Info | ⚙️ | 🧪 | 📋 |
 | :---: | :---: | :---: | :---: |
-| **114 distinct issue types detected** | **24 analysis engines** | **394 test assertions** | **93 test blocks** |
+| **114 distinct issue types detected** | **24 analysis engines** | **565 test assertions** | **128 test blocks** |
 
 </div>
 
@@ -348,7 +349,8 @@ Argus watches your running application and automatically surfaces issues that te
 | **Slack Notifications** | Rich Block Kit reports with inline screenshots routed to `#bugs-critical`, `#bugs-warnings`, `#bugs-digest` |
 | **Slash Command** | `/argus-retest <url>` triggers an on-demand test from any Slack channel |
 | **CI Integration** | GitHub Actions workflow runs daily at 6 AM UTC and on every push to `main` |
-| **MCP Server (AI-callable Argus)** | Register Argus as an MCP server via `.mcp.json`; Claude (or any MCP client) can call `argus_audit`, `argus_audit_full`, `argus_compare`, `argus_last_report`, `argus_watch_snapshot`, and `argus_get_context` directly from a conversation — no CLI, no terminal required. Published to npm as **[argusqa-os](https://www.npmjs.com/package/argusqa-os)** — add via `{ "command": "npx", "args": ["-y", "argusqa-os"] }` in `.mcp.json` |
+| **MCP Server (AI-callable Argus)** | Register Argus as an MCP server via `.mcp.json`; Claude (or any MCP client) can call `argus_audit`, `argus_audit_full`, `argus_compare`, `argus_last_report`, `argus_watch_snapshot`, `argus_get_context`, and `argus_design_audit` directly from a conversation — no CLI, no terminal required. Published to npm as **[argusqa-os](https://www.npmjs.com/package/argusqa-os)** — add via `{ "command": "npx", "args": ["-y", "argusqa-os"] }` in `.mcp.json` |
+| **Figma Design Fidelity** | `argus_design_audit(url, figmaFrameUrl)` compares every extracted Figma property — 13 mismatch finding types: CSS token values, component presence, per-node fill/text color (RGB distance), typography (fontSize/fontWeight/lineHeight/fontFamily/letterSpacing), Auto Layout padding and gap, border-radius (per-corner), bounding-box overflow, **absolute position drift** (scroll-corrected x/y vs Figma bounds, 20px), border stroke (color+weight), box-shadow (offset+blur+**spread**+**color**), opacity, and text content. Selector fallback: tries `[data-testid]`, `[aria-label]`, `#id`, `.class` per node. Requires `FIGMA_API_TOKEN` env var. |
 
 Works with **React + SCSS**, CSS Modules, CSS-in-JS (styled-components / emotion), and plain HTML/CSS apps.
 
@@ -576,6 +578,7 @@ Ask Claude directly — no terminal needed.
 | `argus_last_report` | Return the last saved JSON report without re-running a scan |
 | `argus_watch_snapshot` | Snapshot the currently open Chrome tab without navigating — raw console + network capture |
 | `argus_get_context` | Capture everything broken on the open tab, formatted as a diagnostic context for Claude to diagnose and suggest fixes |
+| `argus_design_audit` | Figma design-to-implementation fidelity audit — 13 finding types across color, typography, spacing, per-corner radius, position drift, stroke, shadow (color+spread), opacity, gap, and text content |
 
 **`argus_audit`** — fast audit of any URL:
 
@@ -632,7 +635,7 @@ Then follow with: *"Here's the context — what's causing these errors and how d
 | `npm run server` | Start the Slack slash command + interaction server (port 3001) |
 | `npm run init` | Interactive setup wizard — generates `.env` + `targets.js` |
 | `npm run test:unit` | Run 61 unit tests (no Chrome required) |
-| `npm run test:harness` | Run 93-block correctness harness (requires Chrome) |
+| `npm run test:harness` | Run 128-block correctness harness (requires Chrome) |
 
 **`npm run crawl`** — full audit of all configured routes:
 
@@ -867,16 +870,16 @@ argus/
 │       └── argus.yml                 # CI pipeline
 ├── .vscode/
 │   └── mcp.json                      # Chrome DevTools MCP config for VS Code
-├── .mcp.json                         # Argus MCP server registration — exposes argus_audit/argus_audit_full/argus_compare/argus_last_report/argus_watch_snapshot/argus_get_context to Claude
+├── .mcp.json                         # Argus MCP server registration — exposes all 7 tools to Claude: argus_audit/argus_audit_full/argus_compare/argus_last_report/argus_watch_snapshot/argus_get_context/argus_design_audit
 ├── src/
 │   ├── argus.js                      # Single-page audit entry point
 │   ├── batch-runner.js               # Multi-page batch audit
-│   ├── mcp-server.js                 # Argus MCP server — argus_audit / argus_audit_full / argus_compare / argus_last_report / argus_watch_snapshot / argus_get_context
+│   ├── mcp-server.js                 # Argus MCP server — argus_audit / argus_audit_full / argus_compare / argus_last_report / argus_watch_snapshot / argus_get_context / argus_design_audit
 │   ├── adapters/
 │   │   └── browser.js                # CdpBrowserAdapter — facade over all chrome-devtools-mcp calls
 │   ├── domain/
 │   │   └── finding.js                # createFinding() factory — canonical finding shape
-│   ├── registry.js                   # Analyzer plugin registry — registerExpensive/getCheap/getExpensive
+│   ├── registry.js                   # Analyzer plugin registry — registerCheap/registerExpensive/getCheap/getExpensive/clearAll
 │   ├── config/
 │   │   ├── targets.js                # Routes to test, thresholds, config
 │   │   └── schema.js                 # Zod validation schema; validateConfig() called inside runCrawl()
@@ -944,12 +947,12 @@ argus/
 │   └── README.md                     # Setup guide, Supabase SQL schema, env vars, deployment
 ├── scripts/
 │   └── dispatch-report.js            # Standalone Slack re-dispatch script (re-posts last report.json to Slack)
-├── test-harness/                     # Fixture server + test runner (93 blocks, 394 hard assertions, 54 fixture pages)
+├── test-harness/                     # Fixture server + test runner (128 blocks, 565 hard assertions, 55 fixture pages)
 │   ├── README.md
 │   ├── server.js                     # Express fixture server (ports 3100 dev / 3101 staging)
 │   ├── harness-config.js             # Route definitions + expected findings
-│   ├── validate.js                   # Test runner — 84 numbered blocks ([80] MCP server, [81] createFinding, [82] withRetry, [83] watch dashboard, [84] cli/init.js)
-│   ├── pages/                        # 54 fixture pages (one per detection category)
+│   ├── validate.js                   # Test runner — 128 numbered blocks ([80]–[84] MCP/createFinding/withRetry/watch/init, [85]–[93] Sprint 0.5 Tier 3, [94]–[126] gap-close, [127] A7 theme, [128] D9 design fidelity)
+│   ├── pages/                        # 55 fixture HTML pages (one per detection category)
 │   ├── nextjs-fixture/               # Next.js app structure for C3 discovery tests (10 files)
 │   ├── source-fixture/               # Minimal app.js for C1 codebase-analyzer tests (env var audit)
 │   └── static/
@@ -989,7 +992,7 @@ argus/
 
 ## Known MCP Tool Limitations
 
-The Chrome DevTools MCP behavioral constraints below cause **3 permanent test failures** in the harness (`391/394` pass). These are MCP-layer restrictions — they cannot be fixed in Argus code. `validate.js` now exits with code 0 when only these 3 failures remain, making the CI harness gate reliable.
+The Chrome DevTools MCP behavioral constraints below cause **3 permanent test failures** in the harness (`562/565` pass). These are MCP-layer restrictions — they cannot be fixed in Argus code. `validate.js` now exits with code 0 when only these 3 failures remain, making the CI harness gate reliable.
 
 > **`type_text` clarification**: `type_text` does fire DOM `input` events when the element is properly focused first with `mcp.click({ uid })`. Always use uid-based focus — passing `{ selector }` to `mcp.click` silently does nothing.
 
@@ -1000,6 +1003,8 @@ The Chrome DevTools MCP behavioral constraints below cause **3 permanent test fa
 
 These constraints are documented with workarounds in [SKILL.md §10](SKILL.md).
 
+The harness passes **562/565** assertions (exits 0). The 3 failures are the permanent MCP-limited ones listed above.
+
 ---
 
 ## Environment Variables Reference

package/glama.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://glama.ai/mcp/schemas/server.json",
   "name": "argus",
-  "description": "AI-powered QA harness that audits web apps via Chrome DevTools Protocol. Catches JS errors, network failures, a11y violations, SEO issues, security headers, CSS regressions, and more — directly from Claude conversations. 6 MCP tools: argus_audit (fast 8-analyzer pass), argus_audit_full (Lighthouse + memory + responsive), argus_compare (dev vs staging diff), argus_last_report (retrieve last JSON report), argus_watch_snapshot (live tab snapshot without navigating), argus_get_context (LLM-optimized context + fix loop with snapshot_id diff). 84 test blocks, 367 hard assertions, 54 detection categories.",
+  "description": "AI-powered QA harness that audits web apps via Chrome DevTools Protocol. Catches JS errors, network failures, a11y violations, SEO issues, security headers, CSS regressions, and more — directly from Claude conversations. 7 MCP tools: argus_audit (fast 8-analyzer pass), argus_audit_full (Lighthouse + memory + responsive), argus_compare (dev vs staging diff), argus_last_report (retrieve last JSON report), argus_watch_snapshot (live tab snapshot without navigating), argus_get_context (LLM-optimized context + fix loop with snapshot_id diff), argus_design_audit (Figma design fidelity — 13 finding types). 128 test blocks, 565 hard assertions, 56 detection categories.",
   "maintainers": ["ironclawdevs27"],
   "tools": [
     {
@@ -27,6 +27,10 @@
     {
       "name": "argus_get_context",
       "description": "LLM-optimized diagnostic context for the open Chrome tab. Returns snapshot_id for fix-loop diffing: pass it back on the next call to get resolved/new_issues/persisting arrays. Accepts optional tabId for multi-tab workflows."
+    },
+    {
+      "name": "argus_design_audit",
+      "description": "Full Figma design-to-implementation fidelity audit. Fetches design spec from a Figma frame URL (requires FIGMA_API_TOKEN) and compares every extracted property against live DOM computed styles. Detects 13 mismatch finding types: CSS token values, component presence, fill/text color (RGB distance), typography (fontSize/fontWeight/lineHeight/fontFamily/letterSpacing), Auto Layout padding and gap, border-radius (per-corner), bounding-box overflow, absolute position drift (scroll-corrected x/y vs Figma bounds), border stroke (color+weight), box-shadow (offset+blur+spread+color), opacity, and text content. Selector fallback: tries [data-testid], [aria-label], #id, .class per node."
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argusqa-os",
-  "version": "9.5.0",
+  "version": "9.5.3",
   "mcpName": "io.github.ironclawdevs27/argus",
   "description": "Argus — AI-powered automated dev-testing platform using Chrome DevTools MCP and Claude Code",
   "keywords": [

package/src/adapters/browser.js

@@ -25,7 +25,7 @@ export class CdpBrowserAdapter {
 
   // ── Evaluation & snapshots ──────────────────────────────────────────────────
   evaluate(fn)             { return this._mcp.evaluate_script({ function: fn }); }
-  snapshot()               { return this._mcp.take_snapshot(); }
+  snapshot(opts = {})      { return this._mcp.take_snapshot(opts); }
   screenshot(opts = {})    { return this._mcp.take_screenshot(opts); }
   heapSnapshot(opts = {})  { return this._mcp.take_heapsnapshot(opts); }
 
@@ -45,9 +45,10 @@ export class CdpBrowserAdapter {
   waitFor(opts)            { return this._mcp.wait_for(opts); }
 
   // ── Viewport ────────────────────────────────────────────────────────────────
-  emulate(viewport)        { return this._mcp.emulate({ viewport }); }
-  emulateCpu(rate)         { return this._mcp.emulate({ cpuThrottlingRate: rate }); }
-  resize(w, h)             { return this._mcp.resize_page({ width: w, height: h }); }
+  emulate(viewport)              { return this._mcp.emulate({ viewport }); }
+  emulateCpu(rate)               { return this._mcp.emulate({ cpuThrottlingRate: rate }); }
+  emulateColorScheme(scheme)     { return this._mcp.emulate({ colorScheme: scheme }); }
+  resize(w, h)                   { return this._mcp.resize_page({ width: w, height: h }); }
 
   // ── Network & performance ───────────────────────────────────────────────────
   getNetworkRequest(reqId) { return this._mcp.get_network_request({ requestId: reqId }); }

package/src/adapters/figma.js

@@ -0,0 +1,336 @@
+/**
+ * Figma REST adapter — extracts the full design spec from a Figma frame.
+ *
+ * For each node in the frame tree, extracts:
+ *   bounds      — x, y, width, height relative to the frame origin
+ *   fill        — primary solid fill color (r,g,b,a — 0-255)
+ *   stroke      — border color + weight
+ *   typography  — fontSize, fontWeight, lineHeightPx, letterSpacing (TEXT nodes)
+ *   spacing     — Auto Layout padding + gap
+ *   cornerRadius
+ *   shadow      — primary DROP_SHADOW effect
+ *   opacity
+ *
+ * Returns null gracefully when FIGMA_API_TOKEN is absent, the URL is invalid,
+ * or the API call fails — callers skip analysis without crashing.
+ *
+ * Supported Figma URL formats:
+ *   https://www.figma.com/file/<fileKey>/Name?node-id=42%3A0
+ *   https://www.figma.com/design/<fileKey>/Name?node-id=42-0
+ *
+ * Requires env: FIGMA_API_TOKEN (Personal Access Token from figma.com/settings)
+ */
+
+import { childLogger } from '../utils/logger.js';
+
+const logger = childLogger('figma-adapter');
+
+const FIGMA_API = 'https://api.figma.com/v1';
+
+// Node types that carry no useful layout/style data — skip during tree walk
+const SKIP_TYPES = new Set(['VECTOR', 'STAR', 'LINE', 'BOOLEAN_OPERATION', 'REGULAR_POLYGON']);
+
+// ── URL parsing ───────────────────────────────────────────────────────────────
+
+/**
+ * Parse fileKey and nodeId from a Figma frame URL.
+ * Returns null if the URL is not a recognisable Figma frame URL.
+ */
+export function parseFigmaUrl(url) {
+  if (!url || typeof url !== 'string') return null;
+  const fileMatch = url.match(/figma\.com\/(?:file|design)\/([A-Za-z0-9]+)/);
+  const nodeMatch = url.match(/node-id=([^&]+)/);
+  if (!fileMatch) return null;
+  const fileKey = fileMatch[1];
+  const rawNode = nodeMatch?.[1];
+  if (!rawNode) return null;
+  // node-id can be URL-encoded "42%3A0" or dash-separated "42-0" — normalise to "42:0"
+  const nodeId = decodeURIComponent(rawNode).replace('-', ':');
+  return { fileKey, nodeId };
+}
+
+// ── Selector inference ────────────────────────────────────────────────────────
+
+/**
+ * Infer a prioritised list of CSS selector candidates from a Figma layer name.
+ * The analyzer tries each in order and uses the first that matches a DOM element.
+ *
+ * Priority:
+ *   1. Explicit selector — if the name starts with #, ., or [ use it verbatim
+ *   2. data-testid attribute (slug form)
+ *   3. aria-label attribute (raw name)
+ *   4. ID selector (slug form)
+ *   5. Class selector (BEM slug: spaces→-, /→--)
+ *
+ * Examples:
+ *   "Button / Primary" → [data-testid="button--primary"], [aria-label="Button / Primary"], #button--primary, .button--primary
+ *   "#hero"            → ["#hero"]   (explicit — used verbatim)
+ *   ".card"            → [".card"]  (explicit)
+ */
+function inferSelectors(node) {
+  const name = node.name;
+
+  // Designer typed an explicit selector — honour it and skip inference
+  if (name.startsWith('#') || name.startsWith('.') || name.startsWith('[')) {
+    return [name];
+  }
+
+  const slug = name
+    .toLowerCase()
+    .replace(/\s*\/\s*/g, '--')
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  if (!slug) return [];
+
+  return [
+    `[data-testid="${slug}"]`,
+    `[aria-label="${name}"]`,
+    `#${slug}`,
+    `.${slug}`,
+  ];
+}
+
+// ── Node extraction ───────────────────────────────────────────────────────────
+
+/**
+ * Extract all design properties from a single Figma node into a flat object.
+ * All color channels are 0-255. Bounds are relative to the frame origin.
+ */
+function extractNode(node, frameX, frameY) {
+  if (!node) return null;
+
+  const selectors = inferSelectors(node);
+  const result = {
+    id:        node.id,
+    name:      node.name,
+    type:      node.type,
+    selectors: selectors,       // ordered candidates — analyzer tries each until one matches
+    selector:  selectors[0] ?? `.${node.name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`,
+    opacity:   node.opacity ?? 1,
+
+    // Populated below
+    bounds:       null,
+    fill:         null,
+    stroke:       null,
+    typography:   null,
+    spacing:      null,
+    cornerRadius: null,
+    shadow:       null,
+  };
+
+  // Bounds — relative to frame origin so they map to viewport coords when the
+  // browser viewport matches the frame dimensions.
+  if (node.absoluteBoundingBox) {
+    result.bounds = {
+      x:      node.absoluteBoundingBox.x - frameX,
+      y:      node.absoluteBoundingBox.y - frameY,
+      width:  node.absoluteBoundingBox.width,
+      height: node.absoluteBoundingBox.height,
+    };
+  }
+
+  // Primary solid fill (first visible solid fill)
+  for (const fill of (node.fills ?? [])) {
+    if (fill.type === 'SOLID' && fill.color && fill.visible !== false) {
+      result.fill = {
+        r: Math.round(fill.color.r * 255),
+        g: Math.round(fill.color.g * 255),
+        b: Math.round(fill.color.b * 255),
+        a: Math.round((fill.opacity ?? 1) * 255),
+      };
+      break;
+    }
+  }
+
+  // Primary stroke
+  for (const stroke of (node.strokes ?? [])) {
+    if (stroke.type === 'SOLID' && stroke.color && stroke.visible !== false) {
+      result.stroke = {
+        r:      Math.round(stroke.color.r * 255),
+        g:      Math.round(stroke.color.g * 255),
+        b:      Math.round(stroke.color.b * 255),
+        a:      Math.round((stroke.opacity ?? 1) * 255),
+        weight: node.strokeWeight ?? 1,
+      };
+      break;
+    }
+  }
+
+  // Typography (TEXT nodes only)
+  if (node.type === 'TEXT' && node.style) {
+    const s = node.style;
+    result.typography = {
+      fontFamily:    s.fontFamily    ?? null,
+      fontSize:      s.fontSize      ?? null,
+      fontWeight:    s.fontWeight    ?? null,
+      lineHeightPx:  s.lineHeightPx  ?? null,
+      letterSpacing: s.letterSpacing ?? 0,
+    };
+  }
+
+  // Text content — actual Figma copy; compared against DOM textContent
+  if (node.type === 'TEXT' && typeof node.characters === 'string') {
+    result.characters = node.characters.trim() || null;
+  }
+
+  // Auto Layout spacing — maps to CSS padding + gap.
+  // layoutMode ('HORIZONTAL'|'VERTICAL') lets the analyzer pick columnGap vs rowGap.
+  if (node.layoutMode && node.layoutMode !== 'NONE') {
+    result.spacing = {
+      paddingTop:    node.paddingTop    ?? 0,
+      paddingRight:  node.paddingRight  ?? 0,
+      paddingBottom: node.paddingBottom ?? 0,
+      paddingLeft:   node.paddingLeft   ?? 0,
+      gap:           node.itemSpacing   ?? 0,
+      layoutMode:    node.layoutMode,
+    };
+  }
+
+  // Corner radius — uniform number or per-corner object.
+  // Figma rectangleCornerRadii = [topLeft, topRight, bottomRight, bottomLeft].
+  if (node.cornerRadius != null) {
+    result.cornerRadius = node.cornerRadius;  // uniform
+  } else if (node.rectangleCornerRadii) {
+    const [tl, tr, br, bl] = node.rectangleCornerRadii;
+    // Collapse to a single number if all corners are equal (avoids noise in findings)
+    result.cornerRadius = (tl === tr && tr === br && br === bl)
+      ? tl
+      : { topLeft: tl, topRight: tr, bottomRight: br, bottomLeft: bl };
+  }
+
+  // Primary DROP_SHADOW effect
+  for (const eff of (node.effects ?? [])) {
+    if (eff.type === 'DROP_SHADOW' && eff.visible !== false) {
+      result.shadow = {
+        offsetX: eff.offset?.x ?? 0,
+        offsetY: eff.offset?.y ?? 0,
+        blur:    eff.radius    ?? 0,
+        spread:  eff.spread    ?? 0,
+        r:       Math.round((eff.color?.r ?? 0) * 255),
+        g:       Math.round((eff.color?.g ?? 0) * 255),
+        b:       Math.round((eff.color?.b ?? 0) * 255),
+        a:       Math.round((eff.color?.a ?? 0.25) * 255),
+      };
+      break;
+    }
+  }
+
+  return result;
+}
+
+// ── Tree walker ───────────────────────────────────────────────────────────────
+
+function parseFigmaNodes(data, nodeId) {
+  const nodeKey  = nodeId.replace(':', '-');
+  const nodeData = data?.nodes?.[nodeKey] ?? data?.nodes?.[nodeId];
+  if (!nodeData?.document) return null;
+
+  const doc    = nodeData.document;
+  const frameX = doc.absoluteBoundingBox?.x ?? 0;
+  const frameY = doc.absoluteBoundingBox?.y ?? 0;
+
+  const nodes      = [];
+  const tokens     = {}; // legacy CSS-var format
+  const components = []; // legacy component presence format
+
+  function walk(node) {
+    if (!node || SKIP_TYPES.has(node.type)) return;
+
+    const extracted = extractNode(node, frameX, frameY);
+    if (extracted) {
+      nodes.push(extracted);
+
+      // Build legacy tokens map for backward compat
+      if (extracted.fill) {
+        const hex = '#' +
+          extracted.fill.r.toString(16).padStart(2, '0') +
+          extracted.fill.g.toString(16).padStart(2, '0') +
+          extracted.fill.b.toString(16).padStart(2, '0');
+        tokens[`--figma-${extracted.selector.slice(1)}-fill`] = hex;
+      }
+
+      // Legacy component presence list
+      if (node.type === 'COMPONENT' || node.type === 'INSTANCE') {
+        components.push({ name: node.name, selector: extracted.selector });
+      }
+    }
+
+    for (const child of (node.children ?? [])) walk(child);
+  }
+
+  walk(doc);
+
+  return {
+    nodes,
+    frame: {
+      name:   doc.name ?? '',
+      x:      frameX,
+      y:      frameY,
+      width:  doc.absoluteBoundingBox?.width  ?? 0,
+      height: doc.absoluteBoundingBox?.height ?? 0,
+    },
+    // Legacy fields — still consumed by backward-compat token comparison path
+    tokens,
+    components,
+  };
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Fetch the full design spec for a Figma frame URL.
+ *
+ * Returns null when FIGMA_API_TOKEN is unset, the URL is unparseable,
+ * or the Figma API returns an error. All errors are logged at warn level.
+ *
+ * @param {string} figmaFrameUrl
+ * @returns {Promise<{nodes, frame, tokens, components}|null>}
+ */
+export async function getFigmaFrame(figmaFrameUrl) {
+  const token = process.env.FIGMA_API_TOKEN;
+  if (!token) {
+    logger.debug('[ARGUS] figma-adapter: FIGMA_API_TOKEN not set — skipping design fidelity fetch');
+    return null;
+  }
+
+  const parsed = parseFigmaUrl(figmaFrameUrl);
+  if (!parsed) {
+    logger.warn(`[ARGUS] figma-adapter: cannot parse Figma URL: ${figmaFrameUrl}`);
+    return null;
+  }
+
+  const { fileKey, nodeId } = parsed;
+  const encodedId = nodeId.replace(':', '-');
+  const apiUrl    = `${FIGMA_API}/files/${fileKey}/nodes?ids=${encodedId}&geometry=paths`;
+
+  try {
+    const res = await fetch(apiUrl, {
+      headers: { 'X-Figma-Token': token },
+      signal:  AbortSignal.timeout(15000),
+    });
+
+    if (!res.ok) {
+      logger.warn(`[ARGUS] figma-adapter: Figma API ${res.status} for ${figmaFrameUrl}`);
+      return null;
+    }
+
+    const data   = await res.json();
+    const result = parseFigmaNodes(data, nodeId);
+
+    if (!result) {
+      logger.warn(`[ARGUS] figma-adapter: no node data for nodeId "${nodeId}" in ${figmaFrameUrl}`);
+      return null;
+    }
+
+    logger.info(
+      `[ARGUS] figma-adapter: extracted ${result.nodes.length} node(s) from "${result.frame.name}" ` +
+      `(${result.frame.width}×${result.frame.height})`
+    );
+    return result;
+
+  } catch (err) {
+    logger.warn(`[ARGUS] figma-adapter: fetch failed for ${figmaFrameUrl}: ${err.message}`);
+    return null;
+  }
+}

package/src/domain/finding.js

@@ -14,7 +14,22 @@ const VALID_SEVERITIES = new Set(['critical', 'warning', 'info']);
 /**
  * Create an immutable finding object.
  *
- * @param {{ type: string, severity: string, message: string, url?: string }} opts
+ * Required fields: type, severity ('critical'|'warning'|'info'), message.
+ * Common optional fields passed via ...rest (use these names for consistency):
+ *   url         — affected URL (defaults to '')
+ *   selector    — CSS selector of the offending element
+ *   requestUrl  — URL of the offending network request
+ *   status      — HTTP status code (number)
+ *   method      — HTTP method string
+ *   element     — human-readable element description (e.g. 'button#submit')
+ *   property    — CSS property name
+ *   metric      — performance metric name (e.g. 'LCP')
+ *   value       — measured value
+ *   budget      — expected threshold value
+ *   count       — numeric count of occurrences
+ *   source      — source file or stylesheet path
+ *
+ * @param {{ type: string, severity: string, message: string, url?: string, [key: string]: any }} opts
  * @returns {Readonly<object>}
  */
 export function createFinding({ type, severity, message, url = '', ...rest }) {

package/src/mcp-server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Argus MCP Server (v9.4.6)
+ * Argus MCP Server (v9.5.3)
  *
  * Exposes Argus as an MCP server so Claude (or any MCP client) can call
  * argus_audit, argus_audit_full, argus_compare, argus_last_report, and
@@ -30,6 +30,8 @@ import { crawlRouteCheap, runCrawl }          from './orchestration/crawl-and-re
 import { runComparison }                      from './orchestration/env-comparison.js';
 import { WatchSession }                       from './orchestration/watch-mode.js';
 import { CdpBrowserAdapter }                  from './adapters/browser.js';
+import { getFigmaFrame }                      from './adapters/figma.js';
+import { analyzeDesignFidelity }             from './utils/design-fidelity-analyzer.js';
 
 const REPORTS_DIR = path.resolve(process.cwd(), 'reports');
 
@@ -117,6 +119,18 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'argus_design_audit',
+    description: 'Full design-to-implementation fidelity audit against a Figma frame. 13 mismatch finding types: CSS token values, component presence, fill/text color (RGB delta), typography (fontSize/fontWeight/lineHeight/fontFamily/letterSpacing), Auto Layout padding and gap, border-radius (per-corner), bounding-box overflow, absolute position drift (scroll-corrected x/y, 20px threshold), border stroke (color+weight), box-shadow (offset+blur+spread+color), opacity, and text content. Selector fallback: tries [data-testid], [aria-label], #id, .class per node. Requires FIGMA_API_TOKEN env var and Chrome on --remote-debugging-port=9222. Returns { findings, summary } where summary includes 13 mismatch-type counts.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url:           { type: 'string', description: 'Full URL of the page to audit (e.g. http://localhost:3000/dashboard). Must be reachable by the running Chrome instance.' },
+        figmaFrameUrl: { type: 'string', description: 'Figma frame URL to fetch design tokens from (e.g. https://www.figma.com/file/ABC123/Name?node-id=42%3A0). Must include the node-id query parameter pointing to the specific frame.' },
+      },
+      required: ['url', 'figmaFrameUrl'],
+    },
+  },
 ];
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
@@ -129,7 +143,7 @@ async function withMcp(fn) {
     logger.error('[ARGUS] MCP tool handler error:', err.message);
     throw err;
   } finally {
-    try { mcp.close(); } catch { /* ignore — process already gone */ }
+    try { mcp.close(); } catch (e) { logger.debug({ err: e }, 'mcp close (ignored)'); }
   }
 }
 
@@ -268,6 +282,42 @@ async function handleGetContext({ url, snapshot_id: prevId, tabId } = {}) {
   });
 }
 
+async function handleDesignAudit({ url, figmaFrameUrl }) {
+  if (!url)           throw new Error('argus_design_audit: url is required');
+  if (!figmaFrameUrl) throw new Error('argus_design_audit: figmaFrameUrl is required');
+
+  const figmaData = await getFigmaFrame(figmaFrameUrl);
+  if (!figmaData) {
+    return { content: [{ type: 'text', text: JSON.stringify({
+      error: 'Could not fetch Figma data. Ensure FIGMA_API_TOKEN is set and the figmaFrameUrl is valid.',
+      findings: [],
+      summary: { tokenMismatches: 0, missingComponents: 0, colorMismatches: 0, typographyMismatches: 0, spacingMismatches: 0, radiusMismatches: 0, boundsOverflows: 0, positionDrifts: 0, strokeMismatches: 0, shadowMismatches: 0, opacityMismatches: 0, gapMismatches: 0, textMismatches: 0 },
+    }) }] };
+  }
+
+  return withMcp(async (mcp) => {
+    const browser  = new CdpBrowserAdapter(mcp);
+    const findings = await analyzeDesignFidelity(browser, url, figmaData);
+    const count    = (type) => findings.filter(f => f.type === type).length;
+    const summary  = {
+      tokenMismatches:      count('design_token_mismatch'),
+      missingComponents:    count('design_component_missing'),
+      colorMismatches:      count('design_color_mismatch'),
+      typographyMismatches: count('design_typography_mismatch'),
+      spacingMismatches:    count('design_spacing_mismatch'),
+      radiusMismatches:     count('design_radius_mismatch'),
+      boundsOverflows:      count('design_bounds_overflow'),
+      positionDrifts:       count('design_position_drift'),
+      strokeMismatches:     count('design_stroke_mismatch'),
+      shadowMismatches:     count('design_shadow_mismatch'),
+      opacityMismatches:    count('design_opacity_mismatch'),
+      gapMismatches:        count('design_gap_mismatch'),
+      textMismatches:       count('design_text_mismatch'),
+    };
+    return { content: [{ type: 'text', text: JSON.stringify({ findings, summary }, null, 2) }] };
+  });
+}
+
 async function handleLastReport() {
   if (!fs.existsSync(REPORTS_DIR)) {
     return { content: [{ type: 'text', text: '{"error":"No reports found in reports/"}' }] };
@@ -286,7 +336,7 @@ async function handleLastReport() {
 // ── Server bootstrap ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'argus', version: '9.4.6' },
+  { name: 'argus', version: '9.5.3' },
   { capabilities: { tools: {} } },
 );
 
@@ -301,6 +351,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       case 'argus_last_report':     return await handleLastReport();
       case 'argus_watch_snapshot':  return await handleWatchSnapshot(req.params.arguments ?? {});
       case 'argus_get_context':     return await handleGetContext(req.params.arguments ?? {});
+      case 'argus_design_audit':    return await handleDesignAudit(req.params.arguments ?? {});
       default: throw new Error(`Unknown tool: ${req.params.name}`);
     }
   } catch (err) {

package/src/orchestration/dispatcher.js

@@ -1,5 +1,5 @@
 /**
- * Argus Report Dispatcher (v9.3.0)
+ * Argus Report Dispatcher
  *
  * Dispatches a completed report to Slack, GitHub, and/or HTML.
  * Extracted from crawl-and-report.js god object.