What Is the Foundation Build Phase in the AI Website Cloner Template?

The Foundation Build phase is the second step of the cloning workflow that establishes immutable, site-wide scaffolding—including fonts, design tokens, TypeScript interfaces, and global assets—before any component-level extraction begins.

The Foundation Build phase serves as the architectural bedrock for every project generated by the JCodesMore/ai-website-cloner-template. According to the clone-website.md workflow documents, this phase ensures that the target website's global design language and asset structure are centralized and validated before AI agents proceed to Phase 3 component extraction.

Why the Foundation Build Phase Matters

Without this centralized foundation, every subsequent component would carry isolated copies of fonts, colors, and icons, leading to maintenance nightmares and design drift. By performing these updates once and centrally in Phase 2, the template guarantees that every builder dispatch in Phase 3 operates against a stable, shared style and data layer. This approach eliminates duplicated markup, prevents typographic inconsistencies, and ensures the cloned Next.js codebase remains production-ready.

The Six Steps of the Foundation Build Phase

The phase follows a strict sequence defined in .windsurf/workflows/clone-website.md and mirrored in .opencode/commands/clone-website.md.

Step 1: Configure Global Typography in src/app/layout.tsx

The developer updates the root layout to match the target site's exact font families, weights, and fallbacks. This ensures typographic consistency across all pages before any components are built.

// src/app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {/* Replace with the exact font URLs discovered on the target site */}
        <link rel="preconnect" href="https://fonts.googleapis.com" />
        <link
          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap"
          rel="stylesheet"
        />
      </head>
      <body className="font-inter antialiased">{children}</body>
    </html>
  );
}

Step 2: Define Design Tokens in src/app/globals.css

This step adds the target's color palette, spacing scale, keyframe animations, and global scrolling behavior to the stylesheet. This creates a single source of truth that shadcn/ui components can consume.

/* src/app/globals.css */

/* Color tokens */
:root {
  --color-primary: #0d6efd;
  --color-muted: #6c757d;
  --color-bg: #f8f9fa;
}

/* Spacing scale */
:root {
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 1rem;
  --space-4: 1.5rem;
}

/* Global smooth‑scroll behavior */
html {
  scroll-behavior: smooth;
}

Step 3: Create TypeScript Interfaces in src/types/

Before components are generated, TypeScript interfaces are defined to describe the shape of discovered content—such as navigation items or blog post front-matter. This provides strict typing for downstream builders.

// src/types/nav.ts
export interface NavItem {
  label: string;
  href: string;
  children?: NavItem[];
}

Step 4: Extract SVG Icons to src/components/icons.tsx

Every inline <svg> from the target page is converted into a reusable React component named after its visual purpose. This guarantees pixel-perfect iconography and allows shadcn/ui Icon primitives to be swapped later if needed.

// src/components/icons.tsx
export const SearchIcon = (props: React.SVGProps<SVGSVGElement>) => (
  <svg viewBox="0 0 24 24" {...props}>
    <path d="M21 21l-4.35-4.35..." />
  </svg>
);

export const ArrowRightIcon = (props: React.SVGProps<SVGSVGElement>) => (
  <svg viewBox="0 0 24 24" {...props}>
    <path d="M5 12h14M12 5l7 7-7 7" />
  </svg>
);

Step 5: Download Global Assets via scripts/download-assets.mjs

The script programmatically fetches all images, videos, and binary assets, storing them under public/ while preserving a meaningful directory hierarchy. This makes the cloned site fully self-contained and eliminates external CDN dependencies.

// scripts/download-assets.mjs
import { writeFile, mkdir } from 'node:fs/promises';
import { dirname } from 'node:path';
import fetch from 'node-fetch';

const assets = /* JSON produced by the browser MCP script (see workflow) */;

async function download(url, dest) {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`Failed ${url}`);
  await mkdir(dirname(dest), { recursive: true });
  const buffer = await res.arrayBuffer();
  await writeFile(dest, Buffer.from(buffer));
}

for (const img of assets.images) {
  const filename = new URL(img.src).pathname.split('/').pop();
  await download(img.src, `public/images/${filename}`);
}

Step 6: Verify the Build with npm run build

The final step runs the Next.js production build to confirm that the newly added globals, types, and assets do not introduce compilation errors. This provides an early sanity check before the intensive component-specification loop begins.

npm run build   # should exit with code 0 and output the compiled app

Key Files Involved in the Foundation Build

The following files constitute the "foundation" that supports all later component-level generation:

• .windsurf/workflows/clone-website.md – Primary workflow guide containing the Phase 2 description at line 75
• .opencode/commands/clone-website.md – Command-line version of the workflow at line 78
• src/app/layout.tsx – Root layout where fonts are declared (Step 1)
• src/app/globals.css – Global stylesheet for design tokens (Step 2)
• src/types/ – Directory for generated TypeScript interfaces (Step 3)
• src/components/icons.tsx – Central SVG icon library (Step 4)
• scripts/download-assets.mjs – Asset-download helper script (Step 5)

Summary

• The Foundation Build phase is Phase 2 of the AI Website Cloner workflow, positioned between initial setup and component extraction.
• It ensures typographic consistency by updating src/app/layout.tsx with the target site's fonts.
• It centralizes design tokens in globals.css to provide a single source of truth for colors, spacing, and animations.
• It establishes type safety by creating TypeScript interfaces in src/types/ before components are generated.
• It guarantees pixel-perfect assets by extracting SVGs to icons.tsx and downloading binary files via download-assets.mjs.
• It validates the pipeline by running npm run build to catch errors before Phase 3 begins.

Frequently Asked Questions

How does the Foundation Build phase differ from the Setup phase?

The Setup phase (Phase 1) initializes the repository and installs dependencies, while the Foundation Build phase (Phase 2) specifically focuses on configuring the immutable scaffolding—fonts, CSS variables, and types—that will govern the entire project. According to the workflow file, the Foundation Build accepts a "human-in-the-loop" to manually verify design tokens, whereas Setup is typically fully automated.

Can the Foundation Build phase be fully automated, or does it require manual intervention?

While the asset download script (download-assets.mjs) runs automatically, the workflow documentation indicates that steps 1–4 (fonts, CSS, types, and icons) are designed for a human-in-the-loop to manually update. This ensures the cloned site faithfully mirrors the target's specific design language rather than relying on automated inference which might miss subtle visual nuances.

What happens if the build verification fails during the Foundation Build phase?

If npm run build exits with a non-zero status code, the workflow halts before entering Phase 3. This early failure prevents AI agents from generating hundreds of components on top of a broken foundation. The developer must fix TypeScript errors, CSS syntax issues, or missing asset references in the global files before restarting the build verification.

Why are TypeScript interfaces created before any components exist?

Interfaces are defined during the Foundation Build phase to provide strict typing for the content structure discovered during site inspection. This enables TypeScript-level safety and autocompletion when Phase 3 builders generate components that consume navigation data, blog posts, or other dynamic content. Creating these types upfront prevents costly refactoring later in the cloning process.

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