What Is the Visual QA Diff Phase? Final Quality Gate in AI Website Cloning

The Visual QA Diff phase is the final quality gate in the AI Website Cloner pipeline that compares rendered clones against original sites via side-by-side screenshots to detect visual discrepancies, validate component specifications, and ensure responsive fidelity before release.

The Visual QA Diff phase serves as the ultimate checkpoint in the JCodesMore/ai-website-cloner-template repository's cloning workflow. After component builders generate code and assemble the page, this phase executes a pixel-perfect comparison between the cloned output and the original website. Understanding this phase is critical for maintaining high-fidelity reproductions of target sites across desktop and mobile viewports.

Core Objectives of the Visual QA Diff Phase

The phase addresses five specific quality criteria defined in the pipeline documentation located at .windsurf/workflows/clone-website.md.

1. Detect Visual Gaps

Spot mismatches in layout, typography, colors, images, or interactive behavior that escaped earlier extraction steps or were introduced during the build process.

2. Validate Component Specifications

When discrepancies appear, the system consults the spec files in docs/research/components/*.spec.md. A wrong spec triggers re-extraction; a correct spec indicates a builder error requiring fixes.

3. Confirm Responsive Fidelity

Comparisons run at desktop (1440 px) and mobile (390 px) breakpoints to guarantee cross-device consistency.

4. Ensure Functional Parity

Beyond static pixels, the phase verifies interactive elements—clicks, tabs, scroll-driven animations, hover states, and smooth-scroll libraries—behave identically to the source.

5. Gate the Final Release

The cloning process only completes after this phase passes. Results including discrepancy lists, spec counts, and build status appear in the pipeline's "Completion" summary.

Workflow Implementation and File Structure

According to the repository's workflow documentation, the Visual QA Diff phase represents Phase 5 of the cloning pipeline. The README.md file's Assembly & QA section provides the high-level overview, while .windsurf/workflows/clone-website.md delivers step-by-step instructions for performing comparisons and handling discrepancies.

The phase specifically examines the output rendered in src/app/page.tsx, comparing it against the original site's screenshots captured at identical viewport widths.

Automating Visual Diff Checks

While the repository defines the process, implementation requires automation tools. Below are practical TypeScript examples using Playwright and pixelmatch to execute the Visual QA Diff methodology.

Capture Screenshots at Target Viewports

Use Playwright to generate comparable screenshots of both the original and cloned sites:

import { chromium } from 'playwright';
import fs from 'fs';
import path from 'path';

async function capture(url: string, outFile: string) {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'networkidle' });
  // Match desktop breakpoint defined in the workflow
  await page.setViewportSize({ width: 1440, height: 900 });
  await page.screenshot({ path: outFile });
  await browser.close();
}

// Original site
await capture('https://example.com', 'orig-desktop.png');
// Local clone
await capture('http://localhost:3000', 'clone-desktop.png');

Execute Pixel-Level Comparison

Run a diff analysis using pixelmatch to quantify visual deviations:

import { readFileSync, writeFileSync } from 'fs';
import { PNG } from 'pngjs';
import pixelmatch from 'pixelmatch';

const img1 = PNG.sync.read(readFileSync('orig-desktop.png'));
const img2 = PNG.sync.read(readFileSync('clone-desktop.png'));

const { width, height } = img1;
const diff = new PNG({ width, height });

const diffPixels = pixelmatch(
  img1.data,
  img2.data,
  diff.data,
  width,
  height,
  { threshold: 0.1 }
);

writeFileSync('diff-desktop.png', PNG.sync.write(diff));
console.log(`Differing pixels: ${diffPixels}`);

A non-zero diffPixels count signals a visual discrepancy requiring investigation per the Phase 5: Visual QA Diff workflow guidelines.

Multi-Breakpoint Automation

Execute the complete Visual QA Diff phase across both required breakpoints:

const breakpoints = [
  { name: 'desktop', width: 1440 },
  { name: 'mobile',  width: 390 },
];

for (const bp of breakpoints) {
  await capture('https://example.com', `orig-${bp.name}.png`);
  await capture('http://localhost:3000', `clone-${bp.name}.png`);
  // Run pixelmatch comparison for each pair
}

This automation mirrors the responsive fidelity checks mandated in the workflow documentation.

Summary

• The Visual QA Diff phase is the final quality gate in the AI Website Cloner pipeline, executing after all builders complete their work.
• It performs side-by-side screenshot comparisons at 1440 px and 390 px viewports to validate visual and functional parity.
• Discrepancies trigger validation against docs/research/components/*.spec.md files to determine whether re-extraction or builder fixes are needed.
• The phase is documented in .windsurf/workflows/clone-website.md under Phase 5 and summarized in README.md.
• Only passing this gate allows the cloning process to reach the "Completion" summary status.

Frequently Asked Questions

What triggers a failure in the Visual QA Diff phase?

Any visual mismatch detected between the original site and the rendered clone triggers a failure. This includes layout shifts, color inaccuracies, font discrepancies, missing images, or broken interactive behaviors. When detected, the system checks the component spec files to determine if the extraction was incorrect or if the builder failed to implement the spec correctly.

Which viewport sizes does the Visual QA Diff phase check?

The phase validates clones at two standard breakpoints: desktop (1440 px) and mobile (390 px). These widths ensure the clone maintains responsive fidelity across device categories, catching breakpoint-specific layout issues that might not appear at other sizes.

Where is the Visual QA Diff phase documented in the repository?

The detailed implementation instructions reside in .windsurf/workflows/clone-website.md under the Phase 5: Visual QA Diff section. High-level pipeline context appears in the Assembly & QA section of README.md. The rendered output checked during this phase originates from src/app/page.tsx.

Can the Visual QA Diff phase detect functional issues like broken clicks?

Yes. Beyond static visual comparison, the phase verifies functional parity including interactive elements such as clicks, tabs, hover states, scroll-driven animations, and smooth-scroll libraries. The clone must behave identically to the source site, not just look similar.

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