Implementing Pixel-Perfect Design Token Extraction for Cloned Sites

Pixel-perfect design token extraction captures live CSS values from any website using browser automation, then injects them into a Next.js 16 codebase via Tailwind v4 oklch variables and component specs for deterministic, AI-driven reconstruction.

The JCodesMore/ai-website-cloner-template repository provides a complete workflow for converting live websites into clean Next.js applications. At the heart of this process lies a rigorous pixel-perfect design token extraction system that bridges the gap between visual inspection and executable code. This system ensures that every color, font, and spacing value from the source site is preserved as a typed token in the generated codebase.

The Two-Phase Extraction Workflow

The extraction process operates across distinct Reconnaissance and Foundation phases defined in the /clone-website workflow.

Phase 1: Reconnaissance and Global Extraction

During the initial reconnaissance phase, a browser-automation tool such as Chrome MCP or Playwright MCP loads the target URL and executes a JavaScript snippet that calls getComputedStyle() on every DOM element. This captures the computed values for colors, fonts, spacing, border-radius, shadows, and breakpoints—regardless of the original CSS framework or media-query overrides.

The extracted data is written to docs/research/DESIGN_TOKENS.md, creating a human-readable reference that serves as the single source of truth for all subsequent build steps. The inspection logic that drives this process is defined in docs/research/INSPECTION_GUIDE.md, which provides the checklist for what properties to capture and how to filter out default browser values.

Phase 2: Foundation Build and Global Integration

Once tokens are extracted, the foundation phase hard-codes these values into src/app/globals.css as CSS custom properties. The template leverages Tailwind v4’s support for the oklch color model, enabling a direct one-to-one mapping of the source palette (e.g., oklch(0.205 0 0)) without manual conversion or perceptual drift.

Font families detected during extraction are added to src/app/layout.tsx using next/font/google or next/font/local, ensuring that typography renders identically to the original site.

Component-Level Token Application

Every component specification file—stored at docs/research/components/<Component>.spec.md—embeds the exact token values it requires. This prevents builder agents from inferring or guessing colors and spacing during the code generation phase. Because each spec references the global tokens directly, the design system remains consistent across the entire component tree.

The Browser-MCP Extraction Script

The extraction logic itself is stored as a browser-side snippet within the workflow definition. The AI agent runs this script via the MCP connection, which walks the DOM, collects curated CSS properties, filters out defaults, and returns a JSON payload.

// Run this in the browser MCP console on the target page
(() => {
  const props = [
    'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
    'backgroundColor','borderRadius','boxShadow','padding','margin'
  ];
  const walk = (el, depth = 0) => {
    if (depth > 4) return null;
    const cs = getComputedStyle(el);
    const styles = {};
    props.forEach(p => {
      const v = cs[p];
      if (v && v !== 'none' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v;
    });
    return {
      tag: el.tagName.toLowerCase(),
      classes: el.className,
      text: el.childNodes.length === 1 && el.childNodes[0].nodeType === 3
            ? el.textContent.trim().slice(0,200) : null,
      styles,
      children: Array.from(el.children).map(c => walk(c, depth + 1)).filter(Boolean)
    };
  };
  return JSON.stringify(walk(document.body), null, 2);
})();

Source: This extraction script is defined in lines 38–80 of .windsurf/workflows/clone-website.md and is synchronized to other agent configurations via scripts/sync-skills.mjs.

Mapping Extracted Tokens to Code

After extraction, the JSON payload is parsed into CSS custom properties. Here is an example of how the extracted color tokens populate src/app/globals.css:

:root {
  /* Example colour tokens extracted from the target site */
  --background: oklch(0.98 0 0);
  --foreground: oklch(0.15 0 0);
  --primary:    oklch(0.22 0.12 260);
  --secondary:  oklch(0.92 0.04 45);
  --muted:     oklch(0.94 0 0);
  --accent:    oklch(0.86 0.1 120);
}

/* Dark mode overrides */
.dark {
  --background: oklch(0.13 0 0);
  --foreground: oklch(0.98 0 0);
  /* …other dark‑mode tokens… */
}

For detected Google Fonts, the template updates src/app/layout.tsx to inject the font family at the root level:

// src/app/layout.tsx
import { Geist_Sans } from 'next/font/google';

const geist = Geist_Sans({
  subsets: ['latin'],
  weight: ['400','500','700'],
});

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={geist.className}>
      <body>{children}</body>
    </html>
  );
}

Verification and Deterministic Builds

Because the global CSS is generated before any component code is written, the build process becomes fully deterministic. After the foundation is in place, running npm run build produces a compiled output that can be compared against the original screenshots using visual diffing tools. This verification step confirms that the pixel-perfect design token extraction successfully replicated the source site's color palette, typography scale, and spacing system.

The AGENTS.md file serves as the ultimate source of truth for these instructions, ensuring that any updates to the token extraction logic propagate correctly across all agent-specific workflow files.

Summary

• Browser-MCP reliability guarantees that computed values reflect actual rendered output, independent of CSS frameworks or media queries.
• Tailwind v4 oklch support enables perceptually uniform color mapping from extracted values to CSS variables.
• Single source of truth in docs/research/DESIGN_TOKENS.md and component specs prevents drift between design and code.
• Deterministic builds allow repeatable compilation and visual QA against the original site.

Frequently Asked Questions

What is pixel-perfect design token extraction?

Pixel-perfect design token extraction is the automated process of crawling a live website, computing the actual rendered CSS values for every visual property, and codifying those values as typed design tokens in a structured format. In the JCodesMore/ai-website-cloner-template, this involves using browser automation to run getComputedStyle() on DOM elements and exporting the results to Markdown spec files that drive code generation.

Why does the template use the oklch color model instead of hex or RGB?

The template uses oklch because Tailwind v4 supports this perceptually-uniform color space natively. OkLCH allows for a direct one-to-one mapping of the source site's computed color values without manual conversion, ensuring that the cloned site maintains the same visual luminance and chromaticity as the original.

How does the extraction handle responsive breakpoints?

During the reconnaissance phase, the browser automation tool evaluates the target site across multiple viewport sizes. The getComputedStyle() calls capture breakpoint-specific values, which are stored alongside the base tokens in docs/research/DESIGN_TOKENS.md. These values are then translated into CSS custom properties or Tailwind configuration definitions that respect the original responsive behavior.

Can this workflow extract tokens from sites using any CSS framework?

Yes. Because the extraction relies on the browser's own rendering engine rather than parsing source files, it works with any frontend stack—whether the target uses Tailwind, Bootstrap, Styled Components, or vanilla CSS. The browser MCP executes the extraction script in the context of the fully rendered DOM, ensuring that the computed styles reflect the actual user experience regardless of the underlying implementation.

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