InterfaceGuard - VS Code Extension

Automated UX/UI analysis extension for VS Code using Playwright MCP and AI-powered recommendations.

Features

Screenshot Capture: Capture screenshots of your web application at multiple viewport sizes
Automated Analysis: Submit screenshots for AI-powered InterfaceGuard analysis
Job Tracking: Track analysis job progress with real-time status updates
Interactive Results: View analysis results in a beautiful, interactive panel
Actionable Recommendations: Get specific, actionable recommendations with code snippets
Multiple Analysis Types: Analyze for accessibility, usability, and consistency issues
Responsive Testing: Test across desktop, tablet, and mobile viewports

Requirements

Prerequisites

Playwright MCP Server (required for screenshot capture)
- The extension requires a locally running Playwright MCP server
- Installation instructions below
InterfaceGuard Analysis Service (required for analysis)
- You need access to the InterfaceGuard Analysis Service API
- Configure the API URL and key in extension settings

Installation

Installing the Extension

Install directly from the VS Code Marketplace, or search InterfaceGuard in the Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
Alternatively, download a .vsix file, open the "..." menu in the Extensions view, and select "Install from VSIX..."

Setting up Playwright MCP Server

The extension requires a Playwright MCP (Model Context Protocol) server to capture screenshots. Follow these steps to set it up:

Option 1: Quick Setup

# Install Playwright
npm init playwright@latest

# Install browsers
npx playwright install

# Install system dependencies (Linux only)
npx playwright install-deps

# Start the MCP server
npx playwright run-server --port 3000

Option 2: Project Setup

Create a separate project for the Playwright MCP server:

mkdir playwright-mcp-server
cd playwright-mcp-server
npm init -y
npm install playwright
npx playwright install

Create a server.js file:

const { chromium, firefox, webkit } = require('playwright');
const express = require('express');
const app = express();
const port = 3000;

app.use(express.json());

let browser;
let context;
let page;

// Health check endpoint
app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

// Screenshot endpoint
app.post('/screenshot', async (req, res) => {
  try {
    const { url, viewport, browser: browserType = 'chromium', fullPage = true } = req.body;

    if (!browser) {
      const browsers = { chromium, firefox, webkit };
      browser = await browsers[browserType].launch();
      context = await browser.newContext({ viewport });
      page = await context.newPage();
    }

    await page.goto(url);
    await page.setViewportSize(viewport);

    const screenshot = await page.screenshot({ fullPage });

    res.set('Content-Type', 'image/png');
    res.send(screenshot);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Cleanup on shutdown
process.on('SIGINT', async () => {
  if (browser) await browser.close();
  process.exit();
});

app.listen(port, () => {
  console.log(`Playwright MCP server running on http://localhost:${port}`);
});

Start the server:

npm install express
node server.js

Configuring the Extension

Open VS Code settings (Ctrl+, / Cmd+,)
Search for "InterfaceGuard"
Configure the following settings:
- API URL: URL of the InterfaceGuard Analysis Service — defaults to the production GCP endpoint. Override with http://localhost:8080 for local development.
- MCP Endpoint: Playwright MCP server endpoint (default: http://localhost:3000)
- Default Browser: Browser to use for screenshots (chromium, firefox, or webkit)
- Default Viewports: Array of viewport sizes for responsive testing

Alternatively, use the built-in configuration commands:

Run InterfaceGuard: Configure Playwright MCP to configure MCP settings
Run InterfaceGuard: Configure API to configure API settings

Usage

Quick Start

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Run "InterfaceGuard: Capture Screenshots"
- Enter the URL of your application
- Select viewports to capture (desktop, tablet, mobile)
- Wait for screenshots to be captured
Run "InterfaceGuard: Analyze Application"
- Select analysis types (accessibility, usability, consistency)
- Wait for analysis to complete
View Results
- Results will appear automatically when analysis completes
- Or run "InterfaceGuard: Show Results" to view previous results

Available Commands

InterfaceGuard: Capture Screenshots - Capture screenshots of your application
InterfaceGuard: Analyze Application - Analyze captured screenshots
InterfaceGuard: Show Results - View analysis results
InterfaceGuard: Configure Playwright MCP - Configure Playwright MCP settings
InterfaceGuard: Configure API - Configure API settings

Using the Status Bar

Click on the "🔭 InterfaceGuard" status bar item to open the quick menu with all available actions.

Workflow

1. Capture Screenshots

Command Palette > InterfaceGuard: Capture Screenshots
↓
Enter URL: https://your-app.com
↓
Select Viewports: Desktop, Tablet, Mobile
↓
Screenshots Captured

2. Analyze Application

Command Palette > InterfaceGuard: Analyze Application
↓
Select Analysis Types: Accessibility, Usability, Consistency
↓
Job Submitted
↓
Track Status (automatic)
↓
Results Available

3. View Results

Command Palette > InterfaceGuard: Show Results
↓
Select Job (if multiple)
↓
Interactive Results Panel Opens

Features in Detail

Screenshot Capture

Multiple Viewports: Capture screenshots at different viewport sizes
Responsive Testing: Test desktop, tablet, and mobile layouts
Custom Viewports: Define custom viewport sizes
Browser Selection: Choose between Chromium, Firefox, and WebKit
Full Page Capture: Capture entire page including scrollable areas

Analysis

Accessibility Analysis: Identify accessibility issues (WCAG compliance)
Usability Analysis: Find usability problems and user experience issues
Consistency Analysis: Detect design inconsistencies across pages
Severity Levels: Issues categorized as Critical, Major, Minor, or Suggestion
AI-Powered: Uses advanced AI models for intelligent analysis

Results

Interactive UI: Beautiful, interactive results panel
Filtering: Filter issues by severity, category, or type
Recommendations: Get specific, actionable recommendations
Code Snippets: Copy-paste ready code fixes
Implementation Steps: Step-by-step guide to fix issues
Visual Indicators: See exactly where issues are located

Configuration

Extension Settings

This extension contributes the following settings:

ux-analyzer.apiUrl: URL of the InterfaceGuard Analysis Service
ux-analyzer.apiKey: API key for authentication (stored securely)
ux-analyzer.mcpEndpoint: Playwright MCP endpoint
ux-analyzer.defaultBrowser: Default browser for screenshots
ux-analyzer.defaultViewports: Array of viewport sizes for responsive testing

Example Configuration

{
  "ux-analyzer.apiUrl": "https://ux-analysis-service-197463040616.us-east4.run.app",
  "ux-analyzer.mcpEndpoint": "http://localhost:3000",
  "ux-analyzer.defaultBrowser": "chromium",
  "ux-analyzer.defaultViewports": [
    { "width": 1920, "height": 1080, "deviceType": "desktop" },
    { "width": 768, "height": 1024, "deviceType": "tablet" },
    { "width": 375, "height": 667, "deviceType": "mobile" }
  ]
}

Troubleshooting

Cannot connect to Playwright MCP

Make sure the Playwright MCP server is running
Check that the MCP endpoint URL is correct in settings
Try running: npx playwright run-server --port 3000

API key validation failed

Check that your API key is correct
Make sure the InterfaceGuard Analysis Service is running
Verify the API URL in settings

Screenshot capture failed

Check browser console for errors
Make sure the URL is accessible
Try a different browser (chromium, firefox, webkit)
Check Playwright MCP server logs

No results showing

Wait for analysis to complete (check status bar)
Try running "InterfaceGuard: Show Results" manually
Check the Output panel (View > Output > InterfaceGuard) for errors

Development

This repository is private. The steps below are for Cre8tiv Systems team members with repo access.

Building from Source

# Clone the repository
git clone https://github.com/cre8tiv/ux.ai.git
cd ux.ai/ux-analyzer-vscode

# Install dependencies
npm install

# Type-check + compile for local debugging (F5)
npm run watch

# Bundle for packaging (esbuild, minified)
npm run package

# Produce the .vsix (requires @vscode/vsce)
npm run vsix

Running in Development

Open the project in VS Code
Press F5 to start debugging
A new VS Code window will open with the extension loaded
Test the extension in the new window

API Documentation

Screenshot Submission

The extension submits screenshots in the following format:

{
  images: Buffer[],
  metadata: [{
    url: string,
    timestamp: string,
    screenName: string,
    viewportSize: { width: number, height: number },
    deviceType: 'desktop' | 'tablet' | 'mobile',
    interactionState: string,
    browserName: string
  }],
  options: {
    analysisTypes: ('accessibility' | 'consistency' | 'usability')[],
    priorityFactors: Record<string, number>
  }
}

Analysis Results

Results are returned in the following format:

{
  jobId: string,
  status: 'completed' | 'failed',
  screenshots: [{
    id: string,
    url: string,
    thumbnailUrl: string,
    metadata: any
  }],
  issues: [{
    id: string,
    type: string,
    category: 'accessibility' | 'usability' | 'consistency',
    severity: 'critical' | 'major' | 'minor' | 'suggestion',
    title: string,
    description: string,
    recommendation: {
      title: string,
      description: string,
      implementationSteps: string[],
      codeSnippet?: string
    }
  }],
  summary: {
    totalIssues: number,
    criticalCount: number,
    majorCount: number,
    minorCount: number,
    suggestionCount: number,
    categoryBreakdown: Record<string, number>
  }
}

License

MIT License

Support

This source repository is private, so GitHub Issues aren't publicly accessible. For help, please use:

Email: support@interfaceguard.com
Support policy & response times: interfaceguard.com/support
Setup guide: interfaceguard.com/integrations/vscode
Questions can also be posted on this extension's Marketplace Q&A tab

Changelog

See CHANGELOG.md.

Acknowledgments

Built with Playwright
Powered by AI-based InterfaceGuard Analysis Service
VS Code Extension API