Agent skill

visual-diff-scorer

Multi-dimensional visual scoring using pixel-diff and structural analysis for design-to-implementation comparison

View SKILL.md on GitHub Repository
Stars 514
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/ux-ui-design/skills/visual-diff-scorer

Metadata

Additional technical details for this skill

author
babysitter-sdk
version
1.0.0
category
visual-testing

SKILL.md

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:

javascript
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

javascript
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:

javascript
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

javascript
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

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

const structuralScore = compareStructures(mockStructure, implStructure);

Input Schema

json
{
  "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

json
{
  "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

bash
/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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

a5c-ai/babysitter

gsd-tools

Central utility skill for GSD operations. Provides config parsing, slug generation, timestamps, path operations, and orchestrates calls to other specialized skills. Acts as the unified entry point that the original gsd-tools.cjs provided via its lib/ modules (commands, config, core, init).

514 31
Explore
a5c-ai/babysitter

model-profile-resolution

Resolve model profile (quality/balanced/budget) at orchestration start and map agents to specific models. Enables cost/quality tradeoffs by selecting appropriate AI models for each agent role.

514 31
Explore
a5c-ai/babysitter

verification-suite

Plan structure validation, phase completeness checks, reference integrity verification, and artifact existence confirmation. Provides the structured verification layer ensuring GSD artifacts are well-formed and complete.

514 31
Explore
a5c-ai/babysitter

state-management

STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.

514 31
Explore
a5c-ai/babysitter

git-integration

Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.

514 31
Explore
a5c-ai/babysitter

frontmatter-parsing

YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.

514 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results