Component Specification Files in the AI Website Cloner Template: Structure and Content

Component specification files are Markdown-based documents stored in docs/research/components/ that contain machine-readable JSON blocks describing every visual state, CSS value, prop interface, and asset dependency for UI elements extracted from target websites.

The AI Website Cloner Template generates these specification files during its inspection phase to create a complete, reproducible blueprint of each component it encounters. According to the repository's source code, the system "writes detailed spec files (docs/research/components/) with exact computed CSS values, states, behaviors, and content" as documented in README.md (lines 92-96).

File Location and Naming Convention

Every extracted UI element receives its own specification file within the docs/research/components/ directory. The naming follows the component's PascalCase identifier (e.g., Button.md, Card.md, Navigation.md). This structure creates a discoverable knowledge base that both human developers and automated build agents can consume during the reconstruction phase.

Anatomy of a Component Specification File

Each specification file follows a strict Markdown structure with embedded JSON blocks. This hybrid format ensures human readability while maintaining parseability for code generation tools.

Header Metadata

The file opens with an H1 containing the component name and a bold description line. This provides immediate context for anyone browsing the docs/research/components/ directory.

# Component: Button

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

Props and Type Definitions

The Props section defines a TypeScript-style interface listing all public props, their types, and allowed values. This drives type-safe code generation and validates component usage.

## Props

```ts
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 the most critical data for pixel-perfect reconstruction. For each state (default, hover, focus, active, disabled), the file stores a JSON object of computed CSS values.

```markdown

## States

### Default

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

Hover

{
  "background": "#0284c7"
}

Disabled

{
  "background": "#94a3b8",
  "color": "#cbd5e1",
  "cursor": "not-allowed"
}

These values are extracted directly from the target website's computed styles, eliminating guesswork during the rebuild process.

### Responsive Breakpoints

Components specify responsive behavior through breakpoint-specific CSS overrides. The specification tracks which values change at mobile, tablet, and desktop widths according to the design tokens extracted during inspection.

```markdown

## Responsive

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

Asset References

The Assets section lists paths to downloaded dependencies required by the component, ensuring proper linkage in the final build.

## Assets

- Icon: `public/images/icons/arrow-right.svg`

Example Usage Code

A minimal JSX snippet demonstrates proper import patterns and prop usage. This serves as the implementation target for downstream code generation agents.

## Example Usage

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

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

### Design Token Integration

The specification links component values to global design tokens (colors, spacing, typography) defined in the project's token system. This maintains consistency across the reconstructed site.

```markdown

## Design Tokens

- `--color-primary: #0ea5e9`
- `--radius-md: 0.5rem`

Parsing and Consuming Specification Files

Developers can programmatically consume these files to generate components or documentation. Below are two practical implementation patterns.

Importing for Custom Builders

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
  return compileToReactComponent({ props, states, responsive, assets });
}

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

Key Files in the Repository

File	Purpose
docs/research/INSPECTION_GUIDE.md	Documents the inspection phase methodology for extracting design tokens and writing component specs.
docs/research/components/*.md	Generated specification files containing component definitions.
src/components/ui/button.tsx	Example UI component implementation that corresponds to a generated spec.
src/lib/utils.ts	Contains the cn() utility function referenced in generated component code and specs.
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/ as individual Markdown documents named after each UI element.
• Each file contains TypeScript-style prop definitions, JSON-encoded CSS values for multiple states, responsive breakpoint overrides, and asset references.
• The hybrid Markdown/JSON format balances human readability with machine parseability for automated code generation.
• These specifications link to global design tokens to ensure visual consistency across the reconstructed website.
• The INSPECTION_GUIDE.md and README.md document the extraction process that populates these files.

Frequently Asked Questions

What format are component specification files written in?

Component specification files use Markdown with embedded JSON code blocks. The Markdown provides structure and human-readable context, while the JSON blocks contain parseable data for CSS values, props, and responsive breakpoints. This format allows developers to read specifications directly in GitHub while enabling build agents to extract structured data programmatically.

How does the AI Website Cloner Template handle component states?

The template extracts computed CSS values for every interactive state including default, hover, focus, active, and disabled. These values are stored as JSON objects within the specification file's States section. According to the source code in docs/research/INSPECTION_GUIDE.md, this ensures pixel-perfect reproduction of interactions without manual inspection of the target site.

Where are design tokens referenced in component specifications?

Design tokens appear in a dedicated section at the end of each specification file, linking component-specific values (like color hex codes or border radii) to global CSS variables. For example, a button's background color might reference --color-primary: #0ea5e9, ensuring that if the token value changes globally, the component remains consistent with the site's design system.

Can I manually edit component specification files after generation?

Yes, specification files are standard Markdown and can be edited manually. However, any manual changes should maintain the JSON structure within code blocks to ensure that build agents can still parse the props, states, and responsive data. The src/components/ui/button.tsx file demonstrates how the final component implementation should align with its corresponding specification.

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