Clone design

Clone Design — a website-cloning engineer's playbook

You are reverse-engineering a real website and rebuilding it so faithfully that someone flipping between the two can't tell which is which — not only the static pixels, but the way it moves and behaves: the sticky pins, the drag-scroll carousels, the scroll-reveals, the hover transitions, the layered overlays, the color grading. Getting the motion and depth right is what separates a clone that is the site from a screenshot that merely resembles it.

This is not "inspect, then build." You are a foreman walking the job site: as you inspect each section you write a precise spec, then hand it to a builder with everything needed to nail it. Extraction and construction run in parallel, but extraction is meticulous and produces auditable artifacts.

When the target is a single section, not a whole page

Most real requests are narrow: "match their carousel," "this hero still looks off," "the overlap is missing." Don't spin up the full page-topology pipeline for those. Jump straight to: (1) identify the interaction model (scroll before you click — see the interaction sweep in Phase 1), (2) extract the exact styles and behavior of that one section — run the getAnimations()/pseudo-element/measurement snippets in references/extraction-toolkit.md, and if it's visually rich, decompose its layers with references/layering.md, (3) match its motion physics via references/frameworks.md and find the recipe in references/effects-cookbook.md, (4) build, (5) prove it with the pixel-diff + onion-skin loop in references/verification.md. Scale the process to the job — but even for one section, measure and diff; don't eyeball.

Bundled references — read them when you reach that step

• references/extraction-toolkit.md — copy-paste browser-console snippets: the deep getComputedStyle walker, live document.getAnimations() motion capture, pseudo-element and advanced-rendering probes, bounding-box spacing measurement, responsive-image/<picture> capture, variable-font descriptors, the source-stack fingerprint, the a11y snapshot, and how to mine tokens out of a saved (minified) HTML source. Read this before extracting any section.
• references/layering.md — the layer-decomposition workflow: how to pull a rich section apart into its depth stack (base → gradient → pattern → noise → glow → SVG → content → floating → overlay → blend/filter), plus stacking-context discipline and per-layer recipes. Read this for any visually rich section — it's how you avoid shipping a flat two-color box where the original had six layers.
• references/frameworks.md — map the source site's detected stack (GSAP, Lenis, Swiper, Embla, Framer Motion, Radix, Next/Nuxt/Astro…) to the library + physics you must reproduce so the motion feels like theirs, not just moves. Read this after running the source-stack fingerprint.
• references/effects-cookbook.md — implementation recipes for the effects you'll meet again and again: sticky-pin, GPU drag carousel, auto-advancing carousel, scroll-reveal, staggered choreography, spring motion, scroll-scrub & parallax, headroom header, negative-margin bleed and band-intersection overlap, diagonal checkerboard grading, gradient-text/glass/clip-path, precise text cropping, per-instance accent theming, and RTL-safe transform tracks. Read the relevant recipe before building an interactive or layered section.
• references/verification.md — the visual-QA loop: the pixel-diff + onion-skin gate, the reliable full-page-screenshot-then-crop technique, the interaction state-matrix, the responsive compare table, and the required fidelity report + confidence score. Read this before you claim a section is done.

---

Pre-flight

1. Browser automation is required. Check for a browser MCP (Playwright, Chrome, Puppeteer, Browserbase). Prefer Chrome/Playwright. If none exists, ask the user which they have. The skill cannot work without it — you have to observe behavior, not just guess at it.
2. Two sources, and the saved source is often better. A live URL lets you observe behavior; a saved HTML file (View Source / "Save as") lets you mine exact token values out of the CSS with regex, offline, with no flakiness. When the user hands you an HTML file, treat it as the authoritative source for colors/fonts/weights/spacing and use the live page for behavior. (On the MIT clone, mining the saved CSS overturned several values eyeballed from screenshots — neon→pastel accents, bold→600 weight, uppercase→sentence-case eyebrows, 72rem→80rem container.)
3. Detect the target project's stack — don't assume one. Read package.json. React+Vite+Tailwind, Next.js+shadcn, SvelteKit, plain HTML — the methodology is identical; only the file layout and class syntax differ. Match the conventions already in the repo (token architecture, RTL handling, existing components) instead of importing a foreign scaffold. Verify the base builds before you start.
4. Fingerprint the source site's stack too. Run the source-stack fingerprint (toolkit §15) on the live page. Detecting that it uses GSAP+ ScrollTrigger, Lenis, Swiper, Embla, Framer Motion, or Radix tells you the physics to reproduce — you can't match a Lenis scroll or a Framer spring you never identified. Map the result to matching libraries via references/frameworks.md.
5. Prepare artifact folders: docs/research/, docs/research/components/, docs/design-references/. For multiple sites, namespace per host (docs/research/<hostname>/).

Scope defaults

Pixel-perfect, pure emulation: exact colors, spacing, typography, and animations/effects. In scope: visual layout, layered composition, component structure, interactions, responsive behavior, mock data, and the interaction semantics that have visual consequences — semantic tags, aria-*, focus order, visible focus rings, and prefers-reduced-motion variants (these are part of how the site behaves, and drive :focus-visible/:focus-within styling). Out of scope (unless asked): real backend, auth, real-time data, SEO, and formal WCAG conformance auditing. Honor any explicit user override.

---

The nine guiding principles

These are the truths that separate a real clone from a "close enough" mess.

1. Completeness beats speed. Every builder must receive everything: screenshot, exact computed values, downloaded assets with local paths, real text, component structure, and the behavior spec. If a builder has to guess a color, a duration, or an easing curve, extraction failed.

2. Small tasks, perfect results. "Build the whole features section" produces approximations. One focused component with exact values gets nailed. Budget rule: if a builder spec exceeds ~150 lines, split the section. Mechanical check — don't override it with "but it's all related."

3. Real content, real assets. Extract actual text, images, SVGs, videos. element.textContent, download every <img>, lift inline <svg> into components. A clone with placeholder art always looks fake no matter how perfect the CSS.

4. Foundation first (sequential, non-negotiable). Global tokens (colors/fonts/spacing), type definitions, global assets, and any global motion (smooth-scroll libs, keyframes, scroll-snap) must exist before any section is built. Everything after can be parallel.

5. Extract how it looks AND how it behaves. A website is a living thing — it moves, changes, appears, and disappears in response to scroll, hover, click, resize, and time. Static CSS alone gives you a clone that looks right in a screenshot and feels dead in the hand. For every element capture the appearance (exact getComputedStyle) and the behavior: what changes, what triggers it, and how it transitions (duration, easing, CSS-vs-JS-vs-animation-timeline). This is the heart of the skill — see the interaction sweep (Phase 1), getAnimations() (toolkit §9), and the effects cookbook.

6. Identify the interaction model before building. The single most expensive mistake is building a click UI when the original is scroll-driven, or vice versa. Answer first: is this section driven by clicks, scrolls, hovers, time, or a mix? (How: the interaction sweep in Phase 1 — scroll before you click.) Getting it wrong is a rewrite, not a tweak.

7. Extract every state, not just the default. Tabs show different cards per tab; a header differs at scrollY 0 vs 100; cards have hover states. Capture all of them — click each tab, scroll past each trigger, hover each element — and record the transition between states.

8. Spec files are the source of truth. Every component gets a spec in docs/research/components/<name>.spec.md before any builder is dispatched. The builder receives the spec inline in its prompt — never "go read the doc." The file also persists as an auditable artifact.

9. Build must always compile. Every builder verifies the typecheck/build passes before finishing. After merging, you verify the whole build. A broken build is never acceptable, even temporarily.

---

Phase 1 — Reconnaissance

Screenshots. Full-page captures at 1440px (desktop) and 390px (mobile) → docs/design-references/. These are your master reference.

Global extraction. Before anything else, pull: fonts (every @font-face family/weight/style actually used on headings, body, labels, mono), the color palette (from computed styles across the page, plus any saved-CSS custom properties), favicons/OG/meta, and global UI patterns (custom scrollbars, scroll-snap on the container, global keyframes, backdrop filters, gradient overlays, and smooth-scroll libraries — check for .lenis, .locomotive-scroll, or a scroll-container wrapper). The exact snippets are in references/extraction-toolkit.md.

Mandatory interaction sweep — a dedicated pass after screenshots, before building. Most behavior is invisible in a static capture, so go find it:

• Scroll sweep: scroll slowly top→bottom. At each section, does the header change (record the scroll position)? Do elements animate in (which, what type)? Does a sidebar/tab indicator auto-switch (record the mechanism)? Are there scroll-snap points? Is a smooth-scroll library active?
• Click sweep: click every button/tab/pill/card. Record what changes. For tabbed content, click each state and record its content.
• Hover sweep: hover every button/card/link/nav item. Record what changes (color, scale, shadow, underline, opacity) and the transition timing.
• Responsive sweep: at 2560 / 1440 / 1024 / 768 / 390, note which sections restructure and at roughly which breakpoint (ultra-wide exposes max-width and centered-container assumptions the desktop width hides).

Save findings to docs/research/BEHAVIORS.md — your behavior bible.

Ten named inventories — turn the sweep's prose into rosters that must reach zero unaccounted before you build. Prose lets things slip; a checklist doesn't. If it's on the page and not on a list, it will be forgotten. Save as docs/research/INVENTORY.md:

1. Component — every distinct component and its variants.
2. Interaction — every hover/click/focus/drag/scroll/keyboard behavior.
3. Animation — every transition, keyframe, scroll-scrub, autoplay, stagger (cross-check with getAnimations(), toolkit §9).
4. Typography — every type role (hed/dek/eyebrow/label/body/mono) with its full descriptor (toolkit §14).
5. Spacing — the spacing scale and any notable measured gaps (toolkit §12).
6. Color / token — every color, gradient, shadow, radius, opacity, duration, easing, blur (design tokens).
7. Image — every image with format and responsive chain (toolkit §13).
8. Icon / SVG — every inline SVG and icon.
9. Decoration / overlay / layer — every divider, glow, noise, mask, blend, pseudo-element graphic, floating shape (toolkit §5/§10/§11, layering.md).
10. Responsive — what restructures at each breakpoint.

Page topology. Map every section top→bottom with a working name, its visual order, whether it's fixed/sticky overlay vs flow content, the z-index layering, each section's interaction model (static / click / scroll / time), and the detected source stack + matched motion libraries (fingerprint, frameworks.md). Save as docs/research/PAGE_TOPOLOGY.md — your assembly blueprint.

---

Phase 2 — Foundation build (do it yourself, sequential)

Wire the target's actual fonts into the project's font system. Put its color tokens, spacing scale, keyframes, utility classes, and global scroll behavior into the global stylesheet using the repo's existing token convention. Create type definitions for the content structures. Extract and dedupe inline SVGs into named icon components. Write and run an asset-download script (batched, ~4 parallel, with error handling) that pulls every image/video to the public assets dir, preserving structure. Verify the build passes.

If the target has image-heavy covers, consider optimizing on the way in (e.g. cwebp -q 80, resizing only when wider than the layout needs) — but never delete source assets without explicit user authorization.

---

Phase 3 — Section loop: extract → spec → dispatch → merge

For each section, top to bottom:

Extract — measure and capture, don't eyeball. Screenshot it in isolation, then run the toolkit over it:

• Static: the deep computed-style walker + the advanced-rendering probe (clip-path/mask/blend/filter/3D) + pseudo-element extraction (dividers, glows, underline bars hide here) + variable-font descriptors for each type role.
• Spacing: measure the rendered gaps with the bounding-box tool — don't reconstruct spacing from computed padding.
• Motion: run getAnimations() first (captures CSS and JS/WAAPI motion), then the keyframe-text extractor for hover/static states; capture both states with the trigger and the exact easing. For a stagger, read each child's delay.
• Depth: if the section is visually rich, decompose its layer stack with references/layering.md — a "single image" hero is often base + gradient + noise + glow + foreground + overlay.
• Assets & a11y: enumerate every asset including overlays and the responsive <picture>/srcset chain; snapshot roles/aria/focus for interactive elements.

Snippets: references/extraction-toolkit.md.

Write the spec → docs/research/components/<name>.spec.md:

# <ComponentName> Specification
## Overview
- Target file: src/.../<ComponentName>.<ext>
- Screenshot: docs/design-references/<name>.png
- Interaction model: static | click-driven | scroll-driven | time-driven
- Source-stack physics to match: <e.g. Framer spring / GSAP scrub / Embla drag / none>

## DOM structure
<hierarchy — what contains what, incl. overlay/layer order and z-index>

## Layer stack (bottom → top)   ← for visually rich sections; see layering.md
<base / gradient / pattern / noise / glow / svg / content / floating / overlay / blend>

## Computed styles (exact getComputedStyle values)
### Container / ### <child 1> / ### <child N>
<every relevant property with exact values, incl. clip-path/mask/blend/filter and
 pseudo-element (::before/::after) graphics>

## Measured spacing (bounding-box gaps, not computed padding)
<e.g. 40px between rows · 10px eyebrow→hed · container 1280px>

## Typography (full descriptor per role)
<family · variation-settings/opsz · weight · size/line-height/tracking · smoothing · text-wrap>

## States & behaviors
### <behavior name, e.g. "sticky pin" / "scroll-reveal" / "hover underline">
- Trigger: <scroll position 120px | IntersectionObserver rootMargin "-30% 0px" | hover | click .tab>
- State A (before): <exact props>   → State B (after): <exact props>
- Transition/animation: <duration, easing (verbatim), stagger interval, iteration>
- Implementation approach: <CSS transition | IO | animation-timeline | Framer spring | GSAP | JS refs>

## Assets (incl. overlays & responsive chain)
- <bg image>, <foreground mockup>, <icon> — local paths, z-index, srcset/<picture>

## Accessibility
- <semantic tags · aria-* · focus order · focus-ring style · reduced-motion variant>

## Text content (verbatim)
## Responsive behavior (2560 / 1440 / 1024 / 768 / 390 + breakpoints)

Fill every field. Think twice before writing "N/A" under States & Behaviors, Layer stack, or Accessibility — even a footer has link hover states, and a plain band often has a pseudo-element rule or a gradient you'd otherwise miss.

Dispatch builders by complexity. Simple section (1–2 subcomponents) → one builder. Complex (3+ distinct subcomponents) → one builder per subcomponent plus a wrapper builder (subcomponents first). Each builder receives: the full spec inline, the screenshot path, which shared components/tokens to import, the target file path, the responsive breakpoints, and the instruction to verify the typecheck before finishing. Don't wait — dispatch, then move on to extracting the next section while builders work in parallel.

Merge. As builders finish, integrate their work, resolve conflicts with your full context, and re-verify the build after each merge.

---

Phase 4 — Page assembly

Wire sections together per PAGE_TOPOLOGY.md: scroll containers, column structure, sticky positioning, z-index layers. Connect real content to props. Implement page-level behavior (scroll-snap, scroll-driven animation, dark↔light section transitions, IntersectionObservers, smooth scroll). Verify the build.

Phase 5 — Visual QA diff (do NOT skip)

Prove fidelity, don't assert it. Run the pixel-diff + onion-skin gate (references/verification.md) per section first — it flags drift the eye misses and points you at the wrong value. Then compare side by side, section by section, at 2560 / 1440 / 1024 / 768 / 390 using the responsive compare table. For each discrepancy: check the spec — if the value was wrong, re-extract and update the spec, then fix; if the spec was right but the build diverged, fix the build. Then drive every behavior live via the state matrix (each element in default/hover/focus/active/disabled), confirm the header transition, the carousel drag/inertia, the reveals and their stagger, scroll-scrub tracking, and the reduced-motion path. Full checklists and the reliable capture technique are in references/verification.md.

Phase 6 — Fidelity report & sign-off (the completion gate)

The clone is not done until you've produced docs/research/FIDELITY_REPORT.md (template in references/verification.md): a per-section confidence table (layout / type / color / motion / responsive / pixel-diff %), an explicit list of remaining approximations, and any deferred deltas. Its purpose is to force the "what did I skip?" pass — writing an honest number per section surfaces the half-finished ones. A section reaches 99–100% only when pixel-diff < ~1%, every state is matched, motion is matched (not approximated), and responsive is verified at all breakpoints. Hand the user the report, not a bare "done."

---

Pre-dispatch checklist

Before dispatching any builder, confirm every box. If you can't, extract more.

• Spec file written with all sections filled
• Every CSS value is from getComputedStyle (incl. clip-path/mask/blend/ filter/3D and ::before/::after), not estimated
• Spacing is measured (bounding-box gaps), not sampled from padding
• Typography descriptor complete (variable-font axes, smoothing, text-wrap)
• Layer stack decomposed for visually rich sections
• Interaction model identified and documented
• For stateful components: every state's content + styles captured
• Motion captured via getAnimations(); trigger, before/after, exact easing, stagger recorded; source-stack physics to match noted
• For hover/focus states: before/after + transition timing recorded
• All assets identified, including overlays, layers, and the responsive <picture>/srcset chain
• Accessibility captured (semantic tags, aria, focus order/ring, reduced-motion)
• Responsive behavior documented at 2560 / 1440 / 1024 / 768 / 390
• Text is verbatim from the site
• Spec is under ~150 lines; if over, split the section

What NOT to do — lessons that cost hours

• Don't guess the interaction model. Scroll before you click. Building click-tabs over a scroll-driven section is a full rewrite. (#1 mistake.)
• Don't extract only the default state. Click every tab, capture the header at scrollY 0 and past its trigger.
• Don't miss overlay/layered images. Inspect each container's full subtree for stacked <img>/background images and absolutely-positioned overlays. A missing overlay makes a correct background look empty.
• Don't fake a layered effect with the wrong mechanism. An "overlap" is usually a real layout relationship — a negative margin, a taller neighbor, a bleed past the container edge — not a z-index hack that paints over and hides the next element. Read the DOM to see which; see the bleed/overlap recipes in the cookbook. (Learned the hard way: a z-index:20 "bleed" silently covered the following article.)
• Don't approximate the aspect ratio. padding-bottom: 56.25% means exactly 16:9. A wrong ratio changes the whole section's rhythm. Read it, don't eyeball.
• Don't approximate CSS values. "Looks like text-lg" is wrong if the computed line-height differs. Extract exact values.
• Don't approximate easing. ease-out where the source is a custom cubic-bezier (or a spring) feels wrong. Copy the curve from getAnimations().timing; reproduce springs as springs, not fixed durations.
• Don't play a scroll-scrubbed animation on a timer. If it tracks scroll and reverses on scroll-up, bind it to scroll — an autoplay version is obviously off.
• Don't be pseudo-element-blind. Cloning only real DOM nodes drops ::before/::after dividers, badges, and underlines — run the pseudo-element walker.
• Don't ship magic-number spacing or fixed heights. mt-[37px] reverse- engineered from a screenshot, or h-[640px] on content that should size itself, breaks at other widths/locales. Measure the real gap; let content define height.
• Don't screenshot-bake a gradient, noise, glow, or blur. A flattened PNG of a CSS effect can't respond to theme/size and gives the clone away. Reproduce the gradient stops / turbulence / radial glow / backdrop-filter in CSS.
• Don't use transform for layout. Transforms are for motion; positioning content with translate that should be laid out by flow/grid breaks reflow and a11y.
• Don't z-index-blindly. Map the stacking context first (isolation, positioned/transform/opacity ancestors) — bumping a number across contexts does nothing and can hide content.
• Don't drop the responsive image chain or use a static font for a variable one. img.src-only loses srcset/AVIF; a static weight misses optical/weight interpolation.
• Don't build mockups of what's actually a video/Lottie/canvas. Check first.
• Don't reference external docs from a builder prompt. Inline the spec.
• Don't skip asset extraction, responsive extraction, or smooth-scroll detection. Each one, skipped, is instantly visible to the user.
• Don't declare done without the pixel-diff and the fidelity report. Screenshot both, diff, drive every state, and write an honest confidence score.