How Hover States and CSS Transitions Are Documented in Component Specs

The ai-website-cloner-template captures hover interactions in *.spec.md files by declaring an Interaction Model, recording exact before/after CSS values from getComputedStyle(), and specifying transition timing functions to ensure pixel-perfect reproduction.

The JCodesMore/ai-website-cloner-template repository defines a rigorous workflow for cloning target websites into Next.js components. At the heart of this system are component specifications (*.spec.md files) that serve as the single source of truth for builder agents, explicitly documenting how hover states and CSS transitions are documented in component specs to guarantee faithful visual replication.

The Anatomy of a Component Spec

Every interactive element requires a dedicated specification file in docs/research/components/. These markdown files contain self-contained documentation that eliminates ambiguity for builder agents parsing the source code.

Interaction Model Declaration

Each spec begins with an explicit Interaction Model line that declares the trigger mechanism. According to .windsurf/workflows/clone-website.md (lines 86-89), this entry identifies whether a component is "hover-driven with opacity transition" or uses other interaction patterns. This declaration sets the context for all subsequent state documentation.

State Value Documentation

The specification captures two distinct sets of computed styles:

• Default (rest) state: The exact CSS values when the element is not hovered
• Hover state: The computed styles after hover is applied

As documented in .windsurf/workflows/clone-website.md (lines 437-440), the inspection process requires recording "before/after values" using exact getComputedStyle() output for each property. This ensures the builder agent receives precise color, shadow, and transform values rather than approximate descriptions.

Transition Specification

Under a dedicated Transitions sub-section, the spec enumerates four critical properties:

• transition-property: Which CSS properties animate
• transition-duration: Length of the animation
• transition-timing-function: Easing curve (e.g., cubic-bezier(0.4, 0, 0.2, 1))
• transition-delay: Any delay before animation starts

The Inspection Workflow

The docs/research/INSPECTION_GUIDE.md establishes the "Hover sweep" protocol. This systematic process ensures no interactive element escapes documentation.

Capturing Before/After Values

Inspectors must extract computed styles for both resting and hovered states. The guide mandates that these values come directly from browser DevTools to prevent discrepancies between design intent and actual rendered output.

Recording Timing Functions

Transition timing is not inferred but measured. The inspection checklist requires documenting the exact cubic-bezier values or keyword timings (like ease-in-out) observed in the source website's CSS.

Responsive Hover Documentation

Hover behavior often varies by viewport. As specified in .windsurf/workflows/clone-website.md (lines 456-459), the same hover and transition data must be gathered at each breakpoint—desktop, tablet, and mobile—to ensure consistent interaction patterns across screen sizes.

Example Component Spec

Below is a simplified excerpt from docs/research/components/button.spec.md illustrating the required format:

# Button Component Specification

## INTERACTION MODEL

hover-driven with background-color fade

## STATES

| Property            | Default (rest)            | Hover |
|---------------------|---------------------------|-------|
| background-color    | rgb(255, 255, 255)        | rgb(240, 240, 240) |
| color               | rgb(0, 0, 0)              | rgb(0, 0, 0) |
| box-shadow          | none                      | 0 0 4px rgba(0,0,0,0.2) |

## TRANSITIONS

- transition-property: background-color, box-shadow
- transition-duration: 150ms
- transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1)
- transition-delay: 0ms

This format provides builder agents with unambiguous instructions for reconstructing the interaction.

Summary

• Component specs (*.spec.md) serve as the single source of truth for hover behavior in the ai-website-cloner-template.
• The Interaction Model line explicitly declares the hover trigger mechanism.
• State values require exact getComputedStyle() output for both default and hover states.
• Transition details must specify property, duration, timing function, and delay.
• The docs/research/INSPECTION_GUIDE.md mandates a "Hover sweep" to capture these values at every responsive breakpoint.

Frequently Asked Questions

Where are hover states documented in the ai-website-cloner-template?

Hover states are documented inline within docs/research/components/*.spec.md files. Each component specification contains a dedicated STATES section that records the exact CSS values for both resting and hovered conditions, ensuring builder agents have self-contained documentation without external references.

What specific transition properties must be recorded?

The specification requires four properties: transition-property (which CSS properties animate), transition-duration (animation length), transition-timing-function (easing curve), and transition-delay (start delay). These are recorded under the Transitions sub-section of the component spec.

How does the inspection guide ensure accurate hover documentation?

The docs/research/INSPECTION_GUIDE.md enforces a "Hover sweep" protocol where inspectors capture before/after values using getComputedStyle() and record exact transition timing functions. This prevents approximation and guarantees the cloned component matches the source website's animation behavior.

Are hover states documented differently for mobile devices?

No, the documentation structure remains consistent across breakpoints, but values may differ. According to .windsurf/workflows/clone-website.md (lines 456-459), inspectors must gather hover state data and transition details separately for desktop, tablet, and mobile viewports to account for responsive design variations.

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