devlens-mcp 0.3.3 → 0.4.0

package/docs/figma-workflow.md

@@ -7,16 +7,16 @@ This guide explains how to use DevLens together with Figma MCP to create a fully
 ## Overview
 
 ```
-┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
-│  Figma   │────►│   AI     │────►│  Code    │────►│  Device  │
-│  Design  │     │  Agent   │     │  Editor  │     │  Screen  │
-└──────────┘     └──────┬───┘     └──────────┘     └────┬─────┘
-                        │                                │
-                        │◄──── devlens_compare ──────────┘
-                        │      (similarity < 95%?)
+┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+│  Figma   │────►│   AI     │────►│  Code    │────►│  Device  │────►│   VQA    │
+│  Design  │     │  Agent   │     │  Editor  │     │  Screen  │     │ Validate │
+└──────────┘     └──────┬───┘     └──────────┘     └──────────┘     └────┬─────┘
+                        │                                                 │
+                        │◄──── devlens_vqa_validate ─────────────────────┘
+                        │      (issues found?)
                         │               │
                         ▼               ▼
-                   Fix Code ◄──── Diff Image
+                   Fix Code ◄──── VQA Report + Fix Suggestions
 ```
 
 ---
@@ -72,16 +72,20 @@ Use DevLens to verify the implementation matches the design.
 The AI executes this loop:
 
 ```
-1. devlens_metro_status              ← Verify Metro is healthy
-2. devlens_dismiss_overlays          ← Remove debug banners
-3. Generate/update React Native code
-4. devlens_hot_reload                ← Trigger Metro fast refresh
-5. devlens_wait_for_screen           ← Wait for screen to stabilize
-6. devlens_snapshot(validate: true)  ← Catch invisible/zero-size elements
-7. devlens_compare_with_figma        ← Compare with Figma design (one call)
-     (figmaUrl: "https://figma.com/design/...")
-8. Analyze diff image                ← Identify mismatches
-9. Fix code & repeat from step 4     ← Until similarity > 95%
+ 1. devlens_metro_status              ← Verify Metro is healthy
+ 2. devlens_dismiss_overlays          ← Remove debug banners
+ 3. devlens_ds_context                ← Load design tokens (correct color/spacing names)
+ 4. Generate/update React Native code
+ 5. devlens_hot_reload                ← Trigger Metro fast refresh
+ 6. devlens_wait_for_screen           ← Wait for screen to stabilize
+ 7. devlens_snapshot(validate: true)  ← Catch invisible/zero-size elements
+ 8. devlens_compare_with_figma        ← Quick compare (similarity score + diff)
+      (figmaUrl: "...", depth: "quick")
+ 9. If similarity < 90%: fix obvious layout issues, repeat from step 5
+10. devlens_vqa_validate              ← Full VQA check (spacing, color, alignment, sizing)
+      (figmaUrl: "...")
+11. Read VQA report → apply suggested fixes
+12. Repeat from step 5 until VQA status = PASS (zero issues)
 ```
 
 Key improvements in v0.3.0:
@@ -103,47 +107,210 @@ The AI reads the diff image to identify specific issues (wrong font size, missin
 ## Example Conversation
 
 ```
-User: Build the login screen from Figma.
-      Figma URL: https://figma.com/design/abc123/MyApp?node-id=10-200
+User: Build the login screen from this Figma and make sure VQA passes with zero issues:
+      https://figma.com/design/abc123/MyApp?node-id=10-200
 
-AI: I'll start by checking Metro health and dismissing debug overlays.
+AI: I'll start by checking Metro, dismissing overlays, and loading the design system.
     [calls devlens_metro_status → Metro healthy on port 8081]
     [calls devlens_dismiss_overlays → LogBox suppressed]
-    [calls get_design_context → reads colors, spacing, typography]
+    [calls devlens_ds_context → loaded JDS3 tokens: colors, spacing, typography]
 
-    I'll create LoginScreen.tsx now.
+    Creating LoginScreen.tsx using JDS3 design tokens...
     [writes LoginScreen.tsx]
     [calls devlens_hot_reload]
     [calls devlens_wait_for_screen(stableMs: 1500)]
     [calls devlens_snapshot(validate: true)]
+    Validation: all elements visible, no zero-size issues.
 
-    Validation report: all elements visible, no issues.
+    Running quick comparison first...
+    [calls devlens_compare_with_figma(figmaUrl: "...", depth: "quick")]
+    Similarity: 72%. Major layout issues — fixing first.
 
-    [calls devlens_compare_with_figma(
-      figmaUrl: "https://figma.com/design/abc123/MyApp?node-id=10-200")]
-
-    Similarity: 72%. The diff shows:
-    - Title text is 18px but should be 24px
-    - Primary button color is #333 but should be #2563EB
-    - Bottom padding missing on form container
-
-    Fixing these issues...
+    Fixing: title font size 18px→24px, button color #333→#2563EB, missing bottom padding.
     [updates LoginScreen.tsx]
     [calls devlens_hot_reload]
     [calls devlens_wait_for_screen(stableMs: 1000)]
-    [calls devlens_compare_with_figma(
-      figmaUrl: "https://figma.com/design/abc123/MyApp?node-id=10-200")]
+    [calls devlens_compare_with_figma(figmaUrl: "...", depth: "quick")]
+    Similarity: 93%. Good enough for full VQA now.
 
-    Similarity: 91%. Remaining: input border radius 8px → should be 12px.
+    Running full VQA validation...
+    [calls devlens_vqa_validate(figmaUrl: "...")]
 
-    [fixes border radius]
+    === VQA Report: WARNING ===
+    Issues: 3 (0 critical, 2 major, 1 minor)
+      1. [MAJOR] [sizing] Input border radius: expected 12px, actual 8px
+      2. [MAJOR] [spacing] Gap between email and password fields: expected 16px, actual 24px
+      3. [minor] [alignment] "Forgot Password" link off by 2px horizontally
+
+    Fixing all 3 issues...
+    [updates LoginScreen.tsx — borderRadius: 12, marginBottom: 16, alignSelf adjustment]
     [calls devlens_hot_reload]
     [calls devlens_wait_for_screen]
-    [calls devlens_compare_with_figma(
-      figmaUrl: "https://figma.com/design/abc123/MyApp?node-id=10-200")]
+    [calls devlens_vqa_validate(figmaUrl: "...")]
+
+    === VQA Report: PASS ===
+    Overall Score: 98.7%
+    Issues: 0
+
+    LoginScreen is ready for designer handoff. Zero VQA issues.
+```
+
+---
+
+## VQA Workflow — Zero Designer Tickets (v0.4.0)
+
+### The Problem VQA Solves
+
+Traditional workflow:
+```
+Dev builds screen  -->  Gives build to designer  -->  Designer raises 15 VQA tickets
+--> Dev fixes  -->  New build  -->  5 more tickets  -->  Fix  -->  Repeat (2-3 days wasted)
+```
+
+With DevLens VQA:
+```
+Dev tells AI "implement + pass VQA"  -->  AI builds + auto-fixes all issues
+--> Designer gets build with ZERO VQA  -->  Done (30 min)
+```
+
+---
+
+### Quick Start: Copy-Paste Prompts for Developers
+
+**Prompt 1 — Build a new screen with VQA validation:**
+```
+Build the HomeScreen component based on this Figma design:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+
+After building, run VQA validation to make sure there are ZERO issues.
+Fix any spacing, color, alignment, or sizing issues automatically.
+Keep running VQA until the report shows PASS.
+```
+
+**Prompt 2 — Run VQA on an existing screen:**
+```
+Take a snapshot of the current screen, then run VQA validation against this Figma:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+
+Show me the full VQA report. If there are any issues, fix them and re-run until PASS.
+```
 
-    Similarity: 97%. The implementation matches the Figma design.
+**Prompt 3 — Quick VQA check after a small change:**
 ```
+I just changed the padding on the header. Do a minimal VQA check — only check
+spacing and alignment against this Figma:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+```
+
+**Prompt 4 — VQA for specific components only:**
+```
+Run VQA only on the product card component (ref e5 to e12) against Figma:
+https://figma.com/design/ABC123/MyApp?node-id=22-450
+
+Check colors and sizing only, skip the rest.
+```
+
+**Prompt 5 — Full implementation + VQA + designer handoff:**
+```
+I need to implement this Figma screen and hand it to the designer with ZERO VQA issues:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+
+Steps:
+1. Load the design system context first
+2. Build the component using correct DS tokens
+3. Hot reload and wait for screen to stabilize
+4. Run full VQA validation (spacing, colors, alignment, sizing, missing elements)
+5. Fix every issue the VQA report finds
+6. Re-run VQA until the report says PASS with 0 issues
+7. Show me the final VQA report as proof
+```
+
+---
+
+### What the AI Does Behind the Scenes
+
+When you use any of the prompts above, the AI agent automatically runs this sequence:
+
+```
+1. devlens_ds_context                         ← Load design tokens
+2. (AI writes/updates component code)
+3. devlens_hot_reload                          ← Push changes to device
+4. devlens_wait_for_screen(stableMs: 1500)     ← Wait for render
+5. devlens_snapshot(validate: true)            ← Get element tree + catch invisible bugs
+6. devlens_vqa_validate(                       ← Run VQA
+     figmaUrl: "https://figma.com/design/...",
+     checkCategories: ["spacing", "color", "alignment", "sizing", "missing"]
+   )
+7. (AI reads VQA report, applies fix suggestions to code)
+8. Repeat steps 3-7 until VQA status = PASS
+```
+
+---
+
+### Understanding the VQA Report
+
+The VQA tool returns a structured report that looks like this:
+
+```
+=== VQA Report: WARNING ===
+Overall Score: 91.3%
+Issues: 3 (0 critical, 2 major, 1 minor)
+
+--- Issues ---
+  1. [MAJOR] [spacing] Vertical gap between [e3] and [e5] differs from Figma.
+     Expected: 12px gap
+     Actual:   20px gap (8px off)
+
+  2. [MAJOR] [color] Color mismatch on [e7]: Significant color mismatch
+     Expected: #1A73E8
+     Actual:   #2196F3
+
+  3. [minor] [alignment] Element [e2] is misaligned from Figma position.
+     Expected: center (215, 120)
+     Actual:   center (218, 122) — off by (3, 2)px
+
+--- Suggested Fixes ---
+  1. [high] Adjust margin/padding on element [e3] to match Figma specs: 12px gap.
+  2. [high] Update color value for [e7]. Expected: #1A73E8. Check design token mapping.
+  3. [medium] Fix alignment of [e2]. Adjust flex alignment or positioning.
+```
+
+**Report status meanings:**
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `PASS` | Zero issues. Safe to hand to designer. | Ship it. |
+| `WARNING` | Only major/minor issues, no critical. | Fix majors, minors are optional. |
+| `FAIL` | Critical issues found (missing elements, huge mismatches). | Must fix before designer sees it. |
+
+**Issue severity meanings:**
+| Severity | What it means | Example |
+|----------|---------------|---------|
+| `critical` | Designer will 100% reject this | Missing component, wrong screen, >40% color mismatch |
+| `major` | Designer will raise a VQA ticket | 8px spacing off, wrong color hex, misaligned by 10px+ |
+| `minor` | Designer might notice, might not | 2px alignment off, slight color shade difference |
+
+**VQA categories:**
+| Category | What it checks |
+|----------|---------------|
+| `spacing` | Gaps between adjacent elements vs Figma |
+| `color` | Dominant colors per region vs Figma reference |
+| `alignment` | Element center/edge positions vs Figma |
+| `sizing` | Element width/height vs Figma dimensions |
+| `missing` | Regions with <60% visual match (content probably missing) |
+| `extra` | Extra elements on device not in design |
+| `typography` | Font sizes and weights via accessibility metadata |
+
+---
+
+### When to Use VQA vs Regular Compare
+
+| Scenario | Use | Why |
+|----------|-----|-----|
+| Building a new screen from Figma | `devlens_vqa_validate` | Full VQA report with fix suggestions |
+| Quick check during iteration | `devlens_compare_with_figma(depth: "quick")` | Fast similarity %, no detailed report |
+| Small CSS tweak, just want to verify | `devlens_analyze(scope: "minimal")` | Fastest — just a pixel diff, no layout report |
+| Final check before designer handoff | `devlens_vqa_validate` | Proves zero VQA issues |
+| Comparing before/after screenshots | `devlens_compare_images` | A/B comparison, no Figma needed |
 
 ---
 

package/docs/setup-guide.md

@@ -8,8 +8,8 @@ Add this to `~/.cursor/mcp.json` and restart Cursor:
 {
   "mcpServers": {
     "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
+      "command": "/bin/zsh",
+      "args": ["-l", "-c", "npx devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081"
       }
@@ -18,9 +18,11 @@ Add this to `~/.cursor/mcp.json` and restart Cursor:
 }
 ```
 
-That's it. DevLens tools will appear in Cursor's MCP panel.
+That's it. DevLens tools will appear in Cursor's MCP panel after restart.
 
-> **Getting `env: node: No such file or directory`?** Jump to [Fix: nvm/PATH issue](#fix-nvmpath-issue-env-node-no-such-file-or-directory).
+> **v0.4.0 Auto-Detection**: DevLens now automatically detects your shell (bash/zsh/fish) and `node`/`npx` path on every startup. If it finds a misconfigured command or path in your MCP config JSON, it patches it automatically (with backup). Check startup logs for `[devlens] Patched` or `[devlens] Config OK` messages.
+>
+> **Why `/bin/zsh -l`?** Cursor doesn't load your shell profile, so `node` from nvm/fnm isn't in PATH. Using `/bin/zsh -l` loads your login profile first. DevLens v0.4.0+ handles this automatically — if you put `/bin/bash` but use zsh, it will auto-correct.
 
 ---
 
@@ -30,6 +32,7 @@ That's it. DevLens tools will appear in Cursor's MCP panel.
 ```bash
 claude mcp add devlens -- npx devlens-mcp@latest
 ```
+> Claude Code loads shell profiles automatically, so no `/bin/zsh` wrapper needed.
 
 ### Claude Desktop
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
@@ -37,8 +40,8 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 {
   "mcpServers": {
     "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
+      "command": "/bin/zsh",
+      "args": ["-l", "-c", "npx devlens-mcp@latest"],
       "env": { "METRO_PORT": "8081" }
     }
   }
@@ -52,7 +55,7 @@ cd mcp-devlens && npm install && npm run build
 npm run register   # auto-registers with Claude Code
 ```
 
-For Cursor with local build, use `"command": "node"` and `"args": ["/absolute/path/to/mcp-devlens/dist/bin/cli.js"]` instead of `npx`.
+For Cursor with local build, use `"command": "node"` and `"args": ["/absolute/path/to/mcp-devlens/dist/bin/cli.js"]` instead of the zsh wrapper.
 
 ---
 
@@ -89,8 +92,8 @@ Full example with all optional vars:
 {
   "mcpServers": {
     "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
+      "command": "/bin/zsh",
+      "args": ["-l", "-c", "npx devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081",
         "FIGMA_TOKEN": "figd_xxxxx",
@@ -113,11 +116,62 @@ Start your emulator/simulator and Metro, then ask your AI:
 | 2 | "Take a screenshot" | Device screenshot as inline image |
 | 3 | "Take a snapshot with validation" | Accessibility tree with `ref=eN` IDs |
 | 4 | "Show Metro logs" | Console output from your app |
+| 5 | "Run VQA on this screen against Figma: `<url>`" | VQA report with PASS/WARNING/FAIL |
 
 If step 1 works, DevLens is running correctly.
 
 ---
 
+## VQA Workflow — Quick Reference for Developers
+
+DevLens v0.4.0 includes a VQA (Visual Quality Assurance) validator. Use it to catch design issues **before** designers see the build — zero VQA tickets.
+
+### Copy-paste prompts you can use in Cursor:
+
+**Build a new screen + VQA:**
+```
+Build the HomeScreen component based on this Figma design:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+
+After building, run VQA validation to make sure there are ZERO issues.
+Fix any spacing, color, alignment, or sizing issues automatically.
+Keep running VQA until the report shows PASS.
+```
+
+**Run VQA on an already-built screen:**
+```
+Take a snapshot of the current screen, then run VQA validation against this Figma:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+
+Show me the full VQA report. If there are any issues, fix them and re-run until PASS.
+```
+
+**Quick check after a small CSS change:**
+```
+I just changed the padding on the header. Do a minimal VQA check — only check
+spacing and alignment against this Figma:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+```
+
+**Full implementation + zero VQA guarantee:**
+```
+I need to implement this Figma screen and hand it to the designer with ZERO VQA issues:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+
+Steps:
+1. Load the design system context first
+2. Build the component using correct DS tokens
+3. Hot reload and wait for screen to stabilize
+4. Run full VQA validation (spacing, colors, alignment, sizing, missing elements)
+5. Fix every issue the VQA report finds
+6. Re-run VQA until the report says PASS with 0 issues
+7. Show me the final VQA report as proof
+```
+
+For the full VQA workflow guide with report format details, see [Figma Workflow](./figma-workflow.md#vqa-workflow--zero-designer-tickets-v040).
+
+---
+
 ## Figma Token Setup
 
 Required only for `devlens_compare_with_figma`.
@@ -177,8 +231,8 @@ Optional. Enables `devlens_ds_context` for design-token-aware code generation.
 {
   "mcpServers": {
     "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
+      "command": "/bin/zsh",
+      "args": ["-l", "-c", "npx devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081",
         "FIGMA_TOKEN": "figd_xxxxx",
@@ -197,37 +251,46 @@ Ask your AI: *"Load the design system context"* — it should return token names
 
 ## Troubleshooting
 
-### Fix: nvm/PATH issue (`env: node: No such file or directory`)
+### Fix: Used `node` as command with shell flags (`-l`, `-c`)
+
+If your old config looked like this:
+```json
+{
+  "command": "/opt/homebrew/bin/node",
+  "args": ["-l", "-c", "npx devlens-mcp@latest"]
+}
+```
+This is incorrect — `-l` and `-c` are shell flags (zsh/bash), not node flags. Node ignores or errors on them.
 
-**This is the most common issue on macOS.** It happens because Cursor (and other GUI apps) don't load your shell profile, so `node` isn't in their PATH even though `npx` works in your terminal.
+**v0.4.0 auto-fix:** DevLens detects this misconfiguration on startup and patches `command` to your actual shell (`/bin/zsh`, `/bin/bash`, etc.) automatically. Check logs for `[devlens] Patched`.
 
-**Fix — use the full path to `npx`:**
+**Manual fix:** Replace `node` with `/bin/zsh`:
+```json
+{
+  "command": "/bin/zsh",
+  "args": ["-l", "-c", "npx devlens-mcp@latest"]
+}
+```
 
-1. Open **Terminal** and run:
-   ```bash
-   which npx
-   ```
-   This prints something like:
-   ```
-   /Users/yourname/.nvm/versions/node/v20.12.2/bin/npx
-   ```
+---
 
-2. Copy that full path and replace `"command": "npx"` in `~/.cursor/mcp.json`:
-   ```json
-   {
-     "mcpServers": {
-       "devlens": {
-         "command": "/Users/yourname/.nvm/versions/node/v20.12.2/bin/npx",
-         "args": ["devlens-mcp@latest"],
-         "env": {
-           "METRO_PORT": "8081"
-         }
-       }
-     }
-   }
-   ```
+### Fix: `env: node: No such file or directory`
+
+This means Cursor can't find `node`. It happens when Node is installed via nvm/fnm and the MCP config uses `"command": "npx"` directly.
+
+**Fix:** Use the `/bin/zsh -l` wrapper as shown in the install section above:
+```json
+{
+  "command": "/bin/zsh",
+  "args": ["-l", "-c", "npx devlens-mcp@latest"]
+}
+```
+
+The `-l` flag loads your login shell profile (where nvm/fnm initialize), making `node` available. This is the default recommended config and works for everyone on macOS. DevLens v0.4.0 auto-detects and patches this if misconfigured.
 
-3. **Restart Cursor.** This fixes it permanently.
+**Alternative:** If you prefer not to use the zsh wrapper, you can use the full absolute path to `npx`:
+1. Run `which npx` in Terminal
+2. Use that full path as `"command"` (e.g. `"/Users/you/.nvm/versions/node/v20.12.2/bin/npx"`)
 
 ---
 
@@ -280,7 +343,7 @@ Then restart Cursor. npx will re-download the latest version.
 
 ## What's Available
 
-DevLens provides **34 tools** across 8 categories:
+DevLens provides **36 tools** across 9 categories:
 
 | Category | Tools | Count |
 |----------|-------|-------|
@@ -292,5 +355,6 @@ DevLens provides **34 tools** across 8 categories:
 | React Native / Metro | metro_status, metro_logs, component_tree, hot_reload, network_requests, dismiss_overlays | 6 |
 | Navigation | open_url, go_back | 2 |
 | Design System | ds_context | 1 |
+| Analysis & VQA | analyze, vqa_validate | 2 |
 
 See the [Tool Reference](./tool-reference.md) for detailed parameter docs.

package/docs/tool-reference.md

@@ -583,6 +583,74 @@ On Android: presses system Back button. On iOS: performs back swipe.
 
 ---
 
+## Analysis & VQA Tools
+
+### devlens_analyze
+Smart analysis tool with configurable depth. Respects scope of request — if a user asks for a minimal check, it performs minimal analysis.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `scope` | `"minimal"` \| `"targeted"` \| `"full"` | No | `"full"` | `"minimal"`: quick pixel diff, no layout report. `"targeted"`: compare specific refs only. `"full"`: complete analysis. |
+| `targetRefs` | string[] | No | — | Element refs to focus on (for `"targeted"` scope). E.g., `["e1", "e5"]`. |
+| `referenceImagePath` | string | No | — | Path or URL to reference image. |
+| `referenceImageBase64` | string | No | — | Base64-encoded reference image. |
+| `figmaUrl` | string | No | — | Figma URL for reference. |
+| `threshold` | number | No | `0.1` | Color difference threshold (0-1). |
+
+**Scope behaviors:**
+- **minimal**: Captures screenshot, runs quick pixel diff with perceptual mode and system bar exclusion. Skips layout report. Fast.
+- **targeted**: Takes full snapshot but only inspects the specified refs. Returns bounds and properties for targeted elements.
+- **full**: Complete snapshot + optional layout report + comparison with reference.
+
+---
+
+### devlens_vqa_validate
+Run Visual Quality Assurance validation against a Figma design. Returns structured VQA report with issues and fix suggestions.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `figmaUrl` | string | No | — | Full Figma URL (e.g., `"https://figma.com/design/ABC123/MyApp?node-id=10-200"`). |
+| `fileKey` | string | No | — | Figma file key (use instead of figmaUrl). |
+| `nodeId` | string | No | — | Figma node ID (e.g., `"10:200"`). |
+| `scale` | number | No | `2` | Figma export scale. |
+| `checkCategories` | string[] | No | `["spacing","color","alignment","sizing","missing"]` | VQA categories to check. Options: `spacing`, `color`, `typography`, `alignment`, `missing`, `extra`, `sizing`. |
+| `enableAutoFix` | boolean | No | `true` | Generate fix suggestions for each issue. |
+| `preprocessReference` | boolean | No | `true` | Remove Figma artifacts before comparison. |
+
+**VQA Check Categories:**
+- **spacing**: Verifies margins/paddings between adjacent elements match Figma specs
+- **color**: Extracts dominant colors per region and compares with design reference
+- **alignment**: Checks element center/edge alignment against Figma positions
+- **sizing**: Verifies element dimensions match Figma within tolerance
+- **missing**: Detects regions with very low visual match (possible missing content)
+- **extra**: Detects extra elements on device not in Figma
+- **typography**: Font size/weight checks via accessibility metadata
+
+**VQA Report format:**
+```
+=== VQA Report: PASS/WARNING/FAIL ===
+Overall Score: 94.2%
+Issues: 3 (0 critical, 2 major, 1 minor)
+
+--- Issues ---
+  1. [MAJOR] [spacing] Vertical gap between [e3] and [e5] differs from Figma.
+     Expected: 12px gap
+     Actual:   20px gap (8px off)
+  2. [MAJOR] [color] Color mismatch on [e7]: Significant color mismatch...
+     Expected: #1A73E8
+     Actual:   #2196F3
+  3. [minor] [alignment] Element [e2] is misaligned from Figma position.
+     Expected: center (215, 120)
+     Actual:   center (218, 122) — off by (3, 2)px
+
+--- Suggested Fixes ---
+  1. [high] Adjust margin/padding on element [e3] to match Figma specs: 12px gap.
+  2. [high] Update color value for [e7]. Expected: #1A73E8. Check design token mapping.
+  3. [medium] Fix alignment of [e2]. Adjust flex alignment or positioning.
+```
+
+---
+
 ## Quick Reference Table
 
 | # | Tool | Category | Key Params |
@@ -620,3 +688,6 @@ On Android: presses system Back button. On iOS: performs back swipe.
 | 31 | `devlens_dismiss_overlays` | Metro | suppressLogBox?, pressBack? |
 | 32 | `devlens_open_url` | Navigation | url |
 | 33 | `devlens_go_back` | Navigation | — |
+| 34 | `devlens_ds_context` | Design System | — |
+| 35 | `devlens_analyze` | Analysis | scope, targetRefs?, referenceImagePath?, referenceImageBase64?, figmaUrl?, threshold? |
+| 36 | `devlens_vqa_validate` | VQA | figmaUrl?, fileKey?, nodeId?, scale?, checkCategories?, enableAutoFix?, preprocessReference? |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlens-mcp",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "DevLens — Playwright-style MCP server for mobile development. Take screenshots, compare with Figma designs, interact with iOS Simulators & Android Emulators, and access Metro bundler logs.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/tsconfig.json

@@ -16,5 +16,5 @@
     "sourceMap": true
   },
   "include": ["src/**/*", "bin/**/*"],
-  "exclude": ["node_modules", "dist", "tests"]
+  "exclude": ["node_modules", "dist", "tests", "src/jds-tokens"]
 }

package/INSTALLATION_GUIDE.md

@@ -1,3 +0,0 @@
-# Installation Guide
-
-This file has moved. See **[docs/setup-guide.md](./docs/setup-guide.md)** for all installation, configuration, and troubleshooting instructions.

package/QUICK_START.md

@@ -1,3 +0,0 @@
-# Quick Start
-
-This file has moved. See **[docs/setup-guide.md](./docs/setup-guide.md)** for all installation, configuration, and troubleshooting instructions.