# How to Write Component Specification Files in the AI Website Cloner Template

> Learn to write component specification files for the AI Website Cloner. Understand the markdown format and blueprint for rebuilding UI elements with exact styles and behavior.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-07-03

---

**Component specification files are markdown documents stored in `docs/research/components/` that serve as the canonical blueprint for reconstructing UI elements, detailing exact computed styles, DOM structure, interactive states, and responsive behavior.**

Component spec files bridge the gap between website extraction and code generation in the JCodesMore/ai-website-cloner-template workflow. These [`.spec.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.spec.md) files provide builder agents with machine-readable instructions that eliminate guesswork during the reconstruction phase. Understanding the strict markdown format defined in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) ensures your reverse-engineered components render pixel-perfectly across all breakpoints.

## Required Spec File Format

Every component spec file must follow the template defined in the clone-website workflow (lines 303–371 of [`clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/clone-website.md)). Store each file as `docs/research/components/<ComponentName>.spec.md` using this exact structure:

```markdown

# <ComponentName> Specification

## Overview

- **Target file:** `src/components/<ComponentName>.tsx`
- **Screenshot:** `docs/design-references/<screenshot-name>.png`
- **Interaction model:** <static | click-driven | scroll-driven | time-driven>

## DOM Structure

<Describe the element hierarchy – which element contains which child>

## Computed Styles (exact values from getComputedStyle)

### Container

- display: …
- padding: …
- maxWidth: …

### <Child element 1>

- fontSize: …
- color: …

## States & Behaviors

### <Behavior name>

- **Trigger:** <exact mechanism>
- **State A (before):** <property>: <value>
- **State B (after):** <property>: <value>
- **Transition:** <transition CSS>
- **Implementation approach:** <CSS, JS, IntersectionObserver, etc.>

## Per-State Content (if applicable)

### State: "Featured"

- Title: "…"
- Cards: [{ title, description, image, link }, …]

## Assets

- Background image: `public/images/<file>.webp`
- Icons used: `<ArrowIcon>` from `src/components/icons.tsx`

## Text Content (verbatim)

<All textual copy taken verbatim>

## Responsive Behavior

- **Desktop (1440 px):** <layout description>
- **Tablet (768 px):** <layout description>
- **Mobile (390 px):** <layout description>
- **Breakpoint:** layout switches at ~<N> px

```

## How to Fill Each Section

The extraction workflow provides specific data sources for each section of the spec template. Map your findings to these fields to ensure completeness:

### Overview Section

Capture the **component name**, the target file path under `src/components/`, a screenshot reference from `docs/design-references/`, and the **interaction model**. Choose from four interaction models defined in the workflow (lines 78–86):

- **Static**: No user interaction affects the component
- **Click-driven**: State changes triggered by user clicks
- **Scroll-driven**: Animations or visibility tied to scroll position
- **Time-driven**: Automatic transitions or animations based on timers

### DOM Structure

Document the exact hierarchy using prose or bullet notation. For example, note that a `<button>` resides inside a `<div class="wrapper">`, or that a `<section>` contains a `<header>` followed by a grid of cards. Inspect the live DOM using Chrome DevTools during the extraction phase.

### Computed Styles

Record every CSS property returned by `getComputedStyle()` that affects rendering, excluding default values (`auto`, `0px`, `none`). Run the extraction script provided in the workflow (lines 38–80) to capture these values automatically. Organize properties by element, starting with the container and drilling down to child elements.

### States & Behaviors

For each interactive state, capture the trigger mechanism, before/after property values, and transition details. Use the **State Extraction** steps (lines 82–90) to capture default styles, then trigger the state via scroll, click, or hover, and capture again. Specify the implementation approach—whether the behavior requires CSS transitions, JavaScript event listeners, or `IntersectionObserver`.

### Per-State Content

Document the literal text, images, or data structures that appear in each UI state. For tab components or accordions, record the content for each panel separately. Gather this during the **Click Sweep** (lines 48–52) by activating each state and extracting the visible content.

### Assets

List every image, video, or SVG with exact repository paths. The asset discovery script (lines 90–124) generates a JSON inventory of images and videos; reference these paths under `public/images/`. For SVG icons, note the component name exported from [`src/components/icons.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/components/icons.tsx).

### Text Content

Paste all visible copy verbatim from the live site. Use `element.textContent` in the extraction script to ensure accuracy, including exact spacing and punctuation.

### Responsive Behavior

Describe layout changes at three standard breakpoints: **1440 px** (desktop), **768 px** (tablet), and **390 px** (mobile). Note the exact pixel value where layout shifts occur. Conduct the **Responsive Sweep** (lines 57–62) using browser DevTools to verify behavior at each width.

## Complete Component Spec File Example

This PrimaryButton specification demonstrates a fully populated file:

```markdown

# PrimaryButton Specification

## Overview

- **Target file:** `src/components/PrimaryButton.tsx`
- **Screenshot:** `docs/design-references/primary-button-desktop.png`
- **Interaction model:** click-driven

## DOM Structure

- `<button class="btn btn-primary">` contains:
  - `<svg class="icon">` (Icon component)
  - Text node "Get Started"

## Computed Styles (exact values from getComputedStyle)

### Container

- display: inline-flex
- alignItems: center
- gap: 0.5rem
- padding: 0.75rem 1.5rem
- borderRadius: 0.5rem
- backgroundColor: #0d6efd
- color: #ffffff
- fontSize: 1rem
- fontWeight: 600
- transition: background-color 0.2s ease, transform 0.2s ease

### Icon

- width: 1rem
- height: 1rem
- fill: currentColor

## States & Behaviors

### Hover

- **Trigger:** mouseenter on `.btn-primary`
- **State A (before):** backgroundColor = #0d6efd
- **State B (after):** backgroundColor = #0b5ed7
- **Transition:** background-color 0.2s ease

### Active (press)

- **Trigger:** mousedown on `.btn-primary`
- **State A:** transform = none
- **State B:** transform = scale(0.97)
- **Transition:** transform 0.1s ease

## Per-State Content

- N/A (button text does not change)

## Assets

- Icon: `SearchIcon` from `src/components/icons.tsx`

## Text Content (verbatim)

Get Started

## Responsive Behavior

- **Desktop (1440 px):** full-width button, gap = 0.5rem
- **Tablet (768 px):** same layout, fontSize = 1rem
- **Mobile (390 px):** same layout, padding = 0.6rem 0.9rem
- **Breakpoint:** layout unchanged; no breakpoint needed

```

## Key Files and Directories

Reference these files when writing and processing component specifications:

- **[`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md)** – Contains the spec-file template (lines 303–371) and the complete extraction workflow including the Interaction Sweep, State Extraction, and Responsive Sweep.
- **`docs/research/components/`** – Directory where each `<ComponentName>.spec.md` must reside.
- **[`src/components/icons.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/components/icons.tsx)** – Storage location for extracted SVG icons referenced in the Assets section.
- **[`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx)** – Where global font configuration derived from specs is applied.
- **[`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css)** – Receives design-token values (colors, spacing) extracted from computed styles.
- **[`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md)** – Explains that component specs drive builder agents (line 92).

## Summary

- Component spec files are markdown documents stored in `docs/research/components/` that serve as the single source of truth for UI reconstruction.
- The format requires eight specific sections: Overview, DOM Structure, Computed Styles, States & Behaviors, Per-State Content, Assets, Text Content, and Responsive Behavior.
- Exact values from `getComputedStyle()` must be recorded for every non-default CSS property to ensure pixel-perfect rendering.
- Interaction models are classified as static, click-driven, scroll-driven, or time-driven according to the workflow definition.
- Builder agents consume these files to generate target components in `src/components/` without ambiguity.

## Frequently Asked Questions

### What is the purpose of the component spec file in the AI Website Cloner Template?

The component spec file acts as a machine-readable blueprint that bridges the extraction and build phases. It tells builder agents exactly how to reconstruct a UI component by providing computed styles, DOM hierarchy, interactive states, and asset paths, eliminating guesswork and ensuring the cloned output matches the original design pixel-for-pixel.

### Where should I place component specification files in the repository?

Store all spec files under `docs/research/components/` using the naming convention `<ComponentName>.spec.md`. The build pipeline expects to find component blueprints in this specific directory, while design references (screenshots) belong in `docs/design-references/` and final components are generated in `src/components/`.

### How do I capture accurate computed styles for the specification?

Run the extraction script referenced in [`clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/clone-website.md) (lines 38–80) against the target website. This script calls `getComputedStyle()` on each element and filters out default values. For interactive states, manually trigger the state (hover, scroll, or click) then re-run style extraction to capture the before and after values required for the States & Behaviors section.

### What is the difference between the four interaction models?

**Static** components never change based on user input. **Click-driven** components alter state or content when users interact with buttons, tabs, or accordions. **Scroll-driven** components animate or reveal content based on viewport position, often using `IntersectionObserver`. **Time-driven** components automatically transition or animate based on timers without user interaction.