Structure of Component Specification Files in AI Website Cloner

Component specification files in the AI Website Cloner Template are Markdown documents stored under docs/research/components/ that encode visual design, interactive states, and implementation details as structured data with TypeScript props and JSON CSS values.

The AI Website Cloner Template generates component specification files to capture every visual and interactive detail extracted from target websites. These files serve as the single source of truth for reconstruction agents, bridging the gap between raw CSS inspection and production-ready code. Understanding the exact structure of these specification files is essential for anyone extending the template or building custom component generators.

Component Specification File Location and Format

Every extracted UI element receives its own specification file in the docs/research/components/ directory. According to the project README, the system "writes detailed spec files (docs/research/components/) with exact computed CSS values, states, behaviors, and content"【https://github.com/JCodesMore/ai-website-cloner-template/blob/master/README.md#L92-L96】. Each file uses Markdown format for human readability while embedding JSON blocks for machine parsing.

Core Sections of a Component Specification File

Header and Metadata

The file opens with a level-one heading containing the component name followed by a bold description. This provides agents and developers with immediate context about the element's purpose.

# Component: Button

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

Props and Type Definitions

The specification includes a TypeScript-style interface defining all public props, their types, and allowed values. This section drives type-safe code generation and ensures the component API matches the extracted design.

## Props

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

### State Variations

For each interactive state—default, hover, focus, active, and disabled—the specification contains a JSON object with computed CSS values. This eliminates guesswork by providing exact pixel-perfect styles including colors, borders, shadows, and cursor properties.

```markdown

### Default

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

Hover

{
  "background": "#0284c7"
}

Disabled

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

### Responsive Breakpoints

The specification documents responsive behavior through separate CSS collections for each breakpoint defined in the design token extraction. Entries typically cover mobile, tablet, and desktop views to guarantee consistent rendering across screen sizes.

```markdown

## Responsive

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

Asset References

This section lists paths to downloaded assets required by the component, such as SVG icons stored in public/images/icons/ or background images. These paths ensure assets are correctly referenced when the component is reconstructed in the final project.

## Assets

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

Implementation Examples

A minimal JSX snippet demonstrates proper import paths and prop usage. This concrete example 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 Links

The final section maps component-specific values to global design tokens, maintaining consistency with the site's style guide. These references link to the token definitions established during the inspection phase.

```markdown

## Design Tokens

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

Consuming Specification Files in Your Build Process

You can import these Markdown specifications directly into custom builders or documentation systems. The hybrid format allows parsing the JSON blocks while rendering the Markdown for human readers.

Parsing for Component 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 in 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 Repository Files

Several files work together to support the component specification system:

• docs/research/INSPECTION_GUIDE.md – Documents how the inspection phase extracts design tokens and writes component specifications.
• docs/research/components/ (generated) – Contains the per-component specification files described above.
• src/components/ui/button.tsx – Example implementation of a UI component that gets documented by a spec file.
• src/lib/utils.ts – Provides the cn() utility function referenced in generated component code within specifications.
• 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 Markdown documents with embedded JSON.
• Each file contains seven core sections: Header, Props, States, Responsive Breakpoints, Assets, Example Usage, and Design Tokens.
• State variations are encoded as JSON objects with exact computed CSS values for default, hover, focus, active, and disabled states.
• TypeScript interfaces define component props to ensure type-safe code generation.
• Responsive breakpoints use CSS override tables to document behavior across mobile, tablet, and desktop views.
• The README.md explains the generation process, while docs/research/INSPECTION_GUIDE.md details the extraction methodology.

Frequently Asked Questions

What file format are component specification files written in?

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

Where are component specification files stored in the repository?

The files are stored under docs/research/components/ with one Markdown file per extracted UI element. This location is explicitly referenced in the README.md as the destination for detailed spec files containing exact computed CSS values.

How do state variations get documented in the specification files?

Each state (default, hover, focus, active, disabled) receives its own subsection containing a JSON object with computed CSS properties. For example, the hover state includes specific color values like "background": "#0284c7", eliminating ambiguity during reconstruction.

Can I use component specification files without the AI Website Cloner automation?

Yes. You can manually create or edit specification files following the documented structure, then import them into custom build pipelines using standard Markdown parsers. The parseSpec pattern shown in the repository demonstrates how to extract the structured JSON data from the Markdown content for use in any code generation system.

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