# Component Specification System in the AI Website Cloner Template

> Discover the Component Specification System in the AI Website Cloner. It creates JSON specs for UI components, empowering builder agents to replicate designs accurately.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: architecture
- Published: 2026-07-11

---

**The Component Specification System generates machine-readable JSON specifications for every UI component discovered during reconnaissance, enabling builder agents to recreate exact design replicas without manual interpretation.**

The Component Specification System serves as the architectural backbone of the JCodesMore/ai-website-cloner-template repository, transforming raw visual inspection data into precise technical blueprints. Located between the reconnaissance and build phases, this system captures computed styles and interaction behaviors to create unambiguous instructions for automated code generation.

## What the Component Specification System Captures

After the initial reconnaissance phases complete, the system writes detailed specification files to `docs/research/components/`. Each spec file documents:

- **Exact CSS values** obtained via `getComputedStyle()`, including colors, spacing, and typography
- **Interaction states** (hover, focus, active, disabled) with their specific style variations
- **Behavioral metadata** such as click actions, scroll-into-view triggers, and responsive breakpoints
- **Content hierarchy** including text, images, SVGs, and placeholder data for demos

## Pipeline Integration: The Component Specification Phase

The cloning workflow follows a strict multi-phase pipeline defined in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) at lines 226-230 and summarized in [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) lines 90-96:

1. **Reconnaissance** – Capture screenshots, extract design tokens, and interact with the page
2. **Foundation** – Install fonts, colors, and download assets
3. **Component Specification** – **(Phase 3)** Write detailed component specification files
4. **Parallel Build** – Dispatch builder agents that consume the specs
5. **Assembly & QA** – Merge worktrees, wire up the final page, and run visual diffs

The Component Specification System explicitly operates as Phase 3, serving as the critical handoff point between data collection and code generation.

## Key Responsibilities and Benefits

The specification system delivers three core advantages to the cloning pipeline:

- **Auditability** – All design decisions persist in plain text files, creating a transparent record of why specific styles were chosen
- **Parallelism** – Self-contained specs allow multiple builder agents to work simultaneously on different components, dramatically reducing total cloning time
- **Reliability** – By relying on computed values from `getComputedStyle()` rather than interpreted CSS, the system eliminates browser-specific rendering ambiguities

## Component Specification File Structure

Below is a simplified illustration of a generated specification file. The actual automated output contains richer metadata, but follows this JSON structure:

```json
// docs/research/components/Button.spec.json
{
  "name": "PrimaryButton",
  "type": "button",
  "styles": {
    "default": {
      "backgroundColor": "#1a73e8",
      "color": "#ffffff",
      "borderRadius": "0.5rem",
      "padding": "0.75rem 1.5rem"
    },
    "hover": {
      "backgroundColor": "#1669c1"
    },
    "focus": {
      "outline": "2px solid #4285f4"
    }
  },
  "states": ["default", "hover", "focus", "disabled"],
  "responsive": {
    "sm": { "fontSize": "0.875rem" },
    "lg": { "fontSize": "1rem" }
  },
  "content": {
    "text": "Click me",
    "icon": "lucide/arrow-right"
  }
}

```

Builder agents import these specifications to generate framework-specific implementations. Here is how a builder translates the spec into a React component using the `cn` utility from [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts):

```tsx
// src/components/ui/PrimaryButton.tsx
import { cn } from '@/lib/utils';
import { ArrowRight } from '@/components/icons';

export function PrimaryButton() {
  return (
    <button
      className={cn(
        'bg-[#1a73e8] text-white rounded-md py-3 px-6',
        'hover:bg-[#1669c1] focus:outline focus:outline-2 focus:outline-[#4285f4]',
      )}
    >
      Click me <ArrowRight className="inline-block ml-2" />
    </button>
  );
}

```

## Critical System Files

Several files support the Component Specification System across the repository:

- **[`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md)** (lines 90-96) – Provides the high-level pipeline overview including the Component Specification phase
- **[`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md)** (lines 226-230) – Details the multi-phase workflow, explicitly naming "Component Specification & Dispatch"
- **[`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md)** – Guides inspection agents on capturing CSS approaches and interaction states
- **[`components.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/components.json)** (root) – Lists expected component types and serves as a template for generated specs
- **[`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts)** – Supplies the `cn` utility function that builders use to translate spec class strings into Tailwind-compatible names

## Summary

- The Component Specification System generates machine-readable JSON files in `docs/research/components/` containing computed styles and interaction states
- It operates as Phase 3 of the cloning pipeline, bridging reconnaissance and parallel code generation
- Specifications capture exact values from `getComputedStyle()` to eliminate rendering ambiguity
- Self-contained specs enable parallel processing by multiple builder agents, reducing overall cloning time
- Builder agents consume these specs to generate framework-specific code using utilities like `cn` from [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts)

## Frequently Asked Questions

### What file format does the Component Specification System use?

The system generates JSON specification files stored in `docs/research/components/`. Each file follows a structured schema that includes style objects, state arrays, responsive breakpoints, and content metadata, making them readable by both humans and automated builder agents.

### How does the Component Specification System handle responsive design?

Each specification includes a `responsive` object that maps breakpoint keys (such as `sm` and `lg`) to specific CSS property overrides. Builder agents reference these mappings to generate media queries or responsive utility classes in the final components.

### Where are component specifications stored in the repository?

Generated specifications are written to the `docs/research/components/` directory. This location serves as the central repository for all component blueprints before they are consumed by builder agents during the Parallel Build phase.

### What is the relationship between component specs and builder agents?

Builder agents treat component specifications as single-source-of-truth instruction manuals. Because each spec contains complete computed styles and interaction states, builders can generate code in parallel without communicating with each other, eliminating merge conflicts and ensuring design consistency across the rebuilt website.