visual-diff-scorer

name	visual-diff-scorer
description	Multi-dimensional visual scoring using pixel-diff and structural analysis for design-to-implementation comparison
allowed-tools	Bash(*) Read Write Edit Glob Grep WebFetch
metadata	{"author":"babysitter-sdk","version":"1.0.0","category":"visual-testing"}
graph	{"domains":["domain:web-development"],"specializations":["specialization:ux-ui-design"],"skillAreas":["skill-area:visual-regression-testing","skill-area:ui-testing"],"roles":["role:qa-engineer","role:product-designer"],"workflows":["workflow:user-feedback-loop","workflow:product-discovery"]}

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" 
       
    
     
       
       
    
  

Output Schema

{
  "type": "object",
  "properties": {
    "overallScore": { "type": "number" },
    "breakdown": {
      "type": "object",
      "properties": {
        "layout": { "type": "number" },
        "typography": { "type": "number" },
        "colors": { "type": "number" },
        "spacing": { "type": "number" },
            
            
      
    
     
       
       
            
            
      
    
        
        
  

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