Component Specification Files in the AI Website Cloner Template: Complete Structure Guide

A component specification file is a Markdown document that stores machine-readable JSON descriptions of a UI component's props, visual states, responsive breakpoints, assets, and design tokens in the docs/research/components/ directory.

The AI Website Cloner Template generates these files during the inspection phase to create a complete, reproducible blueprint of every UI element extracted from a target website. According to the repository source code, the system "writes detailed spec files (docs/research/components/) with exact computed CSS values, states, behaviors, and content" to drive downstream code generation.

What Is a Component Specification File?

A component specification file serves as the single source of truth for a UI component's visual and interactive characteristics. Written in Markdown for human readability, these files embed JSON data blocks that automated agents parse to reconstruct pixel-perfect components. Each file contains TypeScript-style prop definitions, computed CSS values for every state (hover, focus, disabled), responsive breakpoint overrides, and links to design tokens.

Where Component Specification Files Live

The template stores generated specifications in a dedicated research directory:

• docs/research/components/ — Contains one .md file per extracted component (e.g., Button.md, Card.md)
• docs/research/INSPECTION_GUIDE.md — Documents the extraction process that generates these specs
• src/components/ui/ — Contains the actual component implementations (e.g., button.tsx) that correspond to specifications
• src/lib/utils.ts — Houses the cn() utility function referenced in generated component code

The README (lines 92-96) confirms this architecture, explaining that the system writes component specifications with exact computed values during the cloning process.

Anatomy of a Component Specification File

Each specification file follows a standardized structure combining narrative documentation with structured data.

Header and Description

The file opens with the component name and a concise description of its purpose. This gives AI agents and developers immediate context before parsing technical details.

Props and TypeScript Definitions

This section defines the component's public API using TypeScript-style type definitions. It enumerates each prop, its data type, and allowed values, enabling type-safe code generation.

type ButtonProps = {
  variant?: "default" | "outline" | "secondary" | "ghost" | "destructive" | "link";
  size?: "default" | "xs" | "sm" | "lg" | "icon";
  disabled?: boolean;
};

Visual States and Computed CSS

For each interactive state—default, hover, focus, active, and disabled—the spec contains a JSON object with exact computed CSS values. This eliminates guesswork when reconstructing styles.

{
  "background": "#0ea5e9",
  "color": "#ffffff",
  "borderRadius": "0.5rem",
  "padding": "0.5rem 1rem"
}

Responsive Breakpoints

The specification includes separate CSS collections for each breakpoint defined in the design token extraction (mobile, tablet, desktop). This ensures the component renders correctly across all screen sizes without manual media query adjustments.

Breakpoint	CSS Override
sm	{ "fontSize": "0.875rem" }
lg	{ "fontSize": "1rem", "padding": "0.75rem 1.5rem" }

Asset References

Paths to downloaded dependencies—SVG icons, images, or videos—are listed explicitly. This ensures the build process correctly references assets like public/images/icons/arrow-right.svg when assembling the final project.

Example Usage and Design Tokens

The file concludes with a minimal JSX implementation snippet and links to global design tokens (colors, spacing, typography) that the component consumes. This maintains consistency with the project's style guide.

import { Button } from "@/components/ui/button";

<Button variant="outline" size="sm">Click me</Button>

Consuming Component Specification Files

Developers and build agents interact with these specifications in two primary ways.

Parsing Specifications for Automated Builds

Custom builders can import specification files and parse the embedded JSON to generate fully typed component code:

import spec from "@/docs/research/components/Button.md";

function generateButton() {
  const { props, states, responsive, assets } = parseSpec(spec);
  // Use the parsed data to generate a fully typed component
}

Referencing Specifications for Documentation

Design and development teams can link directly to specification files as authoritative documentation:

import Link from "next/link";

export default function ButtonDoc() {
  return (
    <section>
      <h1>Button</h1>
      <p>Primary call-to-action button (see spec below).</p>
      <Link href="/docs/research/components/Button.md">View spec</Link>
    </section>
  );
}

Summary

• Component specification files are Markdown documents generated in docs/research/components/ that describe every visual and interactive aspect of a UI element.
• Each file contains TypeScript prop definitions, JSON-encoded CSS values for multiple states, responsive breakpoint overrides, and asset references.
• The specification format bridges the gap between visual inspection and code generation, enabling the AI Website Cloner Template to reproduce pixel-perfect components from target websites.
• Build agents consume these files to generate type-safe components, while developers use them as authoritative documentation and design handoff materials.

Frequently Asked Questions

What file format are component specification files written in?

Component specification files use Markdown with embedded JSON blocks. This hybrid format ensures human readability while providing machine-parseable data structures for automated build agents.

Where does the AI Website Cloner Template store these specification files?

The system writes all component specifications to the docs/research/components/ directory, with one file per extracted component. The INSPECTION_GUIDE.md file in the parent directory documents the extraction rules.

How do component specification files handle responsive design?

Each specification includes a "Responsive" section containing separate CSS value objects for each breakpoint (sm, lg, etc.). These override the base styles at specific viewport widths, ensuring the component adapts correctly to mobile, tablet, and desktop screens.

Can I manually edit a component specification file after generation?

Yes. Since the files are standard Markdown with JSON code blocks, developers can manually adjust computed CSS values, add new props, or update asset paths. Changes will be picked up by any build process that parses these specifications, though manual edits may be overwritten if the component is re-extracted from the source website.

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