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

> Discover the component specification file format for the AI website cloner. This Markdown structure defines HTML, styles, interactions, and responsive behavior for efficient web component creation.

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

---

**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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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:

```markdown

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

```markdown

## 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()`:

```markdown

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

```markdown

## 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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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】:

```markdown

## Interaction Model

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

```

### Responsive Breakpoints

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

```markdown

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

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

```

## 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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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.