How to Extend INSPECTION_GUIDE.md for New Component Types in ai-website-cloner-template

To extend INSPECTION_GUIDE.md for new component types, add the component to the Phase 2 inventory list, create a stub component file following the button.tsx pattern with structured comment headers, and update any hard-coded scanner registries in scripts/inspect.ts.

The ai-website-cloner-template repository uses INSPECTION_GUIDE.md as the central checklist that drives automated reverse-engineering runs. When cloning websites with custom UI patterns like carousels, accordions, or data tables, you must extend this guide to ensure the inspection agents recognize, categorize, and document these components correctly in the generated inventory.

Understanding the Inspection Guide Structure

docs/research/INSPECTION_GUIDE.md defines the standardized phases for visual audit and component extraction. Under Phase 2 – Component Inventory (approximately lines 41‑52), the guide enumerates the common UI building blocks that cloning agents should identify during analysis.

The guide serves as the single source of truth for the /clone-website CLI. When the inspection script runs, it parses this markdown file to determine which component scanners to execute and what documentation format to expect in the output.

Adding New Components to the Checklist

To register a new component type—such as a Carousel, Accordion, or DataTable—you must first update the master checklist:

1. Open docs/research/INSPECTION_GUIDE.md
2. Locate the "Common Components to Look For" section under Phase 2
3. Insert a new bullet following the existing noun-phrase pattern

- Navigation (top bar, sidebar, bottom bar)
- Cards / list items
- Buttons and links
- Forms and inputs
- Modals and dialogs
- Dropdowns and menus
- Tabs and segmented controls
- Avatars and user badges
- Loading skeletons
- Toast notifications
- Tooltips and popovers
- **Carousel / Slider**          <!-- New entry -->

Keep the phrasing consistent: use a noun phrase with optional parenthetical details that clarify scope or variants.

Creating Reusable Component Templates

After updating the guide, create a reference implementation that follows the repository's established patterns. The src/components/ui/button.tsx file serves as the canonical example for component structure and documentation standards.

Create a new file (e.g., src/components/ui/carousel.tsx) and include a standardized comment header that matches the checklist schema. This header enables automated parsers to extract metadata during the inspection process.

"use client"

import { cn } from "@/lib/utils"

/* ---------------------------------------------------------------
   Component: Carousel
   Structure: <div class="carousel"> → <div class="slide">…</div>
   Variants: size‑sm, size‑lg, with‑indicators, autoplay‑on/off
   States: default, hover, focused, loading, error
   Responsive: md → single slide, lg → multi‑slide
----------------------------------------------------------------- */

export interface CarouselProps {
  children: React.ReactNode
  variant?: "default" | "with-indicators"
  size?: "sm" | "lg"
  autoplay?: boolean
  className?: string
}

export function Carousel({
  children,
  variant = "default",
  size = "lg",
  autoplay = false,
  className,
}: CarouselProps) {
  return (
    <div
      className={cn(
        "carousel",
        `carousel--${variant}`,
        `carousel--${size}`,
        autoplay && "carousel--autoplay",
        className,
      )}
    >
      {children}
    </div>
  )
}

The comment block must document Structure (HTML hierarchy), Variants (modifier classes), States (interactive conditions), and Responsive (breakpoint behavior) to satisfy the inspection protocol.

Updating the Inspection Scripts

The cloning CLI reads INSPECTION_GUIDE.md to determine which component scanners to instantiate. If your installation uses a static scanner registry, locate the hard-coded component lists in scripts/inspect.ts (or similar) and extend the registry.

// scripts/inspect.ts – scanner registry
import { scanButton } from "./scanners/button"
import { scanCarousel } from "./scanners/carousel"   // New import

export const componentScanners = {
  button: scanButton,
  carousel: scanCarousel,   // Registration
  // Additional scanners...
}

If the scanner discovers components dynamically by parsing the guide's markdown, no code changes are required—the system will automatically pick up the new bullet point during the next inspection run.

Documenting Expected Output Format

When the inspection completes, the agent generates docs/research/COMPONENT_INVENTORY.md with standardized entries for each discovered component. Ensure your new component follows the expected documentation pattern by adding a reference entry that illustrates the output format:

## Carousel / Slider

- **Structure**: `<div class="carousel">` → `<div class="slide">…</div>`
- **Variants**  
  - `default` – plain carousel  
  - `with-indicators` – shows navigation dots
- **Sizes**: `sm`, `lg`
- **States**: default, hover, loading, error
- **Responsive**: single‑slide at `md`, multi‑slide at `lg`
- **Interactions**: swipe, click arrows, autoplay toggle

This template ensures that future contributors understand how the new component type will appear in generated documentation.

Step-by-Step Verification Workflow

Follow this sequence to validate your changes:

1. Open docs/research/INSPECTION_GUIDE.md and insert the new component bullet under Phase 2
2. Create the component stub file (e.g., src/components/ui/carousel.tsx) with the standardized comment header
3. If using static scanner registries, update scripts/inspect.ts to import and register the new scanner
4. Run the inspection script (npm run inspect or equivalent) to verify the guide parses without errors
5. Check that docs/research/COMPONENT_INVENTORY.md contains a properly formatted section for the new component
6. Commit both the updated guide and the new component template files

Summary

• Update the master checklist in docs/research/INSPECTION_GUIDE.md by adding new bullets under Phase 2 – Component Inventory
• Reference existing patterns in src/components/ui/button.tsx when creating new component stubs with structured comment headers
• Extend scanner registries in scripts/inspect.ts if your CLI uses static component mappings rather than dynamic discovery
• Document output expectations by adding example entries to COMPONENT_INVENTORY.md to maintain consistent formatting
• Verify changes by running the inspection pipeline and confirming the new component type appears in generated documentation

Frequently Asked Questions

What file defines the component structure standards?

The src/components/ui/button.tsx file defines the canonical pattern for component implementation and documentation. It demonstrates the required comment header format (Component, Structure, Variants, States, Responsive) and the TypeScript interface structure that inspection scanners expect.

Do I need to modify the scanner code for every new component?

It depends on the scanner architecture. If scripts/inspect.ts contains a static registry of component scanners, you must add an import and registry entry for the new component type. If the system parses INSPECTION_GUIDE.md dynamically to discover components, no code changes are necessary—simply adding the bullet to the markdown file suffices.

Where does the inspection output get saved?

The inspection agent writes component discovery results to docs/research/COMPONENT_INVENTORY.md. This file captures the structure, variants, states, and responsive behavior of all identified components based on the criteria defined in INSPECTION_GUIDE.md.

What format should component documentation comments follow?

Documentation comments must be block comments (/* ... */) placed immediately before the component interface or implementation. They must include five specific labels: Component (name), Structure (HTML hierarchy), Variants (modifier classes), States (interactive conditions), and Responsive (breakpoint behavior). This format allows automated parsers to extract structured data during the reverse-engineering process.

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