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

> Learn how ai-website-cloner-template documents multi-state components in spec files, detailing default and state-specific styles with CSS values, interaction models, and asset paths.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: internals
- Published: 2026-06-24

---

**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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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:

```json
{
  "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:

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

```

## From Specification to Implementation

The [`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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.