How to Write a Component Specification File for ai-website-cloner-template

A component specification file is a Markdown document stored in docs/research/components/ that captures exact computed CSS, DOM hierarchy, interaction states, and asset paths, serving as the single source of truth for builder agents to generate type-safe React components without compilation errors.

Writing a component specification file is the critical bridge between website extraction and code generation in the ai-website-cloner-template workflow. Each spec acts as an immutable contract that tells the builder agent exactly how to reconstruct a UI piece in src/components/, ensuring pixel-perfect fidelity to the target site. Understanding how to structure this file correctly prevents build failures and eliminates guesswork during the component generation phase.

What Is a Component Specification File?

In the JCodesMore/ai-website-cloner-template architecture, the cloning pipeline splits work into two phases: Extraction (browser automation) and Specification → Build (code generation). The specification file—conventionally named <component-name>.spec.md—is the artifact produced after extracting data from the live target site.

According to the clone-website workflow documented in .windsurf/workflows/clone-website.md, spec files are declared the "source of truth" for all builder agents (see lines 1008–1013). This design pattern is also summarized in the repository's README.md (lines 92–96), which explains that specs must be written before any builder is invoked. Agents receive the entire spec content inline rather than reading multiple files, meaning the Markdown must contain exhaustive details about styling, behavior, and structure.

Anatomy of a Component Specification File

The official template (located at lines 3030–3070 in .windsurf/workflows/clone-website.md) mandates eight distinct sections. Omitting any section risks incomplete component generation.

Overview and Target File

Every spec must declare:

• Component name (e.g., HeroSection)
• Target file (e.g., src/components/HeroSection.tsx)
• Screenshot path (for visual reference)
• Interaction model (static, click-driven, scroll-driven, or time-driven)

This metadata ensures the builder knows where to write code and how the component behaves at runtime.

DOM Structure

Provide a concise hierarchy showing parent-child relationships. For example:

<header class="hero">
  <h1 class="title">...</h1>
  <p class="subtitle">...</p>
</header>

This guarantees the generated JSX mirrors the original markup exactly.

Computed Styles

List every CSS value obtained via getComputedStyle() from the live site. The template explicitly warns against guessing values. Include:

• Layout properties (display, flex-direction, gap, padding)
• Typography (font-size, font-weight, line-height, color)
• Visual effects (border-radius, box-shadow, background-color)

States and Behaviors

Document each interactive state with:

• Trigger (e.g., hover, scroll-position >= 80px, click)
• Before/After CSS (exact property changes)
• Transition details (duration and easing)

This enables the builder to embed correct logic such as IntersectionObserver thresholds for scroll-driven animations.

Assets and Icons

Reference all external files:

• Images (paths relative to public/)
• Icons (imports from src/components/icons.tsx)
• Videos or fonts

Responsive Behavior

Specify breakpoints (typically desktop 1440px, tablet 768px, mobile 390px) and layout adjustments for each. This ensures the clone remains responsive without manual tweaking.

Per-State Content

Record verbatim text, alt tags, and dynamic data for each state. This preserves SEO-relevant copy and prevents placeholder text from entering the build.

Where to Store Your Specification Files

Place all specification files in the docs/research/components/ directory. Use the naming convention <ComponentName>.spec.md. For example, a navigation bar specification lives at:

docs/research/components/Navbar.spec.md

This path is referenced by the orchestration logic in the clone-website workflow and keeps research artifacts separate from source code.

The Official Template Reference

The canonical structure is defined in .windsurf/workflows/clone-website.md at lines 3030–3070. This block specifies the required Markdown headers and reminds authors that all CSS must be extracted via getComputedStyle() and that every state must be captured before invoking a builder agent.

Complete Example: Hero Section Specification

Below is a production-ready example following the template exactly:

# HeroSection Specification

## Overview

- **Target file:** `src/components/HeroSection.tsx`
- **Screenshot:** `docs/design-references/hero-desktop.png`
- **Interaction model:** scroll-driven

## DOM Structure

<header class="hero">
  <h1 class="title">Build faster with AI</h1>
  <p class="subtitle">Turn any website into a modern Next.js app.</p>
  <a class="cta btn-primary">Start cloning</a>
</header>

## Computed Styles

### Container (.hero)

- display: flex
- flex-direction: column
- align-items: center
- padding: 120px 24px
- background-color: #1e1e2d
- background-image: url("/images/hero-bg.webp")
- gap: 32px

### Title (.title)

- font-size: 56px
- font-weight: 700
- line-height: 1.1
- color: #ffffff

### CTA (.btn-primary)

- padding: 12px 24px
- background-color: #ff6b6b
- border-radius: 8px
- transition: background-color 0.25s ease

## States & Behaviors

### Scroll-triggered shrink

- **Trigger:** scroll-position >= 80px
- **Before:** padding: 120px 24px
- **After:** padding: 80px 24px
- **Transition:** all 0.3s ease-in-out

### Hover on CTA

- **Trigger:** hover on .btn-primary
- **Before:** background-color: #ff6b6b
- **After:** background-color: #ff8787
- **Transition:** background-color 0.2s ease

## Assets

- Background: `public/images/hero-bg.webp`
- Icon: `ArrowRight` from `src/components/icons.tsx`

## Text Content (verbatim)

Build faster with AI
Turn any website into a modern Next.js app.
Start cloning

## Responsive Behavior

- **Desktop (1440px):** title 56px, horizontal layout
- **Tablet (768px):** title 48px, reduced padding
- **Mobile (390px):** title 36px, vertical stack, full-width button

How Builder Agents Consume the Spec

When you dispatch a builder agent, the system reads the spec file and injects its contents directly into the agent's context (no file streaming). The agent then:

1. Creates or updates src/components/HeroSection.tsx
2. Imports utilities from src/lib/utils (including the cn() helper for Tailwind classes)
3. References icons from src/components/icons.tsx
4. Applies global styles from src/app/globals.css and layout configurations from src/app/layout.tsx

After generation, the workflow automatically runs npx tsc --noEmit and npm run build to verify the component compiles (see lines 1313–1316 in .windsurf/workflows/clone-website.md). If the spec omitted required props or assets, this step fails, preventing broken code from entering the repository.

Summary

• Component specification files live in docs/research/components/<Name>.spec.md and serve as the immutable blueprint for each UI element.
• Eight required sections—Overview, DOM Structure, Computed Styles, States & Behaviors, Assets, Responsive Behavior, and Content—must be completed using exact values from getComputedStyle().
• Source of truth: The template in .windsurf/workflows/clone-website.md (lines 3030–3070) dictates the format; deviations cause builder failures.
• Build verification: Every component must pass TypeScript checking (npx tsc --noEmit) and the Next.js build (npm run build) before the task is considered complete.
• Asset management: All images belong in public/, while SVG icons are centralized in src/components/icons.tsx.

Frequently Asked Questions

What happens if I skip the specification file and ask the builder to code directly?

The builder agent lacks the computed CSS values, interaction triggers, and asset paths required to generate a compilable component. According to the workflow rules in ai-website-cloner-template, the spec file must exist before any builder runs; otherwise the agent receives incomplete information, resulting in build errors or visual mismatches (see lines 1008–1013 in .windsurf/workflows/clone-website.md).

How do I handle dynamic content that changes based on API calls?

Document the default state in the spec as if the API returns its initial payload. Include the data structure interface (usually defined in src/types/) in the spec's "Per-State Content" section. The builder will generate the component with TypeScript props matching that interface, allowing you to wire up real data later without changing the component's visual logic.

Can I use Tailwind classes instead of raw CSS values in the specification?

No. The specification must contain exact computed CSS values (e.g., padding: 120px 24px) extracted via getComputedStyle(). The builder agent is responsible for mapping these raw values to Tailwind utility classes (using cn() from src/lib/utils) or inline styles during code generation. Providing Tailwind classes in the spec risks imprecision because the builder might interpret them differently than the original site's computed styles.

Where does the global styling and font configuration live?

Global CSS variables, Tailwind directives, and font imports (via next/font) reside in src/app/globals.css and src/app/layout.tsx. The specification file references these globals for context (e.g., "uses primary color variable"), but the component-specific styles in the spec override or extend these base tokens to match the target site exactly.

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