Pixel Perfect

Skill: Pixel-Perfect Orchestration

Drive a page or component to pixel-perfect fidelity with a baseline by orchestrating visual-diff (screenshot comparison) and computed-styles (CSS property extraction) in a converging loop.

When to Use

• Replicating a production page's look in the local codebase
• Matching a Storybook component to a live reference
• Any task where the user says "make it match" or "pixel perfect"

When NOT to Use

• Building new designs from scratch (no baseline exists)
• Content-only changes with no visual target
• Figma-based design work (use the Figma MCP skill instead)

Prerequisites

1. All prerequisites from the visual-diff and computed-styles skills are met
2. The baseline URL and current URL are known
3. The dev server or Storybook is running

Design System

All fixes must use the Bitovi design token system defined in src/styles/bitovi-theme.css. Prefer token-based Tailwind classes over arbitrary values. Only use [arbitrary] syntax when no matching token exists in the theme.

Workflow Overview

┌─────────────────────────────────────┐
│  For each breakpoint:               │
│  desktop → tablet → mobile          │
│                                     │
│  1. VISUAL DIFF                     │
│     Screenshot both pages           │
│     Run pixel diff                  │
│     Identify problem regions        │
│     diffPercent < 2%? ──── YES ──── next breakpoint (or DONE if all 3 pass)
│              │                      │
│              NO                     │
│              ▼                      │
│  2. COMPUTED STYLES                 │
│     Extract CSS from both pages     │
│     Build property diff table       │
│     Fix mismatches with Tailwind    │
│     Verify fixes took effect        │
│              │                      │
│              ▼                      │
│  3. RE-DIFF                         │
│     Re-screenshot current page      │
│     Run pixel diff again            │
│     diffPercent < 2%? ──── YES ──── next breakpoint
│              │                      │
│              NO                     │
│              ▼                      │
│     Go to step 2 with new regions   │
└─────────────────────────────────────┘

Detailed Steps

Step 1: Initial Visual Diff

Load the visual-diff skill and run the full workflow:

1. Screenshot the baseline at desktop breakpoint (1280x720)
2. Screenshot the current page at the same breakpoint
3. Run node scripts/visual-diff.mjs to produce the diff image and JSON stats
4. View the diff image through the HTTP server + Playwright vision
5. Record the diffPercent and identify which regions (top, middle, bottom) have red clusters

If diffPercent < 2%, the pages are effectively matching. Report success and stop.

If diffPercent >= 2%, proceed to Step 2.

Interpreting the Diff Image

Map red clusters to specific DOM regions:

Step 2: Computed Style Extraction

Load the computed-styles skill. Based on the regions identified in Step 1:

1. Plan extraction targets: Map each red region to specific DOM elements and CSS properties
2. Extract from baseline: Use mcp_playwright_browser_evaluate on the baseline URL
3. Extract from current: Use mcp_playwright_browser_evaluate on the current URL (remember the Storybook iframe pattern if applicable)
4. Build diff table: Compare every property, flag mismatches
5. Fix mismatches: Apply Tailwind classes — always resolve computed values to design tokens from src/styles/bitovi-theme.css first (see the Design System section above). Only use [arbitrary] values when no token matches.
6. Verify each fix: Re-extract from current to confirm the computed value now matches

Prioritization

Fix differences in this order (highest visual impact first):

1. Layout: width, height, maxWidth, padding, margin, display, flexDirection
2. Typography: fontSize, fontWeight, fontFamily, lineHeight, letterSpacing
3. Colors: color, backgroundColor, borderColor
4. Decoration: borderRadius, boxShadow, opacity
5. Fine-tuning: textTransform, gap, overflow

Step 3: Re-Diff

After fixing a batch of computed style differences:

1. Re-screenshot only the current page (baseline hasn't changed)
2. Re-run the pixel diff
3. View the new diff image

Evaluate progress:

Step 4: Convergence

Continue the loop (Steps 2-3) until diffPercent < 2% or the remaining differences are confirmed to be not worth further pursuit.