# What Information Is Included in a Component Specification File?

> Discover what a component specification file contains. Learn about visual details, DOM structure, interaction states, assets, and responsive design for pixel-perfect UI recreation.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: deep-dive
- Published: 2026-07-05

---

**A component specification file is a structured markdown document in `docs/research/components/` that captures every visual, structural, and behavioral detail of a UI component—including computed styles, DOM hierarchy, interaction states, assets, and responsive breakpoints—to enable pixel-perfect recreation by builder agents.**

In the **JCodesMore/ai-website-cloner-template** repository, the component specification file serves as the single source of truth between extraction agents and builder agents. This markdown artifact is generated automatically during **Phase 3: Component Specification & Dispatch** of the cloning pipeline. It eliminates guesswork by documenting exact CSS values, state transitions, and content requirements needed to reconstruct a UI component with complete fidelity.

## The Role of a Component Specification File in the Cloning Pipeline

The specification acts as a strict contract defined in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) (lines 1000–1070). It bridges the gap between raw website extraction and React component generation. By standardizing the documentation format across `docs/research/components/<component-name>.spec.md`, downstream agents can parse the file programmatically and apply precise Tailwind utilities or inline styles without visual regression.

## Core Sections of a Component Specification File

According to the clone-website workflow and [`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md), every specification contains eight mandatory sections that collectively describe the component blueprint.

### Overview and Metadata

The **Overview** section provides high-level context for the builder agent. It specifies the target implementation path (`src/components/<ComponentName>.tsx`), the location of reference screenshots (`docs/design-references/...`), and categorizes the **interaction model** as static, click-driven, scroll-driven, or time-driven. This metadata allows agents to prioritize visual verification and select appropriate implementation strategies.

### DOM Structure and Hierarchy

This section delivers a textual representation of the element tree. It describes parent-child relationships—such as a `<header>` containing a `<div class="logo">`, `<nav class="main-nav">`, and `<button class="menu-toggle">`—guiding the JSX layout and ensuring semantic nesting matches the original source.

### Computed Styles (Visual Fidelity)

The **Computed Styles** section records exact CSS property values returned by `getComputedStyle` for the container and every child element. Documented values include `display`, `padding`, `fontSize`, `color`, `borderRadius`, and `boxShadow`. These measurements guarantee that the generated component matches the source website pixel-for-pixel, feeding precise style values to the implementation phase.

### States and Behaviors

For interactive components, this section catalogs every state transition. It defines **triggers** (scroll position thresholds, hover selectors, click events), property values before and after activation, transition timing functions, and recommended implementation strategies such as CSS transitions, IntersectionObserver, or animation timelines. This captures dynamic UI changes like hover effects, scroll-driven transformations, and modal openings.

### Per-State Content and Text

The specification preserves **verbatim text content** extracted from the live site, including headings, paragraphs, alt text, and ARIA labels. It also documents **Per-State Content**—the specific copy variations that appear during different interaction phases (e.g., titles in an expanded accordion or placeholder strings in form inputs).

### Assets and Dependencies

An **Assets** list maps all external resources required by the component. This includes local image paths (e.g., `public/images/logo.png`) and icon references (e.g., `SearchIcon` or `MenuIcon` from [`src/components/icons.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/components/icons.tsx)), ensuring the builder agent imports the correct dependencies without missing files.

### Responsive Behavior Specifications

The final section details layout adaptations across breakpoints. It defines desktop (1440px), tablet (768px), and mobile (390px) behaviors, specifying which elements hide, stack, or reposition at each pixel threshold. This ensures the component adapts correctly across screen sizes without media query guesswork.

## File Location and Naming Convention

Generated specifications follow a strict filesystem contract. They reside in `docs/research/components/` and use the naming pattern `<component-name>.spec.md` (e.g., [`Header.spec.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/Header.spec.md)). This convention is enforced across agent configurations including [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) and [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md), creating a predictable interface for automated tooling.

## How Builder Agents Consume the Specification

Builder agents parse the markdown file to generate implementation code. They extract computed style values and map them to Tailwind utility classes or CSS-in-JS objects. They reference the DOM structure to write JSX hierarchies and implement state machines based on the documented triggers and transitions.

```typescript
import { cn } from '@/lib/utils';

// Parsed from the Computed Styles section
const headerClasses = cn(
  'flex',
  'px-6',
  'bg-white',
  'shadow-[0_2px_4px_rgba(0,0,0,0.1)]'
);

// Parsed from Text Content section
const navItems = ['Home', 'Products', 'Contact', 'Login'];

```

## Summary

- A **component specification file** is a markdown artifact stored in `docs/research/components/<component-name>.spec.md` that serves as the single source of truth for UI reconstruction.
- It contains eight sections: Overview, DOM Structure, Computed Styles, States & Behaviors, Per-State Content, Assets, Text Content, and Responsive Behavior.
- The file is generated during Phase 3 of the cloning pipeline as defined in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md).
- Builder agents use the exact CSS values, state definitions, and asset references to generate pixel-perfect React components without manual inspection of the source website.

## Frequently Asked Questions

### What file extension does a component specification use?

Component specification files use the [`.spec.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.spec.md) extension. For example, a Header component would be documented in [`docs/research/components/Header.spec.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/components/Header.spec.md) according to the repository's naming conventions.

### How are animation transitions documented in the specification?

The **States & Behaviors** section captures trigger conditions (such as scroll position ≥ 80px or hover selectors), before-and-after property values, transition timing, and suggested implementation approaches like IntersectionObserver or CSS transitions.

### Where do the style values in the specification originate?

All **Computed Styles** values are extracted directly from the live website using the browser's `getComputedStyle` API, ensuring the documented `padding`, `fontSize`, `color`, and other properties reflect the actual rendered output rather than source CSS alone.

### Can developers manually edit a generated specification?

Yes. While specifications are generated automatically during the cloning pipeline, they are human-readable markdown files. Developers can refine text content, adjust responsive breakpoints, or clarify state descriptions in `docs/research/components/<component-name>.spec.md` before builder agents process them.