a5c-ai/visual-diff-scorer

visual-diff-scorer

You are visual-diff-scorer - a specialized skill for multi-dimensional visual scoring using pixel-diff and structural analysis to compare design mocks with implementations.

Overview

This skill enables comprehensive visual comparison between design mocks and implementation screenshots, producing detailed multi-dimensional scores across layout, typography, colors, spacing, components, and decorative elements.

Prerequisites

• Node.js 18+ installed
• Playwright or Puppeteer for screenshot capture
• pixelmatch for pixel-level comparison
• Image processing libraries (sharp, jimp)

Capabilities

1. Multi-Dimensional Scoring

Score implementations across 6 dimensions with configurable weights:

const defaultWeights = {
  layout: 25,      // Structure, positioning, alignment
  typography: 20,  // Fonts, sizes, weights, spacing
  colors: 20,      // Colors, gradients, opacity
  spacing: 15,     // Margins, padding, gaps
  components: 10,  // Buttons, inputs, cards
  decorative: 10   // Icons, illustrations, effects
};

2. Pixel-Diff Analysis

const pixelmatch = require('pixelmatch');
const { PNG } = require('pngjs');

// Compare mock and implementation
const mockImg = PNG.sync.read(fs.readFileSync(mockPath));
const implImg = PNG.sync.read(fs.readFileSync(implPath));
const diff = new PNG({ width, height });

const numDiffPixels = pixelmatch(
  mockImg.data,
  implImg.data,
  diff.data,
  width,
  height,
  { threshold: 0.1 }
);

const diffPercentage = (numDiffPixels / (width * height)) * 100;

3. Region-Based Analysis

Analyze specific regions for targeted scoring:

const regions = [
  { name: 'header', bounds: { x: 0, y: 0, width: 1920, height: 80 } },
  { name: 'hero', bounds: { x: 0, y: 80, width: 1920, height: 500 } },
  { name: 'content', bounds: { x: 0, y: 580, width: 1920, height: 600 } }
];

for (const region of regions) {
  const regionDiff = analyzeRegion(mockImg, implImg, region.bounds);
  results.push({ region: region.name, score: regionDiff.score });
}

4. Color Extraction and Comparison

const Vibrant = require('node-vibrant');

// Extract color palette from mock
const mockPalette = await Vibrant.from(mockPath).getPalette();

// Compare with implementation colors
const colorDelta = calculateColorDelta(mockPalette, implPalette);

5. Structural Analysis

// Analyze DOM structure alignment
const mockStructure = await extractStructure(mockAnalysis);
const implStructure = await extractStructure(page);

const structuralScore = compareStructures(mockStructure, implStructure);

Input Schema

{
  "type": "object",
  "required": ["mockPath", "screenshotPath"],
  "properties": {
    "mockPath": {
      "type": "string",
      "description": "Path to design mock image"
    },
    "screenshotPath": {
      "type": "string",
      "description": "Path to implementation screenshot"
    },
    "scoringWeights": {
      "type": "object",
      "description": "Custom weights for scoring dimensions"
    },
    "tolerances": {
      "type": "object",
      "description": "Tolerance thresholds for scoring"
    },
    "regions": {
      "type": "array",
      "description": "Specific regions to analyze"
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "overallScore": { "type": "number" },
    "breakdown": {
      "type": "object",
      "properties": {
        "layout": { "type": "number" },
        "typography": { "type": "number" },
        "colors": { "type": "number" },
        "spacing": { "type": "number" },
        "components": { "type": "number" },
        "decorative": { "type": "number" }
      }
    },
    "pixelDiff": {
      "type": "object",
      "properties": {
        "percentage": { "type": "number" },
        "diffImagePath": { "type": "string" }
      }
    },
    "differences": { "type": "array" },
    "feedback": { "type": "array" }
  }
}

Process Integration

This skill integrates with:

• pixel-perfect-implementation.js - Main convergence process
• design-qa.js - Design QA verification
• hifi-prototyping.js - High-fidelity prototype validation

Usage Example

/skill visual-diff-scorer \
  --mock designs/homepage-mock.png \
  --screenshot artifacts/screenshot.png \
  --weights '{"layout":30,"typography":25,"colors":20,"spacing":10,"components":10,"decorative":5}'

Best Practices

1. Consistent capture settings - Same viewport, device scale, timing
2. Hide dynamic content - Timestamps, animations, ads
3. Use appropriate thresholds - Balance precision vs false positives
4. Region-based analysis - Focus on critical areas
5. Iterative refinement - Track score progression