Component Specification File Structure in the AI Website Cloner Template

The component specification file is a Markdown-based document stored in docs/research/components/ that contains machine-readable JSON blocks describing a UI element's props, visual states, responsive breakpoints, and assets, enabling AI agents to reconstruct pixel-perfect components.

The JCodesMore/ai-website-cloner-template generates a comprehensive specification file for every UI element extracted from a target website. According to the repository's README (lines 92-96), these files serve as the single source of truth for the cloning agents, capturing exact computed CSS values, behaviors, and content in a format that is both human-readable and machine-parseable.

File Location and Format

Component specification files live in the docs/research/components/ directory, with one Markdown file per extracted component. While the files use .md extensions for readability, they embed structured data as JSON blocks that build agents can parse programmatically. This hybrid approach allows developers to inspect specifications manually while enabling automated tooling to consume the data directly.

Core Sections of the Specification

Each specification file follows a standardized structure that documents every aspect of a component's implementation.

Component Header and Metadata

The file opens with a level-one heading containing the component name, followed by a bold description. This provides immediate context for both human readers and AI agents scanning the codebase.

# Component: Button

**Description:** Primary call‑to‑action button

Props and TypeScript Definitions

The Props section declares the component's public interface using TypeScript-style definitions. This includes allowed values for enumerations, optional flags, and default states, ensuring type safety during code generation.

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

Visual States and CSS Values

The States section contains JSON objects mapping each interactive state—default, hover, focus, active, and disabled—to exact computed CSS values. This eliminates guesswork when reconstructing visual behaviors.

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

Responsive Breakpoints

Specifications include separate CSS collections for each breakpoint defined in the design token extraction (mobile, tablet, desktop). This guarantees the component behaves correctly across all screen sizes without manual trial-and-error.

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

Assets and Dependencies

The Assets section lists paths to downloaded resources such as SVG icons, images, or videos. For example, a button might reference public/images/icons/arrow-right.svg, ensuring the build process correctly links all dependencies.

Implementation Examples

The Example Usage section provides minimal JSX snippets that demonstrate how to import and instantiate the component. This serves as a concrete target for downstream code generation agents.

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

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

Design Token References

Each spec links to global design tokens—such as --color-primary: #0ea5e9 or --radius-md: 0.5rem—that the component relies on. This maintains consistency with the project's global style guide and facilitates theme updates.

Practical Usage Examples

Developers can consume specification files in two primary ways.

Importing for Custom Builders

Build agents can parse the Markdown files to extract structured data for code generation:

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 for Documentation

Designers and developers can link directly to specs for implementation details:

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>
  );
}

Related Files and Architecture

Several key files support the component specification system:

• docs/research/INSPECTION_GUIDE.md – Describes the inspection phase that extracts design tokens and writes component specs.
• src/components/ui/button.tsx – Example of a UI component that gets documented by a corresponding spec file.
• src/lib/utils.ts – Contains the cn() utility used in generated component code, referenced within specifications for class merging logic.
• README.md (lines 92-96) – Provides the high-level overview of the component-spec generation process.

Summary

• Component specification files live in docs/research/components/ and contain complete, machine-readable descriptions of UI elements.
• Each file combines Markdown readability with JSON data blocks for props, states, responsive breakpoints, and assets.
• The specifications enable pixel-perfect reconstruction by capturing exact computed CSS values rather than approximations.
• Design token references ensure components remain consistent with the global style system.
• The cn() utility from src/lib/utils.ts and inspection logic from docs/research/INSPECTION_GUIDE.md form the infrastructure supporting these specifications.

Frequently Asked Questions

Where are component specification files stored?

Specification files are stored in the docs/research/components/ directory of the JCodesMore/ai-website-cloner-template repository. Each UI element gets its own Markdown file in this location, organized by component name.

What format does the component specification file use?

The files use Markdown with embedded JSON blocks. The Markdown structure provides human-readable headers and descriptions, while JSON blocks encode machine-parseable data for props, CSS values, and responsive breakpoints.

How do states get documented in the spec?

Each interactive state (default, hover, focus, active, disabled) receives its own JSON object containing exact computed CSS properties. For example, the hover state might specify {"background": "#0284c7"} to ensure precise color matching during reconstruction.

Can I use the spec files for manual component development?

Yes. While designed for AI agents, the Markdown format makes specifications valuable for human developers. The Example Usage section provides copy-pasteable JSX, and the Props section offers TypeScript definitions that you can transfer directly into your component files.

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