Clone Website — Pixel-Perfect Methodology

Reverse-engineer and rebuild a target website as an exact replica React + Vite clone. Every font, color, icon, image, section, background, transition, and interaction must match the original. Zero guessing, zero placeholders.

Cardinal Rules

1. Raw HTML is the source of truth. Before building ANY section, read the corresponding portion of

   raw.html

   . Never build from memory, screenshots alone, or guessed structure.

2. One component per visual pattern. Never reuse a component designed for one layout (e.g., product cards with prices) for a structurally different layout (e.g., category cards with just names). If two sections look different, they get different components or distinct CSS classes.

3. All assets downloaded before building starts. Every image, font, SVG, and video must be local in

   public/

   before any component code is written. No mid-build downloads.

4. Build all sections, then verify the full page. Building and screenshotting section-by-section is too slow. Build all components from raw HTML, assemble in App.tsx, then take a full-page screenshot and fix any discrepancies. This is 3-5x faster than per-section verification loops.

5. No fabricated content. Every heading, subtitle, button label, badge, price, and link must come from the source HTML. Never invent text that doesn't exist on the original page.

6. Replace the scaffolded CSS entirely. The

   createArtifact

   scaffold includes Tailwind/shadcn boilerplate. Replace

   index.css

   completely with plain CSS — a Google Font import, CSS reset, CSS variables for design tokens, and nothing else. Clone pages don't use component libraries.

Anti-Patterns (Common Mistakes to Avoid)

| Mistake | Correct Approach |

|---------|-----------------|

| Outlined/bordered buttons when original uses filled/solid | Check

raw.html

for button classes and extract

background-color

, not

border

|

| Center-aligned text when original is left-aligned | Extract

text-align

from computed styles |

| Adding badges/labels that don't exist in original | Only add elements that exist in

raw.html

|

| Skipping sections or changing their order | Follow the section inventory checklist exactly |

| Using placeholder images | Download all images in Phase 1 before building |

| Reusing

ProductCard

for category grids | Each visually distinct card type gets its own component |

| Guessing font sizes, colors, spacing | Extract exact computed values; never approximate |

| Building from screenshot interpretation alone | Always cross-reference

raw.html

for structure and content |

| Using an SVG

<text>

element for the logo | Extract the real SVG logo paths from

raw.html

|

| Running per-section screenshot QA loops | Build all sections, then do one full-page verify pass |

| Keeping Tailwind/shadcn/Radix in a clone | Replace index.css with plain CSS; remove unused deps |

| Translating/anglicizing text from a non-English page | Clone must use the EXACT language shown on the target page |

| Guessing the announcement bar color | Extract computed

background-color

from the banner element |

| Centering the logo when it's left-aligned | Take a header screenshot and compare logo position |

| Omitting the account/rewards bar text | Extract ALL header elements including loyalty/rewards UI |

Legitimate Use Policy

Before cloning, confirm the user's intent is legitimate. Ask:

1. "Is this your own website or your client's website?"
2. "What is this clone for?"

Acceptable: rebuilding your own site, design reference/learning, staging copy, platform migration.

Refuse if: impersonation, phishing, traffic theft, trademark infringement, or deception.

For non-owned sites (design inspiration), remind the user to replace logos, brand names, trademarks, product data, and contact info with their own.

Prerequisites

pip install playwright

CHROMIUM_PATH=$(find /nix/store -maxdepth 4 -name "chromium" -type f 2>/dev/null | head -1)

echo "Chromium at: $CHROMIUM_PATH"

Critical Playwright settings

• Always use

  --no-sandbox

  args

• Use

  wait_until="domcontentloaded"

  (not

  "networkidle"

  )

• Add

  page.wait_for_timeout(5000)

  after navigation

• Set

  timeout=60000

  on all

  page.goto()

  calls

---

Phase 1: Reconnaissance & Extraction

All extraction happens before any building. See

extraction.md

for complete Python scripts.

1.1 Save Raw HTML (THE SOURCE OF TRUTH)

raw_html = page.content()

with open(f"{OUT_DIR}/raw.html", "w", encoding="utf-8") as f:

f.write(raw_html)

This file is the authoritative reference for ALL section structure, content, class names, element ordering, and text content. Computed styles supplement it but never replace it.

1.2 Language & Locale Detection (CRITICAL)

If the target URL contains a locale path (e.g.,

/es-do

,

/fr

,

/de

,

/ja

), the clone MUST be in that language. However, server-side rendering may return English even for locale URLs — the localization often happens via client-side JavaScript after page load.

Detection steps

1. After

   page.wait_for_timeout(8000)

   (extra wait for JS locale loading), extract all visible text from key areas:

locale_info = page.evaluate("""

() => ({

bannerText: document.querySelector('[class*="banner"], [class*="announcement"]')?.innerText?.trim(),

navLinks: [...document.querySelectorAll('nav a, .main-nav a')].map(a => a.innerText.trim()).filter(t => t).slice(0, 8),

loyaltyText: document.querySelector('[class*="loyalty"], [class*="rewards"]')?.innerText?.trim(),

headerText: document.querySelector('header')?.innerText?.trim()?.slice(0, 500),

htmlLang: document.documentElement.lang,

url: window.location.href

})

""")

1. If the URL locale doesn't match the extracted text language, the page probably needs more time for JS to run, or the locale is cookie-based.
2. When in doubt, use the language implied by the URL locale. If

   /es-do

   shows English text in the raw HTML, translate all user-facing text to Spanish when building. The URL locale is the user's intent.

Brand terms stay in the original language. Product names (e.g., "ALO Runner"), color names (e.g., "SUNSHINE"), brand names (e.g., "ALO Wellness Club") should NOT be translated — the real site keeps these in English even on localized pages.

1.3 Screenshots (Desktop only for initial build)

Take a full-page screenshot at 1440px. This becomes the primary visual reference. Tablet and mobile screenshots are only needed if the user specifically requests responsive behavior.

Take a separate header-only screenshot at this stage — crop to just the top 150px. This will be your reference for logo placement, nav layout, banner color, and account/rewards UI. Header issues are the most common mistakes.

1.4 Section Inventory

Parse the raw HTML to produce a complete ordered checklist. For each section, record:

• Section index and DOM selector (tag, id, classes)

• Exact heading text and subheading text

• Button labels

• Image count

• Background color (if non-transparent)

Save as

clone-data/inventory.json

. This becomes the build checklist.

1.5 Design Tokens

Extract CSS custom properties, body font-family, heading font-family, primary colors. Save to

clone-data/tokens.json

.

1.6 Font Handling

Priority order

1. Download actual font files — Check

   @font-face

   rules for

   .woff2

   /

   .woff

   URLs. Download to

   public/fonts/

   and declare

   @font-face

   in

   index.css

   .

2. Use Google Fonts if available — If the site uses Google Fonts, add the

   @import

   or

   <link>

   tag.

3. Map to closest equivalent — Only as a last resort:

| Proprietary Font | Google Fonts Equivalent |

|-----------------|----------------------|

| Proxima Nova | DM Sans |

| Geograph | DM Sans |

| Self Modern | DM Serif Text |

| Graphik | Inter |

| Circular | DM Sans |

| GT Walsheim | Plus Jakarta Sans |

| Tiempos | Playfair Display |

| Apercu | Source Sans Pro |

| Founders Grotesk | Space Grotesk |

| National | DM Sans |

| Futura | Jost |

| Avenir | Nunito Sans |

| Gotham | Montserrat |

| Brandon Grotesque | Raleway |

1.7 SVG Logo Extraction (CRITICAL)

The site's logo is almost always an inline SVG in the

raw.html

, NOT just text. Search for it:

# Search raw HTML for SVG near logo references

python3 -c "

with open('clone-data/raw.html') as f:

html = f.read()

# Search around 'logo' class references

import re

for m in re.finditer(r'logo', html[:15000], re.IGNORECASE):

idx = m.start()

# Look for SVG nearby

svg_start = html.find('<svg', max(0, idx-200))

if svg_start != -1 and svg_start < idx + 500:

svg_end = html.find('</svg>', svg_start) + 6

print(html[svg_start:svg_end])

break

"

Never use an SVG

<text>

element as a logo substitute. Extract the real SVG

<path>

elements from the source HTML. The logo is the most recognizable element on the page — getting it wrong immediately signals "fake."

1.8 Asset Download (ALL assets, ALL at once)

Download every image, video, SVG, background image, and font file before building starts. See

extraction.md

for the complete download script.

CDN URL upscaling (increase resolution before downloading):

• Shopify

  _small

  suffix:

  _small.jpg

  →

  _1200x.jpg

  (very common pattern)

• Shopify query params:

  ?width=X

  →

  ?width=1200

• Sanity:

  ?w=X

  →

  ?w=1200

• Cloudinary:

  w_X

  →

  w_1200

• Contentful:

  ?w=X

  →

  ?w=1200

Verification: After downloading, verify every file exists and is >100 bytes. The download script includes automatic retry with fallback User-Agent strings.

1.9 Header Deep Extraction (CRITICAL)

The header is the most error-prone section. Extract detailed information beyond the basic inventory:

header_info = page.evaluate("""

() => {

const header = document.querySelector('header');

if (!header) return null;

// Banner/announcement bar

const banner = document.querySelector('[class*="banner"], [class*="announcement"], [class*="uni-banner"]');

const bannerBg = banner ? getComputedStyle(banner.querySelector('[class*="col"], div') || banner).backgroundColor : null;

// Logo position

const logo = header.querySelector('svg, [class*="logo"] img, [class*="logo"] svg');

const logoRect = logo?.getBoundingClientRect();

const headerRect = header.getBoundingClientRect();

// Nav links

const navLinks = [...header.querySelectorAll('nav a, [class*="nav"] a')].map(a => a.innerText.trim()).filter(t => t && t.length < 30);

// Right-side elements (account, rewards, search, cart, wishlist)

const rightElements = [...header.querySelectorAll('[class*="loyalty"], [class*="rewards"], [class*="account"], [class*="cart"], [class*="wishlist"]')];

return {

bannerText: banner?.innerText?.trim(),

bannerBgColor: bannerBg,

bannerTextColor: banner ? getComputedStyle(banner).color : null,

logoPosition: logoRect ? (logoRect.left < headerRect.width / 3 ? 'left' : logoRect.left < headerRect.width * 2/3 ? 'center' : 'right') : 'unknown',

navLinks: navLinks.slice(0, 10),

rightSideText: rightElements.map(el => el.innerText?.trim()).filter(t => t),

rightSideHTML: rightElements.map(el => el.innerHTML?.slice(0, 300)),

};

}

""")

This prevents the three most common header mistakes: wrong banner color, wrong logo position, missing account/rewards text.

1.10 Footer Link Extraction

Extract all footer links separately — they're needed for the footer component:

footer_data = page.evaluate("""

() => {

const footer = document.querySelector('footer');

if (!footer) return null;

return {

text: footer.innerText,

bgColor: getComputedStyle(footer).backgroundColor,

links: [...footer.querySelectorAll('a')].map(a => ({

text: a.innerText.trim(), href: a.getAttribute('href')

})).filter(l => l.text)

};

}

""")

---

Phase 2: Foundation Build

Sequential — do this yourself, not delegated.

1. Create artifact via

   createArtifact()

   with type

   react-vite

2. Replace

   index.css

   entirely — Remove ALL Tailwind/shadcn boilerplate. Write plain CSS:

• Google Fonts

  @import

  (or

  @font-face

  for self-hosted)

• Universal reset (

  *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }

  )

• CSS variables for design tokens (font families, colors)

• Basic body styles (font-family, color, background, antialiasing)

• Reset styles for

  a

  ,

  button

  ,

  img

  ,

  ul/ol

1. Replace

   App.tsx

   — Remove all router/query/toast boilerplate. A clone is a single static page.
2. Organize assets in

   public/images/

---

Phase 3: Build All Sections

Build all components from the section inventory, referencing

raw.html

for exact content. Use inline styles or CSS modules — not Tailwind.

For EACH section in the inventory

Step 1: Read the raw HTML for that section's exact structure, text, and element hierarchy.

Step 2: Build the component using:

• Exact text content from raw HTML (copy-paste headings, button labels)

• Local image paths from

  public/images/

• Real SVG paths for logos/icons extracted from raw HTML

• Inline styles for layout (position, display, flex, grid, padding, colors, fonts)

• Hover interactions via

  onMouseEnter

  /

  onMouseLeave

  inline handlers

• For carousels:

  useRef

  +

  scrollBy

  with

  overflow-x: auto; scrollbar-width: none

Step 3: Use

import.meta.env.BASE_URL

prefix for all image

src

attributes so they resolve correctly under the artifact's preview path.

Build tips

• Build ALL sections before verifying. Don't stop to screenshot after each one.

• Use inline styles — Simpler than CSS files for clones, and avoids naming/scoping issues.

• Reusable components are okay when the visual pattern is truly identical (e.g., two hero banners that differ only in image/button text can share a

  HeroBanner

  component with props).

• href="#"

  is fine — For a visual clone, real link targets are a nice-to-have, not a requirement.

• Remove unused scaffolded dependencies — The

  package.json

  from

  createArtifact

  includes 40+ shadcn/Radix packages. These are dead weight for a clone.

---

Phase 4: Page Assembly & Verification

1. Import all components into

   App.tsx

   in exact DOM order from the inventory

2. Start the dev server and take a full-page screenshot at 1280px

3. Compare against the original screenshot from Phase 1

4. Fix discrepancies section by section

5. Run e2e test to verify all sections render (use

   runTest()

   )

Verification checklist

• All sections present in correct order

• Logo is the real SVG (not text substitute)

• Logo position matches (left/center/right)

• All images load (no broken images in console)

• Heading text matches exactly

• All text is in the correct language (match URL locale)

• Button styles match (filled vs outlined, correct colors)

• Background colors match for sections with colored backgrounds

• Announcement bar has correct background color AND text

• Account/rewards/loyalty text is present in header (if original has it)

• Carousels scroll properly

• Hover states work on interactive elements

• Footer has correct columns and content

---

Component Specification Format

For complex sections dispatched to subagents, write specs at

docs/research/components/<name>.md

:

# <ComponentName> Specification

## Overview

- Target file: `src/components/<ComponentName>.tsx`
- Interaction model: <static | click | scroll | time>

## DOM Structure (from raw.html)

<Exact element hierarchy with tag names, classes, nesting>

## Computed Styles (exact values)

### Container

- display: flex; flex-direction: row; gap: 24px; padding: 60px 80px;

### Heading

- font-size: 48px; font-weight: 400; color: \#230d0d;

### Button

- background-color: \#f195a7; border-radius: 999px; padding: 12px 32px;

## Text Content (verbatim from raw.html)

<Every heading, paragraph, button label — copy-pasted exactly>

## Assets (local paths)

- /images/products/charm-1.webp

## States & Behaviors

### Hover on card

- transform: none → scale(1.02)
- transition: transform 0.3s ease

---

Quick Reference: Full Workflow

1. pip install playwright; find Chromium path
2. Navigate to target URL with Playwright

3. Save raw.html (page.content()) — THIS IS THE SOURCE OF TRUTH
4. Detect locale/language from URL path (e.g., /es-do = Spanish)

5. Take full-page desktop screenshot + header-only screenshot (top 150px)
6. Build section inventory from raw.html → clone-data/inventory.json

7. Extract design tokens → clone-data/tokens.json
8. Extract SVG logo from raw.html (search for <svg near 'logo' classes)

9. Extract header details: banner color, logo position, nav links, rewards/loyalty text
10. Extract fonts (download .woff2 files or map to Google Fonts)

11. Download ALL images/videos/SVGs to public/images/ (batch with retry)
12. Extract footer links → clone-data/footer.json

13. createArtifact("react-vite", ...)
14. Replace index.css (plain CSS reset + design tokens — NO Tailwind/shadcn)

15. Replace App.tsx (remove router/query boilerplate — single page)
16. Build ALL section components (referencing raw.html, using correct language)

17. Assemble page in App.tsx (exact DOM order from inventory)
18. Start dev server, take full-page screenshot, compare vs original

19. Fix discrepancies (check header first — most common mistake area)
20. Run e2e test to verify all sections render

21. Present artifact

Reference Files

• extraction.md

  — Complete Python extraction scripts (Playwright)

• pitfalls.md

  — Detailed common pitfalls and solutions