# How the Visual QA Diff Process and Side-by-Side Comparison Work in ai-website-cloner-template

> Learn how the Visual QA diff process and side-by-side comparison in ai-website-cloner-template ensure pixel-perfect website cloning by comparing specs against implementations at multiple breakpoints.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: internals
- Published: 2026-07-24

---

**The Visual QA diff process in ai-website-cloner-template implements a rigorous Phase 5 verification that captures side-by-side screenshots of the original and cloned websites at desktop (1440px) and mobile (390px) breakpoints, then iteratively diagnoses and fixes discrepancies by comparing component specs against implementations until achieving pixel-perfect fidelity.**

The ai-website-cloner-template repository automates website replication through a structured five-phase pipeline. The final **Visual QA Diff** phase ensures the generated clone matches the original site pixel-perfectly by employing systematic side-by-side comparison methodologies. This process validates both visual accuracy and interactive functionality before marking any clone as complete.

## Phase 5 Visual QA Diff Workflow

### Workflow Definition and Documentation

The complete Visual QA Diff procedure is defined in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) under **"Phase 5: Visual QA Diff"** (lines 412-426). Identical instructions appear in [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md) (lines 415-426) and [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) (lines 415-426), ensuring consistent execution across all agent implementations.

### The Six-Step Verification Protocol

After the page-assembly phase (Phase 4) completes, the system performs the following validation steps:

1. **Baseline Capture**: Launch the original URL and locally built clone side-by-side, capturing screenshots at identical viewport widths to establish a visual baseline.

2. **Desktop Verification**: Compare each section from top to bottom at the **desktop breakpoint (1440px)**, where subtle CSS mismatches are most visible.

3. **Mobile Verification**: Repeat the comparison at the **mobile breakpoint (390px)** to ensure responsive design fidelity.

4. **Discrepancy Diagnosis**: For every visual difference, inspect the component spec file in `docs/research/components/*.spec.md`. If the spec is incorrect, re-extract values using the MCP tool; if correct, fix the component implementation.

5. **Interactive Testing**: Manually scroll, click, and hover over every interactive element including tabs, buttons, accordions, and animations to detect functional regressions.

6. **Final Affirmation**: Mark the clone complete only after the checklist in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) (lines 626-630) shows no remaining discrepancies, specifically the **"Visual QA results (any remaining discrepancies)"** entry.

## Side-by-Side Comparison Mechanics

### Screenshot Automation

The clone-job agent utilizes a browser MCP (Chrome, Playwright, or similar) to capture full-page screenshots of both the source site and the clone. The system generates images at standardized breakpoints (1440px and 390px) and stores them in temporary directories such as `tmp/source` and `tmp/clone` for comparison.

### Human-in-the-Loop Review

The review process proceeds **section by section**, matching the hierarchy defined in the component spec files. This granularity allows precise identification of which specification or implementation requires correction. The agent or supervising "foreman" opens both images side-by-side in a diff viewer or image editor to perform pixel-level comparison.

### Iterative Correction Loop

When the Visual QA Diff identifies mismatches, the system initiates an iterative fix cycle:

- **Spec Errors**: Re-dispatch the extractor agent to re-run extraction for the problematic section and update the corresponding [`.spec.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.spec.md) file.
- **Implementation Errors**: Task the builder agent with fixing the component code to match the validated spec.
- **Integration**: Merge updated code into the main branch before the next QA pass.

This loop continues until all checklist items are resolved.

## Implementation Examples

The following TypeScript implementations demonstrate how to replicate the Visual QA Diff screenshot capture and comparison logic in custom scripts.

### Capturing Side-by-Side Screenshots

```typescript
// Assume `browser` is a Playwright/Chrome MCP instance
async function captureScreenshots(url: string, outDir: string) {
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: "networkidle" });

  // Desktop
  await page.setViewportSize({ width: 1440, height: 900 });
  await page.screenshot({ path: `${outDir}/desktop-original.png` });

  // Mobile
  await page.setViewportSize({ width: 390, height: 800 });
  await page.screenshot({ path: `${outDir}/mobile-original.png` });
}

// Call for both the source site and the locally built clone
await captureScreenshots(sourceUrl, "tmp/source");
await captureScreenshots(cloneUrl, "tmp/clone");

```

### Automated Pixel Diff Verification

```typescript
import pixelmatch from "pixelmatch";
import { PNG } from "pngjs";
import fs from "fs";

function diffImages(imgAPath: string, imgBPath: string, diffPath: string) {
  const imgA = PNG.sync.read(fs.readFileSync(imgAPath));
  const imgB = PNG.sync.read(fs.readFileSync(imgBPath));

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

  const mismatchedPixels = pixelmatch(
    imgA.data,
    imgB.data,
    diff.data,
    width,
    height,
    { threshold: 0.1 }
  );

  fs.writeFileSync(diffPath, PNG.sync.write(diff));
  return mismatchedPixels;
}

// Example usage
const mismatches = diffImages(
  "tmp/source/desktop-original.png",
  "tmp/clone/desktop-original.png",
  "tmp/diff/desktop.png"
);
console.log(`Desktop diff found ${mismatches} mismatched pixels`);

```

## Key Files in the Visual QA Architecture

- **[`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md)**: Contains the canonical Phase 5 description and side-by-side checklist (lines 412-426 and 626-630).
- **[`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md)**: Mirrors the workflow for Opencode agent compatibility (lines 415-426).
- **[`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md)**: Provides QA instructions for GitHub-based skill execution (lines 415-426).
- **`docs/research/components/*.spec.md`**: Stores extracted design tokens, CSS values, and interaction models validated during QA.
- **`tmp/*`**: Runtime directory holding temporary screenshots for both source and clone at desktop and mobile viewports.

## Summary

- The Visual QA Diff process operates as **Phase 5** of the ai-website-cloner-template pipeline, following page assembly.
- Verification occurs at **1440px (desktop)** and **390px (mobile)** breakpoints using side-by-side screenshot comparison.
- Discrepancies trigger an iterative fix loop involving spec file updates or component re-implementation.
- The workflow is documented identically across [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md), [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md), and [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md).
- Interactive testing of scroll, click, and hover behaviors complements static visual diff checks.
- All verification steps must pass the checklist in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) (lines 626-630) before completion.

## Frequently Asked Questions

### What triggers the Visual QA Diff process in ai-website-cloner-template?

The Visual QA Diff activates automatically after Phase 4 (page assembly) completes successfully. The system requires both the original website URL and the locally built clone to be accessible before initiating side-by-side screenshot capture and comparison.

### How does the system handle responsive design verification?

The process validates responsive design by capturing and comparing screenshots at two standardized breakpoints: **1440px width for desktop** and **390px width for mobile**. This dual-viewport approach ensures the cloned site maintains fidelity across device sizes.

### What happens when a discrepancy is found during the Visual QA Diff?

When discrepancies are detected, the system diagnoses whether the error originates in the component spec file or the implementation. If the spec is incorrect, the extractor agent re-runs extraction; if the implementation is wrong, the builder agent repairs the component. The code is then merged and re-tested until the discrepancy resolves.

### Can the Visual QA process be fully automated?

While the official workflow emphasizes human-in-the-loop review for final affirmation, the architecture supports automation through browser MCP tools like Playwright. Teams can implement automated pixel-diff libraries such as `pixelmatch` (as shown in the implementation examples) to pre-validate screenshots before manual review.