chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,3 @@
|
||||
read:
|
||||
- AGENTS.md
|
||||
- docs/research/INSPECTION_GUIDE.md
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,147 @@
|
||||
<!-- AUTO-GENERATED from AGENTS.md — do not edit directly.
|
||||
Run `bash scripts/sync-agent-rules.sh` to regenerate. -->
|
||||
|
||||
<!-- BEGIN:nextjs-agent-rules -->
|
||||
# This is NOT the Next.js you know
|
||||
|
||||
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
|
||||
<!-- END:nextjs-agent-rules -->
|
||||
|
||||
# Website Reverse-Engineer Template
|
||||
|
||||
## What This Is
|
||||
A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — just run `/clone-website <url1> [<url2> ...]`.
|
||||
|
||||
## Tech Stack
|
||||
- **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
|
||||
- **UI:** shadcn/ui (Radix primitives, Tailwind CSS v4, `cn()` utility)
|
||||
- **Icons:** Lucide React (default — will be replaced/supplemented by extracted SVGs)
|
||||
- **Styling:** Tailwind CSS v4 with oklch design tokens
|
||||
- **Deployment:** Vercel
|
||||
|
||||
## Commands
|
||||
- `npm run dev` — Start dev server
|
||||
- `npm run build` — Production build
|
||||
- `npm run lint` — ESLint check
|
||||
- `npm run typecheck` — TypeScript check
|
||||
- `npm run check` — Run lint + typecheck + build
|
||||
|
||||
## Code Style
|
||||
- TypeScript strict mode, no `any`
|
||||
- Named exports, PascalCase components, camelCase utils
|
||||
- Tailwind utility classes, no inline styles
|
||||
- 2-space indentation
|
||||
- Responsive: mobile-first
|
||||
|
||||
## Design Principles
|
||||
- **Pixel-perfect emulation** — match the target's spacing, colors, typography exactly
|
||||
- **No personal aesthetic changes during emulation phase** — match 1:1 first, customize later
|
||||
- **Real content** — use actual text and assets from the target site, not placeholders
|
||||
- **Beauty-first** — every pixel matters
|
||||
|
||||
## Project Structure
|
||||
```
|
||||
src/
|
||||
app/ # Next.js routes
|
||||
components/ # React components
|
||||
ui/ # shadcn/ui primitives
|
||||
icons.tsx # Extracted SVG icons as React components
|
||||
lib/
|
||||
utils.ts # cn() utility (shadcn)
|
||||
types/ # TypeScript interfaces
|
||||
hooks/ # Custom React hooks
|
||||
public/
|
||||
images/ # Downloaded images from target site
|
||||
videos/ # Downloaded videos from target site
|
||||
seo/ # Favicons, OG images, webmanifest
|
||||
docs/
|
||||
research/ # Inspection output (design tokens, components, layout)
|
||||
design-references/ # Screenshots and visual references
|
||||
scripts/ # Asset download scripts
|
||||
```
|
||||
|
||||
## MOST IMPORTANT NOTES
|
||||
- When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
|
||||
- After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
|
||||
- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
|
||||
|
||||
# Website Inspection Guide
|
||||
|
||||
## How to Reverse-Engineer Any Website
|
||||
|
||||
This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
|
||||
|
||||
## Phase 1: Visual Audit
|
||||
|
||||
### Screenshots to Capture
|
||||
- [ ] Every distinct page — desktop, tablet, mobile
|
||||
- [ ] Dark mode variants (if applicable)
|
||||
- [ ] Light mode variants (if applicable)
|
||||
- [ ] Key interaction states (hover, active, open menus, modals)
|
||||
- [ ] Loading/skeleton states
|
||||
- [ ] Empty states
|
||||
- [ ] Error states
|
||||
|
||||
### Design Tokens to Extract
|
||||
- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
|
||||
- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
|
||||
- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
|
||||
- [ ] **Border radius** — buttons, cards, avatars, inputs
|
||||
- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
|
||||
- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
|
||||
- [ ] **Icons** — which icon library? custom SVGs? sizes?
|
||||
- [ ] **Avatars** — sizes, shapes, fallback behavior
|
||||
- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
|
||||
- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
|
||||
|
||||
## Phase 2: Component Inventory
|
||||
|
||||
For each distinct UI component, document:
|
||||
1. **Name** — what would you call this component?
|
||||
2. **Structure** — what HTML elements / child components does it contain?
|
||||
3. **Variants** — does it have different sizes, colors, or states?
|
||||
4. **States** — default, hover, active, disabled, loading, error, empty
|
||||
5. **Responsive behavior** — how does it change at different breakpoints?
|
||||
6. **Interactions** — click, hover, focus, keyboard navigation
|
||||
7. **Animations** — transitions, entrance/exit animations, micro-interactions
|
||||
|
||||
### Common Components to Look For
|
||||
- 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
|
||||
|
||||
## Phase 3: Layout Architecture
|
||||
|
||||
- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
|
||||
- [ ] **Column layout** — how many columns at each breakpoint?
|
||||
- [ ] **Max-width** — main content area max-width
|
||||
- [ ] **Sticky elements** — header, sidebar, floating buttons
|
||||
- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
|
||||
- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
|
||||
|
||||
## Phase 4: Technical Stack Analysis
|
||||
|
||||
- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
|
||||
- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
|
||||
- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
|
||||
- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
|
||||
- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
|
||||
- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF
|
||||
- [ ] **Animation library** — Framer Motion, GSAP, CSS transitions only
|
||||
|
||||
## Phase 5: Documentation Output
|
||||
|
||||
After inspection, create these files in `docs/research/`:
|
||||
1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
|
||||
2. `COMPONENT_INVENTORY.md` — Every component with structure notes
|
||||
3. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
|
||||
4. `INTERACTION_PATTERNS.md` — Animations, transitions, hover states
|
||||
5. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents
|
||||
@@ -0,0 +1,474 @@
|
||||
---
|
||||
description: "Reverse-engineer and clone any website as a pixel-perfect replica"
|
||||
argument-hint: "<url>"
|
||||
---
|
||||
<!-- AUTO-GENERATED from .claude/skills/clone-website/SKILL.md — do not edit directly.
|
||||
Run `node scripts/sync-skills.mjs` to regenerate. -->
|
||||
|
||||
|
||||
# Clone Website
|
||||
|
||||
You are about to reverse-engineer and rebuild **$ARGUMENTS** as pixel-perfect clones.
|
||||
|
||||
When multiple URLs are provided, process them independently and in parallel where possible, while keeping each site's extraction artifacts isolated in dedicated folders (for example, `docs/research/<hostname>/`).
|
||||
|
||||
This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
|
||||
|
||||
## Scope Defaults
|
||||
|
||||
The target is whatever page `$ARGUMENTS` resolves to. Clone exactly what's visible at that URL. Unless the user specifies otherwise, use these defaults:
|
||||
|
||||
- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, animations
|
||||
- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
|
||||
- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
|
||||
- **Customization:** None — pure emulation
|
||||
|
||||
If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
|
||||
|
||||
## Pre-Flight
|
||||
|
||||
1. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
|
||||
2. Parse `$ARGUMENTS` as one or more URLs. Normalize and validate each URL; if any are invalid, ask the user to correct them before proceeding. For each valid URL, verify it is accessible via your browser MCP tool.
|
||||
3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
|
||||
4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
|
||||
5. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
|
||||
|
||||
### 1. Completeness Beats Speed
|
||||
|
||||
Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
|
||||
|
||||
### 2. Small Tasks, Perfect Results
|
||||
|
||||
When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
|
||||
|
||||
Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
|
||||
|
||||
**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
|
||||
|
||||
### 3. Real Content, Real Assets
|
||||
|
||||
Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
|
||||
|
||||
**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays. Missing an overlay image makes the clone look empty even if the background is correct.
|
||||
|
||||
### 4. Foundation First
|
||||
|
||||
Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
|
||||
|
||||
### 5. Extract How It Looks AND How It Behaves
|
||||
|
||||
A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
|
||||
|
||||
For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens). Not "it looks like 16px" — extract the actual computed value. Not "the nav changes on scroll" — document the exact trigger (scroll position, IntersectionObserver threshold, viewport intersection), the before and after states (both sets of CSS values), and the transition (duration, easing, CSS transition vs. JS-driven vs. CSS `animation-timeline`).
|
||||
|
||||
Examples of behaviors to watch for — these are illustrative, not exhaustive. The page may do things not on this list, and you must catch those too:
|
||||
- A navbar that shrinks, changes background, or gains a shadow after scrolling past a threshold
|
||||
- Elements that animate into view when they enter the viewport (fade-up, slide-in, stagger delays)
|
||||
- Sections that snap into place on scroll (`scroll-snap-type`)
|
||||
- Parallax layers that move at different rates than the scroll
|
||||
- Hover states that animate (not just change — the transition duration and easing matter)
|
||||
- Dropdowns, modals, accordions with enter/exit animations
|
||||
- Scroll-driven progress indicators or opacity transitions
|
||||
- Auto-playing carousels or cycling content
|
||||
- Dark-to-light (or any theme) transitions between page sections
|
||||
- **Tabbed/pill content that cycles** — buttons that switch visible card sets with transitions
|
||||
- **Scroll-driven tab/accordion switching** — sidebars where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
|
||||
- **Smooth scroll libraries** (Lenis, Locomotive Scroll) — check for `.lenis` class or scroll container wrappers
|
||||
|
||||
### 6. Identify the Interaction Model Before Building
|
||||
|
||||
This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa. Before writing any builder prompt for an interactive section, you must definitively answer: **Is this section driven by clicks, scrolls, hovers, time, or some combination?**
|
||||
|
||||
How to determine this:
|
||||
1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
|
||||
2. If they do, it's scroll-driven. Extract the mechanism: `IntersectionObserver`, `scroll-snap`, `position: sticky`, `animation-timeline`, or JS scroll listeners.
|
||||
3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
|
||||
4. Document the interaction model explicitly in the component spec: "INTERACTION MODEL: scroll-driven with IntersectionObserver" or "INTERACTION MODEL: click-to-switch with opacity transition."
|
||||
|
||||
A section with a sticky sidebar and scrolling content panels is fundamentally different from a tabbed interface where clicking switches content. Getting this wrong means a complete rewrite, not a CSS tweak.
|
||||
|
||||
### 7. Extract Every State, Not Just the Default
|
||||
|
||||
Many components have multiple visual states — a tab bar shows different cards per tab, a header looks different at scroll position 0 vs 100, a card has hover effects. You must extract ALL states, not just whatever is visible on page load.
|
||||
|
||||
For tabbed/stateful content:
|
||||
- Click each tab/button via browser MCP
|
||||
- Extract the content, images, and card data for EACH state
|
||||
- Record which content belongs to which state
|
||||
- Note the transition animation between states (opacity, slide, fade, etc.)
|
||||
|
||||
For scroll-dependent elements:
|
||||
- Capture computed styles at scroll position 0 (initial state)
|
||||
- Scroll past the trigger threshold and capture computed styles again (scrolled state)
|
||||
- Diff the two to identify exactly which CSS properties change
|
||||
- Record the transition CSS (duration, easing, properties)
|
||||
- Record the exact trigger threshold (scroll position in px, or viewport intersection ratio)
|
||||
|
||||
### 8. Spec Files Are the Source of Truth
|
||||
|
||||
Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. This file is the contract between your extraction work and the builder agent. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact that the user (or you) can review if something looks wrong.
|
||||
|
||||
The spec file is not optional. It is not a nice-to-have. If you dispatch a builder without first writing a spec file, you are shipping incomplete instructions based on whatever you can remember from a browser MCP session, and the builder will guess to fill gaps.
|
||||
|
||||
### 9. Build Must Always Compile
|
||||
|
||||
Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
|
||||
|
||||
## Phase 1: Reconnaissance
|
||||
|
||||
Navigate to the target URL with browser MCP.
|
||||
|
||||
### Screenshots
|
||||
- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
|
||||
- Save to `docs/design-references/` with descriptive names
|
||||
- These are your master reference — builders will receive section-specific crops/screenshots later
|
||||
|
||||
### Global Extraction
|
||||
Extract these from the page before doing anything else:
|
||||
|
||||
**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements (headings, body, code, labels). Document every family, weight, and style actually used. Configure them in `src/app/layout.tsx` using `next/font/google` or `next/font/local`.
|
||||
|
||||
**Colors** — Extract the site's color palette from computed styles across the page. Update `src/app/globals.css` with the target's actual colors in the `:root` and `.dark` CSS variable blocks. Map them to shadcn's token names (background, foreground, primary, muted, etc.) where they fit. Add custom properties for colors that don't map to shadcn tokens.
|
||||
|
||||
**Favicons & Meta** — Download favicons, apple-touch-icons, OG images, webmanifest to `public/seo/`. Update `layout.tsx` metadata.
|
||||
|
||||
**Global UI patterns** — Identify any site-wide CSS or JS: custom scrollbar hiding, scroll-snap on the page container, global keyframe animations, backdrop filters, gradients used as overlays, **smooth scroll libraries** (Lenis, Locomotive Scroll — check for `.lenis`, `.locomotive-scroll`, or custom scroll container classes). Add these to `globals.css` and note any libraries that need to be installed.
|
||||
|
||||
### Mandatory Interaction Sweep
|
||||
|
||||
This is a dedicated pass AFTER screenshots and BEFORE anything else. Its purpose is to discover every behavior on the page — many of which are invisible in a static screenshot.
|
||||
|
||||
**Scroll sweep:** Scroll the page slowly from top to bottom via browser MCP. At each section, pause and observe:
|
||||
- Does the header change appearance? Record the scroll position where it triggers.
|
||||
- Do elements animate into view? Record which ones and the animation type.
|
||||
- Does a sidebar or tab indicator auto-switch as you scroll? Record the mechanism.
|
||||
- Are there scroll-snap points? Record which containers.
|
||||
- Is there a smooth scroll library active? Check for non-native scroll behavior.
|
||||
|
||||
**Click sweep:** Click every element that looks interactive:
|
||||
- Every button, tab, pill, link, card
|
||||
- Record what happens: does content change? Does a modal open? Does a dropdown appear?
|
||||
- For tabs/pills: click EACH ONE and record the content that appears for each state
|
||||
|
||||
**Hover sweep:** Hover over every element that might have hover states:
|
||||
- Buttons, cards, links, images, nav items
|
||||
- Record what changes: color, scale, shadow, underline, opacity
|
||||
|
||||
**Responsive sweep:** Test at 3 viewport widths via browser MCP:
|
||||
- Desktop: 1440px
|
||||
- Tablet: 768px
|
||||
- Mobile: 390px
|
||||
- At each width, note which sections change layout (column → stack, sidebar disappears, etc.) and at approximately which breakpoint the change occurs.
|
||||
|
||||
Save all findings to `docs/research/BEHAVIORS.md`. This is your behavior bible — reference it when writing every component spec.
|
||||
|
||||
### Page Topology
|
||||
Map out every distinct section of the page from top to bottom. Give each a working name. Document:
|
||||
- Their visual order
|
||||
- Which are fixed/sticky overlays vs. flow content
|
||||
- The overall page layout (scroll container, column structure, z-index layers)
|
||||
- Dependencies between sections (e.g., a floating nav that overlays everything)
|
||||
- **The interaction model** of each section (static, click-driven, scroll-driven, time-driven)
|
||||
|
||||
Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly blueprint.
|
||||
|
||||
## Phase 2: Foundation Build
|
||||
|
||||
This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
|
||||
|
||||
1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
|
||||
2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
|
||||
3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
|
||||
4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
|
||||
5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
|
||||
6. Verify: `npm run build` passes
|
||||
|
||||
### Asset Discovery Script Pattern
|
||||
|
||||
Use browser MCP to enumerate all assets on the page:
|
||||
|
||||
```javascript
|
||||
// Run this via browser MCP to discover all assets
|
||||
JSON.stringify({
|
||||
images: [...document.querySelectorAll('img')].map(img => ({
|
||||
src: img.src || img.currentSrc,
|
||||
alt: img.alt,
|
||||
width: img.naturalWidth,
|
||||
height: img.naturalHeight,
|
||||
// Include parent info to detect layered compositions
|
||||
parentClasses: img.parentElement?.className,
|
||||
siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
|
||||
position: getComputedStyle(img).position,
|
||||
zIndex: getComputedStyle(img).zIndex
|
||||
})),
|
||||
videos: [...document.querySelectorAll('video')].map(v => ({
|
||||
src: v.src || v.querySelector('source')?.src,
|
||||
poster: v.poster,
|
||||
autoplay: v.autoplay,
|
||||
loop: v.loop,
|
||||
muted: v.muted
|
||||
})),
|
||||
backgroundImages: [...document.querySelectorAll('*')].filter(el => {
|
||||
const bg = getComputedStyle(el).backgroundImage;
|
||||
return bg && bg !== 'none';
|
||||
}).map(el => ({
|
||||
url: getComputedStyle(el).backgroundImage,
|
||||
element: el.tagName + '.' + el.className?.split(' ')[0]
|
||||
})),
|
||||
svgCount: document.querySelectorAll('svg').length,
|
||||
fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
|
||||
favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
|
||||
});
|
||||
```
|
||||
|
||||
Then write a download script that fetches everything to `public/`. Use batched parallel downloads (4 at a time) with proper error handling.
|
||||
|
||||
## Phase 3: Component Specification & Dispatch
|
||||
|
||||
This is the core loop. For each section in your page topology (top to bottom), you do THREE things: **extract**, **write the spec file**, then **dispatch builders**.
|
||||
|
||||
### Step 1: Extract
|
||||
|
||||
For each section, use browser MCP to extract everything:
|
||||
|
||||
1. **Screenshot** the section in isolation (scroll to it, screenshot the viewport). Save to `docs/design-references/`.
|
||||
|
||||
2. **Extract CSS** for every element in the section. Use the extraction script below — don't hand-measure individual properties. Run it once per component container and capture the full output:
|
||||
|
||||
```javascript
|
||||
// Per-component extraction — run via browser MCP
|
||||
// Replace SELECTOR with the actual CSS selector for the component
|
||||
(function(selector) {
|
||||
const el = document.querySelector(selector);
|
||||
if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
|
||||
const props = [
|
||||
'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
|
||||
'textTransform','textDecoration','backgroundColor','background',
|
||||
'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
|
||||
'margin','marginTop','marginRight','marginBottom','marginLeft',
|
||||
'width','height','maxWidth','minWidth','maxHeight','minHeight',
|
||||
'display','flexDirection','justifyContent','alignItems','gap',
|
||||
'gridTemplateColumns','gridTemplateRows',
|
||||
'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
|
||||
'boxShadow','overflow','overflowX','overflowY',
|
||||
'position','top','right','bottom','left','zIndex',
|
||||
'opacity','transform','transition','cursor',
|
||||
'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
|
||||
'whiteSpace','textOverflow','WebkitLineClamp'
|
||||
];
|
||||
function extractStyles(element) {
|
||||
const cs = getComputedStyle(element);
|
||||
const styles = {};
|
||||
props.forEach(p => { const v = cs[p]; if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v; });
|
||||
return styles;
|
||||
}
|
||||
function walk(element, depth) {
|
||||
if (depth > 4) return null;
|
||||
const children = [...element.children];
|
||||
return {
|
||||
tag: element.tagName.toLowerCase(),
|
||||
classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
|
||||
text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
|
||||
styles: extractStyles(element),
|
||||
images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
|
||||
childCount: children.length,
|
||||
children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
|
||||
};
|
||||
}
|
||||
return JSON.stringify(walk(el, 0), null, 2);
|
||||
})('SELECTOR');
|
||||
```
|
||||
|
||||
3. **Extract multi-state styles** — for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states:
|
||||
|
||||
```javascript
|
||||
// State A: capture styles at current state (e.g., scroll position 0)
|
||||
// Then trigger the state change (scroll, click, hover via browser MCP)
|
||||
// State B: re-run the extraction script on the same element
|
||||
// The diff between A and B IS the behavior specification
|
||||
```
|
||||
|
||||
Record the diff explicitly: "Property X changes from VALUE_A to VALUE_B, triggered by TRIGGER, with transition: TRANSITION_CSS."
|
||||
|
||||
4. **Extract real content** — all text, alt attributes, aria labels, placeholder text. Use `element.textContent` for each text node. For tabbed/stateful content, **click each tab and extract content per state**.
|
||||
|
||||
5. **Identify assets** this section uses — which downloaded images/videos from `public/`, which icon components from `icons.tsx`. Check for **layered images** (multiple `<img>` or background-images stacked in the same container).
|
||||
|
||||
6. **Assess complexity** — how many distinct sub-components does this section contain? A distinct sub-component is an element with its own unique styling, structure, and behavior (e.g., a card, a nav item, a search panel).
|
||||
|
||||
### Step 2: Write the Component Spec File
|
||||
|
||||
For each section (or sub-component, if you're breaking it up), create a spec file in `docs/research/components/`. This is NOT optional — every builder must have a corresponding spec file.
|
||||
|
||||
**File path:** `docs/research/components/<component-name>.spec.md`
|
||||
|
||||
**Template:**
|
||||
|
||||
```markdown
|
||||
# <ComponentName> Specification
|
||||
|
||||
## Overview
|
||||
- **Target file:** `src/components/<ComponentName>.tsx`
|
||||
- **Screenshot:** `docs/design-references/<screenshot-name>.png`
|
||||
- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
|
||||
|
||||
## DOM Structure
|
||||
<Describe the element hierarchy — what contains what>
|
||||
|
||||
## Computed Styles (exact values from getComputedStyle)
|
||||
|
||||
### Container
|
||||
- display: ...
|
||||
- padding: ...
|
||||
- maxWidth: ...
|
||||
- (every relevant property with exact values)
|
||||
|
||||
### <Child element 1>
|
||||
- fontSize: ...
|
||||
- color: ...
|
||||
- (every relevant property)
|
||||
|
||||
### <Child element N>
|
||||
...
|
||||
|
||||
## States & Behaviors
|
||||
|
||||
### <Behavior name, e.g., "Scroll-triggered floating mode">
|
||||
- **Trigger:** <exact mechanism — scroll position 50px, IntersectionObserver rootMargin "-30% 0px", click on .tab-button, hover>
|
||||
- **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
|
||||
- **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
|
||||
- **Transition:** transition: all 0.3s ease
|
||||
- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
|
||||
|
||||
### Hover states
|
||||
- **<Element>:** <property>: <before> → <after>, transition: <value>
|
||||
|
||||
## Per-State Content (if applicable)
|
||||
|
||||
### State: "Featured"
|
||||
- Title: "..."
|
||||
- Subtitle: "..."
|
||||
- Cards: [{ title, description, image, link }, ...]
|
||||
|
||||
### State: "Productivity"
|
||||
- Title: "..."
|
||||
- Cards: [...]
|
||||
|
||||
## Assets
|
||||
- Background image: `public/images/<file>.webp`
|
||||
- Overlay image: `public/images/<file>.png`
|
||||
- Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
|
||||
|
||||
## Text Content (verbatim)
|
||||
<All text content, copy-pasted from the live site>
|
||||
|
||||
## Responsive Behavior
|
||||
- **Desktop (1440px):** <layout description>
|
||||
- **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
|
||||
- **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
|
||||
- **Breakpoint:** layout switches at ~<N>px
|
||||
```
|
||||
|
||||
Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
|
||||
|
||||
### Step 3: Dispatch Builders
|
||||
|
||||
Based on complexity, dispatch builder agent(s) in worktree(s):
|
||||
|
||||
**Simple section** (1-2 sub-components): One builder agent gets the entire section.
|
||||
|
||||
**Complex section** (3+ distinct sub-components): Break it up. One agent per sub-component, plus one agent for the section wrapper that imports them. Sub-component builders go first since the wrapper depends on them.
|
||||
|
||||
**What every builder agent receives:**
|
||||
- The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
|
||||
- Path to the section screenshot in `docs/design-references/`
|
||||
- Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
|
||||
- The target file path (e.g., `src/components/HeroSection.tsx`)
|
||||
- Instruction to verify with `npx tsc --noEmit` before finishing
|
||||
- For responsive behavior: the specific breakpoint values and what changes
|
||||
|
||||
**Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
|
||||
|
||||
### Step 4: Merge
|
||||
|
||||
As builder agents complete their work:
|
||||
- Merge their worktree branches into main
|
||||
- You have full context on what each agent built, so resolve any conflicts intelligently
|
||||
- After each merge, verify the build still passes: `npm run build`
|
||||
- If a merge introduces type errors, fix them immediately
|
||||
|
||||
The extract → spec → dispatch → merge cycle continues until all sections are built.
|
||||
|
||||
## Phase 4: Page Assembly
|
||||
|
||||
After all sections are built and merged, wire everything together in `src/app/page.tsx`:
|
||||
|
||||
- Import all section components
|
||||
- Implement the page-level layout from your topology doc (scroll containers, column structures, sticky positioning, z-index layering)
|
||||
- Connect real content to component props
|
||||
- Implement page-level behaviors: scroll snap, scroll-driven animations, dark-to-light transitions, intersection observers, smooth scroll (Lenis etc.)
|
||||
- Verify: `npm run build` passes clean
|
||||
|
||||
## Phase 5: Visual QA Diff
|
||||
|
||||
After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
|
||||
|
||||
1. Open the original site and your clone side-by-side (or take screenshots at the same viewport widths)
|
||||
2. Compare section by section, top to bottom, at desktop (1440px)
|
||||
3. Compare again at mobile (390px)
|
||||
4. For each discrepancy found:
|
||||
- Check the component spec file — was the value extracted correctly?
|
||||
- If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
|
||||
- If the spec was right but the builder got it wrong: fix the component to match the spec
|
||||
5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
|
||||
6. Verify smooth scroll feels right, header transitions work, tab switching works, animations play
|
||||
|
||||
Only after this visual QA pass is the clone complete.
|
||||
|
||||
## Pre-Dispatch Checklist
|
||||
|
||||
Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
|
||||
|
||||
- [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
|
||||
- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
|
||||
- [ ] Interaction model is identified and documented (static / click / scroll / time)
|
||||
- [ ] For stateful components: every state's content and styles are captured
|
||||
- [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
|
||||
- [ ] For hover states: before/after values and transition timing are recorded
|
||||
- [ ] All images in the section are identified (including overlays and layered compositions)
|
||||
- [ ] Responsive behavior is documented for at least desktop and mobile
|
||||
- [ ] Text content is verbatim from the site, not paraphrased
|
||||
- [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
These are lessons from previous failed clones — each one cost hours of rework:
|
||||
|
||||
- **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
|
||||
- **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
|
||||
- **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
|
||||
- **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
|
||||
- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
|
||||
- **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
|
||||
- **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
|
||||
- **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
|
||||
- **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
|
||||
- **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
|
||||
- **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
|
||||
- **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
|
||||
- **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
|
||||
|
||||
## Completion
|
||||
|
||||
When done, report:
|
||||
- Total sections built
|
||||
- Total components created
|
||||
- Total spec files written (should match components)
|
||||
- Total assets downloaded (images, videos, SVGs, fonts)
|
||||
- Build status (`npm run build` result)
|
||||
- Visual QA results (any remaining discrepancies)
|
||||
- Any known gaps or limitations
|
||||
@@ -0,0 +1,473 @@
|
||||
---
|
||||
name: clone-website
|
||||
description: Reverse-engineer and clone one or more websites in one shot — extracts assets, CSS, and content section-by-section and proactively dispatches parallel builder agents in worktrees as it goes. Use this whenever the user wants to clone, replicate, rebuild, reverse-engineer, or copy any website. Also triggers on phrases like "make a copy of this site", "rebuild this page", "pixel-perfect clone". Provide one or more target URLs as arguments.
|
||||
argument-hint: "<url1> [<url2> ...]"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Clone Website
|
||||
|
||||
You are about to reverse-engineer and rebuild **$ARGUMENTS** as pixel-perfect clones.
|
||||
|
||||
When multiple URLs are provided, process them independently and in parallel where possible, while keeping each site's extraction artifacts isolated in dedicated folders (for example, `docs/research/<hostname>/`).
|
||||
|
||||
This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
|
||||
|
||||
## Scope Defaults
|
||||
|
||||
The target is whatever page `$ARGUMENTS` resolves to. Clone exactly what's visible at that URL. Unless the user specifies otherwise, use these defaults:
|
||||
|
||||
- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, animations
|
||||
- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
|
||||
- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
|
||||
- **Customization:** None — pure emulation
|
||||
|
||||
If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
|
||||
|
||||
## Pre-Flight
|
||||
|
||||
1. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
|
||||
2. Parse `$ARGUMENTS` as one or more URLs. Normalize and validate each URL; if any are invalid, ask the user to correct them before proceeding. For each valid URL, verify it is accessible via your browser MCP tool.
|
||||
3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
|
||||
4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
|
||||
5. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
|
||||
|
||||
### 1. Completeness Beats Speed
|
||||
|
||||
Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
|
||||
|
||||
### 2. Small Tasks, Perfect Results
|
||||
|
||||
When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
|
||||
|
||||
Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
|
||||
|
||||
**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
|
||||
|
||||
### 3. Real Content, Real Assets
|
||||
|
||||
Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
|
||||
|
||||
**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays. Missing an overlay image makes the clone look empty even if the background is correct.
|
||||
|
||||
### 4. Foundation First
|
||||
|
||||
Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
|
||||
|
||||
### 5. Extract How It Looks AND How It Behaves
|
||||
|
||||
A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
|
||||
|
||||
For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens). Not "it looks like 16px" — extract the actual computed value. Not "the nav changes on scroll" — document the exact trigger (scroll position, IntersectionObserver threshold, viewport intersection), the before and after states (both sets of CSS values), and the transition (duration, easing, CSS transition vs. JS-driven vs. CSS `animation-timeline`).
|
||||
|
||||
Examples of behaviors to watch for — these are illustrative, not exhaustive. The page may do things not on this list, and you must catch those too:
|
||||
- A navbar that shrinks, changes background, or gains a shadow after scrolling past a threshold
|
||||
- Elements that animate into view when they enter the viewport (fade-up, slide-in, stagger delays)
|
||||
- Sections that snap into place on scroll (`scroll-snap-type`)
|
||||
- Parallax layers that move at different rates than the scroll
|
||||
- Hover states that animate (not just change — the transition duration and easing matter)
|
||||
- Dropdowns, modals, accordions with enter/exit animations
|
||||
- Scroll-driven progress indicators or opacity transitions
|
||||
- Auto-playing carousels or cycling content
|
||||
- Dark-to-light (or any theme) transitions between page sections
|
||||
- **Tabbed/pill content that cycles** — buttons that switch visible card sets with transitions
|
||||
- **Scroll-driven tab/accordion switching** — sidebars where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
|
||||
- **Smooth scroll libraries** (Lenis, Locomotive Scroll) — check for `.lenis` class or scroll container wrappers
|
||||
|
||||
### 6. Identify the Interaction Model Before Building
|
||||
|
||||
This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa. Before writing any builder prompt for an interactive section, you must definitively answer: **Is this section driven by clicks, scrolls, hovers, time, or some combination?**
|
||||
|
||||
How to determine this:
|
||||
1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
|
||||
2. If they do, it's scroll-driven. Extract the mechanism: `IntersectionObserver`, `scroll-snap`, `position: sticky`, `animation-timeline`, or JS scroll listeners.
|
||||
3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
|
||||
4. Document the interaction model explicitly in the component spec: "INTERACTION MODEL: scroll-driven with IntersectionObserver" or "INTERACTION MODEL: click-to-switch with opacity transition."
|
||||
|
||||
A section with a sticky sidebar and scrolling content panels is fundamentally different from a tabbed interface where clicking switches content. Getting this wrong means a complete rewrite, not a CSS tweak.
|
||||
|
||||
### 7. Extract Every State, Not Just the Default
|
||||
|
||||
Many components have multiple visual states — a tab bar shows different cards per tab, a header looks different at scroll position 0 vs 100, a card has hover effects. You must extract ALL states, not just whatever is visible on page load.
|
||||
|
||||
For tabbed/stateful content:
|
||||
- Click each tab/button via browser MCP
|
||||
- Extract the content, images, and card data for EACH state
|
||||
- Record which content belongs to which state
|
||||
- Note the transition animation between states (opacity, slide, fade, etc.)
|
||||
|
||||
For scroll-dependent elements:
|
||||
- Capture computed styles at scroll position 0 (initial state)
|
||||
- Scroll past the trigger threshold and capture computed styles again (scrolled state)
|
||||
- Diff the two to identify exactly which CSS properties change
|
||||
- Record the transition CSS (duration, easing, properties)
|
||||
- Record the exact trigger threshold (scroll position in px, or viewport intersection ratio)
|
||||
|
||||
### 8. Spec Files Are the Source of Truth
|
||||
|
||||
Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. This file is the contract between your extraction work and the builder agent. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact that the user (or you) can review if something looks wrong.
|
||||
|
||||
The spec file is not optional. It is not a nice-to-have. If you dispatch a builder without first writing a spec file, you are shipping incomplete instructions based on whatever you can remember from a browser MCP session, and the builder will guess to fill gaps.
|
||||
|
||||
### 9. Build Must Always Compile
|
||||
|
||||
Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
|
||||
|
||||
## Phase 1: Reconnaissance
|
||||
|
||||
Navigate to the target URL with browser MCP.
|
||||
|
||||
### Screenshots
|
||||
- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
|
||||
- Save to `docs/design-references/` with descriptive names
|
||||
- These are your master reference — builders will receive section-specific crops/screenshots later
|
||||
|
||||
### Global Extraction
|
||||
Extract these from the page before doing anything else:
|
||||
|
||||
**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements (headings, body, code, labels). Document every family, weight, and style actually used. Configure them in `src/app/layout.tsx` using `next/font/google` or `next/font/local`.
|
||||
|
||||
**Colors** — Extract the site's color palette from computed styles across the page. Update `src/app/globals.css` with the target's actual colors in the `:root` and `.dark` CSS variable blocks. Map them to shadcn's token names (background, foreground, primary, muted, etc.) where they fit. Add custom properties for colors that don't map to shadcn tokens.
|
||||
|
||||
**Favicons & Meta** — Download favicons, apple-touch-icons, OG images, webmanifest to `public/seo/`. Update `layout.tsx` metadata.
|
||||
|
||||
**Global UI patterns** — Identify any site-wide CSS or JS: custom scrollbar hiding, scroll-snap on the page container, global keyframe animations, backdrop filters, gradients used as overlays, **smooth scroll libraries** (Lenis, Locomotive Scroll — check for `.lenis`, `.locomotive-scroll`, or custom scroll container classes). Add these to `globals.css` and note any libraries that need to be installed.
|
||||
|
||||
### Mandatory Interaction Sweep
|
||||
|
||||
This is a dedicated pass AFTER screenshots and BEFORE anything else. Its purpose is to discover every behavior on the page — many of which are invisible in a static screenshot.
|
||||
|
||||
**Scroll sweep:** Scroll the page slowly from top to bottom via browser MCP. At each section, pause and observe:
|
||||
- Does the header change appearance? Record the scroll position where it triggers.
|
||||
- Do elements animate into view? Record which ones and the animation type.
|
||||
- Does a sidebar or tab indicator auto-switch as you scroll? Record the mechanism.
|
||||
- Are there scroll-snap points? Record which containers.
|
||||
- Is there a smooth scroll library active? Check for non-native scroll behavior.
|
||||
|
||||
**Click sweep:** Click every element that looks interactive:
|
||||
- Every button, tab, pill, link, card
|
||||
- Record what happens: does content change? Does a modal open? Does a dropdown appear?
|
||||
- For tabs/pills: click EACH ONE and record the content that appears for each state
|
||||
|
||||
**Hover sweep:** Hover over every element that might have hover states:
|
||||
- Buttons, cards, links, images, nav items
|
||||
- Record what changes: color, scale, shadow, underline, opacity
|
||||
|
||||
**Responsive sweep:** Test at 3 viewport widths via browser MCP:
|
||||
- Desktop: 1440px
|
||||
- Tablet: 768px
|
||||
- Mobile: 390px
|
||||
- At each width, note which sections change layout (column → stack, sidebar disappears, etc.) and at approximately which breakpoint the change occurs.
|
||||
|
||||
Save all findings to `docs/research/BEHAVIORS.md`. This is your behavior bible — reference it when writing every component spec.
|
||||
|
||||
### Page Topology
|
||||
Map out every distinct section of the page from top to bottom. Give each a working name. Document:
|
||||
- Their visual order
|
||||
- Which are fixed/sticky overlays vs. flow content
|
||||
- The overall page layout (scroll container, column structure, z-index layers)
|
||||
- Dependencies between sections (e.g., a floating nav that overlays everything)
|
||||
- **The interaction model** of each section (static, click-driven, scroll-driven, time-driven)
|
||||
|
||||
Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly blueprint.
|
||||
|
||||
## Phase 2: Foundation Build
|
||||
|
||||
This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
|
||||
|
||||
1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
|
||||
2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
|
||||
3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
|
||||
4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
|
||||
5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
|
||||
6. Verify: `npm run build` passes
|
||||
|
||||
### Asset Discovery Script Pattern
|
||||
|
||||
Use browser MCP to enumerate all assets on the page:
|
||||
|
||||
```javascript
|
||||
// Run this via browser MCP to discover all assets
|
||||
JSON.stringify({
|
||||
images: [...document.querySelectorAll('img')].map(img => ({
|
||||
src: img.src || img.currentSrc,
|
||||
alt: img.alt,
|
||||
width: img.naturalWidth,
|
||||
height: img.naturalHeight,
|
||||
// Include parent info to detect layered compositions
|
||||
parentClasses: img.parentElement?.className,
|
||||
siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
|
||||
position: getComputedStyle(img).position,
|
||||
zIndex: getComputedStyle(img).zIndex
|
||||
})),
|
||||
videos: [...document.querySelectorAll('video')].map(v => ({
|
||||
src: v.src || v.querySelector('source')?.src,
|
||||
poster: v.poster,
|
||||
autoplay: v.autoplay,
|
||||
loop: v.loop,
|
||||
muted: v.muted
|
||||
})),
|
||||
backgroundImages: [...document.querySelectorAll('*')].filter(el => {
|
||||
const bg = getComputedStyle(el).backgroundImage;
|
||||
return bg && bg !== 'none';
|
||||
}).map(el => ({
|
||||
url: getComputedStyle(el).backgroundImage,
|
||||
element: el.tagName + '.' + el.className?.split(' ')[0]
|
||||
})),
|
||||
svgCount: document.querySelectorAll('svg').length,
|
||||
fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
|
||||
favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
|
||||
});
|
||||
```
|
||||
|
||||
Then write a download script that fetches everything to `public/`. Use batched parallel downloads (4 at a time) with proper error handling.
|
||||
|
||||
## Phase 3: Component Specification & Dispatch
|
||||
|
||||
This is the core loop. For each section in your page topology (top to bottom), you do THREE things: **extract**, **write the spec file**, then **dispatch builders**.
|
||||
|
||||
### Step 1: Extract
|
||||
|
||||
For each section, use browser MCP to extract everything:
|
||||
|
||||
1. **Screenshot** the section in isolation (scroll to it, screenshot the viewport). Save to `docs/design-references/`.
|
||||
|
||||
2. **Extract CSS** for every element in the section. Use the extraction script below — don't hand-measure individual properties. Run it once per component container and capture the full output:
|
||||
|
||||
```javascript
|
||||
// Per-component extraction — run via browser MCP
|
||||
// Replace SELECTOR with the actual CSS selector for the component
|
||||
(function(selector) {
|
||||
const el = document.querySelector(selector);
|
||||
if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
|
||||
const props = [
|
||||
'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
|
||||
'textTransform','textDecoration','backgroundColor','background',
|
||||
'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
|
||||
'margin','marginTop','marginRight','marginBottom','marginLeft',
|
||||
'width','height','maxWidth','minWidth','maxHeight','minHeight',
|
||||
'display','flexDirection','justifyContent','alignItems','gap',
|
||||
'gridTemplateColumns','gridTemplateRows',
|
||||
'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
|
||||
'boxShadow','overflow','overflowX','overflowY',
|
||||
'position','top','right','bottom','left','zIndex',
|
||||
'opacity','transform','transition','cursor',
|
||||
'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
|
||||
'whiteSpace','textOverflow','WebkitLineClamp'
|
||||
];
|
||||
function extractStyles(element) {
|
||||
const cs = getComputedStyle(element);
|
||||
const styles = {};
|
||||
props.forEach(p => { const v = cs[p]; if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v; });
|
||||
return styles;
|
||||
}
|
||||
function walk(element, depth) {
|
||||
if (depth > 4) return null;
|
||||
const children = [...element.children];
|
||||
return {
|
||||
tag: element.tagName.toLowerCase(),
|
||||
classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
|
||||
text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
|
||||
styles: extractStyles(element),
|
||||
images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
|
||||
childCount: children.length,
|
||||
children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
|
||||
};
|
||||
}
|
||||
return JSON.stringify(walk(el, 0), null, 2);
|
||||
})('SELECTOR');
|
||||
```
|
||||
|
||||
3. **Extract multi-state styles** — for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states:
|
||||
|
||||
```javascript
|
||||
// State A: capture styles at current state (e.g., scroll position 0)
|
||||
// Then trigger the state change (scroll, click, hover via browser MCP)
|
||||
// State B: re-run the extraction script on the same element
|
||||
// The diff between A and B IS the behavior specification
|
||||
```
|
||||
|
||||
Record the diff explicitly: "Property X changes from VALUE_A to VALUE_B, triggered by TRIGGER, with transition: TRANSITION_CSS."
|
||||
|
||||
4. **Extract real content** — all text, alt attributes, aria labels, placeholder text. Use `element.textContent` for each text node. For tabbed/stateful content, **click each tab and extract content per state**.
|
||||
|
||||
5. **Identify assets** this section uses — which downloaded images/videos from `public/`, which icon components from `icons.tsx`. Check for **layered images** (multiple `<img>` or background-images stacked in the same container).
|
||||
|
||||
6. **Assess complexity** — how many distinct sub-components does this section contain? A distinct sub-component is an element with its own unique styling, structure, and behavior (e.g., a card, a nav item, a search panel).
|
||||
|
||||
### Step 2: Write the Component Spec File
|
||||
|
||||
For each section (or sub-component, if you're breaking it up), create a spec file in `docs/research/components/`. This is NOT optional — every builder must have a corresponding spec file.
|
||||
|
||||
**File path:** `docs/research/components/<component-name>.spec.md`
|
||||
|
||||
**Template:**
|
||||
|
||||
```markdown
|
||||
# <ComponentName> Specification
|
||||
|
||||
## Overview
|
||||
- **Target file:** `src/components/<ComponentName>.tsx`
|
||||
- **Screenshot:** `docs/design-references/<screenshot-name>.png`
|
||||
- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
|
||||
|
||||
## DOM Structure
|
||||
<Describe the element hierarchy — what contains what>
|
||||
|
||||
## Computed Styles (exact values from getComputedStyle)
|
||||
|
||||
### Container
|
||||
- display: ...
|
||||
- padding: ...
|
||||
- maxWidth: ...
|
||||
- (every relevant property with exact values)
|
||||
|
||||
### <Child element 1>
|
||||
- fontSize: ...
|
||||
- color: ...
|
||||
- (every relevant property)
|
||||
|
||||
### <Child element N>
|
||||
...
|
||||
|
||||
## States & Behaviors
|
||||
|
||||
### <Behavior name, e.g., "Scroll-triggered floating mode">
|
||||
- **Trigger:** <exact mechanism — scroll position 50px, IntersectionObserver rootMargin "-30% 0px", click on .tab-button, hover>
|
||||
- **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
|
||||
- **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
|
||||
- **Transition:** transition: all 0.3s ease
|
||||
- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
|
||||
|
||||
### Hover states
|
||||
- **<Element>:** <property>: <before> → <after>, transition: <value>
|
||||
|
||||
## Per-State Content (if applicable)
|
||||
|
||||
### State: "Featured"
|
||||
- Title: "..."
|
||||
- Subtitle: "..."
|
||||
- Cards: [{ title, description, image, link }, ...]
|
||||
|
||||
### State: "Productivity"
|
||||
- Title: "..."
|
||||
- Cards: [...]
|
||||
|
||||
## Assets
|
||||
- Background image: `public/images/<file>.webp`
|
||||
- Overlay image: `public/images/<file>.png`
|
||||
- Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
|
||||
|
||||
## Text Content (verbatim)
|
||||
<All text content, copy-pasted from the live site>
|
||||
|
||||
## Responsive Behavior
|
||||
- **Desktop (1440px):** <layout description>
|
||||
- **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
|
||||
- **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
|
||||
- **Breakpoint:** layout switches at ~<N>px
|
||||
```
|
||||
|
||||
Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
|
||||
|
||||
### Step 3: Dispatch Builders
|
||||
|
||||
Based on complexity, dispatch builder agent(s) in worktree(s):
|
||||
|
||||
**Simple section** (1-2 sub-components): One builder agent gets the entire section.
|
||||
|
||||
**Complex section** (3+ distinct sub-components): Break it up. One agent per sub-component, plus one agent for the section wrapper that imports them. Sub-component builders go first since the wrapper depends on them.
|
||||
|
||||
**What every builder agent receives:**
|
||||
- The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
|
||||
- Path to the section screenshot in `docs/design-references/`
|
||||
- Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
|
||||
- The target file path (e.g., `src/components/HeroSection.tsx`)
|
||||
- Instruction to verify with `npx tsc --noEmit` before finishing
|
||||
- For responsive behavior: the specific breakpoint values and what changes
|
||||
|
||||
**Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
|
||||
|
||||
### Step 4: Merge
|
||||
|
||||
As builder agents complete their work:
|
||||
- Merge their worktree branches into main
|
||||
- You have full context on what each agent built, so resolve any conflicts intelligently
|
||||
- After each merge, verify the build still passes: `npm run build`
|
||||
- If a merge introduces type errors, fix them immediately
|
||||
|
||||
The extract → spec → dispatch → merge cycle continues until all sections are built.
|
||||
|
||||
## Phase 4: Page Assembly
|
||||
|
||||
After all sections are built and merged, wire everything together in `src/app/page.tsx`:
|
||||
|
||||
- Import all section components
|
||||
- Implement the page-level layout from your topology doc (scroll containers, column structures, sticky positioning, z-index layering)
|
||||
- Connect real content to component props
|
||||
- Implement page-level behaviors: scroll snap, scroll-driven animations, dark-to-light transitions, intersection observers, smooth scroll (Lenis etc.)
|
||||
- Verify: `npm run build` passes clean
|
||||
|
||||
## Phase 5: Visual QA Diff
|
||||
|
||||
After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
|
||||
|
||||
1. Open the original site and your clone side-by-side (or take screenshots at the same viewport widths)
|
||||
2. Compare section by section, top to bottom, at desktop (1440px)
|
||||
3. Compare again at mobile (390px)
|
||||
4. For each discrepancy found:
|
||||
- Check the component spec file — was the value extracted correctly?
|
||||
- If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
|
||||
- If the spec was right but the builder got it wrong: fix the component to match the spec
|
||||
5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
|
||||
6. Verify smooth scroll feels right, header transitions work, tab switching works, animations play
|
||||
|
||||
Only after this visual QA pass is the clone complete.
|
||||
|
||||
## Pre-Dispatch Checklist
|
||||
|
||||
Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
|
||||
|
||||
- [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
|
||||
- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
|
||||
- [ ] Interaction model is identified and documented (static / click / scroll / time)
|
||||
- [ ] For stateful components: every state's content and styles are captured
|
||||
- [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
|
||||
- [ ] For hover states: before/after values and transition timing are recorded
|
||||
- [ ] All images in the section are identified (including overlays and layered compositions)
|
||||
- [ ] Responsive behavior is documented for at least desktop and mobile
|
||||
- [ ] Text content is verbatim from the site, not paraphrased
|
||||
- [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
These are lessons from previous failed clones — each one cost hours of rework:
|
||||
|
||||
- **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
|
||||
- **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
|
||||
- **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
|
||||
- **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
|
||||
- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
|
||||
- **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
|
||||
- **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
|
||||
- **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
|
||||
- **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
|
||||
- **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
|
||||
- **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
|
||||
- **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
|
||||
- **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
|
||||
|
||||
## Completion
|
||||
|
||||
When done, report:
|
||||
- Total sections built
|
||||
- Total components created
|
||||
- Total spec files written (should match components)
|
||||
- Total assets downloaded (images, videos, SVGs, fonts)
|
||||
- Build status (`npm run build` result)
|
||||
- Visual QA results (any remaining discrepancies)
|
||||
- Any known gaps or limitations
|
||||
+147
@@ -0,0 +1,147 @@
|
||||
<!-- AUTO-GENERATED from AGENTS.md — do not edit directly.
|
||||
Run `bash scripts/sync-agent-rules.sh` to regenerate. -->
|
||||
|
||||
<!-- BEGIN:nextjs-agent-rules -->
|
||||
# This is NOT the Next.js you know
|
||||
|
||||
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
|
||||
<!-- END:nextjs-agent-rules -->
|
||||
|
||||
# Website Reverse-Engineer Template
|
||||
|
||||
## What This Is
|
||||
A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — just run `/clone-website <url1> [<url2> ...]`.
|
||||
|
||||
## Tech Stack
|
||||
- **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
|
||||
- **UI:** shadcn/ui (Radix primitives, Tailwind CSS v4, `cn()` utility)
|
||||
- **Icons:** Lucide React (default — will be replaced/supplemented by extracted SVGs)
|
||||
- **Styling:** Tailwind CSS v4 with oklch design tokens
|
||||
- **Deployment:** Vercel
|
||||
|
||||
## Commands
|
||||
- `npm run dev` — Start dev server
|
||||
- `npm run build` — Production build
|
||||
- `npm run lint` — ESLint check
|
||||
- `npm run typecheck` — TypeScript check
|
||||
- `npm run check` — Run lint + typecheck + build
|
||||
|
||||
## Code Style
|
||||
- TypeScript strict mode, no `any`
|
||||
- Named exports, PascalCase components, camelCase utils
|
||||
- Tailwind utility classes, no inline styles
|
||||
- 2-space indentation
|
||||
- Responsive: mobile-first
|
||||
|
||||
## Design Principles
|
||||
- **Pixel-perfect emulation** — match the target's spacing, colors, typography exactly
|
||||
- **No personal aesthetic changes during emulation phase** — match 1:1 first, customize later
|
||||
- **Real content** — use actual text and assets from the target site, not placeholders
|
||||
- **Beauty-first** — every pixel matters
|
||||
|
||||
## Project Structure
|
||||
```
|
||||
src/
|
||||
app/ # Next.js routes
|
||||
components/ # React components
|
||||
ui/ # shadcn/ui primitives
|
||||
icons.tsx # Extracted SVG icons as React components
|
||||
lib/
|
||||
utils.ts # cn() utility (shadcn)
|
||||
types/ # TypeScript interfaces
|
||||
hooks/ # Custom React hooks
|
||||
public/
|
||||
images/ # Downloaded images from target site
|
||||
videos/ # Downloaded videos from target site
|
||||
seo/ # Favicons, OG images, webmanifest
|
||||
docs/
|
||||
research/ # Inspection output (design tokens, components, layout)
|
||||
design-references/ # Screenshots and visual references
|
||||
scripts/ # Asset download scripts
|
||||
```
|
||||
|
||||
## MOST IMPORTANT NOTES
|
||||
- When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
|
||||
- After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
|
||||
- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
|
||||
|
||||
# Website Inspection Guide
|
||||
|
||||
## How to Reverse-Engineer Any Website
|
||||
|
||||
This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
|
||||
|
||||
## Phase 1: Visual Audit
|
||||
|
||||
### Screenshots to Capture
|
||||
- [ ] Every distinct page — desktop, tablet, mobile
|
||||
- [ ] Dark mode variants (if applicable)
|
||||
- [ ] Light mode variants (if applicable)
|
||||
- [ ] Key interaction states (hover, active, open menus, modals)
|
||||
- [ ] Loading/skeleton states
|
||||
- [ ] Empty states
|
||||
- [ ] Error states
|
||||
|
||||
### Design Tokens to Extract
|
||||
- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
|
||||
- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
|
||||
- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
|
||||
- [ ] **Border radius** — buttons, cards, avatars, inputs
|
||||
- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
|
||||
- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
|
||||
- [ ] **Icons** — which icon library? custom SVGs? sizes?
|
||||
- [ ] **Avatars** — sizes, shapes, fallback behavior
|
||||
- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
|
||||
- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
|
||||
|
||||
## Phase 2: Component Inventory
|
||||
|
||||
For each distinct UI component, document:
|
||||
1. **Name** — what would you call this component?
|
||||
2. **Structure** — what HTML elements / child components does it contain?
|
||||
3. **Variants** — does it have different sizes, colors, or states?
|
||||
4. **States** — default, hover, active, disabled, loading, error, empty
|
||||
5. **Responsive behavior** — how does it change at different breakpoints?
|
||||
6. **Interactions** — click, hover, focus, keyboard navigation
|
||||
7. **Animations** — transitions, entrance/exit animations, micro-interactions
|
||||
|
||||
### Common Components to Look For
|
||||
- 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
|
||||
|
||||
## Phase 3: Layout Architecture
|
||||
|
||||
- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
|
||||
- [ ] **Column layout** — how many columns at each breakpoint?
|
||||
- [ ] **Max-width** — main content area max-width
|
||||
- [ ] **Sticky elements** — header, sidebar, floating buttons
|
||||
- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
|
||||
- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
|
||||
|
||||
## Phase 4: Technical Stack Analysis
|
||||
|
||||
- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
|
||||
- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
|
||||
- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
|
||||
- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
|
||||
- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
|
||||
- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF
|
||||
- [ ] **Animation library** — Framer Motion, GSAP, CSS transitions only
|
||||
|
||||
## Phase 5: Documentation Output
|
||||
|
||||
After inspection, create these files in `docs/research/`:
|
||||
1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
|
||||
2. `COMPONENT_INVENTORY.md` — Every component with structure notes
|
||||
3. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
|
||||
4. `INTERACTION_PATTERNS.md` — Animations, transitions, hover states
|
||||
5. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents
|
||||
@@ -0,0 +1,473 @@
|
||||
---
|
||||
name: clone-website
|
||||
description: Reverse-engineer and clone one or more websites in one shot — extracts assets, CSS, and content section-by-section and proactively dispatches parallel builder agents in worktrees as it goes. Use this whenever the user wants to clone, replicate, rebuild, reverse-engineer, or copy any website. Also triggers on phrases like "make a copy of this site", "rebuild this page", "pixel-perfect clone". Provide one or more target URLs as arguments.
|
||||
argument-hint: "<url1> [<url2> ...]"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Clone Website
|
||||
|
||||
You are about to reverse-engineer and rebuild **$ARGUMENTS** as pixel-perfect clones.
|
||||
|
||||
When multiple URLs are provided, process them independently and in parallel where possible, while keeping each site's extraction artifacts isolated in dedicated folders (for example, `docs/research/<hostname>/`).
|
||||
|
||||
This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
|
||||
|
||||
## Scope Defaults
|
||||
|
||||
The target is whatever page `$ARGUMENTS` resolves to. Clone exactly what's visible at that URL. Unless the user specifies otherwise, use these defaults:
|
||||
|
||||
- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, animations
|
||||
- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
|
||||
- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
|
||||
- **Customization:** None — pure emulation
|
||||
|
||||
If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
|
||||
|
||||
## Pre-Flight
|
||||
|
||||
1. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
|
||||
2. Parse `$ARGUMENTS` as one or more URLs. Normalize and validate each URL; if any are invalid, ask the user to correct them before proceeding. For each valid URL, verify it is accessible via your browser MCP tool.
|
||||
3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
|
||||
4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
|
||||
5. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
|
||||
|
||||
### 1. Completeness Beats Speed
|
||||
|
||||
Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
|
||||
|
||||
### 2. Small Tasks, Perfect Results
|
||||
|
||||
When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
|
||||
|
||||
Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
|
||||
|
||||
**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
|
||||
|
||||
### 3. Real Content, Real Assets
|
||||
|
||||
Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
|
||||
|
||||
**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays. Missing an overlay image makes the clone look empty even if the background is correct.
|
||||
|
||||
### 4. Foundation First
|
||||
|
||||
Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
|
||||
|
||||
### 5. Extract How It Looks AND How It Behaves
|
||||
|
||||
A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
|
||||
|
||||
For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens). Not "it looks like 16px" — extract the actual computed value. Not "the nav changes on scroll" — document the exact trigger (scroll position, IntersectionObserver threshold, viewport intersection), the before and after states (both sets of CSS values), and the transition (duration, easing, CSS transition vs. JS-driven vs. CSS `animation-timeline`).
|
||||
|
||||
Examples of behaviors to watch for — these are illustrative, not exhaustive. The page may do things not on this list, and you must catch those too:
|
||||
- A navbar that shrinks, changes background, or gains a shadow after scrolling past a threshold
|
||||
- Elements that animate into view when they enter the viewport (fade-up, slide-in, stagger delays)
|
||||
- Sections that snap into place on scroll (`scroll-snap-type`)
|
||||
- Parallax layers that move at different rates than the scroll
|
||||
- Hover states that animate (not just change — the transition duration and easing matter)
|
||||
- Dropdowns, modals, accordions with enter/exit animations
|
||||
- Scroll-driven progress indicators or opacity transitions
|
||||
- Auto-playing carousels or cycling content
|
||||
- Dark-to-light (or any theme) transitions between page sections
|
||||
- **Tabbed/pill content that cycles** — buttons that switch visible card sets with transitions
|
||||
- **Scroll-driven tab/accordion switching** — sidebars where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
|
||||
- **Smooth scroll libraries** (Lenis, Locomotive Scroll) — check for `.lenis` class or scroll container wrappers
|
||||
|
||||
### 6. Identify the Interaction Model Before Building
|
||||
|
||||
This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa. Before writing any builder prompt for an interactive section, you must definitively answer: **Is this section driven by clicks, scrolls, hovers, time, or some combination?**
|
||||
|
||||
How to determine this:
|
||||
1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
|
||||
2. If they do, it's scroll-driven. Extract the mechanism: `IntersectionObserver`, `scroll-snap`, `position: sticky`, `animation-timeline`, or JS scroll listeners.
|
||||
3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
|
||||
4. Document the interaction model explicitly in the component spec: "INTERACTION MODEL: scroll-driven with IntersectionObserver" or "INTERACTION MODEL: click-to-switch with opacity transition."
|
||||
|
||||
A section with a sticky sidebar and scrolling content panels is fundamentally different from a tabbed interface where clicking switches content. Getting this wrong means a complete rewrite, not a CSS tweak.
|
||||
|
||||
### 7. Extract Every State, Not Just the Default
|
||||
|
||||
Many components have multiple visual states — a tab bar shows different cards per tab, a header looks different at scroll position 0 vs 100, a card has hover effects. You must extract ALL states, not just whatever is visible on page load.
|
||||
|
||||
For tabbed/stateful content:
|
||||
- Click each tab/button via browser MCP
|
||||
- Extract the content, images, and card data for EACH state
|
||||
- Record which content belongs to which state
|
||||
- Note the transition animation between states (opacity, slide, fade, etc.)
|
||||
|
||||
For scroll-dependent elements:
|
||||
- Capture computed styles at scroll position 0 (initial state)
|
||||
- Scroll past the trigger threshold and capture computed styles again (scrolled state)
|
||||
- Diff the two to identify exactly which CSS properties change
|
||||
- Record the transition CSS (duration, easing, properties)
|
||||
- Record the exact trigger threshold (scroll position in px, or viewport intersection ratio)
|
||||
|
||||
### 8. Spec Files Are the Source of Truth
|
||||
|
||||
Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. This file is the contract between your extraction work and the builder agent. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact that the user (or you) can review if something looks wrong.
|
||||
|
||||
The spec file is not optional. It is not a nice-to-have. If you dispatch a builder without first writing a spec file, you are shipping incomplete instructions based on whatever you can remember from a browser MCP session, and the builder will guess to fill gaps.
|
||||
|
||||
### 9. Build Must Always Compile
|
||||
|
||||
Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
|
||||
|
||||
## Phase 1: Reconnaissance
|
||||
|
||||
Navigate to the target URL with browser MCP.
|
||||
|
||||
### Screenshots
|
||||
- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
|
||||
- Save to `docs/design-references/` with descriptive names
|
||||
- These are your master reference — builders will receive section-specific crops/screenshots later
|
||||
|
||||
### Global Extraction
|
||||
Extract these from the page before doing anything else:
|
||||
|
||||
**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements (headings, body, code, labels). Document every family, weight, and style actually used. Configure them in `src/app/layout.tsx` using `next/font/google` or `next/font/local`.
|
||||
|
||||
**Colors** — Extract the site's color palette from computed styles across the page. Update `src/app/globals.css` with the target's actual colors in the `:root` and `.dark` CSS variable blocks. Map them to shadcn's token names (background, foreground, primary, muted, etc.) where they fit. Add custom properties for colors that don't map to shadcn tokens.
|
||||
|
||||
**Favicons & Meta** — Download favicons, apple-touch-icons, OG images, webmanifest to `public/seo/`. Update `layout.tsx` metadata.
|
||||
|
||||
**Global UI patterns** — Identify any site-wide CSS or JS: custom scrollbar hiding, scroll-snap on the page container, global keyframe animations, backdrop filters, gradients used as overlays, **smooth scroll libraries** (Lenis, Locomotive Scroll — check for `.lenis`, `.locomotive-scroll`, or custom scroll container classes). Add these to `globals.css` and note any libraries that need to be installed.
|
||||
|
||||
### Mandatory Interaction Sweep
|
||||
|
||||
This is a dedicated pass AFTER screenshots and BEFORE anything else. Its purpose is to discover every behavior on the page — many of which are invisible in a static screenshot.
|
||||
|
||||
**Scroll sweep:** Scroll the page slowly from top to bottom via browser MCP. At each section, pause and observe:
|
||||
- Does the header change appearance? Record the scroll position where it triggers.
|
||||
- Do elements animate into view? Record which ones and the animation type.
|
||||
- Does a sidebar or tab indicator auto-switch as you scroll? Record the mechanism.
|
||||
- Are there scroll-snap points? Record which containers.
|
||||
- Is there a smooth scroll library active? Check for non-native scroll behavior.
|
||||
|
||||
**Click sweep:** Click every element that looks interactive:
|
||||
- Every button, tab, pill, link, card
|
||||
- Record what happens: does content change? Does a modal open? Does a dropdown appear?
|
||||
- For tabs/pills: click EACH ONE and record the content that appears for each state
|
||||
|
||||
**Hover sweep:** Hover over every element that might have hover states:
|
||||
- Buttons, cards, links, images, nav items
|
||||
- Record what changes: color, scale, shadow, underline, opacity
|
||||
|
||||
**Responsive sweep:** Test at 3 viewport widths via browser MCP:
|
||||
- Desktop: 1440px
|
||||
- Tablet: 768px
|
||||
- Mobile: 390px
|
||||
- At each width, note which sections change layout (column → stack, sidebar disappears, etc.) and at approximately which breakpoint the change occurs.
|
||||
|
||||
Save all findings to `docs/research/BEHAVIORS.md`. This is your behavior bible — reference it when writing every component spec.
|
||||
|
||||
### Page Topology
|
||||
Map out every distinct section of the page from top to bottom. Give each a working name. Document:
|
||||
- Their visual order
|
||||
- Which are fixed/sticky overlays vs. flow content
|
||||
- The overall page layout (scroll container, column structure, z-index layers)
|
||||
- Dependencies between sections (e.g., a floating nav that overlays everything)
|
||||
- **The interaction model** of each section (static, click-driven, scroll-driven, time-driven)
|
||||
|
||||
Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly blueprint.
|
||||
|
||||
## Phase 2: Foundation Build
|
||||
|
||||
This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
|
||||
|
||||
1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
|
||||
2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
|
||||
3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
|
||||
4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
|
||||
5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
|
||||
6. Verify: `npm run build` passes
|
||||
|
||||
### Asset Discovery Script Pattern
|
||||
|
||||
Use browser MCP to enumerate all assets on the page:
|
||||
|
||||
```javascript
|
||||
// Run this via browser MCP to discover all assets
|
||||
JSON.stringify({
|
||||
images: [...document.querySelectorAll('img')].map(img => ({
|
||||
src: img.src || img.currentSrc,
|
||||
alt: img.alt,
|
||||
width: img.naturalWidth,
|
||||
height: img.naturalHeight,
|
||||
// Include parent info to detect layered compositions
|
||||
parentClasses: img.parentElement?.className,
|
||||
siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
|
||||
position: getComputedStyle(img).position,
|
||||
zIndex: getComputedStyle(img).zIndex
|
||||
})),
|
||||
videos: [...document.querySelectorAll('video')].map(v => ({
|
||||
src: v.src || v.querySelector('source')?.src,
|
||||
poster: v.poster,
|
||||
autoplay: v.autoplay,
|
||||
loop: v.loop,
|
||||
muted: v.muted
|
||||
})),
|
||||
backgroundImages: [...document.querySelectorAll('*')].filter(el => {
|
||||
const bg = getComputedStyle(el).backgroundImage;
|
||||
return bg && bg !== 'none';
|
||||
}).map(el => ({
|
||||
url: getComputedStyle(el).backgroundImage,
|
||||
element: el.tagName + '.' + el.className?.split(' ')[0]
|
||||
})),
|
||||
svgCount: document.querySelectorAll('svg').length,
|
||||
fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
|
||||
favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
|
||||
});
|
||||
```
|
||||
|
||||
Then write a download script that fetches everything to `public/`. Use batched parallel downloads (4 at a time) with proper error handling.
|
||||
|
||||
## Phase 3: Component Specification & Dispatch
|
||||
|
||||
This is the core loop. For each section in your page topology (top to bottom), you do THREE things: **extract**, **write the spec file**, then **dispatch builders**.
|
||||
|
||||
### Step 1: Extract
|
||||
|
||||
For each section, use browser MCP to extract everything:
|
||||
|
||||
1. **Screenshot** the section in isolation (scroll to it, screenshot the viewport). Save to `docs/design-references/`.
|
||||
|
||||
2. **Extract CSS** for every element in the section. Use the extraction script below — don't hand-measure individual properties. Run it once per component container and capture the full output:
|
||||
|
||||
```javascript
|
||||
// Per-component extraction — run via browser MCP
|
||||
// Replace SELECTOR with the actual CSS selector for the component
|
||||
(function(selector) {
|
||||
const el = document.querySelector(selector);
|
||||
if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
|
||||
const props = [
|
||||
'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
|
||||
'textTransform','textDecoration','backgroundColor','background',
|
||||
'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
|
||||
'margin','marginTop','marginRight','marginBottom','marginLeft',
|
||||
'width','height','maxWidth','minWidth','maxHeight','minHeight',
|
||||
'display','flexDirection','justifyContent','alignItems','gap',
|
||||
'gridTemplateColumns','gridTemplateRows',
|
||||
'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
|
||||
'boxShadow','overflow','overflowX','overflowY',
|
||||
'position','top','right','bottom','left','zIndex',
|
||||
'opacity','transform','transition','cursor',
|
||||
'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
|
||||
'whiteSpace','textOverflow','WebkitLineClamp'
|
||||
];
|
||||
function extractStyles(element) {
|
||||
const cs = getComputedStyle(element);
|
||||
const styles = {};
|
||||
props.forEach(p => { const v = cs[p]; if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v; });
|
||||
return styles;
|
||||
}
|
||||
function walk(element, depth) {
|
||||
if (depth > 4) return null;
|
||||
const children = [...element.children];
|
||||
return {
|
||||
tag: element.tagName.toLowerCase(),
|
||||
classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
|
||||
text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
|
||||
styles: extractStyles(element),
|
||||
images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
|
||||
childCount: children.length,
|
||||
children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
|
||||
};
|
||||
}
|
||||
return JSON.stringify(walk(el, 0), null, 2);
|
||||
})('SELECTOR');
|
||||
```
|
||||
|
||||
3. **Extract multi-state styles** — for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states:
|
||||
|
||||
```javascript
|
||||
// State A: capture styles at current state (e.g., scroll position 0)
|
||||
// Then trigger the state change (scroll, click, hover via browser MCP)
|
||||
// State B: re-run the extraction script on the same element
|
||||
// The diff between A and B IS the behavior specification
|
||||
```
|
||||
|
||||
Record the diff explicitly: "Property X changes from VALUE_A to VALUE_B, triggered by TRIGGER, with transition: TRANSITION_CSS."
|
||||
|
||||
4. **Extract real content** — all text, alt attributes, aria labels, placeholder text. Use `element.textContent` for each text node. For tabbed/stateful content, **click each tab and extract content per state**.
|
||||
|
||||
5. **Identify assets** this section uses — which downloaded images/videos from `public/`, which icon components from `icons.tsx`. Check for **layered images** (multiple `<img>` or background-images stacked in the same container).
|
||||
|
||||
6. **Assess complexity** — how many distinct sub-components does this section contain? A distinct sub-component is an element with its own unique styling, structure, and behavior (e.g., a card, a nav item, a search panel).
|
||||
|
||||
### Step 2: Write the Component Spec File
|
||||
|
||||
For each section (or sub-component, if you're breaking it up), create a spec file in `docs/research/components/`. This is NOT optional — every builder must have a corresponding spec file.
|
||||
|
||||
**File path:** `docs/research/components/<component-name>.spec.md`
|
||||
|
||||
**Template:**
|
||||
|
||||
```markdown
|
||||
# <ComponentName> Specification
|
||||
|
||||
## Overview
|
||||
- **Target file:** `src/components/<ComponentName>.tsx`
|
||||
- **Screenshot:** `docs/design-references/<screenshot-name>.png`
|
||||
- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
|
||||
|
||||
## DOM Structure
|
||||
<Describe the element hierarchy — what contains what>
|
||||
|
||||
## Computed Styles (exact values from getComputedStyle)
|
||||
|
||||
### Container
|
||||
- display: ...
|
||||
- padding: ...
|
||||
- maxWidth: ...
|
||||
- (every relevant property with exact values)
|
||||
|
||||
### <Child element 1>
|
||||
- fontSize: ...
|
||||
- color: ...
|
||||
- (every relevant property)
|
||||
|
||||
### <Child element N>
|
||||
...
|
||||
|
||||
## States & Behaviors
|
||||
|
||||
### <Behavior name, e.g., "Scroll-triggered floating mode">
|
||||
- **Trigger:** <exact mechanism — scroll position 50px, IntersectionObserver rootMargin "-30% 0px", click on .tab-button, hover>
|
||||
- **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
|
||||
- **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
|
||||
- **Transition:** transition: all 0.3s ease
|
||||
- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
|
||||
|
||||
### Hover states
|
||||
- **<Element>:** <property>: <before> → <after>, transition: <value>
|
||||
|
||||
## Per-State Content (if applicable)
|
||||
|
||||
### State: "Featured"
|
||||
- Title: "..."
|
||||
- Subtitle: "..."
|
||||
- Cards: [{ title, description, image, link }, ...]
|
||||
|
||||
### State: "Productivity"
|
||||
- Title: "..."
|
||||
- Cards: [...]
|
||||
|
||||
## Assets
|
||||
- Background image: `public/images/<file>.webp`
|
||||
- Overlay image: `public/images/<file>.png`
|
||||
- Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
|
||||
|
||||
## Text Content (verbatim)
|
||||
<All text content, copy-pasted from the live site>
|
||||
|
||||
## Responsive Behavior
|
||||
- **Desktop (1440px):** <layout description>
|
||||
- **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
|
||||
- **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
|
||||
- **Breakpoint:** layout switches at ~<N>px
|
||||
```
|
||||
|
||||
Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
|
||||
|
||||
### Step 3: Dispatch Builders
|
||||
|
||||
Based on complexity, dispatch builder agent(s) in worktree(s):
|
||||
|
||||
**Simple section** (1-2 sub-components): One builder agent gets the entire section.
|
||||
|
||||
**Complex section** (3+ distinct sub-components): Break it up. One agent per sub-component, plus one agent for the section wrapper that imports them. Sub-component builders go first since the wrapper depends on them.
|
||||
|
||||
**What every builder agent receives:**
|
||||
- The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
|
||||
- Path to the section screenshot in `docs/design-references/`
|
||||
- Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
|
||||
- The target file path (e.g., `src/components/HeroSection.tsx`)
|
||||
- Instruction to verify with `npx tsc --noEmit` before finishing
|
||||
- For responsive behavior: the specific breakpoint values and what changes
|
||||
|
||||
**Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
|
||||
|
||||
### Step 4: Merge
|
||||
|
||||
As builder agents complete their work:
|
||||
- Merge their worktree branches into main
|
||||
- You have full context on what each agent built, so resolve any conflicts intelligently
|
||||
- After each merge, verify the build still passes: `npm run build`
|
||||
- If a merge introduces type errors, fix them immediately
|
||||
|
||||
The extract → spec → dispatch → merge cycle continues until all sections are built.
|
||||
|
||||
## Phase 4: Page Assembly
|
||||
|
||||
After all sections are built and merged, wire everything together in `src/app/page.tsx`:
|
||||
|
||||
- Import all section components
|
||||
- Implement the page-level layout from your topology doc (scroll containers, column structures, sticky positioning, z-index layering)
|
||||
- Connect real content to component props
|
||||
- Implement page-level behaviors: scroll snap, scroll-driven animations, dark-to-light transitions, intersection observers, smooth scroll (Lenis etc.)
|
||||
- Verify: `npm run build` passes clean
|
||||
|
||||
## Phase 5: Visual QA Diff
|
||||
|
||||
After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
|
||||
|
||||
1. Open the original site and your clone side-by-side (or take screenshots at the same viewport widths)
|
||||
2. Compare section by section, top to bottom, at desktop (1440px)
|
||||
3. Compare again at mobile (390px)
|
||||
4. For each discrepancy found:
|
||||
- Check the component spec file — was the value extracted correctly?
|
||||
- If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
|
||||
- If the spec was right but the builder got it wrong: fix the component to match the spec
|
||||
5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
|
||||
6. Verify smooth scroll feels right, header transitions work, tab switching works, animations play
|
||||
|
||||
Only after this visual QA pass is the clone complete.
|
||||
|
||||
## Pre-Dispatch Checklist
|
||||
|
||||
Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
|
||||
|
||||
- [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
|
||||
- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
|
||||
- [ ] Interaction model is identified and documented (static / click / scroll / time)
|
||||
- [ ] For stateful components: every state's content and styles are captured
|
||||
- [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
|
||||
- [ ] For hover states: before/after values and transition timing are recorded
|
||||
- [ ] All images in the section are identified (including overlays and layered compositions)
|
||||
- [ ] Responsive behavior is documented for at least desktop and mobile
|
||||
- [ ] Text content is verbatim from the site, not paraphrased
|
||||
- [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
These are lessons from previous failed clones — each one cost hours of rework:
|
||||
|
||||
- **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
|
||||
- **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
|
||||
- **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
|
||||
- **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
|
||||
- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
|
||||
- **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
|
||||
- **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
|
||||
- **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
|
||||
- **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
|
||||
- **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
|
||||
- **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
|
||||
- **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
|
||||
- **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
|
||||
|
||||
## Completion
|
||||
|
||||
When done, report:
|
||||
- Total sections built
|
||||
- Total components created
|
||||
- Total spec files written (should match components)
|
||||
- Total assets downloaded (images, videos, SVGs, fonts)
|
||||
- Build status (`npm run build` result)
|
||||
- Visual QA results (any remaining discrepancies)
|
||||
- Any known gaps or limitations
|
||||
@@ -0,0 +1,475 @@
|
||||
---
|
||||
name: clone-website
|
||||
description: "Reverse-engineer and clone any website as a pixel-perfect replica"
|
||||
invokable: true
|
||||
---
|
||||
<!-- AUTO-GENERATED from .claude/skills/clone-website/SKILL.md — do not edit directly.
|
||||
Run `node scripts/sync-skills.mjs` to regenerate. -->
|
||||
|
||||
|
||||
# Clone Website
|
||||
|
||||
You are about to reverse-engineer and rebuild **$ARGUMENTS** as pixel-perfect clones.
|
||||
|
||||
When multiple URLs are provided, process them independently and in parallel where possible, while keeping each site's extraction artifacts isolated in dedicated folders (for example, `docs/research/<hostname>/`).
|
||||
|
||||
This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
|
||||
|
||||
## Scope Defaults
|
||||
|
||||
The target is whatever page `$ARGUMENTS` resolves to. Clone exactly what's visible at that URL. Unless the user specifies otherwise, use these defaults:
|
||||
|
||||
- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, animations
|
||||
- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
|
||||
- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
|
||||
- **Customization:** None — pure emulation
|
||||
|
||||
If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
|
||||
|
||||
## Pre-Flight
|
||||
|
||||
1. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
|
||||
2. Parse `$ARGUMENTS` as one or more URLs. Normalize and validate each URL; if any are invalid, ask the user to correct them before proceeding. For each valid URL, verify it is accessible via your browser MCP tool.
|
||||
3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
|
||||
4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
|
||||
5. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
|
||||
|
||||
### 1. Completeness Beats Speed
|
||||
|
||||
Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
|
||||
|
||||
### 2. Small Tasks, Perfect Results
|
||||
|
||||
When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
|
||||
|
||||
Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
|
||||
|
||||
**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
|
||||
|
||||
### 3. Real Content, Real Assets
|
||||
|
||||
Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
|
||||
|
||||
**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays. Missing an overlay image makes the clone look empty even if the background is correct.
|
||||
|
||||
### 4. Foundation First
|
||||
|
||||
Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
|
||||
|
||||
### 5. Extract How It Looks AND How It Behaves
|
||||
|
||||
A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
|
||||
|
||||
For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens). Not "it looks like 16px" — extract the actual computed value. Not "the nav changes on scroll" — document the exact trigger (scroll position, IntersectionObserver threshold, viewport intersection), the before and after states (both sets of CSS values), and the transition (duration, easing, CSS transition vs. JS-driven vs. CSS `animation-timeline`).
|
||||
|
||||
Examples of behaviors to watch for — these are illustrative, not exhaustive. The page may do things not on this list, and you must catch those too:
|
||||
- A navbar that shrinks, changes background, or gains a shadow after scrolling past a threshold
|
||||
- Elements that animate into view when they enter the viewport (fade-up, slide-in, stagger delays)
|
||||
- Sections that snap into place on scroll (`scroll-snap-type`)
|
||||
- Parallax layers that move at different rates than the scroll
|
||||
- Hover states that animate (not just change — the transition duration and easing matter)
|
||||
- Dropdowns, modals, accordions with enter/exit animations
|
||||
- Scroll-driven progress indicators or opacity transitions
|
||||
- Auto-playing carousels or cycling content
|
||||
- Dark-to-light (or any theme) transitions between page sections
|
||||
- **Tabbed/pill content that cycles** — buttons that switch visible card sets with transitions
|
||||
- **Scroll-driven tab/accordion switching** — sidebars where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
|
||||
- **Smooth scroll libraries** (Lenis, Locomotive Scroll) — check for `.lenis` class or scroll container wrappers
|
||||
|
||||
### 6. Identify the Interaction Model Before Building
|
||||
|
||||
This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa. Before writing any builder prompt for an interactive section, you must definitively answer: **Is this section driven by clicks, scrolls, hovers, time, or some combination?**
|
||||
|
||||
How to determine this:
|
||||
1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
|
||||
2. If they do, it's scroll-driven. Extract the mechanism: `IntersectionObserver`, `scroll-snap`, `position: sticky`, `animation-timeline`, or JS scroll listeners.
|
||||
3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
|
||||
4. Document the interaction model explicitly in the component spec: "INTERACTION MODEL: scroll-driven with IntersectionObserver" or "INTERACTION MODEL: click-to-switch with opacity transition."
|
||||
|
||||
A section with a sticky sidebar and scrolling content panels is fundamentally different from a tabbed interface where clicking switches content. Getting this wrong means a complete rewrite, not a CSS tweak.
|
||||
|
||||
### 7. Extract Every State, Not Just the Default
|
||||
|
||||
Many components have multiple visual states — a tab bar shows different cards per tab, a header looks different at scroll position 0 vs 100, a card has hover effects. You must extract ALL states, not just whatever is visible on page load.
|
||||
|
||||
For tabbed/stateful content:
|
||||
- Click each tab/button via browser MCP
|
||||
- Extract the content, images, and card data for EACH state
|
||||
- Record which content belongs to which state
|
||||
- Note the transition animation between states (opacity, slide, fade, etc.)
|
||||
|
||||
For scroll-dependent elements:
|
||||
- Capture computed styles at scroll position 0 (initial state)
|
||||
- Scroll past the trigger threshold and capture computed styles again (scrolled state)
|
||||
- Diff the two to identify exactly which CSS properties change
|
||||
- Record the transition CSS (duration, easing, properties)
|
||||
- Record the exact trigger threshold (scroll position in px, or viewport intersection ratio)
|
||||
|
||||
### 8. Spec Files Are the Source of Truth
|
||||
|
||||
Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. This file is the contract between your extraction work and the builder agent. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact that the user (or you) can review if something looks wrong.
|
||||
|
||||
The spec file is not optional. It is not a nice-to-have. If you dispatch a builder without first writing a spec file, you are shipping incomplete instructions based on whatever you can remember from a browser MCP session, and the builder will guess to fill gaps.
|
||||
|
||||
### 9. Build Must Always Compile
|
||||
|
||||
Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
|
||||
|
||||
## Phase 1: Reconnaissance
|
||||
|
||||
Navigate to the target URL with browser MCP.
|
||||
|
||||
### Screenshots
|
||||
- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
|
||||
- Save to `docs/design-references/` with descriptive names
|
||||
- These are your master reference — builders will receive section-specific crops/screenshots later
|
||||
|
||||
### Global Extraction
|
||||
Extract these from the page before doing anything else:
|
||||
|
||||
**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements (headings, body, code, labels). Document every family, weight, and style actually used. Configure them in `src/app/layout.tsx` using `next/font/google` or `next/font/local`.
|
||||
|
||||
**Colors** — Extract the site's color palette from computed styles across the page. Update `src/app/globals.css` with the target's actual colors in the `:root` and `.dark` CSS variable blocks. Map them to shadcn's token names (background, foreground, primary, muted, etc.) where they fit. Add custom properties for colors that don't map to shadcn tokens.
|
||||
|
||||
**Favicons & Meta** — Download favicons, apple-touch-icons, OG images, webmanifest to `public/seo/`. Update `layout.tsx` metadata.
|
||||
|
||||
**Global UI patterns** — Identify any site-wide CSS or JS: custom scrollbar hiding, scroll-snap on the page container, global keyframe animations, backdrop filters, gradients used as overlays, **smooth scroll libraries** (Lenis, Locomotive Scroll — check for `.lenis`, `.locomotive-scroll`, or custom scroll container classes). Add these to `globals.css` and note any libraries that need to be installed.
|
||||
|
||||
### Mandatory Interaction Sweep
|
||||
|
||||
This is a dedicated pass AFTER screenshots and BEFORE anything else. Its purpose is to discover every behavior on the page — many of which are invisible in a static screenshot.
|
||||
|
||||
**Scroll sweep:** Scroll the page slowly from top to bottom via browser MCP. At each section, pause and observe:
|
||||
- Does the header change appearance? Record the scroll position where it triggers.
|
||||
- Do elements animate into view? Record which ones and the animation type.
|
||||
- Does a sidebar or tab indicator auto-switch as you scroll? Record the mechanism.
|
||||
- Are there scroll-snap points? Record which containers.
|
||||
- Is there a smooth scroll library active? Check for non-native scroll behavior.
|
||||
|
||||
**Click sweep:** Click every element that looks interactive:
|
||||
- Every button, tab, pill, link, card
|
||||
- Record what happens: does content change? Does a modal open? Does a dropdown appear?
|
||||
- For tabs/pills: click EACH ONE and record the content that appears for each state
|
||||
|
||||
**Hover sweep:** Hover over every element that might have hover states:
|
||||
- Buttons, cards, links, images, nav items
|
||||
- Record what changes: color, scale, shadow, underline, opacity
|
||||
|
||||
**Responsive sweep:** Test at 3 viewport widths via browser MCP:
|
||||
- Desktop: 1440px
|
||||
- Tablet: 768px
|
||||
- Mobile: 390px
|
||||
- At each width, note which sections change layout (column → stack, sidebar disappears, etc.) and at approximately which breakpoint the change occurs.
|
||||
|
||||
Save all findings to `docs/research/BEHAVIORS.md`. This is your behavior bible — reference it when writing every component spec.
|
||||
|
||||
### Page Topology
|
||||
Map out every distinct section of the page from top to bottom. Give each a working name. Document:
|
||||
- Their visual order
|
||||
- Which are fixed/sticky overlays vs. flow content
|
||||
- The overall page layout (scroll container, column structure, z-index layers)
|
||||
- Dependencies between sections (e.g., a floating nav that overlays everything)
|
||||
- **The interaction model** of each section (static, click-driven, scroll-driven, time-driven)
|
||||
|
||||
Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly blueprint.
|
||||
|
||||
## Phase 2: Foundation Build
|
||||
|
||||
This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
|
||||
|
||||
1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
|
||||
2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
|
||||
3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
|
||||
4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
|
||||
5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
|
||||
6. Verify: `npm run build` passes
|
||||
|
||||
### Asset Discovery Script Pattern
|
||||
|
||||
Use browser MCP to enumerate all assets on the page:
|
||||
|
||||
```javascript
|
||||
// Run this via browser MCP to discover all assets
|
||||
JSON.stringify({
|
||||
images: [...document.querySelectorAll('img')].map(img => ({
|
||||
src: img.src || img.currentSrc,
|
||||
alt: img.alt,
|
||||
width: img.naturalWidth,
|
||||
height: img.naturalHeight,
|
||||
// Include parent info to detect layered compositions
|
||||
parentClasses: img.parentElement?.className,
|
||||
siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
|
||||
position: getComputedStyle(img).position,
|
||||
zIndex: getComputedStyle(img).zIndex
|
||||
})),
|
||||
videos: [...document.querySelectorAll('video')].map(v => ({
|
||||
src: v.src || v.querySelector('source')?.src,
|
||||
poster: v.poster,
|
||||
autoplay: v.autoplay,
|
||||
loop: v.loop,
|
||||
muted: v.muted
|
||||
})),
|
||||
backgroundImages: [...document.querySelectorAll('*')].filter(el => {
|
||||
const bg = getComputedStyle(el).backgroundImage;
|
||||
return bg && bg !== 'none';
|
||||
}).map(el => ({
|
||||
url: getComputedStyle(el).backgroundImage,
|
||||
element: el.tagName + '.' + el.className?.split(' ')[0]
|
||||
})),
|
||||
svgCount: document.querySelectorAll('svg').length,
|
||||
fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
|
||||
favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
|
||||
});
|
||||
```
|
||||
|
||||
Then write a download script that fetches everything to `public/`. Use batched parallel downloads (4 at a time) with proper error handling.
|
||||
|
||||
## Phase 3: Component Specification & Dispatch
|
||||
|
||||
This is the core loop. For each section in your page topology (top to bottom), you do THREE things: **extract**, **write the spec file**, then **dispatch builders**.
|
||||
|
||||
### Step 1: Extract
|
||||
|
||||
For each section, use browser MCP to extract everything:
|
||||
|
||||
1. **Screenshot** the section in isolation (scroll to it, screenshot the viewport). Save to `docs/design-references/`.
|
||||
|
||||
2. **Extract CSS** for every element in the section. Use the extraction script below — don't hand-measure individual properties. Run it once per component container and capture the full output:
|
||||
|
||||
```javascript
|
||||
// Per-component extraction — run via browser MCP
|
||||
// Replace SELECTOR with the actual CSS selector for the component
|
||||
(function(selector) {
|
||||
const el = document.querySelector(selector);
|
||||
if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
|
||||
const props = [
|
||||
'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
|
||||
'textTransform','textDecoration','backgroundColor','background',
|
||||
'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
|
||||
'margin','marginTop','marginRight','marginBottom','marginLeft',
|
||||
'width','height','maxWidth','minWidth','maxHeight','minHeight',
|
||||
'display','flexDirection','justifyContent','alignItems','gap',
|
||||
'gridTemplateColumns','gridTemplateRows',
|
||||
'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
|
||||
'boxShadow','overflow','overflowX','overflowY',
|
||||
'position','top','right','bottom','left','zIndex',
|
||||
'opacity','transform','transition','cursor',
|
||||
'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
|
||||
'whiteSpace','textOverflow','WebkitLineClamp'
|
||||
];
|
||||
function extractStyles(element) {
|
||||
const cs = getComputedStyle(element);
|
||||
const styles = {};
|
||||
props.forEach(p => { const v = cs[p]; if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v; });
|
||||
return styles;
|
||||
}
|
||||
function walk(element, depth) {
|
||||
if (depth > 4) return null;
|
||||
const children = [...element.children];
|
||||
return {
|
||||
tag: element.tagName.toLowerCase(),
|
||||
classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
|
||||
text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
|
||||
styles: extractStyles(element),
|
||||
images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
|
||||
childCount: children.length,
|
||||
children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
|
||||
};
|
||||
}
|
||||
return JSON.stringify(walk(el, 0), null, 2);
|
||||
})('SELECTOR');
|
||||
```
|
||||
|
||||
3. **Extract multi-state styles** — for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states:
|
||||
|
||||
```javascript
|
||||
// State A: capture styles at current state (e.g., scroll position 0)
|
||||
// Then trigger the state change (scroll, click, hover via browser MCP)
|
||||
// State B: re-run the extraction script on the same element
|
||||
// The diff between A and B IS the behavior specification
|
||||
```
|
||||
|
||||
Record the diff explicitly: "Property X changes from VALUE_A to VALUE_B, triggered by TRIGGER, with transition: TRANSITION_CSS."
|
||||
|
||||
4. **Extract real content** — all text, alt attributes, aria labels, placeholder text. Use `element.textContent` for each text node. For tabbed/stateful content, **click each tab and extract content per state**.
|
||||
|
||||
5. **Identify assets** this section uses — which downloaded images/videos from `public/`, which icon components from `icons.tsx`. Check for **layered images** (multiple `<img>` or background-images stacked in the same container).
|
||||
|
||||
6. **Assess complexity** — how many distinct sub-components does this section contain? A distinct sub-component is an element with its own unique styling, structure, and behavior (e.g., a card, a nav item, a search panel).
|
||||
|
||||
### Step 2: Write the Component Spec File
|
||||
|
||||
For each section (or sub-component, if you're breaking it up), create a spec file in `docs/research/components/`. This is NOT optional — every builder must have a corresponding spec file.
|
||||
|
||||
**File path:** `docs/research/components/<component-name>.spec.md`
|
||||
|
||||
**Template:**
|
||||
|
||||
```markdown
|
||||
# <ComponentName> Specification
|
||||
|
||||
## Overview
|
||||
- **Target file:** `src/components/<ComponentName>.tsx`
|
||||
- **Screenshot:** `docs/design-references/<screenshot-name>.png`
|
||||
- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
|
||||
|
||||
## DOM Structure
|
||||
<Describe the element hierarchy — what contains what>
|
||||
|
||||
## Computed Styles (exact values from getComputedStyle)
|
||||
|
||||
### Container
|
||||
- display: ...
|
||||
- padding: ...
|
||||
- maxWidth: ...
|
||||
- (every relevant property with exact values)
|
||||
|
||||
### <Child element 1>
|
||||
- fontSize: ...
|
||||
- color: ...
|
||||
- (every relevant property)
|
||||
|
||||
### <Child element N>
|
||||
...
|
||||
|
||||
## States & Behaviors
|
||||
|
||||
### <Behavior name, e.g., "Scroll-triggered floating mode">
|
||||
- **Trigger:** <exact mechanism — scroll position 50px, IntersectionObserver rootMargin "-30% 0px", click on .tab-button, hover>
|
||||
- **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
|
||||
- **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
|
||||
- **Transition:** transition: all 0.3s ease
|
||||
- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
|
||||
|
||||
### Hover states
|
||||
- **<Element>:** <property>: <before> → <after>, transition: <value>
|
||||
|
||||
## Per-State Content (if applicable)
|
||||
|
||||
### State: "Featured"
|
||||
- Title: "..."
|
||||
- Subtitle: "..."
|
||||
- Cards: [{ title, description, image, link }, ...]
|
||||
|
||||
### State: "Productivity"
|
||||
- Title: "..."
|
||||
- Cards: [...]
|
||||
|
||||
## Assets
|
||||
- Background image: `public/images/<file>.webp`
|
||||
- Overlay image: `public/images/<file>.png`
|
||||
- Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
|
||||
|
||||
## Text Content (verbatim)
|
||||
<All text content, copy-pasted from the live site>
|
||||
|
||||
## Responsive Behavior
|
||||
- **Desktop (1440px):** <layout description>
|
||||
- **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
|
||||
- **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
|
||||
- **Breakpoint:** layout switches at ~<N>px
|
||||
```
|
||||
|
||||
Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
|
||||
|
||||
### Step 3: Dispatch Builders
|
||||
|
||||
Based on complexity, dispatch builder agent(s) in worktree(s):
|
||||
|
||||
**Simple section** (1-2 sub-components): One builder agent gets the entire section.
|
||||
|
||||
**Complex section** (3+ distinct sub-components): Break it up. One agent per sub-component, plus one agent for the section wrapper that imports them. Sub-component builders go first since the wrapper depends on them.
|
||||
|
||||
**What every builder agent receives:**
|
||||
- The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
|
||||
- Path to the section screenshot in `docs/design-references/`
|
||||
- Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
|
||||
- The target file path (e.g., `src/components/HeroSection.tsx`)
|
||||
- Instruction to verify with `npx tsc --noEmit` before finishing
|
||||
- For responsive behavior: the specific breakpoint values and what changes
|
||||
|
||||
**Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
|
||||
|
||||
### Step 4: Merge
|
||||
|
||||
As builder agents complete their work:
|
||||
- Merge their worktree branches into main
|
||||
- You have full context on what each agent built, so resolve any conflicts intelligently
|
||||
- After each merge, verify the build still passes: `npm run build`
|
||||
- If a merge introduces type errors, fix them immediately
|
||||
|
||||
The extract → spec → dispatch → merge cycle continues until all sections are built.
|
||||
|
||||
## Phase 4: Page Assembly
|
||||
|
||||
After all sections are built and merged, wire everything together in `src/app/page.tsx`:
|
||||
|
||||
- Import all section components
|
||||
- Implement the page-level layout from your topology doc (scroll containers, column structures, sticky positioning, z-index layering)
|
||||
- Connect real content to component props
|
||||
- Implement page-level behaviors: scroll snap, scroll-driven animations, dark-to-light transitions, intersection observers, smooth scroll (Lenis etc.)
|
||||
- Verify: `npm run build` passes clean
|
||||
|
||||
## Phase 5: Visual QA Diff
|
||||
|
||||
After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
|
||||
|
||||
1. Open the original site and your clone side-by-side (or take screenshots at the same viewport widths)
|
||||
2. Compare section by section, top to bottom, at desktop (1440px)
|
||||
3. Compare again at mobile (390px)
|
||||
4. For each discrepancy found:
|
||||
- Check the component spec file — was the value extracted correctly?
|
||||
- If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
|
||||
- If the spec was right but the builder got it wrong: fix the component to match the spec
|
||||
5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
|
||||
6. Verify smooth scroll feels right, header transitions work, tab switching works, animations play
|
||||
|
||||
Only after this visual QA pass is the clone complete.
|
||||
|
||||
## Pre-Dispatch Checklist
|
||||
|
||||
Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
|
||||
|
||||
- [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
|
||||
- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
|
||||
- [ ] Interaction model is identified and documented (static / click / scroll / time)
|
||||
- [ ] For stateful components: every state's content and styles are captured
|
||||
- [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
|
||||
- [ ] For hover states: before/after values and transition timing are recorded
|
||||
- [ ] All images in the section are identified (including overlays and layered compositions)
|
||||
- [ ] Responsive behavior is documented for at least desktop and mobile
|
||||
- [ ] Text content is verbatim from the site, not paraphrased
|
||||
- [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
These are lessons from previous failed clones — each one cost hours of rework:
|
||||
|
||||
- **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
|
||||
- **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
|
||||
- **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
|
||||
- **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
|
||||
- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
|
||||
- **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
|
||||
- **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
|
||||
- **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
|
||||
- **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
|
||||
- **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
|
||||
- **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
|
||||
- **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
|
||||
- **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
|
||||
|
||||
## Completion
|
||||
|
||||
When done, report:
|
||||
- Total sections built
|
||||
- Total components created
|
||||
- Total spec files written (should match components)
|
||||
- Total assets downloaded (images, videos, SVGs, fonts)
|
||||
- Build status (`npm run build` result)
|
||||
- Visual QA results (any remaining discrepancies)
|
||||
- Any known gaps or limitations
|
||||
@@ -0,0 +1,151 @@
|
||||
<!-- AUTO-GENERATED from AGENTS.md — do not edit directly.
|
||||
Run `bash scripts/sync-agent-rules.sh` to regenerate. -->
|
||||
|
||||
---
|
||||
description: Project conventions for AI Website Clone Template
|
||||
alwaysApply: true
|
||||
---
|
||||
<!-- BEGIN:nextjs-agent-rules -->
|
||||
# This is NOT the Next.js you know
|
||||
|
||||
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
|
||||
<!-- END:nextjs-agent-rules -->
|
||||
|
||||
# Website Reverse-Engineer Template
|
||||
|
||||
## What This Is
|
||||
A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — just run `/clone-website <url1> [<url2> ...]`.
|
||||
|
||||
## Tech Stack
|
||||
- **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
|
||||
- **UI:** shadcn/ui (Radix primitives, Tailwind CSS v4, `cn()` utility)
|
||||
- **Icons:** Lucide React (default — will be replaced/supplemented by extracted SVGs)
|
||||
- **Styling:** Tailwind CSS v4 with oklch design tokens
|
||||
- **Deployment:** Vercel
|
||||
|
||||
## Commands
|
||||
- `npm run dev` — Start dev server
|
||||
- `npm run build` — Production build
|
||||
- `npm run lint` — ESLint check
|
||||
- `npm run typecheck` — TypeScript check
|
||||
- `npm run check` — Run lint + typecheck + build
|
||||
|
||||
## Code Style
|
||||
- TypeScript strict mode, no `any`
|
||||
- Named exports, PascalCase components, camelCase utils
|
||||
- Tailwind utility classes, no inline styles
|
||||
- 2-space indentation
|
||||
- Responsive: mobile-first
|
||||
|
||||
## Design Principles
|
||||
- **Pixel-perfect emulation** — match the target's spacing, colors, typography exactly
|
||||
- **No personal aesthetic changes during emulation phase** — match 1:1 first, customize later
|
||||
- **Real content** — use actual text and assets from the target site, not placeholders
|
||||
- **Beauty-first** — every pixel matters
|
||||
|
||||
## Project Structure
|
||||
```
|
||||
src/
|
||||
app/ # Next.js routes
|
||||
components/ # React components
|
||||
ui/ # shadcn/ui primitives
|
||||
icons.tsx # Extracted SVG icons as React components
|
||||
lib/
|
||||
utils.ts # cn() utility (shadcn)
|
||||
types/ # TypeScript interfaces
|
||||
hooks/ # Custom React hooks
|
||||
public/
|
||||
images/ # Downloaded images from target site
|
||||
videos/ # Downloaded videos from target site
|
||||
seo/ # Favicons, OG images, webmanifest
|
||||
docs/
|
||||
research/ # Inspection output (design tokens, components, layout)
|
||||
design-references/ # Screenshots and visual references
|
||||
scripts/ # Asset download scripts
|
||||
```
|
||||
|
||||
## MOST IMPORTANT NOTES
|
||||
- When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
|
||||
- After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
|
||||
- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
|
||||
|
||||
# Website Inspection Guide
|
||||
|
||||
## How to Reverse-Engineer Any Website
|
||||
|
||||
This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
|
||||
|
||||
## Phase 1: Visual Audit
|
||||
|
||||
### Screenshots to Capture
|
||||
- [ ] Every distinct page — desktop, tablet, mobile
|
||||
- [ ] Dark mode variants (if applicable)
|
||||
- [ ] Light mode variants (if applicable)
|
||||
- [ ] Key interaction states (hover, active, open menus, modals)
|
||||
- [ ] Loading/skeleton states
|
||||
- [ ] Empty states
|
||||
- [ ] Error states
|
||||
|
||||
### Design Tokens to Extract
|
||||
- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
|
||||
- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
|
||||
- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
|
||||
- [ ] **Border radius** — buttons, cards, avatars, inputs
|
||||
- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
|
||||
- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
|
||||
- [ ] **Icons** — which icon library? custom SVGs? sizes?
|
||||
- [ ] **Avatars** — sizes, shapes, fallback behavior
|
||||
- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
|
||||
- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
|
||||
|
||||
## Phase 2: Component Inventory
|
||||
|
||||
For each distinct UI component, document:
|
||||
1. **Name** — what would you call this component?
|
||||
2. **Structure** — what HTML elements / child components does it contain?
|
||||
3. **Variants** — does it have different sizes, colors, or states?
|
||||
4. **States** — default, hover, active, disabled, loading, error, empty
|
||||
5. **Responsive behavior** — how does it change at different breakpoints?
|
||||
6. **Interactions** — click, hover, focus, keyboard navigation
|
||||
7. **Animations** — transitions, entrance/exit animations, micro-interactions
|
||||
|
||||
### Common Components to Look For
|
||||
- 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
|
||||
|
||||
## Phase 3: Layout Architecture
|
||||
|
||||
- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
|
||||
- [ ] **Column layout** — how many columns at each breakpoint?
|
||||
- [ ] **Max-width** — main content area max-width
|
||||
- [ ] **Sticky elements** — header, sidebar, floating buttons
|
||||
- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
|
||||
- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
|
||||
|
||||
## Phase 4: Technical Stack Analysis
|
||||
|
||||
- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
|
||||
- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
|
||||
- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
|
||||
- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
|
||||
- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
|
||||
- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF
|
||||
- [ ] **Animation library** — Framer Motion, GSAP, CSS transitions only
|
||||
|
||||
## Phase 5: Documentation Output
|
||||
|
||||
After inspection, create these files in `docs/research/`:
|
||||
1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
|
||||
2. `COMPONENT_INVENTORY.md` — Every component with structure notes
|
||||
3. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
|
||||
4. `INTERACTION_PATTERNS.md` — Animations, transitions, hover states
|
||||
5. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents
|
||||
@@ -0,0 +1,470 @@
|
||||
<!-- AUTO-GENERATED from .claude/skills/clone-website/SKILL.md — do not edit directly.
|
||||
Run `node scripts/sync-skills.mjs` to regenerate. -->
|
||||
|
||||
|
||||
# Clone Website
|
||||
|
||||
You are about to reverse-engineer and rebuild **the target URL provided by the user** as pixel-perfect clones.
|
||||
|
||||
When multiple URLs are provided, process them independently and in parallel where possible, while keeping each site's extraction artifacts isolated in dedicated folders (for example, `docs/research/<hostname>/`).
|
||||
|
||||
This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
|
||||
|
||||
## Scope Defaults
|
||||
|
||||
The target is whatever page `the target URL provided by the user` resolves to. Clone exactly what's visible at that URL. Unless the user specifies otherwise, use these defaults:
|
||||
|
||||
- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, animations
|
||||
- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
|
||||
- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
|
||||
- **Customization:** None — pure emulation
|
||||
|
||||
If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
|
||||
|
||||
## Pre-Flight
|
||||
|
||||
1. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
|
||||
2. Parse `the target URL provided by the user` as one or more URLs. Normalize and validate each URL; if any are invalid, ask the user to correct them before proceeding. For each valid URL, verify it is accessible via your browser MCP tool.
|
||||
3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
|
||||
4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
|
||||
5. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
|
||||
|
||||
### 1. Completeness Beats Speed
|
||||
|
||||
Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
|
||||
|
||||
### 2. Small Tasks, Perfect Results
|
||||
|
||||
When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
|
||||
|
||||
Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
|
||||
|
||||
**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
|
||||
|
||||
### 3. Real Content, Real Assets
|
||||
|
||||
Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
|
||||
|
||||
**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays. Missing an overlay image makes the clone look empty even if the background is correct.
|
||||
|
||||
### 4. Foundation First
|
||||
|
||||
Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
|
||||
|
||||
### 5. Extract How It Looks AND How It Behaves
|
||||
|
||||
A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
|
||||
|
||||
For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens). Not "it looks like 16px" — extract the actual computed value. Not "the nav changes on scroll" — document the exact trigger (scroll position, IntersectionObserver threshold, viewport intersection), the before and after states (both sets of CSS values), and the transition (duration, easing, CSS transition vs. JS-driven vs. CSS `animation-timeline`).
|
||||
|
||||
Examples of behaviors to watch for — these are illustrative, not exhaustive. The page may do things not on this list, and you must catch those too:
|
||||
- A navbar that shrinks, changes background, or gains a shadow after scrolling past a threshold
|
||||
- Elements that animate into view when they enter the viewport (fade-up, slide-in, stagger delays)
|
||||
- Sections that snap into place on scroll (`scroll-snap-type`)
|
||||
- Parallax layers that move at different rates than the scroll
|
||||
- Hover states that animate (not just change — the transition duration and easing matter)
|
||||
- Dropdowns, modals, accordions with enter/exit animations
|
||||
- Scroll-driven progress indicators or opacity transitions
|
||||
- Auto-playing carousels or cycling content
|
||||
- Dark-to-light (or any theme) transitions between page sections
|
||||
- **Tabbed/pill content that cycles** — buttons that switch visible card sets with transitions
|
||||
- **Scroll-driven tab/accordion switching** — sidebars where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
|
||||
- **Smooth scroll libraries** (Lenis, Locomotive Scroll) — check for `.lenis` class or scroll container wrappers
|
||||
|
||||
### 6. Identify the Interaction Model Before Building
|
||||
|
||||
This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa. Before writing any builder prompt for an interactive section, you must definitively answer: **Is this section driven by clicks, scrolls, hovers, time, or some combination?**
|
||||
|
||||
How to determine this:
|
||||
1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
|
||||
2. If they do, it's scroll-driven. Extract the mechanism: `IntersectionObserver`, `scroll-snap`, `position: sticky`, `animation-timeline`, or JS scroll listeners.
|
||||
3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
|
||||
4. Document the interaction model explicitly in the component spec: "INTERACTION MODEL: scroll-driven with IntersectionObserver" or "INTERACTION MODEL: click-to-switch with opacity transition."
|
||||
|
||||
A section with a sticky sidebar and scrolling content panels is fundamentally different from a tabbed interface where clicking switches content. Getting this wrong means a complete rewrite, not a CSS tweak.
|
||||
|
||||
### 7. Extract Every State, Not Just the Default
|
||||
|
||||
Many components have multiple visual states — a tab bar shows different cards per tab, a header looks different at scroll position 0 vs 100, a card has hover effects. You must extract ALL states, not just whatever is visible on page load.
|
||||
|
||||
For tabbed/stateful content:
|
||||
- Click each tab/button via browser MCP
|
||||
- Extract the content, images, and card data for EACH state
|
||||
- Record which content belongs to which state
|
||||
- Note the transition animation between states (opacity, slide, fade, etc.)
|
||||
|
||||
For scroll-dependent elements:
|
||||
- Capture computed styles at scroll position 0 (initial state)
|
||||
- Scroll past the trigger threshold and capture computed styles again (scrolled state)
|
||||
- Diff the two to identify exactly which CSS properties change
|
||||
- Record the transition CSS (duration, easing, properties)
|
||||
- Record the exact trigger threshold (scroll position in px, or viewport intersection ratio)
|
||||
|
||||
### 8. Spec Files Are the Source of Truth
|
||||
|
||||
Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. This file is the contract between your extraction work and the builder agent. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact that the user (or you) can review if something looks wrong.
|
||||
|
||||
The spec file is not optional. It is not a nice-to-have. If you dispatch a builder without first writing a spec file, you are shipping incomplete instructions based on whatever you can remember from a browser MCP session, and the builder will guess to fill gaps.
|
||||
|
||||
### 9. Build Must Always Compile
|
||||
|
||||
Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
|
||||
|
||||
## Phase 1: Reconnaissance
|
||||
|
||||
Navigate to the target URL with browser MCP.
|
||||
|
||||
### Screenshots
|
||||
- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
|
||||
- Save to `docs/design-references/` with descriptive names
|
||||
- These are your master reference — builders will receive section-specific crops/screenshots later
|
||||
|
||||
### Global Extraction
|
||||
Extract these from the page before doing anything else:
|
||||
|
||||
**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements (headings, body, code, labels). Document every family, weight, and style actually used. Configure them in `src/app/layout.tsx` using `next/font/google` or `next/font/local`.
|
||||
|
||||
**Colors** — Extract the site's color palette from computed styles across the page. Update `src/app/globals.css` with the target's actual colors in the `:root` and `.dark` CSS variable blocks. Map them to shadcn's token names (background, foreground, primary, muted, etc.) where they fit. Add custom properties for colors that don't map to shadcn tokens.
|
||||
|
||||
**Favicons & Meta** — Download favicons, apple-touch-icons, OG images, webmanifest to `public/seo/`. Update `layout.tsx` metadata.
|
||||
|
||||
**Global UI patterns** — Identify any site-wide CSS or JS: custom scrollbar hiding, scroll-snap on the page container, global keyframe animations, backdrop filters, gradients used as overlays, **smooth scroll libraries** (Lenis, Locomotive Scroll — check for `.lenis`, `.locomotive-scroll`, or custom scroll container classes). Add these to `globals.css` and note any libraries that need to be installed.
|
||||
|
||||
### Mandatory Interaction Sweep
|
||||
|
||||
This is a dedicated pass AFTER screenshots and BEFORE anything else. Its purpose is to discover every behavior on the page — many of which are invisible in a static screenshot.
|
||||
|
||||
**Scroll sweep:** Scroll the page slowly from top to bottom via browser MCP. At each section, pause and observe:
|
||||
- Does the header change appearance? Record the scroll position where it triggers.
|
||||
- Do elements animate into view? Record which ones and the animation type.
|
||||
- Does a sidebar or tab indicator auto-switch as you scroll? Record the mechanism.
|
||||
- Are there scroll-snap points? Record which containers.
|
||||
- Is there a smooth scroll library active? Check for non-native scroll behavior.
|
||||
|
||||
**Click sweep:** Click every element that looks interactive:
|
||||
- Every button, tab, pill, link, card
|
||||
- Record what happens: does content change? Does a modal open? Does a dropdown appear?
|
||||
- For tabs/pills: click EACH ONE and record the content that appears for each state
|
||||
|
||||
**Hover sweep:** Hover over every element that might have hover states:
|
||||
- Buttons, cards, links, images, nav items
|
||||
- Record what changes: color, scale, shadow, underline, opacity
|
||||
|
||||
**Responsive sweep:** Test at 3 viewport widths via browser MCP:
|
||||
- Desktop: 1440px
|
||||
- Tablet: 768px
|
||||
- Mobile: 390px
|
||||
- At each width, note which sections change layout (column → stack, sidebar disappears, etc.) and at approximately which breakpoint the change occurs.
|
||||
|
||||
Save all findings to `docs/research/BEHAVIORS.md`. This is your behavior bible — reference it when writing every component spec.
|
||||
|
||||
### Page Topology
|
||||
Map out every distinct section of the page from top to bottom. Give each a working name. Document:
|
||||
- Their visual order
|
||||
- Which are fixed/sticky overlays vs. flow content
|
||||
- The overall page layout (scroll container, column structure, z-index layers)
|
||||
- Dependencies between sections (e.g., a floating nav that overlays everything)
|
||||
- **The interaction model** of each section (static, click-driven, scroll-driven, time-driven)
|
||||
|
||||
Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly blueprint.
|
||||
|
||||
## Phase 2: Foundation Build
|
||||
|
||||
This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
|
||||
|
||||
1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
|
||||
2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
|
||||
3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
|
||||
4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
|
||||
5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
|
||||
6. Verify: `npm run build` passes
|
||||
|
||||
### Asset Discovery Script Pattern
|
||||
|
||||
Use browser MCP to enumerate all assets on the page:
|
||||
|
||||
```javascript
|
||||
// Run this via browser MCP to discover all assets
|
||||
JSON.stringify({
|
||||
images: [...document.querySelectorAll('img')].map(img => ({
|
||||
src: img.src || img.currentSrc,
|
||||
alt: img.alt,
|
||||
width: img.naturalWidth,
|
||||
height: img.naturalHeight,
|
||||
// Include parent info to detect layered compositions
|
||||
parentClasses: img.parentElement?.className,
|
||||
siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
|
||||
position: getComputedStyle(img).position,
|
||||
zIndex: getComputedStyle(img).zIndex
|
||||
})),
|
||||
videos: [...document.querySelectorAll('video')].map(v => ({
|
||||
src: v.src || v.querySelector('source')?.src,
|
||||
poster: v.poster,
|
||||
autoplay: v.autoplay,
|
||||
loop: v.loop,
|
||||
muted: v.muted
|
||||
})),
|
||||
backgroundImages: [...document.querySelectorAll('*')].filter(el => {
|
||||
const bg = getComputedStyle(el).backgroundImage;
|
||||
return bg && bg !== 'none';
|
||||
}).map(el => ({
|
||||
url: getComputedStyle(el).backgroundImage,
|
||||
element: el.tagName + '.' + el.className?.split(' ')[0]
|
||||
})),
|
||||
svgCount: document.querySelectorAll('svg').length,
|
||||
fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
|
||||
favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
|
||||
});
|
||||
```
|
||||
|
||||
Then write a download script that fetches everything to `public/`. Use batched parallel downloads (4 at a time) with proper error handling.
|
||||
|
||||
## Phase 3: Component Specification & Dispatch
|
||||
|
||||
This is the core loop. For each section in your page topology (top to bottom), you do THREE things: **extract**, **write the spec file**, then **dispatch builders**.
|
||||
|
||||
### Step 1: Extract
|
||||
|
||||
For each section, use browser MCP to extract everything:
|
||||
|
||||
1. **Screenshot** the section in isolation (scroll to it, screenshot the viewport). Save to `docs/design-references/`.
|
||||
|
||||
2. **Extract CSS** for every element in the section. Use the extraction script below — don't hand-measure individual properties. Run it once per component container and capture the full output:
|
||||
|
||||
```javascript
|
||||
// Per-component extraction — run via browser MCP
|
||||
// Replace SELECTOR with the actual CSS selector for the component
|
||||
(function(selector) {
|
||||
const el = document.querySelector(selector);
|
||||
if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
|
||||
const props = [
|
||||
'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
|
||||
'textTransform','textDecoration','backgroundColor','background',
|
||||
'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
|
||||
'margin','marginTop','marginRight','marginBottom','marginLeft',
|
||||
'width','height','maxWidth','minWidth','maxHeight','minHeight',
|
||||
'display','flexDirection','justifyContent','alignItems','gap',
|
||||
'gridTemplateColumns','gridTemplateRows',
|
||||
'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
|
||||
'boxShadow','overflow','overflowX','overflowY',
|
||||
'position','top','right','bottom','left','zIndex',
|
||||
'opacity','transform','transition','cursor',
|
||||
'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
|
||||
'whiteSpace','textOverflow','WebkitLineClamp'
|
||||
];
|
||||
function extractStyles(element) {
|
||||
const cs = getComputedStyle(element);
|
||||
const styles = {};
|
||||
props.forEach(p => { const v = cs[p]; if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v; });
|
||||
return styles;
|
||||
}
|
||||
function walk(element, depth) {
|
||||
if (depth > 4) return null;
|
||||
const children = [...element.children];
|
||||
return {
|
||||
tag: element.tagName.toLowerCase(),
|
||||
classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
|
||||
text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
|
||||
styles: extractStyles(element),
|
||||
images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
|
||||
childCount: children.length,
|
||||
children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
|
||||
};
|
||||
}
|
||||
return JSON.stringify(walk(el, 0), null, 2);
|
||||
})('SELECTOR');
|
||||
```
|
||||
|
||||
3. **Extract multi-state styles** — for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states:
|
||||
|
||||
```javascript
|
||||
// State A: capture styles at current state (e.g., scroll position 0)
|
||||
// Then trigger the state change (scroll, click, hover via browser MCP)
|
||||
// State B: re-run the extraction script on the same element
|
||||
// The diff between A and B IS the behavior specification
|
||||
```
|
||||
|
||||
Record the diff explicitly: "Property X changes from VALUE_A to VALUE_B, triggered by TRIGGER, with transition: TRANSITION_CSS."
|
||||
|
||||
4. **Extract real content** — all text, alt attributes, aria labels, placeholder text. Use `element.textContent` for each text node. For tabbed/stateful content, **click each tab and extract content per state**.
|
||||
|
||||
5. **Identify assets** this section uses — which downloaded images/videos from `public/`, which icon components from `icons.tsx`. Check for **layered images** (multiple `<img>` or background-images stacked in the same container).
|
||||
|
||||
6. **Assess complexity** — how many distinct sub-components does this section contain? A distinct sub-component is an element with its own unique styling, structure, and behavior (e.g., a card, a nav item, a search panel).
|
||||
|
||||
### Step 2: Write the Component Spec File
|
||||
|
||||
For each section (or sub-component, if you're breaking it up), create a spec file in `docs/research/components/`. This is NOT optional — every builder must have a corresponding spec file.
|
||||
|
||||
**File path:** `docs/research/components/<component-name>.spec.md`
|
||||
|
||||
**Template:**
|
||||
|
||||
```markdown
|
||||
# <ComponentName> Specification
|
||||
|
||||
## Overview
|
||||
- **Target file:** `src/components/<ComponentName>.tsx`
|
||||
- **Screenshot:** `docs/design-references/<screenshot-name>.png`
|
||||
- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
|
||||
|
||||
## DOM Structure
|
||||
<Describe the element hierarchy — what contains what>
|
||||
|
||||
## Computed Styles (exact values from getComputedStyle)
|
||||
|
||||
### Container
|
||||
- display: ...
|
||||
- padding: ...
|
||||
- maxWidth: ...
|
||||
- (every relevant property with exact values)
|
||||
|
||||
### <Child element 1>
|
||||
- fontSize: ...
|
||||
- color: ...
|
||||
- (every relevant property)
|
||||
|
||||
### <Child element N>
|
||||
...
|
||||
|
||||
## States & Behaviors
|
||||
|
||||
### <Behavior name, e.g., "Scroll-triggered floating mode">
|
||||
- **Trigger:** <exact mechanism — scroll position 50px, IntersectionObserver rootMargin "-30% 0px", click on .tab-button, hover>
|
||||
- **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
|
||||
- **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
|
||||
- **Transition:** transition: all 0.3s ease
|
||||
- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
|
||||
|
||||
### Hover states
|
||||
- **<Element>:** <property>: <before> → <after>, transition: <value>
|
||||
|
||||
## Per-State Content (if applicable)
|
||||
|
||||
### State: "Featured"
|
||||
- Title: "..."
|
||||
- Subtitle: "..."
|
||||
- Cards: [{ title, description, image, link }, ...]
|
||||
|
||||
### State: "Productivity"
|
||||
- Title: "..."
|
||||
- Cards: [...]
|
||||
|
||||
## Assets
|
||||
- Background image: `public/images/<file>.webp`
|
||||
- Overlay image: `public/images/<file>.png`
|
||||
- Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
|
||||
|
||||
## Text Content (verbatim)
|
||||
<All text content, copy-pasted from the live site>
|
||||
|
||||
## Responsive Behavior
|
||||
- **Desktop (1440px):** <layout description>
|
||||
- **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
|
||||
- **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
|
||||
- **Breakpoint:** layout switches at ~<N>px
|
||||
```
|
||||
|
||||
Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
|
||||
|
||||
### Step 3: Dispatch Builders
|
||||
|
||||
Based on complexity, dispatch builder agent(s) in worktree(s):
|
||||
|
||||
**Simple section** (1-2 sub-components): One builder agent gets the entire section.
|
||||
|
||||
**Complex section** (3+ distinct sub-components): Break it up. One agent per sub-component, plus one agent for the section wrapper that imports them. Sub-component builders go first since the wrapper depends on them.
|
||||
|
||||
**What every builder agent receives:**
|
||||
- The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
|
||||
- Path to the section screenshot in `docs/design-references/`
|
||||
- Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
|
||||
- The target file path (e.g., `src/components/HeroSection.tsx`)
|
||||
- Instruction to verify with `npx tsc --noEmit` before finishing
|
||||
- For responsive behavior: the specific breakpoint values and what changes
|
||||
|
||||
**Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
|
||||
|
||||
### Step 4: Merge
|
||||
|
||||
As builder agents complete their work:
|
||||
- Merge their worktree branches into main
|
||||
- You have full context on what each agent built, so resolve any conflicts intelligently
|
||||
- After each merge, verify the build still passes: `npm run build`
|
||||
- If a merge introduces type errors, fix them immediately
|
||||
|
||||
The extract → spec → dispatch → merge cycle continues until all sections are built.
|
||||
|
||||
## Phase 4: Page Assembly
|
||||
|
||||
After all sections are built and merged, wire everything together in `src/app/page.tsx`:
|
||||
|
||||
- Import all section components
|
||||
- Implement the page-level layout from your topology doc (scroll containers, column structures, sticky positioning, z-index layering)
|
||||
- Connect real content to component props
|
||||
- Implement page-level behaviors: scroll snap, scroll-driven animations, dark-to-light transitions, intersection observers, smooth scroll (Lenis etc.)
|
||||
- Verify: `npm run build` passes clean
|
||||
|
||||
## Phase 5: Visual QA Diff
|
||||
|
||||
After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
|
||||
|
||||
1. Open the original site and your clone side-by-side (or take screenshots at the same viewport widths)
|
||||
2. Compare section by section, top to bottom, at desktop (1440px)
|
||||
3. Compare again at mobile (390px)
|
||||
4. For each discrepancy found:
|
||||
- Check the component spec file — was the value extracted correctly?
|
||||
- If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
|
||||
- If the spec was right but the builder got it wrong: fix the component to match the spec
|
||||
5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
|
||||
6. Verify smooth scroll feels right, header transitions work, tab switching works, animations play
|
||||
|
||||
Only after this visual QA pass is the clone complete.
|
||||
|
||||
## Pre-Dispatch Checklist
|
||||
|
||||
Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
|
||||
|
||||
- [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
|
||||
- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
|
||||
- [ ] Interaction model is identified and documented (static / click / scroll / time)
|
||||
- [ ] For stateful components: every state's content and styles are captured
|
||||
- [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
|
||||
- [ ] For hover states: before/after values and transition timing are recorded
|
||||
- [ ] All images in the section are identified (including overlays and layered compositions)
|
||||
- [ ] Responsive behavior is documented for at least desktop and mobile
|
||||
- [ ] Text content is verbatim from the site, not paraphrased
|
||||
- [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
These are lessons from previous failed clones — each one cost hours of rework:
|
||||
|
||||
- **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
|
||||
- **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
|
||||
- **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
|
||||
- **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
|
||||
- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
|
||||
- **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
|
||||
- **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
|
||||
- **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
|
||||
- **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
|
||||
- **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
|
||||
- **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
|
||||
- **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
|
||||
- **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
|
||||
|
||||
## Completion
|
||||
|
||||
When done, report:
|
||||
- Total sections built
|
||||
- Total components created
|
||||
- Total spec files written (should match components)
|
||||
- Total assets downloaded (images, videos, SVGs, fonts)
|
||||
- Build status (`npm run build` result)
|
||||
- Visual QA results (any remaining discrepancies)
|
||||
- Any known gaps or limitations
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
description: Project conventions — see AGENTS.md for full details
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
This project uses AGENTS.md as the single source of truth for all AI agent instructions.
|
||||
Cursor reads AGENTS.md automatically — see the project root for complete guidelines.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Dependencies (reinstalled inside Docker)
|
||||
node_modules
|
||||
pnpm-debug.log*
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
|
||||
# Build output
|
||||
.next
|
||||
out
|
||||
build
|
||||
dist
|
||||
|
||||
# Git
|
||||
.git
|
||||
.gitignore
|
||||
|
||||
# Environment files (pass via docker-compose env_file or runtime env vars)
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
# Editor / OS
|
||||
.vscode
|
||||
.idea
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
*.swp
|
||||
*.swo
|
||||
|
||||
# Agent / AI tool configs (not needed at runtime)
|
||||
.claude
|
||||
.codex
|
||||
.cursor
|
||||
.windsurf
|
||||
.gemini
|
||||
.continue
|
||||
.amazonq
|
||||
.augment
|
||||
.opencode
|
||||
.aider.conf.yml
|
||||
.clinerules
|
||||
.windsurfrules
|
||||
AGENTS.md
|
||||
CLAUDE.md
|
||||
GEMINI.md
|
||||
|
||||
# Docs / research (large, not needed at runtime)
|
||||
docs
|
||||
scripts
|
||||
|
||||
# Docker files themselves (no need to copy into image)
|
||||
Dockerfile
|
||||
docker-compose.yml
|
||||
.dockerignore
|
||||
|
||||
# Misc
|
||||
*.tsbuildinfo
|
||||
README.md
|
||||
CHANGELOG.md
|
||||
LICENSE
|
||||
@@ -0,0 +1,476 @@
|
||||
# AUTO-GENERATED from .claude/skills/clone-website/SKILL.md
|
||||
# Run `node scripts/sync-skills.mjs` to regenerate.
|
||||
|
||||
description = "Reverse-engineer and clone any website as a pixel-perfect replica"
|
||||
name = "clone-website"
|
||||
|
||||
prompt = '''
|
||||
|
||||
# Clone Website
|
||||
|
||||
You are about to reverse-engineer and rebuild **{{args}}** as pixel-perfect clones.
|
||||
|
||||
When multiple URLs are provided, process them independently and in parallel where possible, while keeping each site's extraction artifacts isolated in dedicated folders (for example, `docs/research/<hostname>/`).
|
||||
|
||||
This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
|
||||
|
||||
## Scope Defaults
|
||||
|
||||
The target is whatever page `{{args}}` resolves to. Clone exactly what's visible at that URL. Unless the user specifies otherwise, use these defaults:
|
||||
|
||||
- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, animations
|
||||
- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
|
||||
- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
|
||||
- **Customization:** None — pure emulation
|
||||
|
||||
If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
|
||||
|
||||
## Pre-Flight
|
||||
|
||||
1. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
|
||||
2. Parse `{{args}}` as one or more URLs. Normalize and validate each URL; if any are invalid, ask the user to correct them before proceeding. For each valid URL, verify it is accessible via your browser MCP tool.
|
||||
3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
|
||||
4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
|
||||
5. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
|
||||
|
||||
### 1. Completeness Beats Speed
|
||||
|
||||
Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
|
||||
|
||||
### 2. Small Tasks, Perfect Results
|
||||
|
||||
When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
|
||||
|
||||
Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
|
||||
|
||||
**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
|
||||
|
||||
### 3. Real Content, Real Assets
|
||||
|
||||
Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
|
||||
|
||||
**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays. Missing an overlay image makes the clone look empty even if the background is correct.
|
||||
|
||||
### 4. Foundation First
|
||||
|
||||
Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
|
||||
|
||||
### 5. Extract How It Looks AND How It Behaves
|
||||
|
||||
A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
|
||||
|
||||
For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens). Not "it looks like 16px" — extract the actual computed value. Not "the nav changes on scroll" — document the exact trigger (scroll position, IntersectionObserver threshold, viewport intersection), the before and after states (both sets of CSS values), and the transition (duration, easing, CSS transition vs. JS-driven vs. CSS `animation-timeline`).
|
||||
|
||||
Examples of behaviors to watch for — these are illustrative, not exhaustive. The page may do things not on this list, and you must catch those too:
|
||||
- A navbar that shrinks, changes background, or gains a shadow after scrolling past a threshold
|
||||
- Elements that animate into view when they enter the viewport (fade-up, slide-in, stagger delays)
|
||||
- Sections that snap into place on scroll (`scroll-snap-type`)
|
||||
- Parallax layers that move at different rates than the scroll
|
||||
- Hover states that animate (not just change — the transition duration and easing matter)
|
||||
- Dropdowns, modals, accordions with enter/exit animations
|
||||
- Scroll-driven progress indicators or opacity transitions
|
||||
- Auto-playing carousels or cycling content
|
||||
- Dark-to-light (or any theme) transitions between page sections
|
||||
- **Tabbed/pill content that cycles** — buttons that switch visible card sets with transitions
|
||||
- **Scroll-driven tab/accordion switching** — sidebars where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
|
||||
- **Smooth scroll libraries** (Lenis, Locomotive Scroll) — check for `.lenis` class or scroll container wrappers
|
||||
|
||||
### 6. Identify the Interaction Model Before Building
|
||||
|
||||
This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa. Before writing any builder prompt for an interactive section, you must definitively answer: **Is this section driven by clicks, scrolls, hovers, time, or some combination?**
|
||||
|
||||
How to determine this:
|
||||
1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
|
||||
2. If they do, it's scroll-driven. Extract the mechanism: `IntersectionObserver`, `scroll-snap`, `position: sticky`, `animation-timeline`, or JS scroll listeners.
|
||||
3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
|
||||
4. Document the interaction model explicitly in the component spec: "INTERACTION MODEL: scroll-driven with IntersectionObserver" or "INTERACTION MODEL: click-to-switch with opacity transition."
|
||||
|
||||
A section with a sticky sidebar and scrolling content panels is fundamentally different from a tabbed interface where clicking switches content. Getting this wrong means a complete rewrite, not a CSS tweak.
|
||||
|
||||
### 7. Extract Every State, Not Just the Default
|
||||
|
||||
Many components have multiple visual states — a tab bar shows different cards per tab, a header looks different at scroll position 0 vs 100, a card has hover effects. You must extract ALL states, not just whatever is visible on page load.
|
||||
|
||||
For tabbed/stateful content:
|
||||
- Click each tab/button via browser MCP
|
||||
- Extract the content, images, and card data for EACH state
|
||||
- Record which content belongs to which state
|
||||
- Note the transition animation between states (opacity, slide, fade, etc.)
|
||||
|
||||
For scroll-dependent elements:
|
||||
- Capture computed styles at scroll position 0 (initial state)
|
||||
- Scroll past the trigger threshold and capture computed styles again (scrolled state)
|
||||
- Diff the two to identify exactly which CSS properties change
|
||||
- Record the transition CSS (duration, easing, properties)
|
||||
- Record the exact trigger threshold (scroll position in px, or viewport intersection ratio)
|
||||
|
||||
### 8. Spec Files Are the Source of Truth
|
||||
|
||||
Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. This file is the contract between your extraction work and the builder agent. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact that the user (or you) can review if something looks wrong.
|
||||
|
||||
The spec file is not optional. It is not a nice-to-have. If you dispatch a builder without first writing a spec file, you are shipping incomplete instructions based on whatever you can remember from a browser MCP session, and the builder will guess to fill gaps.
|
||||
|
||||
### 9. Build Must Always Compile
|
||||
|
||||
Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
|
||||
|
||||
## Phase 1: Reconnaissance
|
||||
|
||||
Navigate to the target URL with browser MCP.
|
||||
|
||||
### Screenshots
|
||||
- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
|
||||
- Save to `docs/design-references/` with descriptive names
|
||||
- These are your master reference — builders will receive section-specific crops/screenshots later
|
||||
|
||||
### Global Extraction
|
||||
Extract these from the page before doing anything else:
|
||||
|
||||
**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements (headings, body, code, labels). Document every family, weight, and style actually used. Configure them in `src/app/layout.tsx` using `next/font/google` or `next/font/local`.
|
||||
|
||||
**Colors** — Extract the site's color palette from computed styles across the page. Update `src/app/globals.css` with the target's actual colors in the `:root` and `.dark` CSS variable blocks. Map them to shadcn's token names (background, foreground, primary, muted, etc.) where they fit. Add custom properties for colors that don't map to shadcn tokens.
|
||||
|
||||
**Favicons & Meta** — Download favicons, apple-touch-icons, OG images, webmanifest to `public/seo/`. Update `layout.tsx` metadata.
|
||||
|
||||
**Global UI patterns** — Identify any site-wide CSS or JS: custom scrollbar hiding, scroll-snap on the page container, global keyframe animations, backdrop filters, gradients used as overlays, **smooth scroll libraries** (Lenis, Locomotive Scroll — check for `.lenis`, `.locomotive-scroll`, or custom scroll container classes). Add these to `globals.css` and note any libraries that need to be installed.
|
||||
|
||||
### Mandatory Interaction Sweep
|
||||
|
||||
This is a dedicated pass AFTER screenshots and BEFORE anything else. Its purpose is to discover every behavior on the page — many of which are invisible in a static screenshot.
|
||||
|
||||
**Scroll sweep:** Scroll the page slowly from top to bottom via browser MCP. At each section, pause and observe:
|
||||
- Does the header change appearance? Record the scroll position where it triggers.
|
||||
- Do elements animate into view? Record which ones and the animation type.
|
||||
- Does a sidebar or tab indicator auto-switch as you scroll? Record the mechanism.
|
||||
- Are there scroll-snap points? Record which containers.
|
||||
- Is there a smooth scroll library active? Check for non-native scroll behavior.
|
||||
|
||||
**Click sweep:** Click every element that looks interactive:
|
||||
- Every button, tab, pill, link, card
|
||||
- Record what happens: does content change? Does a modal open? Does a dropdown appear?
|
||||
- For tabs/pills: click EACH ONE and record the content that appears for each state
|
||||
|
||||
**Hover sweep:** Hover over every element that might have hover states:
|
||||
- Buttons, cards, links, images, nav items
|
||||
- Record what changes: color, scale, shadow, underline, opacity
|
||||
|
||||
**Responsive sweep:** Test at 3 viewport widths via browser MCP:
|
||||
- Desktop: 1440px
|
||||
- Tablet: 768px
|
||||
- Mobile: 390px
|
||||
- At each width, note which sections change layout (column → stack, sidebar disappears, etc.) and at approximately which breakpoint the change occurs.
|
||||
|
||||
Save all findings to `docs/research/BEHAVIORS.md`. This is your behavior bible — reference it when writing every component spec.
|
||||
|
||||
### Page Topology
|
||||
Map out every distinct section of the page from top to bottom. Give each a working name. Document:
|
||||
- Their visual order
|
||||
- Which are fixed/sticky overlays vs. flow content
|
||||
- The overall page layout (scroll container, column structure, z-index layers)
|
||||
- Dependencies between sections (e.g., a floating nav that overlays everything)
|
||||
- **The interaction model** of each section (static, click-driven, scroll-driven, time-driven)
|
||||
|
||||
Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly blueprint.
|
||||
|
||||
## Phase 2: Foundation Build
|
||||
|
||||
This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
|
||||
|
||||
1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
|
||||
2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
|
||||
3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
|
||||
4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
|
||||
5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
|
||||
6. Verify: `npm run build` passes
|
||||
|
||||
### Asset Discovery Script Pattern
|
||||
|
||||
Use browser MCP to enumerate all assets on the page:
|
||||
|
||||
```javascript
|
||||
// Run this via browser MCP to discover all assets
|
||||
JSON.stringify({
|
||||
images: [...document.querySelectorAll('img')].map(img => ({
|
||||
src: img.src || img.currentSrc,
|
||||
alt: img.alt,
|
||||
width: img.naturalWidth,
|
||||
height: img.naturalHeight,
|
||||
// Include parent info to detect layered compositions
|
||||
parentClasses: img.parentElement?.className,
|
||||
siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
|
||||
position: getComputedStyle(img).position,
|
||||
zIndex: getComputedStyle(img).zIndex
|
||||
})),
|
||||
videos: [...document.querySelectorAll('video')].map(v => ({
|
||||
src: v.src || v.querySelector('source')?.src,
|
||||
poster: v.poster,
|
||||
autoplay: v.autoplay,
|
||||
loop: v.loop,
|
||||
muted: v.muted
|
||||
})),
|
||||
backgroundImages: [...document.querySelectorAll('*')].filter(el => {
|
||||
const bg = getComputedStyle(el).backgroundImage;
|
||||
return bg && bg !== 'none';
|
||||
}).map(el => ({
|
||||
url: getComputedStyle(el).backgroundImage,
|
||||
element: el.tagName + '.' + el.className?.split(' ')[0]
|
||||
})),
|
||||
svgCount: document.querySelectorAll('svg').length,
|
||||
fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
|
||||
favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
|
||||
});
|
||||
```
|
||||
|
||||
Then write a download script that fetches everything to `public/`. Use batched parallel downloads (4 at a time) with proper error handling.
|
||||
|
||||
## Phase 3: Component Specification & Dispatch
|
||||
|
||||
This is the core loop. For each section in your page topology (top to bottom), you do THREE things: **extract**, **write the spec file**, then **dispatch builders**.
|
||||
|
||||
### Step 1: Extract
|
||||
|
||||
For each section, use browser MCP to extract everything:
|
||||
|
||||
1. **Screenshot** the section in isolation (scroll to it, screenshot the viewport). Save to `docs/design-references/`.
|
||||
|
||||
2. **Extract CSS** for every element in the section. Use the extraction script below — don't hand-measure individual properties. Run it once per component container and capture the full output:
|
||||
|
||||
```javascript
|
||||
// Per-component extraction — run via browser MCP
|
||||
// Replace SELECTOR with the actual CSS selector for the component
|
||||
(function(selector) {
|
||||
const el = document.querySelector(selector);
|
||||
if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
|
||||
const props = [
|
||||
'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
|
||||
'textTransform','textDecoration','backgroundColor','background',
|
||||
'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
|
||||
'margin','marginTop','marginRight','marginBottom','marginLeft',
|
||||
'width','height','maxWidth','minWidth','maxHeight','minHeight',
|
||||
'display','flexDirection','justifyContent','alignItems','gap',
|
||||
'gridTemplateColumns','gridTemplateRows',
|
||||
'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
|
||||
'boxShadow','overflow','overflowX','overflowY',
|
||||
'position','top','right','bottom','left','zIndex',
|
||||
'opacity','transform','transition','cursor',
|
||||
'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
|
||||
'whiteSpace','textOverflow','WebkitLineClamp'
|
||||
];
|
||||
function extractStyles(element) {
|
||||
const cs = getComputedStyle(element);
|
||||
const styles = {};
|
||||
props.forEach(p => { const v = cs[p]; if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v; });
|
||||
return styles;
|
||||
}
|
||||
function walk(element, depth) {
|
||||
if (depth > 4) return null;
|
||||
const children = [...element.children];
|
||||
return {
|
||||
tag: element.tagName.toLowerCase(),
|
||||
classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
|
||||
text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
|
||||
styles: extractStyles(element),
|
||||
images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
|
||||
childCount: children.length,
|
||||
children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
|
||||
};
|
||||
}
|
||||
return JSON.stringify(walk(el, 0), null, 2);
|
||||
})('SELECTOR');
|
||||
```
|
||||
|
||||
3. **Extract multi-state styles** — for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states:
|
||||
|
||||
```javascript
|
||||
// State A: capture styles at current state (e.g., scroll position 0)
|
||||
// Then trigger the state change (scroll, click, hover via browser MCP)
|
||||
// State B: re-run the extraction script on the same element
|
||||
// The diff between A and B IS the behavior specification
|
||||
```
|
||||
|
||||
Record the diff explicitly: "Property X changes from VALUE_A to VALUE_B, triggered by TRIGGER, with transition: TRANSITION_CSS."
|
||||
|
||||
4. **Extract real content** — all text, alt attributes, aria labels, placeholder text. Use `element.textContent` for each text node. For tabbed/stateful content, **click each tab and extract content per state**.
|
||||
|
||||
5. **Identify assets** this section uses — which downloaded images/videos from `public/`, which icon components from `icons.tsx`. Check for **layered images** (multiple `<img>` or background-images stacked in the same container).
|
||||
|
||||
6. **Assess complexity** — how many distinct sub-components does this section contain? A distinct sub-component is an element with its own unique styling, structure, and behavior (e.g., a card, a nav item, a search panel).
|
||||
|
||||
### Step 2: Write the Component Spec File
|
||||
|
||||
For each section (or sub-component, if you're breaking it up), create a spec file in `docs/research/components/`. This is NOT optional — every builder must have a corresponding spec file.
|
||||
|
||||
**File path:** `docs/research/components/<component-name>.spec.md`
|
||||
|
||||
**Template:**
|
||||
|
||||
```markdown
|
||||
# <ComponentName> Specification
|
||||
|
||||
## Overview
|
||||
- **Target file:** `src/components/<ComponentName>.tsx`
|
||||
- **Screenshot:** `docs/design-references/<screenshot-name>.png`
|
||||
- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
|
||||
|
||||
## DOM Structure
|
||||
<Describe the element hierarchy — what contains what>
|
||||
|
||||
## Computed Styles (exact values from getComputedStyle)
|
||||
|
||||
### Container
|
||||
- display: ...
|
||||
- padding: ...
|
||||
- maxWidth: ...
|
||||
- (every relevant property with exact values)
|
||||
|
||||
### <Child element 1>
|
||||
- fontSize: ...
|
||||
- color: ...
|
||||
- (every relevant property)
|
||||
|
||||
### <Child element N>
|
||||
...
|
||||
|
||||
## States & Behaviors
|
||||
|
||||
### <Behavior name, e.g., "Scroll-triggered floating mode">
|
||||
- **Trigger:** <exact mechanism — scroll position 50px, IntersectionObserver rootMargin "-30% 0px", click on .tab-button, hover>
|
||||
- **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
|
||||
- **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
|
||||
- **Transition:** transition: all 0.3s ease
|
||||
- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
|
||||
|
||||
### Hover states
|
||||
- **<Element>:** <property>: <before> → <after>, transition: <value>
|
||||
|
||||
## Per-State Content (if applicable)
|
||||
|
||||
### State: "Featured"
|
||||
- Title: "..."
|
||||
- Subtitle: "..."
|
||||
- Cards: [{ title, description, image, link }, ...]
|
||||
|
||||
### State: "Productivity"
|
||||
- Title: "..."
|
||||
- Cards: [...]
|
||||
|
||||
## Assets
|
||||
- Background image: `public/images/<file>.webp`
|
||||
- Overlay image: `public/images/<file>.png`
|
||||
- Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
|
||||
|
||||
## Text Content (verbatim)
|
||||
<All text content, copy-pasted from the live site>
|
||||
|
||||
## Responsive Behavior
|
||||
- **Desktop (1440px):** <layout description>
|
||||
- **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
|
||||
- **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
|
||||
- **Breakpoint:** layout switches at ~<N>px
|
||||
```
|
||||
|
||||
Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
|
||||
|
||||
### Step 3: Dispatch Builders
|
||||
|
||||
Based on complexity, dispatch builder agent(s) in worktree(s):
|
||||
|
||||
**Simple section** (1-2 sub-components): One builder agent gets the entire section.
|
||||
|
||||
**Complex section** (3+ distinct sub-components): Break it up. One agent per sub-component, plus one agent for the section wrapper that imports them. Sub-component builders go first since the wrapper depends on them.
|
||||
|
||||
**What every builder agent receives:**
|
||||
- The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
|
||||
- Path to the section screenshot in `docs/design-references/`
|
||||
- Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
|
||||
- The target file path (e.g., `src/components/HeroSection.tsx`)
|
||||
- Instruction to verify with `npx tsc --noEmit` before finishing
|
||||
- For responsive behavior: the specific breakpoint values and what changes
|
||||
|
||||
**Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
|
||||
|
||||
### Step 4: Merge
|
||||
|
||||
As builder agents complete their work:
|
||||
- Merge their worktree branches into main
|
||||
- You have full context on what each agent built, so resolve any conflicts intelligently
|
||||
- After each merge, verify the build still passes: `npm run build`
|
||||
- If a merge introduces type errors, fix them immediately
|
||||
|
||||
The extract → spec → dispatch → merge cycle continues until all sections are built.
|
||||
|
||||
## Phase 4: Page Assembly
|
||||
|
||||
After all sections are built and merged, wire everything together in `src/app/page.tsx`:
|
||||
|
||||
- Import all section components
|
||||
- Implement the page-level layout from your topology doc (scroll containers, column structures, sticky positioning, z-index layering)
|
||||
- Connect real content to component props
|
||||
- Implement page-level behaviors: scroll snap, scroll-driven animations, dark-to-light transitions, intersection observers, smooth scroll (Lenis etc.)
|
||||
- Verify: `npm run build` passes clean
|
||||
|
||||
## Phase 5: Visual QA Diff
|
||||
|
||||
After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
|
||||
|
||||
1. Open the original site and your clone side-by-side (or take screenshots at the same viewport widths)
|
||||
2. Compare section by section, top to bottom, at desktop (1440px)
|
||||
3. Compare again at mobile (390px)
|
||||
4. For each discrepancy found:
|
||||
- Check the component spec file — was the value extracted correctly?
|
||||
- If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
|
||||
- If the spec was right but the builder got it wrong: fix the component to match the spec
|
||||
5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
|
||||
6. Verify smooth scroll feels right, header transitions work, tab switching works, animations play
|
||||
|
||||
Only after this visual QA pass is the clone complete.
|
||||
|
||||
## Pre-Dispatch Checklist
|
||||
|
||||
Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
|
||||
|
||||
- [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
|
||||
- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
|
||||
- [ ] Interaction model is identified and documented (static / click / scroll / time)
|
||||
- [ ] For stateful components: every state's content and styles are captured
|
||||
- [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
|
||||
- [ ] For hover states: before/after values and transition timing are recorded
|
||||
- [ ] All images in the section are identified (including overlays and layered compositions)
|
||||
- [ ] Responsive behavior is documented for at least desktop and mobile
|
||||
- [ ] Text content is verbatim from the site, not paraphrased
|
||||
- [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
These are lessons from previous failed clones — each one cost hours of rework:
|
||||
|
||||
- **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
|
||||
- **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
|
||||
- **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
|
||||
- **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
|
||||
- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
|
||||
- **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
|
||||
- **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
|
||||
- **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
|
||||
- **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
|
||||
- **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
|
||||
- **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
|
||||
- **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
|
||||
- **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
|
||||
|
||||
## Completion
|
||||
|
||||
When done, report:
|
||||
- Total sections built
|
||||
- Total components created
|
||||
- Total spec files written (should match components)
|
||||
- Total assets downloaded (images, videos, SVGs, fonts)
|
||||
- Build status (`npm run build` result)
|
||||
- Visual QA results (any remaining discrepancies)
|
||||
- Any known gaps or limitations
|
||||
|
||||
'''
|
||||
@@ -0,0 +1,9 @@
|
||||
# Auto-detect text files and normalise line endings to LF in the repo
|
||||
* text=auto
|
||||
|
||||
# Shell scripts must always use LF, even on Windows
|
||||
*.sh text eol=lf
|
||||
|
||||
# Batch files must always use CRLF
|
||||
*.bat text eol=crlf
|
||||
*.cmd text eol=crlf
|
||||
@@ -0,0 +1,2 @@
|
||||
# Funding model platforms — https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository
|
||||
github: JCodesMore
|
||||
@@ -0,0 +1,86 @@
|
||||
name: Bug Report
|
||||
description: Report a bug or unexpected behavior
|
||||
title: "[Bug]: "
|
||||
labels: ["bug"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for taking the time to report a bug! Please fill out the form below so we can reproduce and fix it.
|
||||
|
||||
- type: textarea
|
||||
id: description
|
||||
attributes:
|
||||
label: Description
|
||||
description: A clear description of what the bug is.
|
||||
placeholder: What happened?
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: reproduction
|
||||
attributes:
|
||||
label: Steps to Reproduce
|
||||
description: Step-by-step instructions to reproduce the behavior.
|
||||
placeholder: |
|
||||
1. Run `/clone-website https://example.com`
|
||||
2. Wait for agents to finish
|
||||
3. See error in terminal...
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: expected
|
||||
attributes:
|
||||
label: Expected Behavior
|
||||
description: What did you expect to happen?
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: actual
|
||||
attributes:
|
||||
label: Actual Behavior
|
||||
description: What actually happened? Include error messages or screenshots if possible.
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: target-url
|
||||
attributes:
|
||||
label: Target URL
|
||||
description: The website URL you were trying to clone (if applicable).
|
||||
placeholder: https://example.com
|
||||
|
||||
- type: dropdown
|
||||
id: os
|
||||
attributes:
|
||||
label: Operating System
|
||||
options:
|
||||
- macOS
|
||||
- Windows
|
||||
- Linux
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: node-version
|
||||
attributes:
|
||||
label: Node.js Version
|
||||
description: Run `node -v` to find this.
|
||||
placeholder: v24.x.x
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: claude-code-version
|
||||
attributes:
|
||||
label: Claude Code Version
|
||||
description: Run `claude --version` to find this.
|
||||
placeholder: 1.x.x
|
||||
|
||||
- type: textarea
|
||||
id: additional
|
||||
attributes:
|
||||
label: Additional Context
|
||||
description: Any other context, logs, or screenshots.
|
||||
@@ -0,0 +1,5 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: Questions & Discussion
|
||||
url: https://discord.gg/hrTSX5yTpB
|
||||
about: Ask questions and chat with the community on Discord
|
||||
@@ -0,0 +1,50 @@
|
||||
name: Feature Request
|
||||
description: Suggest a new feature or improvement
|
||||
title: "[Feature]: "
|
||||
labels: ["enhancement"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for suggesting a feature! Please describe the problem and your proposed solution.
|
||||
|
||||
- type: textarea
|
||||
id: problem
|
||||
attributes:
|
||||
label: Problem
|
||||
description: What problem does this feature solve? What's missing or frustrating?
|
||||
placeholder: "I'm always frustrated when..."
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: solution
|
||||
attributes:
|
||||
label: Proposed Solution
|
||||
description: How would you like this to work?
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: alternatives
|
||||
attributes:
|
||||
label: Alternatives Considered
|
||||
description: Any other approaches you've thought about?
|
||||
|
||||
- type: dropdown
|
||||
id: category
|
||||
attributes:
|
||||
label: Category
|
||||
options:
|
||||
- Cloning pipeline
|
||||
- Asset extraction
|
||||
- Component generation
|
||||
- Documentation
|
||||
- Developer experience
|
||||
- Other
|
||||
|
||||
- type: textarea
|
||||
id: additional
|
||||
attributes:
|
||||
label: Additional Context
|
||||
description: Screenshots, mockups, links, or any other context.
|
||||
@@ -0,0 +1,19 @@
|
||||
## Summary
|
||||
|
||||
<!-- What does this PR do and why? -->
|
||||
|
||||
## Related Issue
|
||||
|
||||
<!-- Link to the issue this addresses, e.g. Closes #123 -->
|
||||
|
||||
## Type of Change
|
||||
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Documentation
|
||||
- [ ] Refactoring
|
||||
- [ ] Breaking change
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] `npm run check` passes (lint + typecheck + build)
|
||||
@@ -0,0 +1,147 @@
|
||||
<!-- AUTO-GENERATED from AGENTS.md — do not edit directly.
|
||||
Run `bash scripts/sync-agent-rules.sh` to regenerate. -->
|
||||
|
||||
<!-- BEGIN:nextjs-agent-rules -->
|
||||
# This is NOT the Next.js you know
|
||||
|
||||
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
|
||||
<!-- END:nextjs-agent-rules -->
|
||||
|
||||
# Website Reverse-Engineer Template
|
||||
|
||||
## What This Is
|
||||
A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — just run `/clone-website <url1> [<url2> ...]`.
|
||||
|
||||
## Tech Stack
|
||||
- **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
|
||||
- **UI:** shadcn/ui (Radix primitives, Tailwind CSS v4, `cn()` utility)
|
||||
- **Icons:** Lucide React (default — will be replaced/supplemented by extracted SVGs)
|
||||
- **Styling:** Tailwind CSS v4 with oklch design tokens
|
||||
- **Deployment:** Vercel
|
||||
|
||||
## Commands
|
||||
- `npm run dev` — Start dev server
|
||||
- `npm run build` — Production build
|
||||
- `npm run lint` — ESLint check
|
||||
- `npm run typecheck` — TypeScript check
|
||||
- `npm run check` — Run lint + typecheck + build
|
||||
|
||||
## Code Style
|
||||
- TypeScript strict mode, no `any`
|
||||
- Named exports, PascalCase components, camelCase utils
|
||||
- Tailwind utility classes, no inline styles
|
||||
- 2-space indentation
|
||||
- Responsive: mobile-first
|
||||
|
||||
## Design Principles
|
||||
- **Pixel-perfect emulation** — match the target's spacing, colors, typography exactly
|
||||
- **No personal aesthetic changes during emulation phase** — match 1:1 first, customize later
|
||||
- **Real content** — use actual text and assets from the target site, not placeholders
|
||||
- **Beauty-first** — every pixel matters
|
||||
|
||||
## Project Structure
|
||||
```
|
||||
src/
|
||||
app/ # Next.js routes
|
||||
components/ # React components
|
||||
ui/ # shadcn/ui primitives
|
||||
icons.tsx # Extracted SVG icons as React components
|
||||
lib/
|
||||
utils.ts # cn() utility (shadcn)
|
||||
types/ # TypeScript interfaces
|
||||
hooks/ # Custom React hooks
|
||||
public/
|
||||
images/ # Downloaded images from target site
|
||||
videos/ # Downloaded videos from target site
|
||||
seo/ # Favicons, OG images, webmanifest
|
||||
docs/
|
||||
research/ # Inspection output (design tokens, components, layout)
|
||||
design-references/ # Screenshots and visual references
|
||||
scripts/ # Asset download scripts
|
||||
```
|
||||
|
||||
## MOST IMPORTANT NOTES
|
||||
- When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
|
||||
- After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
|
||||
- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
|
||||
|
||||
# Website Inspection Guide
|
||||
|
||||
## How to Reverse-Engineer Any Website
|
||||
|
||||
This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
|
||||
|
||||
## Phase 1: Visual Audit
|
||||
|
||||
### Screenshots to Capture
|
||||
- [ ] Every distinct page — desktop, tablet, mobile
|
||||
- [ ] Dark mode variants (if applicable)
|
||||
- [ ] Light mode variants (if applicable)
|
||||
- [ ] Key interaction states (hover, active, open menus, modals)
|
||||
- [ ] Loading/skeleton states
|
||||
- [ ] Empty states
|
||||
- [ ] Error states
|
||||
|
||||
### Design Tokens to Extract
|
||||
- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
|
||||
- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
|
||||
- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
|
||||
- [ ] **Border radius** — buttons, cards, avatars, inputs
|
||||
- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
|
||||
- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
|
||||
- [ ] **Icons** — which icon library? custom SVGs? sizes?
|
||||
- [ ] **Avatars** — sizes, shapes, fallback behavior
|
||||
- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
|
||||
- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
|
||||
|
||||
## Phase 2: Component Inventory
|
||||
|
||||
For each distinct UI component, document:
|
||||
1. **Name** — what would you call this component?
|
||||
2. **Structure** — what HTML elements / child components does it contain?
|
||||
3. **Variants** — does it have different sizes, colors, or states?
|
||||
4. **States** — default, hover, active, disabled, loading, error, empty
|
||||
5. **Responsive behavior** — how does it change at different breakpoints?
|
||||
6. **Interactions** — click, hover, focus, keyboard navigation
|
||||
7. **Animations** — transitions, entrance/exit animations, micro-interactions
|
||||
|
||||
### Common Components to Look For
|
||||
- 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
|
||||
|
||||
## Phase 3: Layout Architecture
|
||||
|
||||
- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
|
||||
- [ ] **Column layout** — how many columns at each breakpoint?
|
||||
- [ ] **Max-width** — main content area max-width
|
||||
- [ ] **Sticky elements** — header, sidebar, floating buttons
|
||||
- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
|
||||
- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
|
||||
|
||||
## Phase 4: Technical Stack Analysis
|
||||
|
||||
- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
|
||||
- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
|
||||
- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
|
||||
- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
|
||||
- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
|
||||
- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF
|
||||
- [ ] **Animation library** — Framer Motion, GSAP, CSS transitions only
|
||||
|
||||
## Phase 5: Documentation Output
|
||||
|
||||
After inspection, create these files in `docs/research/`:
|
||||
1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
|
||||
2. `COMPONENT_INVENTORY.md` — Every component with structure notes
|
||||
3. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
|
||||
4. `INTERACTION_PATTERNS.md` — Animations, transitions, hover states
|
||||
5. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents
|
||||
@@ -0,0 +1,3 @@
|
||||
steps:
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
@@ -0,0 +1,473 @@
|
||||
---
|
||||
name: clone-website
|
||||
description: Reverse-engineer and clone one or more websites in one shot — extracts assets, CSS, and content section-by-section and proactively dispatches parallel builder agents in worktrees as it goes. Use this whenever the user wants to clone, replicate, rebuild, reverse-engineer, or copy any website. Also triggers on phrases like "make a copy of this site", "rebuild this page", "pixel-perfect clone". Provide one or more target URLs as arguments.
|
||||
argument-hint: "<url1> [<url2> ...]"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Clone Website
|
||||
|
||||
You are about to reverse-engineer and rebuild **$ARGUMENTS** as pixel-perfect clones.
|
||||
|
||||
When multiple URLs are provided, process them independently and in parallel where possible, while keeping each site's extraction artifacts isolated in dedicated folders (for example, `docs/research/<hostname>/`).
|
||||
|
||||
This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
|
||||
|
||||
## Scope Defaults
|
||||
|
||||
The target is whatever page `$ARGUMENTS` resolves to. Clone exactly what's visible at that URL. Unless the user specifies otherwise, use these defaults:
|
||||
|
||||
- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, animations
|
||||
- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
|
||||
- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
|
||||
- **Customization:** None — pure emulation
|
||||
|
||||
If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
|
||||
|
||||
## Pre-Flight
|
||||
|
||||
1. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
|
||||
2. Parse `$ARGUMENTS` as one or more URLs. Normalize and validate each URL; if any are invalid, ask the user to correct them before proceeding. For each valid URL, verify it is accessible via your browser MCP tool.
|
||||
3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
|
||||
4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
|
||||
5. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
|
||||
|
||||
### 1. Completeness Beats Speed
|
||||
|
||||
Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
|
||||
|
||||
### 2. Small Tasks, Perfect Results
|
||||
|
||||
When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
|
||||
|
||||
Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
|
||||
|
||||
**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
|
||||
|
||||
### 3. Real Content, Real Assets
|
||||
|
||||
Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
|
||||
|
||||
**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays. Missing an overlay image makes the clone look empty even if the background is correct.
|
||||
|
||||
### 4. Foundation First
|
||||
|
||||
Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
|
||||
|
||||
### 5. Extract How It Looks AND How It Behaves
|
||||
|
||||
A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
|
||||
|
||||
For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens). Not "it looks like 16px" — extract the actual computed value. Not "the nav changes on scroll" — document the exact trigger (scroll position, IntersectionObserver threshold, viewport intersection), the before and after states (both sets of CSS values), and the transition (duration, easing, CSS transition vs. JS-driven vs. CSS `animation-timeline`).
|
||||
|
||||
Examples of behaviors to watch for — these are illustrative, not exhaustive. The page may do things not on this list, and you must catch those too:
|
||||
- A navbar that shrinks, changes background, or gains a shadow after scrolling past a threshold
|
||||
- Elements that animate into view when they enter the viewport (fade-up, slide-in, stagger delays)
|
||||
- Sections that snap into place on scroll (`scroll-snap-type`)
|
||||
- Parallax layers that move at different rates than the scroll
|
||||
- Hover states that animate (not just change — the transition duration and easing matter)
|
||||
- Dropdowns, modals, accordions with enter/exit animations
|
||||
- Scroll-driven progress indicators or opacity transitions
|
||||
- Auto-playing carousels or cycling content
|
||||
- Dark-to-light (or any theme) transitions between page sections
|
||||
- **Tabbed/pill content that cycles** — buttons that switch visible card sets with transitions
|
||||
- **Scroll-driven tab/accordion switching** — sidebars where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
|
||||
- **Smooth scroll libraries** (Lenis, Locomotive Scroll) — check for `.lenis` class or scroll container wrappers
|
||||
|
||||
### 6. Identify the Interaction Model Before Building
|
||||
|
||||
This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa. Before writing any builder prompt for an interactive section, you must definitively answer: **Is this section driven by clicks, scrolls, hovers, time, or some combination?**
|
||||
|
||||
How to determine this:
|
||||
1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
|
||||
2. If they do, it's scroll-driven. Extract the mechanism: `IntersectionObserver`, `scroll-snap`, `position: sticky`, `animation-timeline`, or JS scroll listeners.
|
||||
3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
|
||||
4. Document the interaction model explicitly in the component spec: "INTERACTION MODEL: scroll-driven with IntersectionObserver" or "INTERACTION MODEL: click-to-switch with opacity transition."
|
||||
|
||||
A section with a sticky sidebar and scrolling content panels is fundamentally different from a tabbed interface where clicking switches content. Getting this wrong means a complete rewrite, not a CSS tweak.
|
||||
|
||||
### 7. Extract Every State, Not Just the Default
|
||||
|
||||
Many components have multiple visual states — a tab bar shows different cards per tab, a header looks different at scroll position 0 vs 100, a card has hover effects. You must extract ALL states, not just whatever is visible on page load.
|
||||
|
||||
For tabbed/stateful content:
|
||||
- Click each tab/button via browser MCP
|
||||
- Extract the content, images, and card data for EACH state
|
||||
- Record which content belongs to which state
|
||||
- Note the transition animation between states (opacity, slide, fade, etc.)
|
||||
|
||||
For scroll-dependent elements:
|
||||
- Capture computed styles at scroll position 0 (initial state)
|
||||
- Scroll past the trigger threshold and capture computed styles again (scrolled state)
|
||||
- Diff the two to identify exactly which CSS properties change
|
||||
- Record the transition CSS (duration, easing, properties)
|
||||
- Record the exact trigger threshold (scroll position in px, or viewport intersection ratio)
|
||||
|
||||
### 8. Spec Files Are the Source of Truth
|
||||
|
||||
Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. This file is the contract between your extraction work and the builder agent. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact that the user (or you) can review if something looks wrong.
|
||||
|
||||
The spec file is not optional. It is not a nice-to-have. If you dispatch a builder without first writing a spec file, you are shipping incomplete instructions based on whatever you can remember from a browser MCP session, and the builder will guess to fill gaps.
|
||||
|
||||
### 9. Build Must Always Compile
|
||||
|
||||
Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
|
||||
|
||||
## Phase 1: Reconnaissance
|
||||
|
||||
Navigate to the target URL with browser MCP.
|
||||
|
||||
### Screenshots
|
||||
- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
|
||||
- Save to `docs/design-references/` with descriptive names
|
||||
- These are your master reference — builders will receive section-specific crops/screenshots later
|
||||
|
||||
### Global Extraction
|
||||
Extract these from the page before doing anything else:
|
||||
|
||||
**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements (headings, body, code, labels). Document every family, weight, and style actually used. Configure them in `src/app/layout.tsx` using `next/font/google` or `next/font/local`.
|
||||
|
||||
**Colors** — Extract the site's color palette from computed styles across the page. Update `src/app/globals.css` with the target's actual colors in the `:root` and `.dark` CSS variable blocks. Map them to shadcn's token names (background, foreground, primary, muted, etc.) where they fit. Add custom properties for colors that don't map to shadcn tokens.
|
||||
|
||||
**Favicons & Meta** — Download favicons, apple-touch-icons, OG images, webmanifest to `public/seo/`. Update `layout.tsx` metadata.
|
||||
|
||||
**Global UI patterns** — Identify any site-wide CSS or JS: custom scrollbar hiding, scroll-snap on the page container, global keyframe animations, backdrop filters, gradients used as overlays, **smooth scroll libraries** (Lenis, Locomotive Scroll — check for `.lenis`, `.locomotive-scroll`, or custom scroll container classes). Add these to `globals.css` and note any libraries that need to be installed.
|
||||
|
||||
### Mandatory Interaction Sweep
|
||||
|
||||
This is a dedicated pass AFTER screenshots and BEFORE anything else. Its purpose is to discover every behavior on the page — many of which are invisible in a static screenshot.
|
||||
|
||||
**Scroll sweep:** Scroll the page slowly from top to bottom via browser MCP. At each section, pause and observe:
|
||||
- Does the header change appearance? Record the scroll position where it triggers.
|
||||
- Do elements animate into view? Record which ones and the animation type.
|
||||
- Does a sidebar or tab indicator auto-switch as you scroll? Record the mechanism.
|
||||
- Are there scroll-snap points? Record which containers.
|
||||
- Is there a smooth scroll library active? Check for non-native scroll behavior.
|
||||
|
||||
**Click sweep:** Click every element that looks interactive:
|
||||
- Every button, tab, pill, link, card
|
||||
- Record what happens: does content change? Does a modal open? Does a dropdown appear?
|
||||
- For tabs/pills: click EACH ONE and record the content that appears for each state
|
||||
|
||||
**Hover sweep:** Hover over every element that might have hover states:
|
||||
- Buttons, cards, links, images, nav items
|
||||
- Record what changes: color, scale, shadow, underline, opacity
|
||||
|
||||
**Responsive sweep:** Test at 3 viewport widths via browser MCP:
|
||||
- Desktop: 1440px
|
||||
- Tablet: 768px
|
||||
- Mobile: 390px
|
||||
- At each width, note which sections change layout (column → stack, sidebar disappears, etc.) and at approximately which breakpoint the change occurs.
|
||||
|
||||
Save all findings to `docs/research/BEHAVIORS.md`. This is your behavior bible — reference it when writing every component spec.
|
||||
|
||||
### Page Topology
|
||||
Map out every distinct section of the page from top to bottom. Give each a working name. Document:
|
||||
- Their visual order
|
||||
- Which are fixed/sticky overlays vs. flow content
|
||||
- The overall page layout (scroll container, column structure, z-index layers)
|
||||
- Dependencies between sections (e.g., a floating nav that overlays everything)
|
||||
- **The interaction model** of each section (static, click-driven, scroll-driven, time-driven)
|
||||
|
||||
Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly blueprint.
|
||||
|
||||
## Phase 2: Foundation Build
|
||||
|
||||
This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
|
||||
|
||||
1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
|
||||
2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
|
||||
3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
|
||||
4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
|
||||
5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
|
||||
6. Verify: `npm run build` passes
|
||||
|
||||
### Asset Discovery Script Pattern
|
||||
|
||||
Use browser MCP to enumerate all assets on the page:
|
||||
|
||||
```javascript
|
||||
// Run this via browser MCP to discover all assets
|
||||
JSON.stringify({
|
||||
images: [...document.querySelectorAll('img')].map(img => ({
|
||||
src: img.src || img.currentSrc,
|
||||
alt: img.alt,
|
||||
width: img.naturalWidth,
|
||||
height: img.naturalHeight,
|
||||
// Include parent info to detect layered compositions
|
||||
parentClasses: img.parentElement?.className,
|
||||
siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
|
||||
position: getComputedStyle(img).position,
|
||||
zIndex: getComputedStyle(img).zIndex
|
||||
})),
|
||||
videos: [...document.querySelectorAll('video')].map(v => ({
|
||||
src: v.src || v.querySelector('source')?.src,
|
||||
poster: v.poster,
|
||||
autoplay: v.autoplay,
|
||||
loop: v.loop,
|
||||
muted: v.muted
|
||||
})),
|
||||
backgroundImages: [...document.querySelectorAll('*')].filter(el => {
|
||||
const bg = getComputedStyle(el).backgroundImage;
|
||||
return bg && bg !== 'none';
|
||||
}).map(el => ({
|
||||
url: getComputedStyle(el).backgroundImage,
|
||||
element: el.tagName + '.' + el.className?.split(' ')[0]
|
||||
})),
|
||||
svgCount: document.querySelectorAll('svg').length,
|
||||
fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
|
||||
favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
|
||||
});
|
||||
```
|
||||
|
||||
Then write a download script that fetches everything to `public/`. Use batched parallel downloads (4 at a time) with proper error handling.
|
||||
|
||||
## Phase 3: Component Specification & Dispatch
|
||||
|
||||
This is the core loop. For each section in your page topology (top to bottom), you do THREE things: **extract**, **write the spec file**, then **dispatch builders**.
|
||||
|
||||
### Step 1: Extract
|
||||
|
||||
For each section, use browser MCP to extract everything:
|
||||
|
||||
1. **Screenshot** the section in isolation (scroll to it, screenshot the viewport). Save to `docs/design-references/`.
|
||||
|
||||
2. **Extract CSS** for every element in the section. Use the extraction script below — don't hand-measure individual properties. Run it once per component container and capture the full output:
|
||||
|
||||
```javascript
|
||||
// Per-component extraction — run via browser MCP
|
||||
// Replace SELECTOR with the actual CSS selector for the component
|
||||
(function(selector) {
|
||||
const el = document.querySelector(selector);
|
||||
if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
|
||||
const props = [
|
||||
'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
|
||||
'textTransform','textDecoration','backgroundColor','background',
|
||||
'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
|
||||
'margin','marginTop','marginRight','marginBottom','marginLeft',
|
||||
'width','height','maxWidth','minWidth','maxHeight','minHeight',
|
||||
'display','flexDirection','justifyContent','alignItems','gap',
|
||||
'gridTemplateColumns','gridTemplateRows',
|
||||
'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
|
||||
'boxShadow','overflow','overflowX','overflowY',
|
||||
'position','top','right','bottom','left','zIndex',
|
||||
'opacity','transform','transition','cursor',
|
||||
'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
|
||||
'whiteSpace','textOverflow','WebkitLineClamp'
|
||||
];
|
||||
function extractStyles(element) {
|
||||
const cs = getComputedStyle(element);
|
||||
const styles = {};
|
||||
props.forEach(p => { const v = cs[p]; if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v; });
|
||||
return styles;
|
||||
}
|
||||
function walk(element, depth) {
|
||||
if (depth > 4) return null;
|
||||
const children = [...element.children];
|
||||
return {
|
||||
tag: element.tagName.toLowerCase(),
|
||||
classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
|
||||
text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
|
||||
styles: extractStyles(element),
|
||||
images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
|
||||
childCount: children.length,
|
||||
children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
|
||||
};
|
||||
}
|
||||
return JSON.stringify(walk(el, 0), null, 2);
|
||||
})('SELECTOR');
|
||||
```
|
||||
|
||||
3. **Extract multi-state styles** — for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states:
|
||||
|
||||
```javascript
|
||||
// State A: capture styles at current state (e.g., scroll position 0)
|
||||
// Then trigger the state change (scroll, click, hover via browser MCP)
|
||||
// State B: re-run the extraction script on the same element
|
||||
// The diff between A and B IS the behavior specification
|
||||
```
|
||||
|
||||
Record the diff explicitly: "Property X changes from VALUE_A to VALUE_B, triggered by TRIGGER, with transition: TRANSITION_CSS."
|
||||
|
||||
4. **Extract real content** — all text, alt attributes, aria labels, placeholder text. Use `element.textContent` for each text node. For tabbed/stateful content, **click each tab and extract content per state**.
|
||||
|
||||
5. **Identify assets** this section uses — which downloaded images/videos from `public/`, which icon components from `icons.tsx`. Check for **layered images** (multiple `<img>` or background-images stacked in the same container).
|
||||
|
||||
6. **Assess complexity** — how many distinct sub-components does this section contain? A distinct sub-component is an element with its own unique styling, structure, and behavior (e.g., a card, a nav item, a search panel).
|
||||
|
||||
### Step 2: Write the Component Spec File
|
||||
|
||||
For each section (or sub-component, if you're breaking it up), create a spec file in `docs/research/components/`. This is NOT optional — every builder must have a corresponding spec file.
|
||||
|
||||
**File path:** `docs/research/components/<component-name>.spec.md`
|
||||
|
||||
**Template:**
|
||||
|
||||
```markdown
|
||||
# <ComponentName> Specification
|
||||
|
||||
## Overview
|
||||
- **Target file:** `src/components/<ComponentName>.tsx`
|
||||
- **Screenshot:** `docs/design-references/<screenshot-name>.png`
|
||||
- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
|
||||
|
||||
## DOM Structure
|
||||
<Describe the element hierarchy — what contains what>
|
||||
|
||||
## Computed Styles (exact values from getComputedStyle)
|
||||
|
||||
### Container
|
||||
- display: ...
|
||||
- padding: ...
|
||||
- maxWidth: ...
|
||||
- (every relevant property with exact values)
|
||||
|
||||
### <Child element 1>
|
||||
- fontSize: ...
|
||||
- color: ...
|
||||
- (every relevant property)
|
||||
|
||||
### <Child element N>
|
||||
...
|
||||
|
||||
## States & Behaviors
|
||||
|
||||
### <Behavior name, e.g., "Scroll-triggered floating mode">
|
||||
- **Trigger:** <exact mechanism — scroll position 50px, IntersectionObserver rootMargin "-30% 0px", click on .tab-button, hover>
|
||||
- **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
|
||||
- **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
|
||||
- **Transition:** transition: all 0.3s ease
|
||||
- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
|
||||
|
||||
### Hover states
|
||||
- **<Element>:** <property>: <before> → <after>, transition: <value>
|
||||
|
||||
## Per-State Content (if applicable)
|
||||
|
||||
### State: "Featured"
|
||||
- Title: "..."
|
||||
- Subtitle: "..."
|
||||
- Cards: [{ title, description, image, link }, ...]
|
||||
|
||||
### State: "Productivity"
|
||||
- Title: "..."
|
||||
- Cards: [...]
|
||||
|
||||
## Assets
|
||||
- Background image: `public/images/<file>.webp`
|
||||
- Overlay image: `public/images/<file>.png`
|
||||
- Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
|
||||
|
||||
## Text Content (verbatim)
|
||||
<All text content, copy-pasted from the live site>
|
||||
|
||||
## Responsive Behavior
|
||||
- **Desktop (1440px):** <layout description>
|
||||
- **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
|
||||
- **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
|
||||
- **Breakpoint:** layout switches at ~<N>px
|
||||
```
|
||||
|
||||
Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
|
||||
|
||||
### Step 3: Dispatch Builders
|
||||
|
||||
Based on complexity, dispatch builder agent(s) in worktree(s):
|
||||
|
||||
**Simple section** (1-2 sub-components): One builder agent gets the entire section.
|
||||
|
||||
**Complex section** (3+ distinct sub-components): Break it up. One agent per sub-component, plus one agent for the section wrapper that imports them. Sub-component builders go first since the wrapper depends on them.
|
||||
|
||||
**What every builder agent receives:**
|
||||
- The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
|
||||
- Path to the section screenshot in `docs/design-references/`
|
||||
- Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
|
||||
- The target file path (e.g., `src/components/HeroSection.tsx`)
|
||||
- Instruction to verify with `npx tsc --noEmit` before finishing
|
||||
- For responsive behavior: the specific breakpoint values and what changes
|
||||
|
||||
**Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
|
||||
|
||||
### Step 4: Merge
|
||||
|
||||
As builder agents complete their work:
|
||||
- Merge their worktree branches into main
|
||||
- You have full context on what each agent built, so resolve any conflicts intelligently
|
||||
- After each merge, verify the build still passes: `npm run build`
|
||||
- If a merge introduces type errors, fix them immediately
|
||||
|
||||
The extract → spec → dispatch → merge cycle continues until all sections are built.
|
||||
|
||||
## Phase 4: Page Assembly
|
||||
|
||||
After all sections are built and merged, wire everything together in `src/app/page.tsx`:
|
||||
|
||||
- Import all section components
|
||||
- Implement the page-level layout from your topology doc (scroll containers, column structures, sticky positioning, z-index layering)
|
||||
- Connect real content to component props
|
||||
- Implement page-level behaviors: scroll snap, scroll-driven animations, dark-to-light transitions, intersection observers, smooth scroll (Lenis etc.)
|
||||
- Verify: `npm run build` passes clean
|
||||
|
||||
## Phase 5: Visual QA Diff
|
||||
|
||||
After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
|
||||
|
||||
1. Open the original site and your clone side-by-side (or take screenshots at the same viewport widths)
|
||||
2. Compare section by section, top to bottom, at desktop (1440px)
|
||||
3. Compare again at mobile (390px)
|
||||
4. For each discrepancy found:
|
||||
- Check the component spec file — was the value extracted correctly?
|
||||
- If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
|
||||
- If the spec was right but the builder got it wrong: fix the component to match the spec
|
||||
5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
|
||||
6. Verify smooth scroll feels right, header transitions work, tab switching works, animations play
|
||||
|
||||
Only after this visual QA pass is the clone complete.
|
||||
|
||||
## Pre-Dispatch Checklist
|
||||
|
||||
Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
|
||||
|
||||
- [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
|
||||
- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
|
||||
- [ ] Interaction model is identified and documented (static / click / scroll / time)
|
||||
- [ ] For stateful components: every state's content and styles are captured
|
||||
- [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
|
||||
- [ ] For hover states: before/after values and transition timing are recorded
|
||||
- [ ] All images in the section are identified (including overlays and layered compositions)
|
||||
- [ ] Responsive behavior is documented for at least desktop and mobile
|
||||
- [ ] Text content is verbatim from the site, not paraphrased
|
||||
- [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
These are lessons from previous failed clones — each one cost hours of rework:
|
||||
|
||||
- **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
|
||||
- **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
|
||||
- **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
|
||||
- **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
|
||||
- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
|
||||
- **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
|
||||
- **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
|
||||
- **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
|
||||
- **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
|
||||
- **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
|
||||
- **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
|
||||
- **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
|
||||
- **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
|
||||
|
||||
## Completion
|
||||
|
||||
When done, report:
|
||||
- Total sections built
|
||||
- Total components created
|
||||
- Total spec files written (should match components)
|
||||
- Total assets downloaded (images, videos, SVGs, fonts)
|
||||
- Build status (`npm run build` result)
|
||||
- Visual QA results (any remaining discrepancies)
|
||||
- Any known gaps or limitations
|
||||
@@ -0,0 +1,36 @@
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
pull_request:
|
||||
branches:
|
||||
- master
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 24
|
||||
cache: npm
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Lint
|
||||
run: npm run lint
|
||||
|
||||
- name: Type check
|
||||
run: npm run typecheck
|
||||
|
||||
- name: Build
|
||||
run: npm run build
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
# Dependencies
|
||||
node_modules/
|
||||
.pnp
|
||||
.pnp.js
|
||||
|
||||
# Build
|
||||
.next/
|
||||
out/
|
||||
build/
|
||||
dist/
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
.env.development.local
|
||||
.env.test.local
|
||||
.env.production.local
|
||||
|
||||
# Debug
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
*.swo
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# TypeScript
|
||||
*.tsbuildinfo
|
||||
next-env.d.ts
|
||||
|
||||
# Vercel
|
||||
.vercel
|
||||
|
||||
# Local settings (not project config)
|
||||
.claude/settings.local.json
|
||||
|
||||
# User-specific skills (not part of the template)
|
||||
.claude/skills/customize/
|
||||
.claude/skills/release/
|
||||
|
||||
# Local temp files
|
||||
temp/
|
||||
@@ -0,0 +1,473 @@
|
||||
---
|
||||
description: "Reverse-engineer and clone any website as a pixel-perfect replica"
|
||||
---
|
||||
<!-- AUTO-GENERATED from .claude/skills/clone-website/SKILL.md — do not edit directly.
|
||||
Run `node scripts/sync-skills.mjs` to regenerate. -->
|
||||
|
||||
|
||||
# Clone Website
|
||||
|
||||
You are about to reverse-engineer and rebuild **$ARGUMENTS** as pixel-perfect clones.
|
||||
|
||||
When multiple URLs are provided, process them independently and in parallel where possible, while keeping each site's extraction artifacts isolated in dedicated folders (for example, `docs/research/<hostname>/`).
|
||||
|
||||
This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
|
||||
|
||||
## Scope Defaults
|
||||
|
||||
The target is whatever page `$ARGUMENTS` resolves to. Clone exactly what's visible at that URL. Unless the user specifies otherwise, use these defaults:
|
||||
|
||||
- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, animations
|
||||
- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
|
||||
- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
|
||||
- **Customization:** None — pure emulation
|
||||
|
||||
If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
|
||||
|
||||
## Pre-Flight
|
||||
|
||||
1. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
|
||||
2. Parse `$ARGUMENTS` as one or more URLs. Normalize and validate each URL; if any are invalid, ask the user to correct them before proceeding. For each valid URL, verify it is accessible via your browser MCP tool.
|
||||
3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
|
||||
4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
|
||||
5. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
|
||||
|
||||
### 1. Completeness Beats Speed
|
||||
|
||||
Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
|
||||
|
||||
### 2. Small Tasks, Perfect Results
|
||||
|
||||
When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
|
||||
|
||||
Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
|
||||
|
||||
**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
|
||||
|
||||
### 3. Real Content, Real Assets
|
||||
|
||||
Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
|
||||
|
||||
**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays. Missing an overlay image makes the clone look empty even if the background is correct.
|
||||
|
||||
### 4. Foundation First
|
||||
|
||||
Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
|
||||
|
||||
### 5. Extract How It Looks AND How It Behaves
|
||||
|
||||
A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
|
||||
|
||||
For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens). Not "it looks like 16px" — extract the actual computed value. Not "the nav changes on scroll" — document the exact trigger (scroll position, IntersectionObserver threshold, viewport intersection), the before and after states (both sets of CSS values), and the transition (duration, easing, CSS transition vs. JS-driven vs. CSS `animation-timeline`).
|
||||
|
||||
Examples of behaviors to watch for — these are illustrative, not exhaustive. The page may do things not on this list, and you must catch those too:
|
||||
- A navbar that shrinks, changes background, or gains a shadow after scrolling past a threshold
|
||||
- Elements that animate into view when they enter the viewport (fade-up, slide-in, stagger delays)
|
||||
- Sections that snap into place on scroll (`scroll-snap-type`)
|
||||
- Parallax layers that move at different rates than the scroll
|
||||
- Hover states that animate (not just change — the transition duration and easing matter)
|
||||
- Dropdowns, modals, accordions with enter/exit animations
|
||||
- Scroll-driven progress indicators or opacity transitions
|
||||
- Auto-playing carousels or cycling content
|
||||
- Dark-to-light (or any theme) transitions between page sections
|
||||
- **Tabbed/pill content that cycles** — buttons that switch visible card sets with transitions
|
||||
- **Scroll-driven tab/accordion switching** — sidebars where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
|
||||
- **Smooth scroll libraries** (Lenis, Locomotive Scroll) — check for `.lenis` class or scroll container wrappers
|
||||
|
||||
### 6. Identify the Interaction Model Before Building
|
||||
|
||||
This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa. Before writing any builder prompt for an interactive section, you must definitively answer: **Is this section driven by clicks, scrolls, hovers, time, or some combination?**
|
||||
|
||||
How to determine this:
|
||||
1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
|
||||
2. If they do, it's scroll-driven. Extract the mechanism: `IntersectionObserver`, `scroll-snap`, `position: sticky`, `animation-timeline`, or JS scroll listeners.
|
||||
3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
|
||||
4. Document the interaction model explicitly in the component spec: "INTERACTION MODEL: scroll-driven with IntersectionObserver" or "INTERACTION MODEL: click-to-switch with opacity transition."
|
||||
|
||||
A section with a sticky sidebar and scrolling content panels is fundamentally different from a tabbed interface where clicking switches content. Getting this wrong means a complete rewrite, not a CSS tweak.
|
||||
|
||||
### 7. Extract Every State, Not Just the Default
|
||||
|
||||
Many components have multiple visual states — a tab bar shows different cards per tab, a header looks different at scroll position 0 vs 100, a card has hover effects. You must extract ALL states, not just whatever is visible on page load.
|
||||
|
||||
For tabbed/stateful content:
|
||||
- Click each tab/button via browser MCP
|
||||
- Extract the content, images, and card data for EACH state
|
||||
- Record which content belongs to which state
|
||||
- Note the transition animation between states (opacity, slide, fade, etc.)
|
||||
|
||||
For scroll-dependent elements:
|
||||
- Capture computed styles at scroll position 0 (initial state)
|
||||
- Scroll past the trigger threshold and capture computed styles again (scrolled state)
|
||||
- Diff the two to identify exactly which CSS properties change
|
||||
- Record the transition CSS (duration, easing, properties)
|
||||
- Record the exact trigger threshold (scroll position in px, or viewport intersection ratio)
|
||||
|
||||
### 8. Spec Files Are the Source of Truth
|
||||
|
||||
Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. This file is the contract between your extraction work and the builder agent. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact that the user (or you) can review if something looks wrong.
|
||||
|
||||
The spec file is not optional. It is not a nice-to-have. If you dispatch a builder without first writing a spec file, you are shipping incomplete instructions based on whatever you can remember from a browser MCP session, and the builder will guess to fill gaps.
|
||||
|
||||
### 9. Build Must Always Compile
|
||||
|
||||
Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
|
||||
|
||||
## Phase 1: Reconnaissance
|
||||
|
||||
Navigate to the target URL with browser MCP.
|
||||
|
||||
### Screenshots
|
||||
- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
|
||||
- Save to `docs/design-references/` with descriptive names
|
||||
- These are your master reference — builders will receive section-specific crops/screenshots later
|
||||
|
||||
### Global Extraction
|
||||
Extract these from the page before doing anything else:
|
||||
|
||||
**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements (headings, body, code, labels). Document every family, weight, and style actually used. Configure them in `src/app/layout.tsx` using `next/font/google` or `next/font/local`.
|
||||
|
||||
**Colors** — Extract the site's color palette from computed styles across the page. Update `src/app/globals.css` with the target's actual colors in the `:root` and `.dark` CSS variable blocks. Map them to shadcn's token names (background, foreground, primary, muted, etc.) where they fit. Add custom properties for colors that don't map to shadcn tokens.
|
||||
|
||||
**Favicons & Meta** — Download favicons, apple-touch-icons, OG images, webmanifest to `public/seo/`. Update `layout.tsx` metadata.
|
||||
|
||||
**Global UI patterns** — Identify any site-wide CSS or JS: custom scrollbar hiding, scroll-snap on the page container, global keyframe animations, backdrop filters, gradients used as overlays, **smooth scroll libraries** (Lenis, Locomotive Scroll — check for `.lenis`, `.locomotive-scroll`, or custom scroll container classes). Add these to `globals.css` and note any libraries that need to be installed.
|
||||
|
||||
### Mandatory Interaction Sweep
|
||||
|
||||
This is a dedicated pass AFTER screenshots and BEFORE anything else. Its purpose is to discover every behavior on the page — many of which are invisible in a static screenshot.
|
||||
|
||||
**Scroll sweep:** Scroll the page slowly from top to bottom via browser MCP. At each section, pause and observe:
|
||||
- Does the header change appearance? Record the scroll position where it triggers.
|
||||
- Do elements animate into view? Record which ones and the animation type.
|
||||
- Does a sidebar or tab indicator auto-switch as you scroll? Record the mechanism.
|
||||
- Are there scroll-snap points? Record which containers.
|
||||
- Is there a smooth scroll library active? Check for non-native scroll behavior.
|
||||
|
||||
**Click sweep:** Click every element that looks interactive:
|
||||
- Every button, tab, pill, link, card
|
||||
- Record what happens: does content change? Does a modal open? Does a dropdown appear?
|
||||
- For tabs/pills: click EACH ONE and record the content that appears for each state
|
||||
|
||||
**Hover sweep:** Hover over every element that might have hover states:
|
||||
- Buttons, cards, links, images, nav items
|
||||
- Record what changes: color, scale, shadow, underline, opacity
|
||||
|
||||
**Responsive sweep:** Test at 3 viewport widths via browser MCP:
|
||||
- Desktop: 1440px
|
||||
- Tablet: 768px
|
||||
- Mobile: 390px
|
||||
- At each width, note which sections change layout (column → stack, sidebar disappears, etc.) and at approximately which breakpoint the change occurs.
|
||||
|
||||
Save all findings to `docs/research/BEHAVIORS.md`. This is your behavior bible — reference it when writing every component spec.
|
||||
|
||||
### Page Topology
|
||||
Map out every distinct section of the page from top to bottom. Give each a working name. Document:
|
||||
- Their visual order
|
||||
- Which are fixed/sticky overlays vs. flow content
|
||||
- The overall page layout (scroll container, column structure, z-index layers)
|
||||
- Dependencies between sections (e.g., a floating nav that overlays everything)
|
||||
- **The interaction model** of each section (static, click-driven, scroll-driven, time-driven)
|
||||
|
||||
Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly blueprint.
|
||||
|
||||
## Phase 2: Foundation Build
|
||||
|
||||
This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
|
||||
|
||||
1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
|
||||
2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
|
||||
3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
|
||||
4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
|
||||
5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
|
||||
6. Verify: `npm run build` passes
|
||||
|
||||
### Asset Discovery Script Pattern
|
||||
|
||||
Use browser MCP to enumerate all assets on the page:
|
||||
|
||||
```javascript
|
||||
// Run this via browser MCP to discover all assets
|
||||
JSON.stringify({
|
||||
images: [...document.querySelectorAll('img')].map(img => ({
|
||||
src: img.src || img.currentSrc,
|
||||
alt: img.alt,
|
||||
width: img.naturalWidth,
|
||||
height: img.naturalHeight,
|
||||
// Include parent info to detect layered compositions
|
||||
parentClasses: img.parentElement?.className,
|
||||
siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
|
||||
position: getComputedStyle(img).position,
|
||||
zIndex: getComputedStyle(img).zIndex
|
||||
})),
|
||||
videos: [...document.querySelectorAll('video')].map(v => ({
|
||||
src: v.src || v.querySelector('source')?.src,
|
||||
poster: v.poster,
|
||||
autoplay: v.autoplay,
|
||||
loop: v.loop,
|
||||
muted: v.muted
|
||||
})),
|
||||
backgroundImages: [...document.querySelectorAll('*')].filter(el => {
|
||||
const bg = getComputedStyle(el).backgroundImage;
|
||||
return bg && bg !== 'none';
|
||||
}).map(el => ({
|
||||
url: getComputedStyle(el).backgroundImage,
|
||||
element: el.tagName + '.' + el.className?.split(' ')[0]
|
||||
})),
|
||||
svgCount: document.querySelectorAll('svg').length,
|
||||
fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
|
||||
favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
|
||||
});
|
||||
```
|
||||
|
||||
Then write a download script that fetches everything to `public/`. Use batched parallel downloads (4 at a time) with proper error handling.
|
||||
|
||||
## Phase 3: Component Specification & Dispatch
|
||||
|
||||
This is the core loop. For each section in your page topology (top to bottom), you do THREE things: **extract**, **write the spec file**, then **dispatch builders**.
|
||||
|
||||
### Step 1: Extract
|
||||
|
||||
For each section, use browser MCP to extract everything:
|
||||
|
||||
1. **Screenshot** the section in isolation (scroll to it, screenshot the viewport). Save to `docs/design-references/`.
|
||||
|
||||
2. **Extract CSS** for every element in the section. Use the extraction script below — don't hand-measure individual properties. Run it once per component container and capture the full output:
|
||||
|
||||
```javascript
|
||||
// Per-component extraction — run via browser MCP
|
||||
// Replace SELECTOR with the actual CSS selector for the component
|
||||
(function(selector) {
|
||||
const el = document.querySelector(selector);
|
||||
if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
|
||||
const props = [
|
||||
'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
|
||||
'textTransform','textDecoration','backgroundColor','background',
|
||||
'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
|
||||
'margin','marginTop','marginRight','marginBottom','marginLeft',
|
||||
'width','height','maxWidth','minWidth','maxHeight','minHeight',
|
||||
'display','flexDirection','justifyContent','alignItems','gap',
|
||||
'gridTemplateColumns','gridTemplateRows',
|
||||
'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
|
||||
'boxShadow','overflow','overflowX','overflowY',
|
||||
'position','top','right','bottom','left','zIndex',
|
||||
'opacity','transform','transition','cursor',
|
||||
'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
|
||||
'whiteSpace','textOverflow','WebkitLineClamp'
|
||||
];
|
||||
function extractStyles(element) {
|
||||
const cs = getComputedStyle(element);
|
||||
const styles = {};
|
||||
props.forEach(p => { const v = cs[p]; if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v; });
|
||||
return styles;
|
||||
}
|
||||
function walk(element, depth) {
|
||||
if (depth > 4) return null;
|
||||
const children = [...element.children];
|
||||
return {
|
||||
tag: element.tagName.toLowerCase(),
|
||||
classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
|
||||
text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
|
||||
styles: extractStyles(element),
|
||||
images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
|
||||
childCount: children.length,
|
||||
children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
|
||||
};
|
||||
}
|
||||
return JSON.stringify(walk(el, 0), null, 2);
|
||||
})('SELECTOR');
|
||||
```
|
||||
|
||||
3. **Extract multi-state styles** — for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states:
|
||||
|
||||
```javascript
|
||||
// State A: capture styles at current state (e.g., scroll position 0)
|
||||
// Then trigger the state change (scroll, click, hover via browser MCP)
|
||||
// State B: re-run the extraction script on the same element
|
||||
// The diff between A and B IS the behavior specification
|
||||
```
|
||||
|
||||
Record the diff explicitly: "Property X changes from VALUE_A to VALUE_B, triggered by TRIGGER, with transition: TRANSITION_CSS."
|
||||
|
||||
4. **Extract real content** — all text, alt attributes, aria labels, placeholder text. Use `element.textContent` for each text node. For tabbed/stateful content, **click each tab and extract content per state**.
|
||||
|
||||
5. **Identify assets** this section uses — which downloaded images/videos from `public/`, which icon components from `icons.tsx`. Check for **layered images** (multiple `<img>` or background-images stacked in the same container).
|
||||
|
||||
6. **Assess complexity** — how many distinct sub-components does this section contain? A distinct sub-component is an element with its own unique styling, structure, and behavior (e.g., a card, a nav item, a search panel).
|
||||
|
||||
### Step 2: Write the Component Spec File
|
||||
|
||||
For each section (or sub-component, if you're breaking it up), create a spec file in `docs/research/components/`. This is NOT optional — every builder must have a corresponding spec file.
|
||||
|
||||
**File path:** `docs/research/components/<component-name>.spec.md`
|
||||
|
||||
**Template:**
|
||||
|
||||
```markdown
|
||||
# <ComponentName> Specification
|
||||
|
||||
## Overview
|
||||
- **Target file:** `src/components/<ComponentName>.tsx`
|
||||
- **Screenshot:** `docs/design-references/<screenshot-name>.png`
|
||||
- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
|
||||
|
||||
## DOM Structure
|
||||
<Describe the element hierarchy — what contains what>
|
||||
|
||||
## Computed Styles (exact values from getComputedStyle)
|
||||
|
||||
### Container
|
||||
- display: ...
|
||||
- padding: ...
|
||||
- maxWidth: ...
|
||||
- (every relevant property with exact values)
|
||||
|
||||
### <Child element 1>
|
||||
- fontSize: ...
|
||||
- color: ...
|
||||
- (every relevant property)
|
||||
|
||||
### <Child element N>
|
||||
...
|
||||
|
||||
## States & Behaviors
|
||||
|
||||
### <Behavior name, e.g., "Scroll-triggered floating mode">
|
||||
- **Trigger:** <exact mechanism — scroll position 50px, IntersectionObserver rootMargin "-30% 0px", click on .tab-button, hover>
|
||||
- **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
|
||||
- **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
|
||||
- **Transition:** transition: all 0.3s ease
|
||||
- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
|
||||
|
||||
### Hover states
|
||||
- **<Element>:** <property>: <before> → <after>, transition: <value>
|
||||
|
||||
## Per-State Content (if applicable)
|
||||
|
||||
### State: "Featured"
|
||||
- Title: "..."
|
||||
- Subtitle: "..."
|
||||
- Cards: [{ title, description, image, link }, ...]
|
||||
|
||||
### State: "Productivity"
|
||||
- Title: "..."
|
||||
- Cards: [...]
|
||||
|
||||
## Assets
|
||||
- Background image: `public/images/<file>.webp`
|
||||
- Overlay image: `public/images/<file>.png`
|
||||
- Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
|
||||
|
||||
## Text Content (verbatim)
|
||||
<All text content, copy-pasted from the live site>
|
||||
|
||||
## Responsive Behavior
|
||||
- **Desktop (1440px):** <layout description>
|
||||
- **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
|
||||
- **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
|
||||
- **Breakpoint:** layout switches at ~<N>px
|
||||
```
|
||||
|
||||
Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
|
||||
|
||||
### Step 3: Dispatch Builders
|
||||
|
||||
Based on complexity, dispatch builder agent(s) in worktree(s):
|
||||
|
||||
**Simple section** (1-2 sub-components): One builder agent gets the entire section.
|
||||
|
||||
**Complex section** (3+ distinct sub-components): Break it up. One agent per sub-component, plus one agent for the section wrapper that imports them. Sub-component builders go first since the wrapper depends on them.
|
||||
|
||||
**What every builder agent receives:**
|
||||
- The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
|
||||
- Path to the section screenshot in `docs/design-references/`
|
||||
- Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
|
||||
- The target file path (e.g., `src/components/HeroSection.tsx`)
|
||||
- Instruction to verify with `npx tsc --noEmit` before finishing
|
||||
- For responsive behavior: the specific breakpoint values and what changes
|
||||
|
||||
**Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
|
||||
|
||||
### Step 4: Merge
|
||||
|
||||
As builder agents complete their work:
|
||||
- Merge their worktree branches into main
|
||||
- You have full context on what each agent built, so resolve any conflicts intelligently
|
||||
- After each merge, verify the build still passes: `npm run build`
|
||||
- If a merge introduces type errors, fix them immediately
|
||||
|
||||
The extract → spec → dispatch → merge cycle continues until all sections are built.
|
||||
|
||||
## Phase 4: Page Assembly
|
||||
|
||||
After all sections are built and merged, wire everything together in `src/app/page.tsx`:
|
||||
|
||||
- Import all section components
|
||||
- Implement the page-level layout from your topology doc (scroll containers, column structures, sticky positioning, z-index layering)
|
||||
- Connect real content to component props
|
||||
- Implement page-level behaviors: scroll snap, scroll-driven animations, dark-to-light transitions, intersection observers, smooth scroll (Lenis etc.)
|
||||
- Verify: `npm run build` passes clean
|
||||
|
||||
## Phase 5: Visual QA Diff
|
||||
|
||||
After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
|
||||
|
||||
1. Open the original site and your clone side-by-side (or take screenshots at the same viewport widths)
|
||||
2. Compare section by section, top to bottom, at desktop (1440px)
|
||||
3. Compare again at mobile (390px)
|
||||
4. For each discrepancy found:
|
||||
- Check the component spec file — was the value extracted correctly?
|
||||
- If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
|
||||
- If the spec was right but the builder got it wrong: fix the component to match the spec
|
||||
5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
|
||||
6. Verify smooth scroll feels right, header transitions work, tab switching works, animations play
|
||||
|
||||
Only after this visual QA pass is the clone complete.
|
||||
|
||||
## Pre-Dispatch Checklist
|
||||
|
||||
Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
|
||||
|
||||
- [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
|
||||
- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
|
||||
- [ ] Interaction model is identified and documented (static / click / scroll / time)
|
||||
- [ ] For stateful components: every state's content and styles are captured
|
||||
- [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
|
||||
- [ ] For hover states: before/after values and transition timing are recorded
|
||||
- [ ] All images in the section are identified (including overlays and layered compositions)
|
||||
- [ ] Responsive behavior is documented for at least desktop and mobile
|
||||
- [ ] Text content is verbatim from the site, not paraphrased
|
||||
- [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
These are lessons from previous failed clones — each one cost hours of rework:
|
||||
|
||||
- **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
|
||||
- **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
|
||||
- **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
|
||||
- **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
|
||||
- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
|
||||
- **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
|
||||
- **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
|
||||
- **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
|
||||
- **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
|
||||
- **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
|
||||
- **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
|
||||
- **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
|
||||
- **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
|
||||
|
||||
## Completion
|
||||
|
||||
When done, report:
|
||||
- Total sections built
|
||||
- Total components created
|
||||
- Total spec files written (should match components)
|
||||
- Total assets downloaded (images, videos, SVGs, fonts)
|
||||
- Build status (`npm run build` result)
|
||||
- Visual QA results (any remaining discrepancies)
|
||||
- Any known gaps or limitations
|
||||
@@ -0,0 +1,470 @@
|
||||
<!-- AUTO-GENERATED from .claude/skills/clone-website/SKILL.md — do not edit directly.
|
||||
Run `node scripts/sync-skills.mjs` to regenerate. -->
|
||||
|
||||
|
||||
# Clone Website
|
||||
|
||||
You are about to reverse-engineer and rebuild **the target URL provided by the user** as pixel-perfect clones.
|
||||
|
||||
When multiple URLs are provided, process them independently and in parallel where possible, while keeping each site's extraction artifacts isolated in dedicated folders (for example, `docs/research/<hostname>/`).
|
||||
|
||||
This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
|
||||
|
||||
## Scope Defaults
|
||||
|
||||
The target is whatever page `the target URL provided by the user` resolves to. Clone exactly what's visible at that URL. Unless the user specifies otherwise, use these defaults:
|
||||
|
||||
- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, animations
|
||||
- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
|
||||
- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
|
||||
- **Customization:** None — pure emulation
|
||||
|
||||
If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
|
||||
|
||||
## Pre-Flight
|
||||
|
||||
1. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
|
||||
2. Parse `the target URL provided by the user` as one or more URLs. Normalize and validate each URL; if any are invalid, ask the user to correct them before proceeding. For each valid URL, verify it is accessible via your browser MCP tool.
|
||||
3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
|
||||
4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
|
||||
5. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
|
||||
|
||||
### 1. Completeness Beats Speed
|
||||
|
||||
Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
|
||||
|
||||
### 2. Small Tasks, Perfect Results
|
||||
|
||||
When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
|
||||
|
||||
Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
|
||||
|
||||
**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
|
||||
|
||||
### 3. Real Content, Real Assets
|
||||
|
||||
Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
|
||||
|
||||
**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays. Missing an overlay image makes the clone look empty even if the background is correct.
|
||||
|
||||
### 4. Foundation First
|
||||
|
||||
Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
|
||||
|
||||
### 5. Extract How It Looks AND How It Behaves
|
||||
|
||||
A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
|
||||
|
||||
For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens). Not "it looks like 16px" — extract the actual computed value. Not "the nav changes on scroll" — document the exact trigger (scroll position, IntersectionObserver threshold, viewport intersection), the before and after states (both sets of CSS values), and the transition (duration, easing, CSS transition vs. JS-driven vs. CSS `animation-timeline`).
|
||||
|
||||
Examples of behaviors to watch for — these are illustrative, not exhaustive. The page may do things not on this list, and you must catch those too:
|
||||
- A navbar that shrinks, changes background, or gains a shadow after scrolling past a threshold
|
||||
- Elements that animate into view when they enter the viewport (fade-up, slide-in, stagger delays)
|
||||
- Sections that snap into place on scroll (`scroll-snap-type`)
|
||||
- Parallax layers that move at different rates than the scroll
|
||||
- Hover states that animate (not just change — the transition duration and easing matter)
|
||||
- Dropdowns, modals, accordions with enter/exit animations
|
||||
- Scroll-driven progress indicators or opacity transitions
|
||||
- Auto-playing carousels or cycling content
|
||||
- Dark-to-light (or any theme) transitions between page sections
|
||||
- **Tabbed/pill content that cycles** — buttons that switch visible card sets with transitions
|
||||
- **Scroll-driven tab/accordion switching** — sidebars where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
|
||||
- **Smooth scroll libraries** (Lenis, Locomotive Scroll) — check for `.lenis` class or scroll container wrappers
|
||||
|
||||
### 6. Identify the Interaction Model Before Building
|
||||
|
||||
This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa. Before writing any builder prompt for an interactive section, you must definitively answer: **Is this section driven by clicks, scrolls, hovers, time, or some combination?**
|
||||
|
||||
How to determine this:
|
||||
1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
|
||||
2. If they do, it's scroll-driven. Extract the mechanism: `IntersectionObserver`, `scroll-snap`, `position: sticky`, `animation-timeline`, or JS scroll listeners.
|
||||
3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
|
||||
4. Document the interaction model explicitly in the component spec: "INTERACTION MODEL: scroll-driven with IntersectionObserver" or "INTERACTION MODEL: click-to-switch with opacity transition."
|
||||
|
||||
A section with a sticky sidebar and scrolling content panels is fundamentally different from a tabbed interface where clicking switches content. Getting this wrong means a complete rewrite, not a CSS tweak.
|
||||
|
||||
### 7. Extract Every State, Not Just the Default
|
||||
|
||||
Many components have multiple visual states — a tab bar shows different cards per tab, a header looks different at scroll position 0 vs 100, a card has hover effects. You must extract ALL states, not just whatever is visible on page load.
|
||||
|
||||
For tabbed/stateful content:
|
||||
- Click each tab/button via browser MCP
|
||||
- Extract the content, images, and card data for EACH state
|
||||
- Record which content belongs to which state
|
||||
- Note the transition animation between states (opacity, slide, fade, etc.)
|
||||
|
||||
For scroll-dependent elements:
|
||||
- Capture computed styles at scroll position 0 (initial state)
|
||||
- Scroll past the trigger threshold and capture computed styles again (scrolled state)
|
||||
- Diff the two to identify exactly which CSS properties change
|
||||
- Record the transition CSS (duration, easing, properties)
|
||||
- Record the exact trigger threshold (scroll position in px, or viewport intersection ratio)
|
||||
|
||||
### 8. Spec Files Are the Source of Truth
|
||||
|
||||
Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. This file is the contract between your extraction work and the builder agent. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact that the user (or you) can review if something looks wrong.
|
||||
|
||||
The spec file is not optional. It is not a nice-to-have. If you dispatch a builder without first writing a spec file, you are shipping incomplete instructions based on whatever you can remember from a browser MCP session, and the builder will guess to fill gaps.
|
||||
|
||||
### 9. Build Must Always Compile
|
||||
|
||||
Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
|
||||
|
||||
## Phase 1: Reconnaissance
|
||||
|
||||
Navigate to the target URL with browser MCP.
|
||||
|
||||
### Screenshots
|
||||
- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
|
||||
- Save to `docs/design-references/` with descriptive names
|
||||
- These are your master reference — builders will receive section-specific crops/screenshots later
|
||||
|
||||
### Global Extraction
|
||||
Extract these from the page before doing anything else:
|
||||
|
||||
**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements (headings, body, code, labels). Document every family, weight, and style actually used. Configure them in `src/app/layout.tsx` using `next/font/google` or `next/font/local`.
|
||||
|
||||
**Colors** — Extract the site's color palette from computed styles across the page. Update `src/app/globals.css` with the target's actual colors in the `:root` and `.dark` CSS variable blocks. Map them to shadcn's token names (background, foreground, primary, muted, etc.) where they fit. Add custom properties for colors that don't map to shadcn tokens.
|
||||
|
||||
**Favicons & Meta** — Download favicons, apple-touch-icons, OG images, webmanifest to `public/seo/`. Update `layout.tsx` metadata.
|
||||
|
||||
**Global UI patterns** — Identify any site-wide CSS or JS: custom scrollbar hiding, scroll-snap on the page container, global keyframe animations, backdrop filters, gradients used as overlays, **smooth scroll libraries** (Lenis, Locomotive Scroll — check for `.lenis`, `.locomotive-scroll`, or custom scroll container classes). Add these to `globals.css` and note any libraries that need to be installed.
|
||||
|
||||
### Mandatory Interaction Sweep
|
||||
|
||||
This is a dedicated pass AFTER screenshots and BEFORE anything else. Its purpose is to discover every behavior on the page — many of which are invisible in a static screenshot.
|
||||
|
||||
**Scroll sweep:** Scroll the page slowly from top to bottom via browser MCP. At each section, pause and observe:
|
||||
- Does the header change appearance? Record the scroll position where it triggers.
|
||||
- Do elements animate into view? Record which ones and the animation type.
|
||||
- Does a sidebar or tab indicator auto-switch as you scroll? Record the mechanism.
|
||||
- Are there scroll-snap points? Record which containers.
|
||||
- Is there a smooth scroll library active? Check for non-native scroll behavior.
|
||||
|
||||
**Click sweep:** Click every element that looks interactive:
|
||||
- Every button, tab, pill, link, card
|
||||
- Record what happens: does content change? Does a modal open? Does a dropdown appear?
|
||||
- For tabs/pills: click EACH ONE and record the content that appears for each state
|
||||
|
||||
**Hover sweep:** Hover over every element that might have hover states:
|
||||
- Buttons, cards, links, images, nav items
|
||||
- Record what changes: color, scale, shadow, underline, opacity
|
||||
|
||||
**Responsive sweep:** Test at 3 viewport widths via browser MCP:
|
||||
- Desktop: 1440px
|
||||
- Tablet: 768px
|
||||
- Mobile: 390px
|
||||
- At each width, note which sections change layout (column → stack, sidebar disappears, etc.) and at approximately which breakpoint the change occurs.
|
||||
|
||||
Save all findings to `docs/research/BEHAVIORS.md`. This is your behavior bible — reference it when writing every component spec.
|
||||
|
||||
### Page Topology
|
||||
Map out every distinct section of the page from top to bottom. Give each a working name. Document:
|
||||
- Their visual order
|
||||
- Which are fixed/sticky overlays vs. flow content
|
||||
- The overall page layout (scroll container, column structure, z-index layers)
|
||||
- Dependencies between sections (e.g., a floating nav that overlays everything)
|
||||
- **The interaction model** of each section (static, click-driven, scroll-driven, time-driven)
|
||||
|
||||
Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly blueprint.
|
||||
|
||||
## Phase 2: Foundation Build
|
||||
|
||||
This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
|
||||
|
||||
1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
|
||||
2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
|
||||
3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
|
||||
4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
|
||||
5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
|
||||
6. Verify: `npm run build` passes
|
||||
|
||||
### Asset Discovery Script Pattern
|
||||
|
||||
Use browser MCP to enumerate all assets on the page:
|
||||
|
||||
```javascript
|
||||
// Run this via browser MCP to discover all assets
|
||||
JSON.stringify({
|
||||
images: [...document.querySelectorAll('img')].map(img => ({
|
||||
src: img.src || img.currentSrc,
|
||||
alt: img.alt,
|
||||
width: img.naturalWidth,
|
||||
height: img.naturalHeight,
|
||||
// Include parent info to detect layered compositions
|
||||
parentClasses: img.parentElement?.className,
|
||||
siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
|
||||
position: getComputedStyle(img).position,
|
||||
zIndex: getComputedStyle(img).zIndex
|
||||
})),
|
||||
videos: [...document.querySelectorAll('video')].map(v => ({
|
||||
src: v.src || v.querySelector('source')?.src,
|
||||
poster: v.poster,
|
||||
autoplay: v.autoplay,
|
||||
loop: v.loop,
|
||||
muted: v.muted
|
||||
})),
|
||||
backgroundImages: [...document.querySelectorAll('*')].filter(el => {
|
||||
const bg = getComputedStyle(el).backgroundImage;
|
||||
return bg && bg !== 'none';
|
||||
}).map(el => ({
|
||||
url: getComputedStyle(el).backgroundImage,
|
||||
element: el.tagName + '.' + el.className?.split(' ')[0]
|
||||
})),
|
||||
svgCount: document.querySelectorAll('svg').length,
|
||||
fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
|
||||
favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
|
||||
});
|
||||
```
|
||||
|
||||
Then write a download script that fetches everything to `public/`. Use batched parallel downloads (4 at a time) with proper error handling.
|
||||
|
||||
## Phase 3: Component Specification & Dispatch
|
||||
|
||||
This is the core loop. For each section in your page topology (top to bottom), you do THREE things: **extract**, **write the spec file**, then **dispatch builders**.
|
||||
|
||||
### Step 1: Extract
|
||||
|
||||
For each section, use browser MCP to extract everything:
|
||||
|
||||
1. **Screenshot** the section in isolation (scroll to it, screenshot the viewport). Save to `docs/design-references/`.
|
||||
|
||||
2. **Extract CSS** for every element in the section. Use the extraction script below — don't hand-measure individual properties. Run it once per component container and capture the full output:
|
||||
|
||||
```javascript
|
||||
// Per-component extraction — run via browser MCP
|
||||
// Replace SELECTOR with the actual CSS selector for the component
|
||||
(function(selector) {
|
||||
const el = document.querySelector(selector);
|
||||
if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
|
||||
const props = [
|
||||
'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
|
||||
'textTransform','textDecoration','backgroundColor','background',
|
||||
'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
|
||||
'margin','marginTop','marginRight','marginBottom','marginLeft',
|
||||
'width','height','maxWidth','minWidth','maxHeight','minHeight',
|
||||
'display','flexDirection','justifyContent','alignItems','gap',
|
||||
'gridTemplateColumns','gridTemplateRows',
|
||||
'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
|
||||
'boxShadow','overflow','overflowX','overflowY',
|
||||
'position','top','right','bottom','left','zIndex',
|
||||
'opacity','transform','transition','cursor',
|
||||
'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
|
||||
'whiteSpace','textOverflow','WebkitLineClamp'
|
||||
];
|
||||
function extractStyles(element) {
|
||||
const cs = getComputedStyle(element);
|
||||
const styles = {};
|
||||
props.forEach(p => { const v = cs[p]; if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v; });
|
||||
return styles;
|
||||
}
|
||||
function walk(element, depth) {
|
||||
if (depth > 4) return null;
|
||||
const children = [...element.children];
|
||||
return {
|
||||
tag: element.tagName.toLowerCase(),
|
||||
classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
|
||||
text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
|
||||
styles: extractStyles(element),
|
||||
images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
|
||||
childCount: children.length,
|
||||
children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
|
||||
};
|
||||
}
|
||||
return JSON.stringify(walk(el, 0), null, 2);
|
||||
})('SELECTOR');
|
||||
```
|
||||
|
||||
3. **Extract multi-state styles** — for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states:
|
||||
|
||||
```javascript
|
||||
// State A: capture styles at current state (e.g., scroll position 0)
|
||||
// Then trigger the state change (scroll, click, hover via browser MCP)
|
||||
// State B: re-run the extraction script on the same element
|
||||
// The diff between A and B IS the behavior specification
|
||||
```
|
||||
|
||||
Record the diff explicitly: "Property X changes from VALUE_A to VALUE_B, triggered by TRIGGER, with transition: TRANSITION_CSS."
|
||||
|
||||
4. **Extract real content** — all text, alt attributes, aria labels, placeholder text. Use `element.textContent` for each text node. For tabbed/stateful content, **click each tab and extract content per state**.
|
||||
|
||||
5. **Identify assets** this section uses — which downloaded images/videos from `public/`, which icon components from `icons.tsx`. Check for **layered images** (multiple `<img>` or background-images stacked in the same container).
|
||||
|
||||
6. **Assess complexity** — how many distinct sub-components does this section contain? A distinct sub-component is an element with its own unique styling, structure, and behavior (e.g., a card, a nav item, a search panel).
|
||||
|
||||
### Step 2: Write the Component Spec File
|
||||
|
||||
For each section (or sub-component, if you're breaking it up), create a spec file in `docs/research/components/`. This is NOT optional — every builder must have a corresponding spec file.
|
||||
|
||||
**File path:** `docs/research/components/<component-name>.spec.md`
|
||||
|
||||
**Template:**
|
||||
|
||||
```markdown
|
||||
# <ComponentName> Specification
|
||||
|
||||
## Overview
|
||||
- **Target file:** `src/components/<ComponentName>.tsx`
|
||||
- **Screenshot:** `docs/design-references/<screenshot-name>.png`
|
||||
- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
|
||||
|
||||
## DOM Structure
|
||||
<Describe the element hierarchy — what contains what>
|
||||
|
||||
## Computed Styles (exact values from getComputedStyle)
|
||||
|
||||
### Container
|
||||
- display: ...
|
||||
- padding: ...
|
||||
- maxWidth: ...
|
||||
- (every relevant property with exact values)
|
||||
|
||||
### <Child element 1>
|
||||
- fontSize: ...
|
||||
- color: ...
|
||||
- (every relevant property)
|
||||
|
||||
### <Child element N>
|
||||
...
|
||||
|
||||
## States & Behaviors
|
||||
|
||||
### <Behavior name, e.g., "Scroll-triggered floating mode">
|
||||
- **Trigger:** <exact mechanism — scroll position 50px, IntersectionObserver rootMargin "-30% 0px", click on .tab-button, hover>
|
||||
- **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
|
||||
- **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
|
||||
- **Transition:** transition: all 0.3s ease
|
||||
- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
|
||||
|
||||
### Hover states
|
||||
- **<Element>:** <property>: <before> → <after>, transition: <value>
|
||||
|
||||
## Per-State Content (if applicable)
|
||||
|
||||
### State: "Featured"
|
||||
- Title: "..."
|
||||
- Subtitle: "..."
|
||||
- Cards: [{ title, description, image, link }, ...]
|
||||
|
||||
### State: "Productivity"
|
||||
- Title: "..."
|
||||
- Cards: [...]
|
||||
|
||||
## Assets
|
||||
- Background image: `public/images/<file>.webp`
|
||||
- Overlay image: `public/images/<file>.png`
|
||||
- Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
|
||||
|
||||
## Text Content (verbatim)
|
||||
<All text content, copy-pasted from the live site>
|
||||
|
||||
## Responsive Behavior
|
||||
- **Desktop (1440px):** <layout description>
|
||||
- **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
|
||||
- **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
|
||||
- **Breakpoint:** layout switches at ~<N>px
|
||||
```
|
||||
|
||||
Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
|
||||
|
||||
### Step 3: Dispatch Builders
|
||||
|
||||
Based on complexity, dispatch builder agent(s) in worktree(s):
|
||||
|
||||
**Simple section** (1-2 sub-components): One builder agent gets the entire section.
|
||||
|
||||
**Complex section** (3+ distinct sub-components): Break it up. One agent per sub-component, plus one agent for the section wrapper that imports them. Sub-component builders go first since the wrapper depends on them.
|
||||
|
||||
**What every builder agent receives:**
|
||||
- The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
|
||||
- Path to the section screenshot in `docs/design-references/`
|
||||
- Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
|
||||
- The target file path (e.g., `src/components/HeroSection.tsx`)
|
||||
- Instruction to verify with `npx tsc --noEmit` before finishing
|
||||
- For responsive behavior: the specific breakpoint values and what changes
|
||||
|
||||
**Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
|
||||
|
||||
### Step 4: Merge
|
||||
|
||||
As builder agents complete their work:
|
||||
- Merge their worktree branches into main
|
||||
- You have full context on what each agent built, so resolve any conflicts intelligently
|
||||
- After each merge, verify the build still passes: `npm run build`
|
||||
- If a merge introduces type errors, fix them immediately
|
||||
|
||||
The extract → spec → dispatch → merge cycle continues until all sections are built.
|
||||
|
||||
## Phase 4: Page Assembly
|
||||
|
||||
After all sections are built and merged, wire everything together in `src/app/page.tsx`:
|
||||
|
||||
- Import all section components
|
||||
- Implement the page-level layout from your topology doc (scroll containers, column structures, sticky positioning, z-index layering)
|
||||
- Connect real content to component props
|
||||
- Implement page-level behaviors: scroll snap, scroll-driven animations, dark-to-light transitions, intersection observers, smooth scroll (Lenis etc.)
|
||||
- Verify: `npm run build` passes clean
|
||||
|
||||
## Phase 5: Visual QA Diff
|
||||
|
||||
After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
|
||||
|
||||
1. Open the original site and your clone side-by-side (or take screenshots at the same viewport widths)
|
||||
2. Compare section by section, top to bottom, at desktop (1440px)
|
||||
3. Compare again at mobile (390px)
|
||||
4. For each discrepancy found:
|
||||
- Check the component spec file — was the value extracted correctly?
|
||||
- If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
|
||||
- If the spec was right but the builder got it wrong: fix the component to match the spec
|
||||
5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
|
||||
6. Verify smooth scroll feels right, header transitions work, tab switching works, animations play
|
||||
|
||||
Only after this visual QA pass is the clone complete.
|
||||
|
||||
## Pre-Dispatch Checklist
|
||||
|
||||
Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
|
||||
|
||||
- [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
|
||||
- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
|
||||
- [ ] Interaction model is identified and documented (static / click / scroll / time)
|
||||
- [ ] For stateful components: every state's content and styles are captured
|
||||
- [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
|
||||
- [ ] For hover states: before/after values and transition timing are recorded
|
||||
- [ ] All images in the section are identified (including overlays and layered compositions)
|
||||
- [ ] Responsive behavior is documented for at least desktop and mobile
|
||||
- [ ] Text content is verbatim from the site, not paraphrased
|
||||
- [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
These are lessons from previous failed clones — each one cost hours of rework:
|
||||
|
||||
- **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
|
||||
- **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
|
||||
- **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
|
||||
- **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
|
||||
- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
|
||||
- **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
|
||||
- **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
|
||||
- **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
|
||||
- **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
|
||||
- **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
|
||||
- **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
|
||||
- **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
|
||||
- **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
|
||||
|
||||
## Completion
|
||||
|
||||
When done, report:
|
||||
- Total sections built
|
||||
- Total components created
|
||||
- Total spec files written (should match components)
|
||||
- Total assets downloaded (images, videos, SVGs, fonts)
|
||||
- Build status (`npm run build` result)
|
||||
- Visual QA results (any remaining discrepancies)
|
||||
- Any known gaps or limitations
|
||||
@@ -0,0 +1,2 @@
|
||||
This project uses AGENTS.md as the single source of truth for all AI agent instructions.
|
||||
Windsurf reads AGENTS.md automatically — see the project root for complete guidelines.
|
||||
@@ -0,0 +1,65 @@
|
||||
<!-- BEGIN:nextjs-agent-rules -->
|
||||
# This is NOT the Next.js you know
|
||||
|
||||
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
|
||||
<!-- END:nextjs-agent-rules -->
|
||||
|
||||
# Website Reverse-Engineer Template
|
||||
|
||||
## What This Is
|
||||
A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — just run `/clone-website <url1> [<url2> ...]`.
|
||||
|
||||
## Tech Stack
|
||||
- **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
|
||||
- **UI:** shadcn/ui (Radix primitives, Tailwind CSS v4, `cn()` utility)
|
||||
- **Icons:** Lucide React (default — will be replaced/supplemented by extracted SVGs)
|
||||
- **Styling:** Tailwind CSS v4 with oklch design tokens
|
||||
- **Deployment:** Vercel
|
||||
|
||||
## Commands
|
||||
- `npm run dev` — Start dev server
|
||||
- `npm run build` — Production build
|
||||
- `npm run lint` — ESLint check
|
||||
- `npm run typecheck` — TypeScript check
|
||||
- `npm run check` — Run lint + typecheck + build
|
||||
|
||||
## Code Style
|
||||
- TypeScript strict mode, no `any`
|
||||
- Named exports, PascalCase components, camelCase utils
|
||||
- Tailwind utility classes, no inline styles
|
||||
- 2-space indentation
|
||||
- Responsive: mobile-first
|
||||
|
||||
## Design Principles
|
||||
- **Pixel-perfect emulation** — match the target's spacing, colors, typography exactly
|
||||
- **No personal aesthetic changes during emulation phase** — match 1:1 first, customize later
|
||||
- **Real content** — use actual text and assets from the target site, not placeholders
|
||||
- **Beauty-first** — every pixel matters
|
||||
|
||||
## Project Structure
|
||||
```
|
||||
src/
|
||||
app/ # Next.js routes
|
||||
components/ # React components
|
||||
ui/ # shadcn/ui primitives
|
||||
icons.tsx # Extracted SVG icons as React components
|
||||
lib/
|
||||
utils.ts # cn() utility (shadcn)
|
||||
types/ # TypeScript interfaces
|
||||
hooks/ # Custom React hooks
|
||||
public/
|
||||
images/ # Downloaded images from target site
|
||||
videos/ # Downloaded videos from target site
|
||||
seo/ # Favicons, OG images, webmanifest
|
||||
docs/
|
||||
research/ # Inspection output (design tokens, components, layout)
|
||||
design-references/ # Screenshots and visual references
|
||||
scripts/ # Asset download scripts
|
||||
```
|
||||
|
||||
## MOST IMPORTANT NOTES
|
||||
- When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
|
||||
- After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
|
||||
- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
|
||||
|
||||
@docs/research/INSPECTION_GUIDE.md
|
||||
@@ -0,0 +1,80 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Changed
|
||||
- Raised the project Node.js baseline to 24 across local development, CI, Docker, and contributor-facing documentation
|
||||
|
||||
## [0.3.1] - 2026-03-29
|
||||
|
||||
### Fixed
|
||||
- `sync-agent-rules.sh` failing to resolve `@file` imports on Windows due to CRLF line endings — platform instruction files now correctly inline the Inspection Guide content
|
||||
|
||||
## [0.3.0] - 2026-03-29
|
||||
|
||||
### Added
|
||||
- Multi-URL support for `/clone-website` — clone multiple sites in a single command with parallel processing and isolated output
|
||||
- CI quality gates via GitHub Actions — automated lint, typecheck, and build on every push and PR
|
||||
- `npm run typecheck` and `npm run check` scripts for local quality validation
|
||||
- `.gitattributes` for cross-platform line ending normalization
|
||||
- `.nvmrc` to pin Node.js 20 for contributor consistency
|
||||
|
||||
### Changed
|
||||
- Streamlined PR template — removed redundant checklist items and screenshots section
|
||||
- Improved project description and README — clearer use cases, limitations, and modern wording
|
||||
- Refined documentation and agent rules across all platforms for clarity and consistency
|
||||
- Fixed CRLF handling in `sync-skills.mjs` for reliable Windows operation
|
||||
|
||||
### Removed
|
||||
- Outdated use case from README documentation
|
||||
|
||||
## [0.2.0] - 2026-03-28
|
||||
|
||||
### Added
|
||||
- Multi-platform AI agent support: Claude Code, Codex CLI, OpenCode, GitHub Copilot, Cursor, Windsurf, Gemini CLI, Cline/Roo Code, Continue, Amazon Q, Augment Code, Aider
|
||||
- Platform-specific instruction files and `/clone-website` skill for each supported agent
|
||||
- `scripts/sync-agent-rules.sh` to regenerate platform instruction files from AGENTS.md
|
||||
- `scripts/sync-skills.mjs` to regenerate `/clone-website` skill across all platforms
|
||||
- GEMINI.md for Gemini CLI configuration
|
||||
- Supported Platforms table in README
|
||||
- "Updating for Other Platforms" documentation section in README
|
||||
|
||||
### Changed
|
||||
- README now describes the project as multi-agent (Claude Code recommended, not required)
|
||||
- AGENTS.md updated with sync script reminders
|
||||
|
||||
## [0.1.1] - 2026-03-28
|
||||
|
||||
### Added
|
||||
- Bug report and feature request issue templates
|
||||
- Pull request template with checklist
|
||||
- CHANGELOG.md following Keep a Changelog format
|
||||
- Package.json metadata (description, repository, homepage, keywords, engines)
|
||||
|
||||
### Fixed
|
||||
- LICENSE copyright holder now attributed to JCodesMore
|
||||
|
||||
## [0.1.0] - 2026-03-28
|
||||
|
||||
### Added
|
||||
- Initial template scaffold for website reverse-engineering with Claude Code
|
||||
- `/clone-website` skill for full-site cloning pipeline
|
||||
- `/build-from-spec` and `/customize` skills
|
||||
- Parallel builder agents with git worktree isolation
|
||||
- Chrome MCP integration for design token extraction
|
||||
- Comprehensive inspection guide and project structure documentation
|
||||
- Next.js 16 + shadcn/ui + Tailwind CSS v4 base scaffold
|
||||
- MIT license
|
||||
- README with badges, demo section, quick start, and star history
|
||||
|
||||
[Unreleased]: https://github.com/JCodesMore/ai-website-cloner-template/compare/v0.3.1...HEAD
|
||||
[0.3.1]: https://github.com/JCodesMore/ai-website-cloner-template/compare/v0.3.0...v0.3.1
|
||||
[0.3.0]: https://github.com/JCodesMore/ai-website-cloner-template/compare/v0.2.0...v0.3.0
|
||||
[0.2.0]: https://github.com/JCodesMore/ai-website-cloner-template/compare/v0.1.1...v0.2.0
|
||||
[0.1.1]: https://github.com/JCodesMore/ai-website-cloner-template/compare/v0.1.0...v0.1.1
|
||||
[0.1.0]: https://github.com/JCodesMore/ai-website-cloner-template/releases/tag/v0.1.0
|
||||
+114
@@ -0,0 +1,114 @@
|
||||
# SRC https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile
|
||||
|
||||
# ============================================
|
||||
# Stage 1: Dependencies Installation Stage
|
||||
# ============================================
|
||||
|
||||
# IMPORTANT: Node.js Version Maintenance
|
||||
# This Dockerfile defaults to Node.js 24.14.1-slim to match the repo's Node 24 baseline.
|
||||
# To ensure security and compatibility, update the NODE_VERSION ARG when the project's Node baseline changes.
|
||||
ARG NODE_VERSION=24.14.1-slim
|
||||
|
||||
FROM node:${NODE_VERSION} AS dependencies
|
||||
|
||||
# Set working directory
|
||||
WORKDIR /app
|
||||
|
||||
# Copy package-related files first to leverage Docker's caching mechanism
|
||||
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./
|
||||
|
||||
# Install project dependencies with frozen lockfile for reproducible builds
|
||||
RUN --mount=type=cache,target=/root/.npm \
|
||||
--mount=type=cache,target=/usr/local/share/.cache/yarn \
|
||||
--mount=type=cache,target=/root/.local/share/pnpm/store \
|
||||
if [ -f package-lock.json ]; then \
|
||||
npm ci --no-audit --no-fund; \
|
||||
elif [ -f yarn.lock ]; then \
|
||||
corepack enable yarn && yarn install --frozen-lockfile --production=false; \
|
||||
elif [ -f pnpm-lock.yaml ]; then \
|
||||
corepack enable pnpm && pnpm install --frozen-lockfile; \
|
||||
else \
|
||||
echo "No lockfile found." && exit 1; \
|
||||
fi
|
||||
|
||||
# ============================================
|
||||
# Stage 2: Build Next.js application in standalone mode
|
||||
# ============================================
|
||||
|
||||
FROM node:${NODE_VERSION} AS builder
|
||||
|
||||
# Set working directory
|
||||
WORKDIR /app
|
||||
|
||||
# Copy project dependencies from dependencies stage
|
||||
COPY --from=dependencies /app/node_modules ./node_modules
|
||||
|
||||
# Copy application source code
|
||||
COPY . .
|
||||
|
||||
ENV NODE_ENV=production
|
||||
|
||||
# Next.js collects completely anonymous telemetry data about general usage.
|
||||
# Learn more here: https://nextjs.org/telemetry
|
||||
# Uncomment the following line in case you want to disable telemetry during the build.
|
||||
# ENV NEXT_TELEMETRY_DISABLED=1
|
||||
|
||||
# Build Next.js application
|
||||
# If you want to speed up Docker rebuilds, you can cache the build artifacts
|
||||
# by adding: --mount=type=cache,target=/app/.next/cache
|
||||
# This caches the .next/cache directory across builds, but it also prevents
|
||||
# .next/cache/fetch-cache from being included in the final image, meaning
|
||||
# cached fetch responses from the build won't be available at runtime.
|
||||
RUN if [ -f package-lock.json ]; then \
|
||||
npm run build; \
|
||||
elif [ -f yarn.lock ]; then \
|
||||
corepack enable yarn && yarn build; \
|
||||
elif [ -f pnpm-lock.yaml ]; then \
|
||||
corepack enable pnpm && pnpm build; \
|
||||
else \
|
||||
echo "No lockfile found." && exit 1; \
|
||||
fi
|
||||
|
||||
# ============================================
|
||||
# Stage 3: Run Next.js application
|
||||
# ============================================
|
||||
|
||||
FROM node:${NODE_VERSION} AS runner
|
||||
|
||||
# Set working directory
|
||||
WORKDIR /app
|
||||
|
||||
# Set production environment variables
|
||||
ENV NODE_ENV=production
|
||||
ENV PORT=3000
|
||||
ENV HOSTNAME="0.0.0.0"
|
||||
|
||||
# Next.js collects completely anonymous telemetry data about general usage.
|
||||
# Learn more here: https://nextjs.org/telemetry
|
||||
# Uncomment the following line in case you want to disable telemetry during the run time.
|
||||
# ENV NEXT_TELEMETRY_DISABLED=1
|
||||
|
||||
# Copy production assets
|
||||
COPY --from=builder --chown=node:node /app/public ./public
|
||||
|
||||
# Set the correct permission for prerender cache
|
||||
RUN mkdir .next
|
||||
RUN chown node:node .next
|
||||
|
||||
# Automatically leverage output traces to reduce image size
|
||||
# https://nextjs.org/docs/advanced-features/output-file-tracing
|
||||
COPY --from=builder --chown=node:node /app/.next/standalone ./
|
||||
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
|
||||
|
||||
# If you want to persist the fetch cache generated during the build so that
|
||||
# cached responses are available immediately on startup, uncomment this line:
|
||||
# COPY --from=builder --chown=node:node /app/.next/cache ./.next/cache
|
||||
|
||||
# Switch to non-root user for security best practices
|
||||
USER node
|
||||
|
||||
# Expose port 3000 to allow HTTP traffic
|
||||
EXPOSE 3000
|
||||
|
||||
# Start Next.js standalone server
|
||||
CMD ["node", "server.js"]
|
||||
@@ -0,0 +1,15 @@
|
||||
FROM node:24-alpine
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
COPY package.json package-lock.json ./
|
||||
RUN npm install
|
||||
|
||||
# Source files are mounted as a volume at runtime for hot reload
|
||||
|
||||
EXPOSE 3000
|
||||
|
||||
ENV NODE_ENV=development
|
||||
ENV NEXT_TELEMETRY_DISABLED=1
|
||||
|
||||
CMD ["npm", "run", "dev"]
|
||||
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2025 JCodesMore
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -0,0 +1,171 @@
|
||||
# AI Website Cloner Template
|
||||
|
||||
<a href="https://github.com/JCodesMore/ai-website-cloner-template/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a> <a href="https://github.com/JCodesMore/ai-website-cloner-template/stargazers"><img src="https://img.shields.io/github/stars/JCodesMore/ai-website-cloner-template?style=flat" alt="Stars" /></a> <a href="https://discord.gg/hrTSX5yTpB"><img src="https://img.shields.io/discord/1400896964597383279?label=discord" alt="Discord" /></a>
|
||||
|
||||
A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents.
|
||||
|
||||
**Recommended: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with Opus 4.8 for best results** — but works with a variety of AI coding agents.
|
||||
|
||||
Point it at a URL, run `/clone-website`, and your AI agent will inspect the site, extract design tokens and assets, write component specs, and dispatch parallel builders to reconstruct every section.
|
||||
|
||||
## Demo
|
||||
|
||||
[](https://youtu.be/O669pVZ_qr0)
|
||||
|
||||
> Click the image above to watch the full demo on YouTube.
|
||||
|
||||
## Quick Start
|
||||
|
||||
> **Important:** Start by making your own copy with GitHub's **Use this template** button. Do not clone this template repository directly for your website project, and do not open pull requests here with your generated website.
|
||||
|
||||
1. **Create your own repository from this template**
|
||||
|
||||
On the GitHub page for this project, click **Use this template**, then click **Create a new repository**.
|
||||
|
||||
Give your new repository a name, choose whether it should be public or private, then click **Create repository**. If GitHub shows an **Include all branches** option, you can leave it off.
|
||||
|
||||
This gives you your own separate project to work in, so your website changes stay in your account instead of coming back to the main template.
|
||||
|
||||
2. **Open your new repository on your computer**
|
||||
|
||||
After GitHub creates your copy, open that new repository. Click **Code** and open or clone your new repository with your preferred coding tool.
|
||||
|
||||
If you use the terminal, the command will look like this:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR-USERNAME/YOUR-NEW-REPOSITORY.git
|
||||
cd YOUR-NEW-REPOSITORY
|
||||
```
|
||||
|
||||
3. **Install dependencies**
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
4. **Start your AI agent** — Claude Code recommended:
|
||||
```bash
|
||||
claude --chrome
|
||||
```
|
||||
5. **Run the skill**:
|
||||
```
|
||||
/clone-website <target-url1> [<target-url2> ...]
|
||||
```
|
||||
6. **Customize** (optional) — after the base clone is built, modify as needed
|
||||
|
||||
> Using a different agent? Open `AGENTS.md` for project instructions — most agents pick it up automatically.
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
| Agent | Status |
|
||||
| ------------------------------------------------------------- | -------------------------- |
|
||||
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | **Recommended** — Opus 4.8 |
|
||||
| [Codex CLI](https://github.com/openai/codex) | Supported |
|
||||
| [OpenCode](https://opencode.ai/) | Supported |
|
||||
| [GitHub Copilot](https://github.com/features/copilot) | Supported |
|
||||
| [Cursor](https://cursor.com/) | Supported |
|
||||
| [Windsurf](https://codeium.com/windsurf) | Supported |
|
||||
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Supported |
|
||||
| [Cline](https://github.com/cline/cline) | Supported |
|
||||
| [Roo Code](https://github.com/RooCodeInc/Roo-Code) | Supported |
|
||||
| [Continue](https://continue.dev/) | Supported |
|
||||
| [Amazon Q](https://aws.amazon.com/q/developer/) | Supported |
|
||||
| [Augment Code](https://www.augmentcode.com/) | Supported |
|
||||
| [Aider](https://aider.chat/) | Supported |
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Node.js](https://nodejs.org/) 24+
|
||||
- An AI coding agent (see [Supported Platforms](#supported-platforms))
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Next.js 16** — App Router, React 19, TypeScript strict
|
||||
- **shadcn/ui** — Radix primitives + Tailwind CSS v4
|
||||
- **Tailwind CSS v4** — oklch design tokens
|
||||
- **Lucide React** — default icons (replaced by extracted SVGs during cloning)
|
||||
|
||||
## How It Works
|
||||
|
||||
The `/clone-website` skill runs a multi-phase pipeline:
|
||||
|
||||
1. **Reconnaissance** — screenshots, design token extraction, interaction sweep (scroll, click, hover, responsive)
|
||||
2. **Foundation** — updates fonts, colors, globals, downloads all assets
|
||||
3. **Component Specs** — writes detailed spec files (`docs/research/components/`) with exact computed CSS values, states, behaviors, and content
|
||||
4. **Parallel Build** — dispatches builder agents in git worktrees, one per section/component
|
||||
5. **Assembly & QA** — merges worktrees, wires up the page, runs visual diff against the original
|
||||
|
||||
Each builder agent receives the full component specification inline — exact `getComputedStyle()` values, interaction models, multi-state content, responsive breakpoints, and asset paths. No guessing.
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **Platform migration** — rebuild a site you own from WordPress/Webflow/Squarespace into a modern Next.js codebase
|
||||
- **Lost source code** — your site is live but the repo is gone, the developer left, or the stack is legacy. Get the code back in a modern format
|
||||
- **Learning** — deconstruct how production sites achieve specific layouts, animations, and responsive behavior by working with real code
|
||||
|
||||
## Not Intended For
|
||||
|
||||
- **Phishing or impersonation** — this project must not be used for deceptive purposes, impersonation, or any activity that breaks the law.
|
||||
- **Passing off someone's design as your own** — logos, brand assets, and original copy belong to their owners.
|
||||
- **Violating terms of service** — some sites explicitly prohibit scraping or reproduction. Check first.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
app/ # Next.js routes
|
||||
components/ # React components
|
||||
ui/ # shadcn/ui primitives
|
||||
icons.tsx # Extracted SVG icons
|
||||
lib/utils.ts # cn() utility
|
||||
types/ # TypeScript interfaces
|
||||
hooks/ # Custom React hooks
|
||||
public/
|
||||
images/ # Downloaded images from target
|
||||
videos/ # Downloaded videos from target
|
||||
seo/ # Favicons, OG images
|
||||
docs/
|
||||
research/ # Extraction output & component specs
|
||||
design-references/ # Screenshots
|
||||
scripts/
|
||||
sync-agent-rules.sh # Regenerate agent instruction files
|
||||
sync-skills.mjs # Regenerate /clone-website for all platforms
|
||||
AGENTS.md # Agent instructions (single source of truth)
|
||||
CLAUDE.md # Claude Code config (imports AGENTS.md)
|
||||
GEMINI.md # Gemini CLI config (imports AGENTS.md)
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
npm run dev # Start dev server
|
||||
npm run build # Production build
|
||||
npm run lint # ESLint check
|
||||
npm run typecheck # TypeScript check
|
||||
npm run check # Run lint + typecheck + build
|
||||
```
|
||||
|
||||
### If using docker
|
||||
|
||||
```bash
|
||||
docker compose up app --build # build and run the app
|
||||
docker compose up dev --build # run the app in dev mode on port 3001
|
||||
```
|
||||
|
||||
## Updating for Other Platforms
|
||||
|
||||
Two source-of-truth files power all platform support. Edit the source, then run the sync script:
|
||||
|
||||
| What | Source of truth | Sync command |
|
||||
| ---------------------- | --------------------------------------- | ---------------------------------- |
|
||||
| Project instructions | `AGENTS.md` | `bash scripts/sync-agent-rules.sh` |
|
||||
| `/clone-website` skill | `.claude/skills/clone-website/SKILL.md` | `node scripts/sync-skills.mjs` |
|
||||
|
||||
Each script regenerates the platform-specific copies automatically. Agents that read the source files natively need no regeneration.
|
||||
|
||||
|
||||
## Star History
|
||||
|
||||
[](https://star-history.com/#JCodesMore/ai-website-cloner-template&Date)
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
@@ -0,0 +1,7 @@
|
||||
# WeHub 来源说明
|
||||
|
||||
- 原始项目：`JCodesMore/ai-website-cloner-template`
|
||||
- 原始仓库：https://github.com/JCodesMore/ai-website-cloner-template
|
||||
- 导入方式：上游默认分支的最新快照
|
||||
- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
|
||||
- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
|
||||
@@ -0,0 +1,25 @@
|
||||
{
|
||||
"$schema": "https://ui.shadcn.com/schema.json",
|
||||
"style": "base-nova",
|
||||
"rsc": true,
|
||||
"tsx": true,
|
||||
"tailwind": {
|
||||
"config": "",
|
||||
"css": "src/app/globals.css",
|
||||
"baseColor": "neutral",
|
||||
"cssVariables": true,
|
||||
"prefix": ""
|
||||
},
|
||||
"iconLibrary": "lucide",
|
||||
"rtl": false,
|
||||
"aliases": {
|
||||
"components": "@/components",
|
||||
"utils": "@/lib/utils",
|
||||
"ui": "@/components/ui",
|
||||
"lib": "@/lib",
|
||||
"hooks": "@/hooks"
|
||||
},
|
||||
"menuColor": "default",
|
||||
"menuAccent": "subtle",
|
||||
"registries": {}
|
||||
}
|
||||
@@ -0,0 +1,53 @@
|
||||
services:
|
||||
app:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile
|
||||
target: runner
|
||||
image: ai-website-cloner:latest
|
||||
container_name: ai-website-cloner
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "${PORT:-3000}:3000"
|
||||
environment:
|
||||
- NODE_ENV=production
|
||||
- NEXT_TELEMETRY_DISABLED=1
|
||||
env_file:
|
||||
- path: .env.local
|
||||
required: false
|
||||
- path: .env
|
||||
required: false
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "wget -qO- http://localhost:3000/ || exit 1"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 10s
|
||||
|
||||
dev:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile.dev
|
||||
image: ai-website-cloner:dev
|
||||
container_name: ai-website-cloner-dev
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "${DEV_PORT:-3001}:3000"
|
||||
environment:
|
||||
- NODE_ENV=development
|
||||
- NEXT_TELEMETRY_DISABLED=1
|
||||
env_file:
|
||||
- path: .env.local
|
||||
required: false
|
||||
- path: .env
|
||||
required: false
|
||||
volumes:
|
||||
- .:/app
|
||||
- /app/node_modules
|
||||
- /app/.next
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "wget -qO- http://localhost:3000/ || exit 1"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 15s
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 724 KiB |
@@ -0,0 +1,80 @@
|
||||
# Website Inspection Guide
|
||||
|
||||
## How to Reverse-Engineer Any Website
|
||||
|
||||
This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
|
||||
|
||||
## Phase 1: Visual Audit
|
||||
|
||||
### Screenshots to Capture
|
||||
- [ ] Every distinct page — desktop, tablet, mobile
|
||||
- [ ] Dark mode variants (if applicable)
|
||||
- [ ] Light mode variants (if applicable)
|
||||
- [ ] Key interaction states (hover, active, open menus, modals)
|
||||
- [ ] Loading/skeleton states
|
||||
- [ ] Empty states
|
||||
- [ ] Error states
|
||||
|
||||
### Design Tokens to Extract
|
||||
- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
|
||||
- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
|
||||
- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
|
||||
- [ ] **Border radius** — buttons, cards, avatars, inputs
|
||||
- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
|
||||
- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
|
||||
- [ ] **Icons** — which icon library? custom SVGs? sizes?
|
||||
- [ ] **Avatars** — sizes, shapes, fallback behavior
|
||||
- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
|
||||
- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
|
||||
|
||||
## Phase 2: Component Inventory
|
||||
|
||||
For each distinct UI component, document:
|
||||
1. **Name** — what would you call this component?
|
||||
2. **Structure** — what HTML elements / child components does it contain?
|
||||
3. **Variants** — does it have different sizes, colors, or states?
|
||||
4. **States** — default, hover, active, disabled, loading, error, empty
|
||||
5. **Responsive behavior** — how does it change at different breakpoints?
|
||||
6. **Interactions** — click, hover, focus, keyboard navigation
|
||||
7. **Animations** — transitions, entrance/exit animations, micro-interactions
|
||||
|
||||
### Common Components to Look For
|
||||
- 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
|
||||
|
||||
## Phase 3: Layout Architecture
|
||||
|
||||
- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
|
||||
- [ ] **Column layout** — how many columns at each breakpoint?
|
||||
- [ ] **Max-width** — main content area max-width
|
||||
- [ ] **Sticky elements** — header, sidebar, floating buttons
|
||||
- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
|
||||
- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
|
||||
|
||||
## Phase 4: Technical Stack Analysis
|
||||
|
||||
- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
|
||||
- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
|
||||
- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
|
||||
- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
|
||||
- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
|
||||
- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF
|
||||
- [ ] **Animation library** — Framer Motion, GSAP, CSS transitions only
|
||||
|
||||
## Phase 5: Documentation Output
|
||||
|
||||
After inspection, create these files in `docs/research/`:
|
||||
1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
|
||||
2. `COMPONENT_INVENTORY.md` — Every component with structure notes
|
||||
3. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
|
||||
4. `INTERACTION_PATTERNS.md` — Animations, transitions, hover states
|
||||
5. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents
|
||||
@@ -0,0 +1,18 @@
|
||||
import { defineConfig, globalIgnores } from "eslint/config";
|
||||
import nextVitals from "eslint-config-next/core-web-vitals";
|
||||
import nextTs from "eslint-config-next/typescript";
|
||||
|
||||
const eslintConfig = defineConfig([
|
||||
...nextVitals,
|
||||
...nextTs,
|
||||
// Override default ignores of eslint-config-next.
|
||||
globalIgnores([
|
||||
// Default ignores of eslint-config-next:
|
||||
".next/**",
|
||||
"out/**",
|
||||
"build/**",
|
||||
"next-env.d.ts",
|
||||
]),
|
||||
]);
|
||||
|
||||
export default eslintConfig;
|
||||
@@ -0,0 +1,8 @@
|
||||
import type { NextConfig } from "next";
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
/* config options here */
|
||||
output: "standalone",
|
||||
};
|
||||
|
||||
export default nextConfig;
|
||||
Generated
+9782
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,59 @@
|
||||
{
|
||||
"name": "ai-website-clone-template",
|
||||
"version": "0.3.1",
|
||||
"private": true,
|
||||
"description": "Clone any website into a clean, modern Next.js codebase using AI coding agents",
|
||||
"author": "JCodesMore",
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/JCodesMore/ai-website-cloner-template.git"
|
||||
},
|
||||
"homepage": "https://github.com/JCodesMore/ai-website-cloner-template",
|
||||
"bugs": {
|
||||
"url": "https://github.com/JCodesMore/ai-website-cloner-template/issues"
|
||||
},
|
||||
"keywords": [
|
||||
"claude-code",
|
||||
"website-clone",
|
||||
"reverse-engineering",
|
||||
"nextjs",
|
||||
"ai",
|
||||
"template",
|
||||
"tailwindcss",
|
||||
"shadcn-ui"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=24"
|
||||
},
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "next start",
|
||||
"lint": "eslint",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"check": "npm run lint && npm run typecheck && npm run build"
|
||||
},
|
||||
"dependencies": {
|
||||
"@base-ui/react": "^1.3.0",
|
||||
"class-variance-authority": "^0.7.1",
|
||||
"clsx": "^2.1.1",
|
||||
"lucide-react": "^1.6.0",
|
||||
"next": "16.2.1",
|
||||
"react": "19.2.4",
|
||||
"react-dom": "19.2.4",
|
||||
"shadcn": "^4.1.0",
|
||||
"tailwind-merge": "^3.5.0",
|
||||
"tw-animate-css": "^1.4.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@tailwindcss/postcss": "^4",
|
||||
"@types/node": "^24",
|
||||
"@types/react": "^19",
|
||||
"@types/react-dom": "^19",
|
||||
"eslint": "^9",
|
||||
"eslint-config-next": "16.2.1",
|
||||
"tailwindcss": "^4",
|
||||
"typescript": "^5"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,7 @@
|
||||
const config = {
|
||||
plugins: {
|
||||
"@tailwindcss/postcss": {},
|
||||
},
|
||||
};
|
||||
|
||||
export default config;
|
||||
@@ -0,0 +1,88 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# sync-agent-rules.sh — Generate AI agent config files from AGENTS.md
|
||||
#
|
||||
# AGENTS.md is the single source of truth. This script creates copies
|
||||
# for agents that don't read AGENTS.md natively (Cline, Continue,
|
||||
# Amazon Q, GitHub Copilot Chat).
|
||||
#
|
||||
# Usage:
|
||||
# bash scripts/sync-agent-rules.sh
|
||||
#
|
||||
# Agents that DON'T need generated files (they read AGENTS.md natively):
|
||||
# Codex CLI, OpenCode, Cursor, Windsurf, Copilot Coding Agent,
|
||||
# Roo Code, Aider, Augment Code
|
||||
#
|
||||
# Agents with their own thin pointer files (created manually):
|
||||
# Claude Code → CLAUDE.md (@AGENTS.md import)
|
||||
# Gemini CLI → GEMINI.md (@AGENTS.md import)
|
||||
# Cursor → .cursor/rules/project.mdc (pointer)
|
||||
# Windsurf → .windsurfrules (pointer)
|
||||
# Aider → .aider.conf.yml (read: [AGENTS.md])
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
SOURCE="$REPO_ROOT/AGENTS.md"
|
||||
|
||||
if [[ ! -f "$SOURCE" ]]; then
|
||||
echo "Error: AGENTS.md not found at $SOURCE" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Resolve @file imports (Claude Code syntax) into inline content.
|
||||
# Lines like "@docs/research/INSPECTION_GUIDE.md" become the file's contents.
|
||||
resolve_imports() {
|
||||
while IFS= read -r line || [[ -n "$line" ]]; do
|
||||
line="${line%$'\r'}"
|
||||
if [[ "$line" =~ ^@(.+)$ ]]; then
|
||||
local import_path="${BASH_REMATCH[1]}"
|
||||
local resolved="$REPO_ROOT/$import_path"
|
||||
if [[ -f "$resolved" ]]; then
|
||||
cat "$resolved"
|
||||
echo ""
|
||||
else
|
||||
echo "<!-- Import not found: $import_path -->"
|
||||
fi
|
||||
else
|
||||
echo "$line"
|
||||
fi
|
||||
done < "$SOURCE"
|
||||
}
|
||||
|
||||
RESOLVED_CONTENT="$(resolve_imports)"
|
||||
|
||||
HEADER="<!-- AUTO-GENERATED from AGENTS.md — do not edit directly.
|
||||
Run \`bash scripts/sync-agent-rules.sh\` to regenerate. -->"
|
||||
|
||||
# Helper: write a generated file with header
|
||||
write_file() {
|
||||
local target="$1"
|
||||
local content="$2"
|
||||
mkdir -p "$(dirname "$target")"
|
||||
printf '%s\n\n%s\n' "$HEADER" "$content" > "$target"
|
||||
echo " ✓ $target"
|
||||
}
|
||||
|
||||
echo "Syncing agent rules from AGENTS.md..."
|
||||
|
||||
# GitHub Copilot Chat — .github/copilot-instructions.md
|
||||
write_file "$REPO_ROOT/.github/copilot-instructions.md" "$RESOLVED_CONTENT"
|
||||
|
||||
# Cline / Roo Code — .clinerules
|
||||
write_file "$REPO_ROOT/.clinerules" "$RESOLVED_CONTENT"
|
||||
|
||||
# Continue — .continue/rules/project.md
|
||||
CONTINUE_FRONTMATTER="---
|
||||
description: Project conventions for AI Website Clone Template
|
||||
alwaysApply: true
|
||||
---"
|
||||
write_file "$REPO_ROOT/.continue/rules/project.md" "$CONTINUE_FRONTMATTER
|
||||
$RESOLVED_CONTENT"
|
||||
|
||||
# Amazon Q Developer — .amazonq/rules/project.md
|
||||
write_file "$REPO_ROOT/.amazonq/rules/project.md" "$RESOLVED_CONTENT"
|
||||
|
||||
echo ""
|
||||
echo "Done. Generated files are committed to the repo but sourced from AGENTS.md."
|
||||
echo "Edit AGENTS.md, then re-run this script to update all agent configs."
|
||||
@@ -0,0 +1,112 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Generates clone-website command/skill files for all supported AI coding platforms.
|
||||
* Source of truth: .claude/skills/clone-website/SKILL.md
|
||||
*
|
||||
* Usage: node scripts/sync-skills.mjs
|
||||
*/
|
||||
|
||||
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
|
||||
import { dirname, join } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
|
||||
const SOURCE = join(ROOT, '.claude', 'skills', 'clone-website', 'SKILL.md');
|
||||
|
||||
// --- Parse source skill ---
|
||||
|
||||
let raw;
|
||||
try {
|
||||
raw = readFileSync(SOURCE, 'utf8').replace(/\r\n/g, '\n');
|
||||
} catch {
|
||||
console.error(`Error: Source skill not found at .claude/skills/clone-website/SKILL.md`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
|
||||
if (!match) {
|
||||
console.error('Error: Could not parse SKILL.md frontmatter');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const body = match[2];
|
||||
const shortDesc = 'Reverse-engineer and clone any website as a pixel-perfect replica';
|
||||
|
||||
// --- Helpers ---
|
||||
|
||||
function write(relPath, content) {
|
||||
const full = join(ROOT, relPath);
|
||||
mkdirSync(dirname(full), { recursive: true });
|
||||
writeFileSync(full, content, 'utf8');
|
||||
console.log(` \u2713 ${relPath}`);
|
||||
}
|
||||
|
||||
const HEADER =
|
||||
'<!-- AUTO-GENERATED from .claude/skills/clone-website/SKILL.md \u2014 do not edit directly.\n' +
|
||||
' Run `node scripts/sync-skills.mjs` to regenerate. -->\n\n';
|
||||
|
||||
const noArgs = (text) => text.replace(/\$ARGUMENTS/g, 'the target URL provided by the user');
|
||||
|
||||
// --- Generate ---
|
||||
|
||||
console.log('Syncing clone-website skill to all platforms...');
|
||||
console.log(` Source: .claude/skills/clone-website/SKILL.md\n`);
|
||||
|
||||
// 1. Codex CLI — same SKILL.md format, same $ARGUMENTS syntax
|
||||
write('.codex/skills/clone-website/SKILL.md', raw);
|
||||
|
||||
// 2. GitHub Copilot — same SKILL.md format
|
||||
write('.github/skills/clone-website/SKILL.md', raw);
|
||||
|
||||
// 3. Cursor — plain markdown, no argument substitution support
|
||||
write('.cursor/commands/clone-website.md', HEADER + noArgs(body));
|
||||
|
||||
// 4. Windsurf — markdown workflow
|
||||
write('.windsurf/workflows/clone-website.md', HEADER + noArgs(body));
|
||||
|
||||
// 5. Gemini CLI — TOML format, {{args}} for arguments
|
||||
const geminiBody = body.replace(/\$ARGUMENTS/g, '{{args}}');
|
||||
write(
|
||||
'.gemini/commands/clone-website.toml',
|
||||
`# AUTO-GENERATED from .claude/skills/clone-website/SKILL.md\n` +
|
||||
`# Run \`node scripts/sync-skills.mjs\` to regenerate.\n\n` +
|
||||
`description = "${shortDesc}"\n` +
|
||||
`name = "clone-website"\n\n` +
|
||||
`prompt = '''\n${geminiBody}\n'''\n`
|
||||
);
|
||||
|
||||
// 6. OpenCode — markdown + YAML frontmatter, $ARGUMENTS works natively
|
||||
write(
|
||||
'.opencode/commands/clone-website.md',
|
||||
`---\ndescription: "${shortDesc}"\n---\n${HEADER}${body}`
|
||||
);
|
||||
|
||||
// 7. Augment Code — markdown + YAML frontmatter
|
||||
write(
|
||||
'.augment/commands/clone-website.md',
|
||||
`---\ndescription: "${shortDesc}"\nargument-hint: "<url>"\n---\n${HEADER}${body}`
|
||||
);
|
||||
|
||||
// 8. Continue — prompt file with invokable: true
|
||||
write(
|
||||
'.continue/commands/clone-website.md',
|
||||
`---\nname: clone-website\ndescription: "${shortDesc}"\ninvokable: true\n---\n${HEADER}${body}`
|
||||
);
|
||||
|
||||
// 9. Amazon Q — JSON agent definition
|
||||
write(
|
||||
'.amazonq/cli-agents/clone-website.json',
|
||||
JSON.stringify(
|
||||
{
|
||||
name: 'clone-website',
|
||||
description: shortDesc,
|
||||
prompt: noArgs(body),
|
||||
fileContext: ['AGENTS.md', 'docs/research/**'],
|
||||
},
|
||||
null,
|
||||
2
|
||||
) + '\n'
|
||||
);
|
||||
|
||||
console.log('\nDone! 9 platform command files generated from source skill.');
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
@@ -0,0 +1,130 @@
|
||||
@import "tailwindcss";
|
||||
@import "tw-animate-css";
|
||||
@import "shadcn/tailwind.css";
|
||||
|
||||
@custom-variant dark (&:is(.dark *));
|
||||
|
||||
@theme inline {
|
||||
--color-background: var(--background);
|
||||
--color-foreground: var(--foreground);
|
||||
--font-sans: "Geist", "Geist Fallback", ui-sans-serif, system-ui, sans-serif;
|
||||
--font-mono: "Geist Mono", "Geist Mono Fallback", ui-monospace, monospace;
|
||||
--font-heading: var(--font-sans);
|
||||
--color-sidebar-ring: var(--sidebar-ring);
|
||||
--color-sidebar-border: var(--sidebar-border);
|
||||
--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
|
||||
--color-sidebar-accent: var(--sidebar-accent);
|
||||
--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
|
||||
--color-sidebar-primary: var(--sidebar-primary);
|
||||
--color-sidebar-foreground: var(--sidebar-foreground);
|
||||
--color-sidebar: var(--sidebar);
|
||||
--color-chart-5: var(--chart-5);
|
||||
--color-chart-4: var(--chart-4);
|
||||
--color-chart-3: var(--chart-3);
|
||||
--color-chart-2: var(--chart-2);
|
||||
--color-chart-1: var(--chart-1);
|
||||
--color-ring: var(--ring);
|
||||
--color-input: var(--input);
|
||||
--color-border: var(--border);
|
||||
--color-destructive: var(--destructive);
|
||||
--color-accent-foreground: var(--accent-foreground);
|
||||
--color-accent: var(--accent);
|
||||
--color-muted-foreground: var(--muted-foreground);
|
||||
--color-muted: var(--muted);
|
||||
--color-secondary-foreground: var(--secondary-foreground);
|
||||
--color-secondary: var(--secondary);
|
||||
--color-primary-foreground: var(--primary-foreground);
|
||||
--color-primary: var(--primary);
|
||||
--color-popover-foreground: var(--popover-foreground);
|
||||
--color-popover: var(--popover);
|
||||
--color-card-foreground: var(--card-foreground);
|
||||
--color-card: var(--card);
|
||||
--radius-sm: calc(var(--radius) * 0.6);
|
||||
--radius-md: calc(var(--radius) * 0.8);
|
||||
--radius-lg: var(--radius);
|
||||
--radius-xl: calc(var(--radius) * 1.4);
|
||||
--radius-2xl: calc(var(--radius) * 1.8);
|
||||
--radius-3xl: calc(var(--radius) * 2.2);
|
||||
--radius-4xl: calc(var(--radius) * 2.6);
|
||||
}
|
||||
|
||||
:root {
|
||||
--background: oklch(1 0 0);
|
||||
--foreground: oklch(0.145 0 0);
|
||||
--card: oklch(1 0 0);
|
||||
--card-foreground: oklch(0.145 0 0);
|
||||
--popover: oklch(1 0 0);
|
||||
--popover-foreground: oklch(0.145 0 0);
|
||||
--primary: oklch(0.205 0 0);
|
||||
--primary-foreground: oklch(0.985 0 0);
|
||||
--secondary: oklch(0.97 0 0);
|
||||
--secondary-foreground: oklch(0.205 0 0);
|
||||
--muted: oklch(0.97 0 0);
|
||||
--muted-foreground: oklch(0.556 0 0);
|
||||
--accent: oklch(0.97 0 0);
|
||||
--accent-foreground: oklch(0.205 0 0);
|
||||
--destructive: oklch(0.577 0.245 27.325);
|
||||
--border: oklch(0.922 0 0);
|
||||
--input: oklch(0.922 0 0);
|
||||
--ring: oklch(0.708 0 0);
|
||||
--chart-1: oklch(0.87 0 0);
|
||||
--chart-2: oklch(0.556 0 0);
|
||||
--chart-3: oklch(0.439 0 0);
|
||||
--chart-4: oklch(0.371 0 0);
|
||||
--chart-5: oklch(0.269 0 0);
|
||||
--radius: 0.625rem;
|
||||
--sidebar: oklch(0.985 0 0);
|
||||
--sidebar-foreground: oklch(0.145 0 0);
|
||||
--sidebar-primary: oklch(0.205 0 0);
|
||||
--sidebar-primary-foreground: oklch(0.985 0 0);
|
||||
--sidebar-accent: oklch(0.97 0 0);
|
||||
--sidebar-accent-foreground: oklch(0.205 0 0);
|
||||
--sidebar-border: oklch(0.922 0 0);
|
||||
--sidebar-ring: oklch(0.708 0 0);
|
||||
}
|
||||
|
||||
.dark {
|
||||
--background: oklch(0.145 0 0);
|
||||
--foreground: oklch(0.985 0 0);
|
||||
--card: oklch(0.205 0 0);
|
||||
--card-foreground: oklch(0.985 0 0);
|
||||
--popover: oklch(0.205 0 0);
|
||||
--popover-foreground: oklch(0.985 0 0);
|
||||
--primary: oklch(0.922 0 0);
|
||||
--primary-foreground: oklch(0.205 0 0);
|
||||
--secondary: oklch(0.269 0 0);
|
||||
--secondary-foreground: oklch(0.985 0 0);
|
||||
--muted: oklch(0.269 0 0);
|
||||
--muted-foreground: oklch(0.708 0 0);
|
||||
--accent: oklch(0.269 0 0);
|
||||
--accent-foreground: oklch(0.985 0 0);
|
||||
--destructive: oklch(0.704 0.191 22.216);
|
||||
--border: oklch(1 0 0 / 10%);
|
||||
--input: oklch(1 0 0 / 15%);
|
||||
--ring: oklch(0.556 0 0);
|
||||
--chart-1: oklch(0.87 0 0);
|
||||
--chart-2: oklch(0.556 0 0);
|
||||
--chart-3: oklch(0.439 0 0);
|
||||
--chart-4: oklch(0.371 0 0);
|
||||
--chart-5: oklch(0.269 0 0);
|
||||
--sidebar: oklch(0.205 0 0);
|
||||
--sidebar-foreground: oklch(0.985 0 0);
|
||||
--sidebar-primary: oklch(0.488 0.243 264.376);
|
||||
--sidebar-primary-foreground: oklch(0.985 0 0);
|
||||
--sidebar-accent: oklch(0.269 0 0);
|
||||
--sidebar-accent-foreground: oklch(0.985 0 0);
|
||||
--sidebar-border: oklch(1 0 0 / 10%);
|
||||
--sidebar-ring: oklch(0.556 0 0);
|
||||
}
|
||||
|
||||
@layer base {
|
||||
* {
|
||||
@apply border-border outline-ring/50;
|
||||
}
|
||||
body {
|
||||
@apply bg-background text-foreground;
|
||||
}
|
||||
html {
|
||||
@apply font-sans;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
import type { Metadata } from "next";
|
||||
import { Geist, Geist_Mono } from "next/font/google";
|
||||
import "./globals.css";
|
||||
|
||||
const geistSans = Geist({
|
||||
variable: "--font-geist-sans",
|
||||
subsets: ["latin"],
|
||||
});
|
||||
|
||||
const geistMono = Geist_Mono({
|
||||
variable: "--font-geist-mono",
|
||||
subsets: ["latin"],
|
||||
});
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: "Website Clone",
|
||||
description: "Pixel-perfect website clone",
|
||||
};
|
||||
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: Readonly<{
|
||||
children: React.ReactNode;
|
||||
}>) {
|
||||
return (
|
||||
<html
|
||||
lang="en"
|
||||
className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
|
||||
>
|
||||
<body className="min-h-full flex flex-col">{children}</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
export default function Home() {
|
||||
return (
|
||||
<main className="flex min-h-screen items-center justify-center">
|
||||
<p className="text-muted-foreground">
|
||||
Clone target not yet built. Run <code className="font-mono text-foreground">/clone-website</code> to start.
|
||||
</p>
|
||||
</main>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,60 @@
|
||||
"use client"
|
||||
|
||||
import { Button as ButtonPrimitive } from "@base-ui/react/button"
|
||||
import { cva, type VariantProps } from "class-variance-authority"
|
||||
|
||||
import { cn } from "@/lib/utils"
|
||||
|
||||
const buttonVariants = cva(
|
||||
"group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
|
||||
{
|
||||
variants: {
|
||||
variant: {
|
||||
default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
|
||||
outline:
|
||||
"border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
|
||||
secondary:
|
||||
"bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
|
||||
ghost:
|
||||
"hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
|
||||
destructive:
|
||||
"bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
|
||||
link: "text-primary underline-offset-4 hover:underline",
|
||||
},
|
||||
size: {
|
||||
default:
|
||||
"h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
|
||||
xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
|
||||
sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
|
||||
lg: "h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3",
|
||||
icon: "size-8",
|
||||
"icon-xs":
|
||||
"size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
|
||||
"icon-sm":
|
||||
"size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
|
||||
"icon-lg": "size-9",
|
||||
},
|
||||
},
|
||||
defaultVariants: {
|
||||
variant: "default",
|
||||
size: "default",
|
||||
},
|
||||
}
|
||||
)
|
||||
|
||||
function Button({
|
||||
className,
|
||||
variant = "default",
|
||||
size = "default",
|
||||
...props
|
||||
}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) {
|
||||
return (
|
||||
<ButtonPrimitive
|
||||
data-slot="button"
|
||||
className={cn(buttonVariants({ variant, size, className }))}
|
||||
{...props}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
export { Button, buttonVariants }
|
||||
@@ -0,0 +1,6 @@
|
||||
import { clsx, type ClassValue } from "clsx"
|
||||
import { twMerge } from "tailwind-merge"
|
||||
|
||||
export function cn(...inputs: ClassValue[]) {
|
||||
return twMerge(clsx(inputs))
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2017",
|
||||
"lib": ["dom", "dom.iterable", "esnext"],
|
||||
"allowJs": true,
|
||||
"skipLibCheck": true,
|
||||
"strict": true,
|
||||
"noEmit": true,
|
||||
"esModuleInterop": true,
|
||||
"module": "esnext",
|
||||
"moduleResolution": "bundler",
|
||||
"resolveJsonModule": true,
|
||||
"isolatedModules": true,
|
||||
"jsx": "react-jsx",
|
||||
"incremental": true,
|
||||
"plugins": [
|
||||
{
|
||||
"name": "next"
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"@/*": ["./src/*"]
|
||||
}
|
||||
},
|
||||
"include": [
|
||||
"next-env.d.ts",
|
||||
"**/*.ts",
|
||||
"**/*.tsx",
|
||||
".next/types/**/*.ts",
|
||||
".next/dev/types/**/*.ts",
|
||||
"**/*.mts"
|
||||
],
|
||||
"exclude": ["node_modules"]
|
||||
}
|
||||
Reference in New Issue
Block a user