# What Information Is Required in a Component Spec File for AI Website Cloning?

> Learn what information component spec files need for AI website cloning. Explore the 12 essential sections for building with JCodesMore ai-website-cloner-template.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-07-07

---

**A component spec file must contain twelve mandatory sections: Component name, HTML/JSX structure, Design tokens, Variants, States, Responsive behavior, Interactions, Animations/Transitions, Assets, Content, Props schema, and Example usage.**

The `JCodesMore/ai-website-cloner-template` repository defines a rigorous specification format that serves as the single source of truth for AI builder agents recreating UI components in Next.js. These specifications eliminate ambiguity by providing exact `getComputedStyle()` values, interaction models, and asset paths that the builder needs to generate pixel-perfect replicas without making assumptions.

## Anatomy of a Component Spec File

The cloning pipeline described in [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) (lines 92-96) requires every spec to be comprehensive enough that the builder receives "the full component specification inline" with no missing context. According to [`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md) (lines 30-40), each specification must capture the following data:

### Component Name and File Structure

The **component name** must be a clear, PascalCase identifier (e.g., `PrimaryButton`, `HeaderNav`). This value determines the file name and import statements throughout the project. The `HTML/JSX structure` section provides an ordered list of the element hierarchy, including tags, class names, child components, data-attributes, and ARIA roles that define the exact DOM tree to render.

### Visual Design Tokens

**Design tokens** reference the centralized token system defined in [`docs/research/DESIGN_TOKENS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/DESIGN_TOKENS.md). Each spec must map **colors**, **typography**, **spacing**, **border-radius**, **shadows**, and **breakpoints** to their token values. This guarantees visual consistency with the original site and ensures the builder uses the correct Tailwind v4 classes through the `cn()` utility found in `src/components/ui/**`.

### Variants and States Configuration

The **Variants** section enumerates every visual variant (size, style, theme) and maps them to specific token values. For example, `variant: "secondary"` must resolve to `bg-token: colors.gray.200`.

The **States** section is exhaustive. For every variant, you must document all possible UI states: `default`, `hover`, `focus`, `active`, `disabled`, `loading`, `error`, and `empty`. Each state requires the exact CSS values computed via `getComputedStyle()` so the builder generates the correct conditional Tailwind classes and logic.

### Responsive Behavior and Interactions

**Responsive behavior** specifies breakpoint-specific overrides for layout, spacing, font size, or visibility. Include the minimum width where changes occur (e.g., `@media (min-width: 768px) { … }`) to ensure the component adapts exactly like the source site on tablet and desktop viewports.

**Interactions** document click handlers, hover effects, focus management, keyboard shortcuts, and custom event handling. Specify expected side effects such as state toggles or navigation (e.g., `onClick → toggle menu`). This guides the generation of React event handlers and accessibility attributes.

### Motion and Assets

**Animations/Transitions** record the animation name (e.g., `fade-in`, `slide-up`), duration, easing function, and trigger event (e.g., `onMount`, `onHover`). Include CSS animation properties like `transform: translateY(0)` so the builder can apply `framer-motion` or CSS transitions that mirror the original motion.

**Assets** list paths to SVG icons, images, or videos required by the component. Reference downloaded assets under `public/` (e.g., `icons/close.svg`) to guarantee the component renders the exact graphics from the source site.

### Content and Type Safety

**Content** defines literal text, placeholders, or dynamic data slots. Mark which strings are static (e.g., button label) versus injected (e.g., children) to prevent generic placeholders and ensure the final component matches the real copy.

The **Props schema** provides a TypeScript interface describing the component's public API, including props, default values, and required/optional flags. This enables strict typing (`strict` mode) and downstream reuse throughout the codebase.

### Example Usage

Every spec must include an **Example usage** section containing a short JSX snippet that demonstrates the component with several variants and states. This serves as a sanity check for the generated component and acts as living documentation.

## Component Spec File Structure in Practice

Here is a complete specification following the repository's required format:

```json
{
  "name": "PrimaryButton",
  "structure": [
    "button",
    {
      "class": "flex items-center justify-center gap-2 rounded-md",
      "children": ["Icon?", "Label"]
    }
  ],
  "designTokens": {
    "background": "colors.blue.600",
    "text": "colors.white",
    "padding": "spacing.2",
    "borderRadius": "radius.md"
  },
  "variants": {
    "size": ["sm", "md", "lg"],
    "style": ["primary", "secondary"]
  },
  "states": {
    "default": { "opacity": "1" },
    "hover": { "background": "colors.blue.700" },
    "disabled": { "background": "colors.gray.300", "cursor": "not-allowed" }
  },
  "responsive": {
    "md": { "padding": "spacing.3" },
    "lg": { "fontSize": "text-lg" }
  },
  "interactions": {
    "onClick": "navigate to href",
    "onKeyPress": "trigger click on Enter"
  },
  "animations": {
    "enter": { "type": "fade", "duration": "150ms", "easing": "ease-out" }
  },
  "assets": {
    "icon": "/public/icons/arrow-right.svg"
  },
  "content": {
    "label": "Get Started"
  },
  "props": {
    "href": "string | undefined",
    "size": "\"sm\" | \"md\" | \"lg\"",
    "disabled": "boolean"
  },
  "example": "<PrimaryButton href=\"/signup\" size=\"md\">Get Started</PrimaryButton>"
}

```

## Key Files Defining the Spec Contract

The repository contains several critical files that establish the component spec file requirements:

- **[`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md)** (lines 92-96): Defines the overall pipeline requirement that builders receive complete specifications with computed styles and interaction models.

- **[`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md)** (lines 30-40): Enumerates the exact fields that must appear in each spec file, providing the checklist for the inspection phase.

- **[`docs/research/DESIGN_TOKENS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/DESIGN_TOKENS.md)**: Establishes the token system that all specs must reference for visual properties.

- **`src/components/ui/**`**: Contains shadcn/ui component implementations that demonstrate the target code style (Tailwind v4, `cn()` utility) that specs must drive.

- **[`scripts/sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/sync-agent-rules.sh)** and **`scripts/sync-skills.mjs`**: Generate AI-agent instructions ensuring the spec format is understood by all supported agents in the pipeline.

## Summary

- A component spec file must contain twelve mandatory sections: Component name, HTML/JSX structure, Design tokens, Variants, States, Responsive behavior, Interactions, Animations/Transitions, Assets, Content, Props schema, and Example usage.

- Design tokens must reference [`docs/research/DESIGN_TOKENS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/DESIGN_TOKENS.md) to ensure visual consistency with the original site.

- States require exact CSS values computed via `getComputedStyle()` for `default`, `hover`, `focus`, `active`, `disabled`, `loading`, `error`, and `empty` conditions.

- The specification is consumed by the AI builder pipeline defined in [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) and validated against the [`INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/INSPECTION_GUIDE.md) checklist.

- All specs must provide TypeScript interfaces for props and runnable JSX examples for validation.

## Frequently Asked Questions

### What happens if a component spec file is missing the States section?

The AI builder cannot generate conditional logic for interactive elements, resulting in static components that lack hover effects, focus rings, or disabled styling. According to the [`INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/INSPECTION_GUIDE.md) requirements, missing state data forces the builder to make assumptions, which violates the pixel-perfect cloning goal of the `JCodesMore/ai-website-cloner-template` pipeline.

### How do Design tokens in a spec file connect to the actual CSS?

The **Design tokens** section references values defined in [`docs/research/DESIGN_TOKENS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/DESIGN_TOKENS.md), which maps semantic names (e.g., `colors.blue.600`) to specific Tailwind v4 classes or CSS variables. The builder uses these references to invoke the `cn()` utility function found in `src/components/ui/**`, ensuring the generated component uses the exact same visual properties as the source site.

### Why is the Props schema required if the builder could infer types from usage?

The **Props schema** enforces strict TypeScript typing (`strict` mode) and documents the component's public API explicitly. While the builder could infer types from example usage, the schema prevents type errors, ensures downstream developers understand required versus optional properties, and enables IDE autocomplete across the Next.js codebase.

### Can a component spec file reference external assets outside the public folder?

No. The **Assets** section must reference paths under `public/` (e.g., `public/icons/close.svg`). This ensures that all required graphics are bundled with the Next.js application and available at runtime. Assets outside this directory would not be served correctly in the static export or development environment.