How Multi-State Components Are Documented in ai-website-cloner-template Spec Files

The ai-website-cloner-template captures multi-state components in JSON specification files under docs/research/components/, recording default styles alongside state-specific variations (hover, active, scrolled) with computed CSS values, interaction models, and asset paths.

The JCodesMore/ai-website-cloner-template treats every UI element as a contractual specification rather than a static snapshot. When components possess multiple visual states—such as hover effects, active tabs, or scroll-triggered animations—the template documents every variant side-by-side in structured spec files, ensuring builder agents receive complete visual contracts without inference.

Specification File Structure for Multi-State Components

When a component has more than one visual state, the specification file stores both states side-by-side so that builder agents receive a complete contract. The format contains six core sections:

• element — Contains the HTML selector or semantic description (e.g., "selector": ".nav-link").

• defaultStyle — Stores exact getComputedStyle() values for the element in its normal state, including colors, typography, and spacing.

• states — An array of objects describing named states (hover, active, scrolled), each capturing computed CSS values and any changed content such as text or SVG.

• breakpoints — Responsive breakpoints (sm, md, lg) with corresponding style snapshots for each size variant.

• assets — Paths to images, icons, or fonts that differ between states (e.g., a default icon versus a hover-state icon).

• interactionModel — Description of the user interaction triggering the state (e.g., :hover, click, scroll-into-view).

Source Code References for Multi-State Extraction

According to the repository source code, the extraction workflow explicitly mandates capturing every state variant. The README.md (lines 96-98) states that builder agents receive "the full component specification inline — exact getComputedStyle() values, interaction models, multi-state content, responsive breakpoints, and asset paths."

The .windsurf/workflows/clone-website.md (lines 282-286) provides the concrete instruction: "Extract multi-state styles – for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states." This ensures the spec file serves as the single source of truth for all visual variants, and builders never have to infer missing states.

Practical Examples of Multi-State Specifications

Navigation Link with Hover State

Below is a minimal example of a generated spec file for a navigation link that changes color on hover:

{
  "selector": ".nav-link",
  "defaultStyle": {
    "color": "#111111",
    "backgroundColor": "transparent",
    "fontWeight": "400"
  },
  "states": [
    {
      "name": "hover",
      "style": {
        "color": "#0055ff",
        "backgroundColor": "rgba(0,85,255,0.1)",
        "fontWeight": "600"
      },
      "interactionModel": "hover"
    }
  ],
  "breakpoints": {
    "md": {
      "fontSize": "1rem"
    },
    "lg": {
      "fontSize": "1.125rem"
    }
  },
  "assets": {
    "default": "icons/link.svg",
    "hover": "icons/link-hover.svg"
  }
}

Scroll-Triggered Animation State

A component with scroll-triggered animation would contain an additional entry in the states array:

{
  "name": "scrolled",
  "style": { 
    "opacity": "1", 
    "transform": "translateY(0)" 
  },
  "interactionModel": "scroll-into-view"
}

From Specification to Implementation

The docs/research/INSPECTION_GUIDE.md outlines the high-level process for extracting these component specifications, including the handling of multi-state elements. Once extracted, the raw style data requires conversion into utility classes.

The src/lib/utils.ts file contains helper utilities such as cn() that assist in transforming the captured getComputedStyle() values from the specification files into Tailwind class strings for the generated code. This bridges the gap between the documented multi-state specifications and the final implemented components.

Summary

• Multi-state components in ai-website-cloner-template are documented in JSON spec files under docs/research/components/
• Each spec file contains element, defaultStyle, states, breakpoints, assets, and interactionModel sections
• The extraction workflow in .windsurf/workflows/clone-website.md (lines 282-286) mandates capturing BOTH the default and alternate states for complete fidelity
• State variations include computed CSS values, content changes, and asset paths for interactions including hover, active tabs, and scroll-triggered animations
• Helper utilities in src/lib/utils.ts (such as cn()) convert captured specifications into Tailwind classes for code generation

Frequently Asked Questions

What file format does ai-website-cloner-template use for component specifications?

The template uses JSON specification files stored in docs/research/components/. These files capture structured data including selectors, computed styles for multiple states, responsive breakpoints, and asset paths, creating a complete contract that builder agents can execute without ambiguity.

How does the template handle responsive variants of multi-state components?

Responsive behavior is documented in the breakpoints section of each spec file. For each breakpoint (sm, md, lg), the specification records style snapshots that work in combination with state definitions, allowing builder agents to replicate complex responsive hover states or mobile-specific active states.

Where is the extraction logic for multi-state components defined?

The extraction instructions reside in .windsurf/workflows/clone-website.md at lines 282-286, which explicitly instructs agents to "Extract multi-state styles" and capture "BOTH" states for elements with multiple visual conditions. Supporting process documentation is located in docs/research/INSPECTION_GUIDE.md.

How are specification values converted into actual code?

After extraction, specification values are processed using helper utilities. The src/lib/utils.ts file contains the cn() function, which assists in converting raw getComputedStyle() values from the spec files into Tailwind CSS class strings during the code generation phase.

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