Component Specification System in the AI Website Cloner Template

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 at lines 226-230 and summarized in 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:

// 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:

// 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 (lines 90-96) – Provides the high-level pipeline overview including the Component Specification phase
• .windsurf/workflows/clone-website.md (lines 226-230) – Details the multi-phase workflow, explicitly naming "Component Specification & Dispatch"
• docs/research/INSPECTION_GUIDE.md – Guides inspection agents on capturing CSS approaches and interaction states
• components.json (root) – Lists expected component types and serves as a template for generated specs
• 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

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.

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