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

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 (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 (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. 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:

{
  "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 (lines 92-96): Defines the overall pipeline requirement that builders receive complete specifications with computed styles and interaction models.

• 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: 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 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 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 and validated against the 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 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, 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.

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