#Common Pitfalls & Solutions

Documented from real-world cloning projects. Each pitfall was encountered during production use and caused user-visible quality issues.

#Pitfall 1: Building from Memory Instead of Source HTML

Problem: After extracting the page, the builder works from a mental model or screenshot interpretation, leading to wrong section types, missing elements, and fabricated content.

Solution: Before writing ANY component, open raw.htmland read the exact HTML for that section. Verify:

• Exact heading text (copy-paste, don't retype)

• Button labels and their HTML classes

• Which elements actually exist (don't add badges/labels that aren't there)

• Layout structure (flex vs grid vs absolute)

• Number of child elements

#Pitfall 2: Reusing Components for Different Visual Patterns

Problem: AProductCarouselcomponent with price badges and "personalize" labels gets reused for a category carousel that should only have images and names. The result looks completely wrong.

Solution: Apply the "one component per visual pattern" rule:

• If two sections have different card structures, they need different components

• Product cards (image + name + price + badge) ≠ Category cards (image + name only)

• Even if the layout is similar (horizontal scroll), the card contents dictate the component

• When in doubt, create a new component — it's cheaper than debugging a wrong reuse

#Pitfall 3: Wrong Button Styles

Problem: Using outlined/bordered buttons when the original has solid/filled buttons (or vice versa). Using wrong colors, wrong border-radius, wrong font-size.

Solution: For every button in raw.html:

1. Check the HTML classes — do they include "filled", "primary", "solid", etc.?

2. Extract computed styles:background-color, border, border-radius, color, font-size, padding

3. Especially check: is background-colortransparent (outlined) or a solid color (filled)?

4. Match the exactborder-radius—4px≠999px(pill shape)

#Pitfall 4: Wrong Text Alignment

Problem: Center-aligning text when the original is left-aligned, or vice versa.

Solution: Always extracttext-alignfrom computed styles. Common patterns:

• Hero headings: often centered

• Split-layout text blocks: usually left-aligned

• Card titles: varies — check each one

• Footer columns: usually left-aligned

#Pitfall 5: Missing Mobile Navigation

Problem: Clones skip the hamburger menu, making the site unusable on mobile.

Solution: At 390px viewport width:

1. Look for hamburger/menu buttons

2. Click the button to open the drawer

3. Capture: drawer width, slide direction, background color, link list, close mechanism

4. Screenshot the open state

5. Implement with: slide-in animation, backdrop overlay, body scroll lock, close on backdrop click

#Pitfall 6: Placeholder Images

Problem: Builder can't find the right image, so it reuses a hero image or leaves a broken<img>tag.

Solution:

• Download ALL images in Phase 1, before building starts

• Map each image to its section indownloaded-assets.json

• If an image download fails, immediately try alternative approaches:

• Add User-Agent header

• Try different CDN size parameters

• Use curlwith-Lflag for redirects

• Screenshot the element as a fallback

• Never use a placeholder or borrowed image from another section

#Pitfall 7: Fabricated Content

Problem: Builder adds text, badges, or decorative elements that don't exist on the original page.

Solution: The raw HTML is the source of truth. Before adding any element, verify it exists inraw.html. Specifically:

• Don't add "NEW" badges unless they're in the HTML

• Don't add star ratings unless they're in the HTML

• Don't add prices to category cards that only have names

• Don't add "Shop Now" buttons that don't exist

• Don't add background patterns or gradients that aren't in the original CSS

#Pitfall 8: Skipped Sections

Problem: Builder misses sections because they weren't prominent in the screenshot or seemed redundant.

Solution: Use the section inventory checklist. Every single section must be built and checked off. Common sections that get skipped:

• Announcement bars (thin bar at top of page)

• Brand logo marquees

• "As seen in" sections

• Newsletter signup sections (often above footer)

• Secondary CTAs between major sections

#Pitfall 9: Wrong Section Order

Problem: Sections are arranged in a different order than the original.

Solution: The section inventory records the exact top-to-bottom order from the DOM. Assemble App.tsxin exactly this order. Don't reorder for "better flow" — match the original exactly.

#Pitfall 10: Font Loading Issues

Problem: Fonts flash, don't load, or use the wrong weight/style.

Solution:

• Use<link rel="preconnect">for font domains

• Addfont-display: swapto all@font-facedeclarations

• Load the exact font weights used (don't just load 400 and 700 — check if 500 or 600 is used)

• For self-hosted fonts, use@font-faceinindex.csswith local paths topublic/fonts/

#Pitfall 11: Playwright networkidleTimeout

Problem:page.goto(url, wait_until="networkidle")hangs forever on sites with persistent WebSocket/analytics connections.

Solution: Usewait_until="domcontentloaded"+page.wait_for_timeout(5000).

#Pitfall 12: CDN Image 403 Errors

Problem: CDN images return 403 when fetched without proper headers.

Solution: Always download with a real browser User-Agent:

User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36

For Shopify CDN, also try appending ?v=timestamp.

#Pitfall 13: Oversized or Undersized Elements

Problem: Buttons, images, or containers are dramatically too large or too small because they inherited wrong CSS classes or had unconstrained widths.

Solution: For every visible element, extract and set:

• width/max-width(especially for buttons — don't let them fill 100%) -height(especially for images — maintain aspect ratio withobject-fit)

• font-size(don't let headings inherit a 72px size from a parent)

• Usemax-widthon containers (typically 1200-1440px) to prevent full-viewport stretch

#Pitfall 14: Unused Template Dependencies

Problem: Artifact scaffolding includes 40+ shadcn/Radix dependencies that bloat the project.

Solution: Replaceindex.cssentirely with plain CSS (no Tailwind/shadcn). Forpackage.json, the only deps a clone needs are: react, react-dom, vite, @vitejs/plugin-react, and Replit vite plugins. Remove everything else.

#Pitfall 15: Sticky Header Not Working

Problem: Header doesn't stick or doesn't show scroll-triggered style changes.

Solution:

const [scrolled, setScrolled] = useState(false);

useEffect(() => {

const handler = () => setScrolled(window.scrollY > 50);

window.addEventListener('scroll', handler, { passive: true });

return () => window.removeEventListener('scroll', handler);

}, []);

Apply position: sticky; top: 0; z-index: 50with CSS transition onbackground-colorandbox-shadow.

#Pitfall 16: Text-Based Logo Instead of Real SVG

Problem: Builder uses an SVG <text>element or a styled<span>to render the brand name, instead of extracting the real logo SVG paths from the source HTML. The result looks obviously fake.

Solution: Searchraw.htmlfor<svgelements near logo/brand class names. Most sites embed their logo as inline SVG with<path>elements. Extract the complete SVG includingviewBox, width, height, and all <path> data. Common search patterns:

# Search near 'logo' class references in raw HTML

idx = html.find('logo')

# Then look for <svg nearby

#Pitfall 17: Per-Section Verification Loops Are Too Slow

Problem: Building one section, screenshotting it, comparing, fixing, then moving to the next section creates 10+ screenshot cycles that consume enormous time and context.

Solution: Build ALL sections from raw HTML in one pass, assemble them in App.tsx, then take ONE full-page screenshot and fix all issues at once. The raw HTML provides enough information to get sections 90% right on the first build. The full-page screenshot catches the remaining 10%.

#Pitfall 18: Shopify CDN _smallSuffix Not Upscaled

Problem: Shopify product/hero images contain_small.jpgor_small.pngin the filename, producing low-resolution downloads. The CDN upscaler only handles?width=X query params but not the filename suffix pattern.

Solution: Add filename suffix replacement alongside query param upscaling:

if 'cdn.shopify.com' in url and '_small.' in url:

url = url.replace('_small.', '_1200x.')

#Pitfall 19: Keeping Router/Query Boilerplate in Clone

Problem: The createArtifactscaffold includes wouter Router, React Query provider, toast provider, etc. These are dead code for a single-page static clone and add complexity.

Solution: ReplaceApp.tsxwith a simple component that renders all sections in order. No router, no query client, no toast provider. A clone is one page rendered statically.

#Pitfall 20: Translating or Anglicizing a Non-English Page

Problem: The target URL is a localized page (e.g.,/es-dofor Spanish,/fr for French), but the clone is built in English. This happens because: (a) the raw HTML may return English text (localization happens via client-side JS), or (b) the builder unconsciously writes English text instead of copying from the source.

Solution:

1. Check the URL for locale indicators (/es, /fr, /de, /ja, /pt, etc.)

2. If a locale is present, ALL user-facing text must be in that language — headings, buttons, nav links, footer, CTAs, descriptions

3. If the raw HTML shows English despite a locale URL, translate the UI text to match the URL's language

4. Brand terms stay in English: product names, color names, brand program names (e.g., "ALO Wellness Club", "SUNSHINE")

5. Do NOT assume the page is English just because raw.htmlcontains English — many sites load translations via JavaScript

#Pitfall 21: Wrong Announcement Bar Background Color

Problem: The announcement/promo bar at the top of the page gets a guessed background color (commonly black or white) instead of the actual color. The real color is often a distinctive brand color (e.g., lime yellow-green#f2f5a2).

Solution: During Phase 1, extract the computed background-color from the banner element AND its child containers:

banner = document.querySelector('[class*="banner"], [class*="announcement"]')

bannerBg = getComputedStyle(banner.querySelector('div, .col-12') or banner).backgroundColor

The background may be on a child element (e.g., .col-12inside the banner), not the banner itself. Always check both.

#Pitfall 22: Wrong Logo Position (Centered vs Left-Aligned)

Problem: The logo is placed in the center of the header when the original has it left-aligned (or vice versa). This is one of the most visually jarring mistakes because the logo's position defines the entire header layout.

Solution: Take a header-only screenshot (top 150px) during Phase 1 extraction and use it as the definitive reference. The three common header layouts are:

• Logo-left + nav-right: Logo left-aligned, nav links to the right of logo, icons on far right

• Logo-center + nav-split: Nav links split left/right with logo centered

• Logo-left + nav-center: Logo left, nav links centered, icons right

Extract the logo's bounding rect and compare itsleftposition toheaderWidth / 3 to classify.

#Pitfall 23: Missing Account/Rewards/Loyalty UI in Header

Problem: The header is built with just logo + nav + icons, but the original has additional text elements like "SIGN IN TO GET REWARDS", loyalty program links, or account status text. These are easy to miss because they look like minor text, but they're prominent UI elements.

Solution: During Phase 1, search for loyalty/rewards/account elements in the header:

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

Extract their text and HTML. Include them in the header component alongside the icon bar. Common patterns:

• Account icon + "Sign in to get rewards" text

• Points balance display

• "Join Now" or "Login" links next to nav icons