How Design Tokens Are Extracted and Mapped to Tailwind CSS v4 in the AI Website Cloner Template

The template automates design token extraction by scraping computed styles from target sites via browser automation, converting color values to the Oklch model, and injecting them as CSS custom properties in src/app/globals.css for Tailwind CSS v4 to consume.

The JCodesMore/ai-website-cloner-template repository provides a deterministic pipeline that transforms any website into a pixel-perfect Next.js clone. It extracts visual design tokens—including colors, typography, spacing, and radii—and maps them to Tailwind CSS v4's native design token system without manual configuration.

The Three-Stage Token Pipeline

The workflow is fully automated and consists of three tightly-coupled stages that bridge the gap between a target site's visual language and Tailwind's utility-first architecture.

Stage 1: Reconnaissance – Design Token Audit

The pipeline begins with a browser-automation client such as Chrome MCP or Playwright MCP running a script that calls getComputedStyle() on every element in the target page. This script collects the complete color palette, typographic stack, spacing scale, border-radius values, and any global CSS custom properties.

The audit checklist defining which tokens to extract is documented in docs/research/INSPECTION_GUIDE.md (lines 18-23). This file instructs the agent to capture specific visual properties including color values, font families, font sizes, line heights, padding, margins, and shadow definitions.

Stage 2: Normalisation – Oklch Conversion

Raw RGB and hex values extracted from the target site are converted to the Oklch color model that Tailwind CSS v4 natively uses. This conversion happens inside the extraction script before the data is written to specification files.

The normalization process uses a conversion helper (typically leveraging the colorjs.io package in Node.js ≥ 18) to transform values like rgb(255, 0, 0) into Oklch strings such as oklch(0.205 0 0). The result is a map of semantic token names—such as background, primary, and muted—to standardized Oklch values.

Stage 3: Mapping – Tailwind CSS v4 Token Injection

The normalized token map is written into src/app/globals.css as CSS custom properties inside the :root block for light mode and the .dark class for dark mode (lines 52-78 and 86-110). These variables follow the --color-* naming convention that Tailwind CSS v4 automatically detects.

Because Tailwind v4 reads any --color-* custom properties in the CSS, the utility classes automatically resolve to these design-token values without additional configuration. Component authors can then use classes like bg-background or text-primary-foreground, and Tailwind outputs the correct Oklch colors.

Step-by-Step Technical Walkthrough

The entire pipeline is orchestrated from the clone-website workflow defined in .windsurf/workflows/clone-website.md (lines 31-33).

1. Launch the browser MCP – The agent starts a headless Chrome session and navigates to the target URL.

2. Run the extraction script – The script executes inside the browser context:

   /**
    * Extract all relevant CSS properties from a DOM element.
    * The script runs inside the browser via Chrome MCP.
    */
   function extractStyles(element) {
     const s = getComputedStyle(element);
     return {
       color: s.color,
       backgroundColor: s.backgroundColor,
       fontFamily: s.fontFamily,
       fontSize: s.fontSize,
       fontWeight: s.fontWeight,
       lineHeight: s.lineHeight,
       letterSpacing: s.letterSpacing,
       padding: s.padding,
       margin: s.margin,
       borderRadius: s.borderRadius,
       boxShadow: s.boxShadow,
     };
   }
   
   // Example usage – collect from every component root:
   const components = document.querySelectorAll('[data-clone]');
   const specs = Array.from(components).map(el => ({
     name: el.getAttribute('data-clone'),
     styles: extractStyles(el),
   }));
   console.log(JSON.stringify(specs, null, 2));

3. Merge the raw values – The agent consolidates all color occurrences, removes duplicates, and builds a coherent color scale.

4. Convert to Oklch – Each hex or RGB string is processed by a conversion helper:

   import { parse } from 'colorjs.io';
   
   export function rgbToOklch(rgb: string): string {
     const c = parse(rgb);                // e.g. "rgb(255, 0, 0)"
     const oklch = c.convert('oklch');    // → { l:…, c:…, h:… }
     const { l, c: chroma, h } = oklch;
     return `oklch(${l.toFixed(3)} ${chroma.toFixed(3)} ${h.toFixed(1)})`;
   }

5. Write the Tailwind token file – The helper writes the CSS into src/app/globals.css:

   :root {
     --background: oklch(1 0 0);
     --foreground: oklch(0.145 0 0);
     --primary: oklch(0.205 0 0);
     --primary-foreground: oklch(0.985 0 0);
     /* …more tokens… */
   }
   
   .dark {
     --background: oklch(0.145 0 0);
     --foreground: oklch(0.985 0 0);
     /* …more tokens… */
   }

6. Tailwind compiler picks up the tokens – Because Tailwind CSS v4 automatically registers --color-* properties, no additional configuration is required.

7. Component authors use the tokens – In component JSX, developers reference the tokens directly:

   import { cn } from '@/lib/utils';
   
   export function PrimaryButton({ children }: { children: React.ReactNode }) {
     return (
       <button
         className={cn(
           'px-4 py-2 rounded-md',
           'bg-primary text-primary-foreground',
           'hover:bg-primary-foreground hover:text-primary',
           'transition-colors'
         )}
       >
         {children}
       </button>
     );
   }

Key Files in the Repository

Understanding the following files is essential for customizing or debugging the token extraction pipeline:

• docs/research/INSPECTION_GUIDE.md – Defines the checklist that tells the agent what design tokens to pull (colors, typography, spacing, etc.) from the target site.

• .windsurf/workflows/clone-website.md – Contains the human-readable workflow that explains how the extraction is performed and how the token map is written to globals.css (lines 31-33).

• src/app/globals.css – The concrete Tailwind CSS v4 design-token definition file containing the light mode (lines 52-78) and dark mode (lines 86-110) Oklch variable declarations.

• src/lib/utils.ts – Provides the cn() helper function used in component examples, following the shadcn pattern for conditional class merging.

Summary

• Browser automation via Chrome MCP or Playwright MCP extracts raw computed styles from target sites using getComputedStyle().
• Color normalization converts all RGB and hex values to Oklch for Tailwind CSS v4 compatibility.
• Token injection writes semantic CSS custom properties to src/app/globals.css inside :root and .dark blocks.
• Zero-config consumption allows components to use utility classes like bg-primary that automatically resolve to the extracted Oklch values.
• Deterministic workflow ensures every clone matches the source site pixel-for-pixel by deriving all visual values from the original design system.

Frequently Asked Questions

Why does the template convert colors to Oklch instead of using hex or RGB?

Tailwind CSS v4 natively supports the Oklch color model for better perceptual uniformity and consistent lightness across different hues. By converting extracted hex and RGB values to Oklch before injection, the template ensures that the cloned website maintains the same visual luminance as the original while leveraging Tailwind's modern color system. The conversion is handled automatically by the extraction script using the colorjs.io library.

How does Tailwind CSS v4 detect the custom properties written to globals.css?

Tailwind CSS v4 automatically reads any CSS custom property prefixed with --color-* from the stylesheet. When the pipeline writes tokens like --background: oklch(1 0 0) to src/app/globals.css, Tailwind's compiler immediately registers these as theme colors. This allows utility classes like bg-background and text-primary to resolve to the injected Oklch values without requiring a tailwind.config.js file or manual theme extensions.

Where is the design token extraction logic defined in the repository?

The extraction logic is defined in .windsurf/workflows/clone-website.md at lines 31-33, which describes the browser automation steps. The specific checklist of which tokens to extract (colors, fonts, spacing, radii) is documented in docs/research/INSPECTION_GUIDE.md at lines 18-23. The actual CSS custom property definitions that Tailwind consumes are located in src/app/globals.css at lines 52-98.

Can I manually modify the extracted design tokens after generation?

Yes. The extracted tokens in src/app/globals.css are standard CSS custom properties. You can edit the Oklch values directly in the :root or .dark blocks to adjust the theme after the initial extraction. Because Tailwind CSS v4 reads these values at compile time, any changes to the custom properties will immediately reflect in the utility classes throughout your application without requiring a rebuild of the component code.

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