Component Specification File Format for AI Website Cloner: Complete Markdown Structure

The component specification file format in ai-website-cloner-template is a Markdown-based schema stored in docs/research/components/ that uses standardized headings to define HTML structure, computed styles, interaction states, and responsive behavior.

The JCodesMore/ai-website-cloner-template repository uses a strict component specification file format to bridge the gap between visual inspection and code generation. This format allows AI agents to parse website components systematically and recreate them with high fidelity. Each spec file acts as a single source of truth that drives the generation of JSX components and Tailwind CSS classes in the final output.

File Location and Naming Convention

Component specifications reside in the docs/research/components/ directory. Each component receives its own Markdown file, enabling the cloning pipeline to process components individually or in parallel. According to the repository documentation, this structure is explicitly defined as the "Component Specification" pipeline step in README.md【README.md†L92-L96】.

Anatomy of the Component Specification

The format follows a rigid heading hierarchy that agents parse verbatim. Missing sections or incorrect heading levels will cause the code generation to fail or produce incomplete components.

Component Name and Description

The file opens with an H1 heading containing the component identifier, followed by a concise description:

# ButtonPrimary

## Description

Primary call-to-action button used throughout the site.

Markup

The ## Markup section contains the exact HTML or JSX snippet extracted from the target website. This must include original class names to maintain semantic meaning and styling hooks:

## Markup

<button class="btn btn-primary">Sign up</button>

Styles

Under ## Styles, the specification lists CSS property-value pairs derived from getComputedStyle(). Values use the project's design-token format, typically expressing colors in oklch():

## Styles

background-color: oklch(0.62 0.12 250);
color: oklch(0.99 0 0);
padding: 0.75rem 1.5rem;
border-radius: 0.5rem;
font-weight: 600;

States

The ## States section contains sub-sections for every visual state (hover, focus, active, disabled). Each state repeats the Styles block with values specific to that condition:

## States

### Hover

background-color: oklch(0.65 0.15 250);
color: oklch(1 0 0);

### Active

background-color: oklch(0.55 0.10 250);
transform: translateY(1px);

Interaction Model

This section defines behavioral logic using the specific prefix INTERACTION MODEL:. As documented in .windsurf/workflows/clone-website.md, agents must embed this heading to describe how the component reacts to input【.windsurf/workflows/clone-website.md†L86-L90】:

## Interaction Model

INTERACTION MODEL: click-to-switch with opacity transition.

Responsive Breakpoints

The ## Responsive Breakpoints section maps CSS values to specific viewport sizes:

## Responsive Breakpoints

- Mobile: font-size 0.875rem
- Tablet: font-size 1rem
- Desktop: font-size 1.125rem

Assets and Content

The specification concludes with references to external resources and literal text content:

• ## Assets: Relative paths to images, SVGs, videos, or fonts stored in public/

• ## Content: Verbatim text or inner-HTML copied from the live site

Complete Component Specification Example

Here is a fully valid specification for a primary button component:

# ButtonPrimary

## Description

Primary call-to-action button used throughout the site.

## Markup

<button class="btn btn-primary">Sign up</button>

## Styles

background-color: oklch(0.62 0.12 250);
color: oklch(0.99 0 0);
padding: 0.75rem 1.5rem;
border-radius: 0.5rem;
font-weight: 600;

## States

### Hover

background-color: oklch(0.65 0.15 250);
color: oklch(1 0 0);

### Active

background-color: oklch(0.55 0.10 250);
transform: translateY(1px);

## Interaction Model

INTERACTION MODEL: click-to-switch with opacity transition.

## Responsive Breakpoints

- Mobile: font-size 0.875rem
- Tablet: font-size 1rem
- Desktop: font-size 1.125rem

## Assets

(no external assets)

## Content

Sign up

From Specification to Implementation

The component specification file format directly drives code generation in src/app/* and src/components/*. The cloning agents read these Markdown files and translate the structured data into React components with Tailwind CSS classes. The docs/research/INSPECTION_GUIDE.md serves as the reference manual that outlines the inspection process and validates the expected layout of these specifications.

Summary

• Component specs are Markdown files located in docs/research/components/
• The format requires specific headings: Component Name, Description, Markup, Styles, States, Interaction Model, Responsive Breakpoints, Assets, and Content
• Markup must preserve original class names for accurate regeneration
• Styles use design-token format (e.g., oklch()) rather than raw pixel values
• States nest under H3 sub-headings within the States section
• Interaction Model uses a specific prefixed string format recognized by the pipeline
• Generated code consumes these specs to produce files in src/app/ and src/components/

Frequently Asked Questions

What file extension should component specification files use?

Component specification files must use the .md extension. The AI agents scan the docs/research/components/ directory for Markdown files specifically, and the parsing logic expects standard Markdown syntax with ATX-style headings.

Can I include custom sections in the component specification?

No, the pipeline expects only the standardized sections defined in the format. While Markdown allows arbitrary content, the code generation agents look for specific heading strings like "## Interaction Model" and "## Styles". Custom sections will be ignored during the build process.

How does the Interaction Model section affect generated code?

The INTERACTION MODEL declaration dictates whether the generated component includes event handlers, state management, or animation logic. For example, "click-to-switch with opacity transition" signals the agent to implement a toggle state with CSS transitions, while "scroll-driven with IntersectionObserver" triggers observer-based lazy loading implementations.

Where are images and fonts referenced in the specification?

External assets are listed under the ## Assets section with paths relative to the public/ directory. During cloning, these files are extracted from the target website and stored in the appropriate public subdirectories, with the specification linking to these locations for the generated components to import.

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