Figma vs. Flutter Visual Verifier 🎨📱

Automate visual QA for Flutter applications. Validate live Figma design frames against running iOS/Android simulator screenshots and Flutter Golden test assets directly inside Visual Studio Code using perceptual pixel diffing and structural analysis.

🚀 Step-by-Step Usage Guide (How to Use)

Follow these 4 simple steps to run visual verification on any Flutter screen or component:

┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 1: Configure Figma Access Token (One-Time Setup)                       │
│ 1. In Figma, go to Account Settings > Personal access tokens & copy token. │
│ 2. In VS Code, press Cmd+Shift+P (or Ctrl+Shift+P on Windows).             │
│ 3. Run: Figma Visual Verifier: Set Figma Access Token & paste your token.  │
├─────────────────────────────────────────────────────────────────────────────┤
│ STEP 2: Copy Target Figma URL                                               │
│ 1. Open your Figma design file.                                             │
│ 2. Right-click the screen frame or component -> Copy link to selection.     │
│    (e.g., https://www.figma.com/design/FILE_KEY/AppName?node-id=102-304)   │
├─────────────────────────────────────────────────────────────────────────────┤
│ STEP 3: Run Visual Verification                                             │
│ 1. Launch your Flutter app on iOS Simulator / Android Emulator.             │
│ 2. In VS Code, press Cmd+Shift+P (or Ctrl+Shift+P).                         │
│ 3. Run: Figma Visual Verifier: Compare Figma URL with Screenshot/Simulator  │
│ 4. Paste your Figma URL & hit Enter.                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│ STEP 4: Inspect Visual Differences in Diff Studio                          │
│ Interactive VS Code Studio opens automatically:                             │
│ ↔️ Split Slider: Drag separator left/right to compare side-by-side.         │
│ 🎚️ Opacity Blend: Adjust 0-100% slider to overlay Figma over Simulator.    │
│ 🟥 Diff Heatmap: View magenta highlighted non-matching pixel zones.         │
│ 📊 Status Badge: View instant PASS/FAIL verdict with exact mismatch %.     │
└─────────────────────────────────────────────────────────────────────────────┘

🌟 Key Features

• 🔗 Live Figma URL Fetching: Paste any Figma frame or component node URL. The extension queries Figma's REST API to render high-resolution @3x vector PNGs automatically.
• 📱 Automated Simulator Capture: Detects booted iOS Simulators (xcrun simctl) or Android Emulators (adb) and captures screenshots instantly.
• 🖼️ Flutter Golden Test Integration: Compare Figma designs against baseline Flutter Golden test PNGs (test/goldens/*.png).
• 🔬 Visual Diff Studio:
  • ↔️ Split View Slider: Drag separator horizontally to compare Figma design vs. Flutter screen side-by-side.
  • 🎚️ Opacity Blend Slider: Layer Figma design over simulator screenshot with 0% to 100% opacity.
  • 🟥 Diff Heatmap: High-contrast magenta highlighting of non-matching pixel zones.
• 📊 Real-time Pixel Metrics: Instantly calculates mismatch percentage (%), pixel difference count, and visual PASS/FAIL verdicts.

🔒 Security & Client Figma PAT Safety

If you are using a Figma Personal Access Token (PAT) provided by a client, rest assured that your token and design data are completely protected:

1. Native OS Encrypted Storage (SecretStorage):
   • The token is saved using VS Code's vscode.ExtensionContext.secrets API, which leverages your Operating System's native keychain:
     • macOS: Apple Keychain Services (security)
     • Windows: Windows Credential Manager (DPAPI)
     • Linux: GNOME Keyring / Secret Service (libsecret)
2. Zero Third-Party Cloud Servers:
   • Your token is NEVER transmitted to any middleman server, analytics service, or third-party cloud.
3. Direct Encrypted HTTPS Requests Only:
   • Requests travel strictly over end-to-end encrypted HTTPS (https://api.figma.com) directly from your machine to official Figma servers.
4. Client Best Practice:
   • Ask your client to generate a Read-Only / File Read Scope token. A read-only PAT cannot edit or alter any client Figma files.

📐 How Partial Screenshots Are Measured

If your simulator capture or image does not cover the full screen (e.g. a single modal, bottom sheet, or widget component):

1. Automatic Canvas Normalization:
   • The engine automatically calculates max(width) and max(height) across both images and centers/pads them on a transparent canvas so aspect ratios and pixel metrics never crash or warp.
2. Target Specific Figma Component Nodes:
   • Instead of linking a full Figma page, copy the URL of the exact component node in Figma (e.g., ?node-id=102-304). Figma API will render only that component at its exact pixel dimensions.
3. Interactive Opacity & Split Alignment:
   • In the Visual Diff Studio, use the Opacity Overlay Mode to align and overlay partial captures over Figma design frames effortlessly.

🎯 Strategies for Maximum Accuracy (Without Extra Packages)

If you prefer not to add extra third-party Flutter packages (like alchemist or golden_toolkit) to your pubspec.yaml, use these strategies to achieve 95%+ visual QA accuracy:

1. Component Node Isolation (Highest Accuracy):
   • Link specific component nodes (?node-id=...) rather than full page frames. Isolated cards/buttons eliminate noise from dynamic screen data (timestamps, status bars, dynamic avatars).
2. Standardize Display DPI Scale:
   • Match your Figma export scale to your device's Retina multiplier:
     • iPhone @3x displays (e.g. iPhone 15 Pro) -> Set figmaFlutterVerifier.defaultScale: 3
     • Android @2x / @3x displays -> Match scale in VS Code settings.
3. Perceptual Threshold Calibration:
   • Keep figmaFlutterVerifier.diffThreshold set between 0.10 and 0.15. This ignores micro sub-pixel font anti-aliasing differences while strictly flagging padding, alignment, font weight, and color discrepancies.

⚙️ Configuration Settings

Customize settings in VS Code Settings (Cmd + ,) under Figma Flutter Verifier:

🛠️ Extension Commands

📄 License

Distributed under the MIT License. See LICENSE for more information.