How the Visual QA Diff Process Validates Cloned Website Sections Against Originals

The visual QA diff process performs pixel-level screenshot comparisons at desktop and mobile breakpoints while cross-referencing computed CSS values from component specs to ensure cloned sections match both the static appearance and interactive behavior of the original website.

The AI Website Cloner template by JCodesMore automates the replication of production websites into React/Next.js codebases. After developers construct components and merge worktrees according to the workflow defined in .windsurf/workflows/clone-website.md, the visual QA diff process serves as the final verification gate, systematically comparing assembled clones against live targets using side-by-side screenshots and spec-driven validation.

Side-by-Side Screenshot Comparison at Critical Breakpoints

The verification begins with side-by-side screenshots captured at the desktop breakpoint of 1440 px and the mobile breakpoint of 390 px. As documented in .windsurf/workflows/clone-website.md (lines 12–18), the process opens the original page and the assembled clone simultaneously—or captures sequential screenshots of each viewport width—to enable direct visual comparison section by section.

This pixel-level comparison ensures that layout, spacing, typography, and color values render identically across the two most common device categories before proceeding to behavioral validation.

Spec-Driven Validation Against Extracted Computed Styles

When visual discrepancies appear, the system consults the component specification file located at docs/research/components/<name>.spec.md. These specification files contain the exact getComputedStyle() values extracted from the live original site during the initial research phase (lines 20–23).

Rather than relying solely on human visual inspection, the diff process validates the clone's CSS properties against these recorded specifications. This approach eliminates ambiguity by providing objective, measurable criteria for styling decisions such as exact color hex codes, font sizes, padding values, and positioning coordinates.

Two-Way Diff Resolution Strategy

The visual QA employs a two-way diff methodology to isolate the source of any mismatch:

• If the specification is wrong – The extraction process is rerun via the browser MCP (Model Context Protocol), the specification file is updated with corrected values, and the component is rebuilt to match the new specification.
• If the specification is correct – The component's implementation is corrected to align with the existing specification, ensuring the code matches the validated design intent.

This bifurcated approach prevents compounding errors by verifying whether discrepancies stem from incorrect data capture or implementation deviations.

Interactive Behavior Verification

Beyond static visual comparison, the process exercises every interaction model defined in the specifications. According to .windsurf/workflows/clone-website.md (lines 23–26), this includes scroll-driven effects, click-driven state changes, hover transitions, and timed animations.

The verification protocol requires developers to scroll through the entire page, click every button and tab, hover over interactive elements, and confirm that transitions, animations, and scroll effects behave exactly as recorded in the docs/research/components/<name>.spec.md file. This ensures the cloned website replicates not just the look but the dynamic feel of the original.

The Iterative Correction Loop

Discrepancies identified during screenshot comparison or interaction testing trigger an iterative correction loop. As specified in .windsurf/workflows/clone-website.md (lines 31–33), the workflow returns to the extraction phase, updates the relevant specification, and rebuilds the component until side-by-side screenshots achieve pixel-perfect parity and all interactive behaviors match the original.

Only when the assembled sections in src/app/page.tsx demonstrate exact visual alignment—using global design tokens from src/app/globals.css and src/app/layout.tsx—is the clone considered complete.

Code Examples

Extracting Computed Style Diffs for Scroll-Triggered Elements

The following JavaScript demonstrates how to capture and compare computed styles before and after scroll interactions, creating a diff that gets recorded in the component specification:

// 1️⃣ Capture state A (top of page)
const stateA = getComputedStyle(document.querySelector('.header'));

// 2️⃣ Trigger the scroll change (e.g., scroll to 120 px)
window.scrollTo(0, 120);
await new Promise(r => setTimeout(r, 300)); // wait for transition

// 3️⃣ Capture state B (after scroll)
const stateB = getComputedStyle(document.querySelector('.header'));

// 4️⃣ Diff the two states
const diff = {};
for (const prop of stateA) {
  if (stateA[prop] !== stateB[prop]) {
    diff[prop] = { before: stateA[prop], after: stateB[prop] };
  }
}
console.log('Scroll-diff:', diff);

This diff is written into the component spec under "States & Behaviors" according to the workflow defined in the repository.

Automated Visual Diff with Playwright

While the repository does not ship with a test runner, the following Playwright example illustrates how to automate the visual QA comparison:

import { test, expect } from '@playwright/test';

test('visual QA – compare original vs clone', async ({ page }) => {
  // Load original
  await page.goto('https://original.example.com');
  await page.screenshot({ path: 'original.png', fullPage: true });

  // Load clone
  await page.goto('http://localhost:3000');
  await page.screenshot({ path: 'clone.png', fullPage: true });

  // Compare screenshots (pixel diff)
  const diff = await page.evaluate(() => {
    // Use a simple pixel-by-pixel diff library like pixelmatch
    // This placeholder demonstrates intent; real implementation would import pixelmatch.
    return 'diff-result';
  });
  expect(diff).toBe('no-diff');
});

Running such tests after the build (npm run build) provides an automated safety net for the visual QA step.

Summary

• The visual QA diff process operates at 1440 px desktop and 390 px mobile breakpoints, capturing side-by-side screenshots for direct comparison.
• Validation relies on getComputedStyle() values stored in docs/research/components/<name>.spec.md files, providing objective criteria for styling accuracy.
• Two-way diff resolution distinguishes between specification errors and implementation flaws, preventing error propagation.
• Interactive verification tests scroll-driven, click-driven, hover, and timed behaviors to ensure functional parity with the original site.
• Iterative loops continue until pixel-perfect visual match and behavioral alignment are achieved, as documented in .windsurf/workflows/clone-website.md.

Frequently Asked Questions

What specific breakpoints does the visual QA diff process use for comparison?

The process evaluates the cloned website at 1440 px for desktop viewports and 390 px for mobile viewports. These breakpoints represent the standard devices used during the side-by-side screenshot comparison phase defined in .windsurf/workflows/clone-website.md.

How does the visual QA process handle styling discrepancies between the clone and original?

The process implements a two-way diff strategy. If the specification file contains incorrect values, the browser MCP reruns the extraction to update docs/research/components/<name>.spec.md. If the specification is accurate, the component implementation is corrected to match the recorded getComputedStyle() values.

Which interaction types are tested during the visual QA verification phase?

The verification exercises scroll-driven effects, click-driven state changes, hover transitions, and timed animations. Developers must scroll through the entire page, activate every button and tab, hover interactive elements, and verify that all transitions and animations behave exactly as specified in the component spec files.

Where are the computed style specifications stored for comparison?

The exact computed CSS values are stored in component specification files located at docs/research/components/<component>.spec.md. These files are generated during the initial inspection phase and serve as the authoritative reference during the visual QA diff process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}