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

> Explore the Markdown component specification file format in ai-website-cloner-template. Learn how it captures HTML structure, styles, interactions, and responsive behavior for precise website cloning. Understand the standard now.

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

---

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

```markdown
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:

```markdown

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

```markdown

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

```markdown

## 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】:

```markdown

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

```markdown

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

```markdown

# 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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) | Documents the high-level "Component Specification" pipeline step and the expected directory structure【README.md†L92-L96】 |
| [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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.