Component Specification File Format in ai-website-cloner-template: The Markdown Standard

The ai-website-cloner-template employs a Markdown-based component specification file format that resides in docs/research/components/ and uses standardized headings to capture HTML structure, computed styles, interaction models, and responsive behavior for accurate website replication.

The ai-website-cloner-template repository provides an opinionated framework for AI agents to deconstruct and recreate websites from live URLs. The component specification file format acts as the critical intermediary documentation that translation layers consume to generate framework-specific code. Each Markdown file represents a single UI element extracted from the target site, containing exhaustive details required for pixel-perfect reconstruction.

Where Component Specifications Are Stored

The template expects each component to be described in a Markdown file placed under docs/research/components/. According to the repository's README, this directory serves as the output destination for the "Component Specification" pipeline step, where raw inspection data becomes structured documentation readable by downstream agents【README.md†L92-L96】.

The path structure typically follows:

docs/research/components/
├── ButtonPrimary.md
├── HeroSection.md
├── NavigationBar.md
└── ...

Required Sections in the Specification Format

A component-spec file follows a strict, opinionated structure defined by Markdown headings. The cloning agents read these sections verbatim when generating code, making adherence to the format essential for successful website replication.

Component Name and Description

Every file must begin with a top-level heading identifying the element:

# ButtonPrimary

## Description

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

The Component Name typically reflects the original HTML tag or a descriptive identifier, while the Description provides a concise summary of the element's purpose within the interface.

Markup and Styles

The Markup section contains the exact HTML or JSX snippet that reproduces the element, including original class names for reference. The Styles section catalogs CSS property-value pairs extracted via getComputedStyle(), expressed using the project's design-token format:

## 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 and Interaction Models

Interactive components must document all visual states through nested H3 headings under States. Each state repeats the Styles block with values specific to that condition:

## States

### Hover

background-color: oklch(0.65 0.15 250);

### Active

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

The Interaction Model section specifies behavior using a standardized format. As documented in the Windsurf workflow guides, this heading must follow the pattern INTERACTION MODEL: followed by the mechanism description【.windsurf/workflows/clone-website.md†L86-L90】:

## Interaction Model

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

Assets and Responsive Breakpoints

The Responsive Breakpoints section maps CSS values to specific viewport sizes from the original site:

## Responsive Breakpoints

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

The Assets section lists relative paths to external resources stored in public/, including images, SVGs, videos, or fonts required by the component.

Complete Component Specification Example

Below is a minimal but complete specification for a primary button component, demonstrating all required sections:

# 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

Key Files Defining the Format

Several source files govern how the component specification file format is implemented and consumed:

File	Purpose
README.md	Documents the high-level "Component Specification" pipeline step and the expected directory structure【README.md†L92-L96】
.windsurf/workflows/clone-website.md	Specifies how agents must embed full specifications inline, including the mandatory "INTERACTION MODEL" syntax【.windsurf/workflows/clone-website.md†L86-L90】
docs/research/INSPECTION_GUIDE.md	Provides the reference guide outlining the inspection process and specification layout standards
src/app/* and src/components/*	Contain the generated code that consumes these spec files; the Markdown structure directly drives the resulting JSX and Tailwind class outputs

Summary

• Component specification files in ai-website-cloner-template are Markdown documents stored in docs/research/components/.
• The format requires eight standardized sections: Component Name, Description, Markup, Styles, States, Interaction Model, Responsive Breakpoints, and Assets.
• Markup sections must preserve original HTML class names, while Styles sections use design-token format (e.g., oklch() values).
• The Interaction Model heading follows a strict INTERACTION MODEL: prefix as defined in the Windsurf workflow documentation.
• Generated code in src/components/ consumes these specifications to produce framework-specific implementations.

Frequently Asked Questions

What file extension should component specification files use?

Component specification files must use the .md extension and follow Markdown syntax. The template's agents specifically parse Markdown headings to identify sections, making proper ATX-style heading syntax (# and ## ) mandatory for correct processing.

Where does the Interaction Model syntax originate?

The INTERACTION MODEL: prefix requirement is defined in .windsurf/workflows/clone-website.md, which instructs AI agents to embed the full component specification including this specific heading format【.windsurf/workflows/clone-website.md†L86-L90】. This standardization ensures consistent behavior documentation across all components.

Can I include multiple components in one specification file?

No, the format requires one component per file. Each Markdown file should represent a single UI element (such as a button or navigation bar) with its own # Component Name heading at the top of the document. This one-to-one mapping allows the cloning pipeline to process components atomically.

How are assets referenced in the specification format?

Assets are listed under the ## Assets section using relative paths pointing to the public/ directory. The specification should enumerate any images, SVGs, videos, or fonts required by the component, while the actual asset files are stored separately in the public/ folder structure.

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