design-clone 1.0.0

package/docs/pixel-perfect.md

@@ -0,0 +1,86 @@
+# Pixel-Perfect Clone Workflow
+
+Full design replication with asset extraction, AI analysis, and verification.
+
+## When to Use
+
+- Production-ready design implementation
+- Complete asset and structure extraction
+- Sites with complex navigation or interactions
+
+## Full Workflow
+
+### Step 1: Capture + Extract
+
+```bash
+node src/core/screenshot.js \
+  --url "https://example.com" \
+  --output ./clone \
+  --extract-html --extract-css \
+  --full-page
+```
+
+### Step 2: Filter CSS
+
+```bash
+node src/core/filter-css.js \
+  --html ./clone/source.html \
+  --css ./clone/source-raw.css \
+  --output ./clone/source.css
+```
+
+### Step 3: Extract Assets
+
+```bash
+node src/core/extract-assets.js \
+  --url "https://example.com" \
+  --output ./clone
+```
+
+Downloads: images, fonts, icons, SVGs to `./clone/assets/`
+
+### Step 4: AI Structure Analysis
+
+Requires `GEMINI_API_KEY` in environment.
+
+```bash
+python src/ai/analyze-structure.py \
+  -s ./clone/desktop.png \
+  -o ./clone \
+  --html ./clone/source.html \
+  --css ./clone/source.css
+```
+
+Output: `./clone/structure.md` with section breakdown and BEM suggestions.
+
+### Step 5: Extract Design Tokens
+
+```bash
+python src/ai/extract-design-tokens.py \
+  -s ./clone/desktop.png \
+  -o ./clone
+```
+
+Output: `./clone/tokens.json` with colors, typography, spacing.
+
+### Step 6: Verify Menu
+
+```bash
+node src/verification/verify-menu.js --html ./clone/source.html
+```
+
+Reports: missing links, broken structure, accessibility issues.
+
+## Output Structure
+
+```
+./clone/
+├── desktop.png, tablet.png, mobile.png
+├── source.html, source.css
+├── structure.md      # AI analysis
+├── tokens.json       # Design tokens
+└── assets/
+    ├── images/
+    ├── fonts/
+    └── icons/
+```

package/docs/troubleshooting.md

@@ -0,0 +1,97 @@
+# Troubleshooting
+
+Common issues and solutions.
+
+## Browser Issues
+
+### Chrome/Chromium not found
+
+**Error:** `Could not find Chrome`
+
+**Solution:**
+```bash
+# macOS
+brew install --cask google-chrome
+
+# Ubuntu
+sudo apt install chromium-browser
+
+# Or set path manually
+export CHROME_PATH="/path/to/chrome"
+```
+
+### Puppeteer launch fails
+
+**Error:** `Failed to launch browser`
+
+**Solutions:**
+1. Install dependencies: `npm install puppeteer`
+2. Linux: Install required libs: `apt install libnss3 libatk1.0-0 libatk-bridge2.0-0`
+3. Run with `--no-sandbox` (Docker): Set `PUPPETEER_NO_SANDBOX=1`
+
+## CSS Issues
+
+### CORS-blocked stylesheets
+
+**Symptom:** CSS extraction returns empty or partial styles.
+
+**Solution:** Some sites block cross-origin stylesheet access. Use browser DevTools manually or try `--wait 3000` for dynamic CSS.
+
+### CSS too large
+
+**Error:** `CSS file exceeds 10MB limit`
+
+**Solution:** filter-css.js has 10MB limit. Split manually or increase `MAX_CSS_INPUT_SIZE` in filter-css.js.
+
+## Python Issues
+
+### Module not found
+
+**Error:** `ModuleNotFoundError: google.genai`
+
+**Solution:**
+```bash
+pip install -r requirements.txt
+# Or: pip install google-genai
+```
+
+### Wrong Python version
+
+**Error:** `SyntaxError` on type hints
+
+**Solution:** Requires Python 3.9+. Check: `python3 --version`
+
+## Gemini API Issues
+
+### API key not set
+
+**Error:** `GEMINI_API_KEY not found`
+
+**Solution:** Create `.env` file:
+```bash
+GEMINI_API_KEY=your-api-key-here
+```
+
+### Rate limit exceeded
+
+**Error:** `429 Too Many Requests`
+
+**Solution:** Wait 1 minute, or use `--model gemini-1.5-flash` for lower limits.
+
+## Screenshot Issues
+
+### Incomplete page capture
+
+**Symptom:** Missing sections in screenshot.
+
+**Solutions:**
+1. Increase wait: `--wait 5000`
+2. Use full page: `--full-page`
+3. Check for lazy-loaded content
+
+### Wrong viewport size
+
+**Solution:** Specify custom viewports:
+```bash
+--viewports '[{"width":1440,"height":900,"name":"custom"}]'
+```

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "design-clone",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Claude Code skill for cloning website designs via multi-viewport screenshots, HTML/CSS extraction, and Gemini AI analysis",
+  "bin": {
+    "design-clone": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "docs/",
+    "SKILL.md",
+    "requirements.txt",
+    ".env.example"
+  ],
+  "scripts": {
+    "screenshot": "node src/core/screenshot.js",
+    "filter-css": "node src/core/filter-css.js",
+    "extract-assets": "node src/core/extract-assets.js",
+    "verify-menu": "node src/verification/verify-menu.js",
+    "verify-layout": "node src/verification/verify-layout.js",
+    "test": "node tests/run-all-tests.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skill",
+    "design",
+    "clone",
+    "screenshot",
+    "puppeteer",
+    "gemini",
+    "website"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bienhoang/design-clone"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "css-tree": "^2.3.1"
+  },
+  "peerDependencies": {
+    "puppeteer": ">=21.0.0"
+  },
+  "peerDependenciesMeta": {
+    "puppeteer": {
+      "optional": true
+    }
+  }
+}

package/requirements.txt

@@ -0,0 +1,5 @@
+# Design Clone Skill - Python Dependencies
+# Install: pip install -r requirements.txt
+
+# Gemini AI for structure analysis and token extraction
+google-genai>=1.0.0

package/src/ai/analyze-structure.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""
+Analyze website screenshot structure using Gemini Vision API.
+
+Usage:
+  python analyze-structure.py --screenshot ./analysis/desktop.png --output ./analysis
+  python analyze-structure.py -s desktop.png -o ./out --html source.html --css source.css
+
+Options:
+  --screenshot   Path to desktop screenshot
+  --output       Output directory for structure.md
+  --html         Path to source HTML file (optional, improves accuracy)
+  --css          Path to filtered CSS file (optional, improves accuracy)
+  --model        Gemini model (default: gemini-2.5-flash)
+  --verbose      Enable verbose output
+
+Output:
+  - structure.md: Markdown description of page structure
+
+When HTML/CSS provided, extracts EXACT values from source instead of estimating.
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+# Add src directory to path for local imports
+SCRIPT_DIR = Path(__file__).parent.resolve()
+SRC_DIR = SCRIPT_DIR.parent
+sys.path.insert(0, str(SRC_DIR))
+
+# Import local env resolver (portable)
+try:
+    from utils.env import resolve_env, load_env
+    load_env()  # Load .env files on startup
+except ImportError:
+    # Fallback: simple env getter
+    def resolve_env(key, default=None):
+        return os.environ.get(key, default)
+
+# Check for google-genai dependency
+try:
+    from google import genai
+    from google.genai import types
+except ImportError:
+    print(json.dumps({
+        "success": False,
+        "error": "google-genai not installed",
+        "hint": "Run: pip install google-genai"
+    }, indent=2))
+    sys.exit(1)
+
+# Import prompts from extracted module
+from prompts.structure_analysis import build_structure_prompt
+
+
+# Fallback structure when analysis fails
+DEFAULT_STRUCTURE = """# Page Structure Analysis
+
+## 1. Header Section
+- Logo: Left-aligned, text-based
+- Navigation: Horizontal, 4-5 items
+- CTA Button: Right-aligned, primary color
+- Mobile menu: Hamburger icon for small screens
+
+## 2. Hero Section
+- Layout: Centered
+- Headline: Large (36-48px), bold, dark text
+- Subheadline: Medium (18-20px), lighter text
+- Primary CTA: Prominent button, primary color
+- Background: Solid light color
+
+## 3. Content Sections
+### Features Section
+- Layout: 3-column grid
+- Items: 3 feature cards with icons
+- Components: Icon + heading + description
+
+### About/Info Section
+- Layout: 2-column (text + image)
+- Alternating left-right pattern
+
+## 4. Footer Section
+- Layout: 4-column grid
+- Content: Logo, nav links, contact, social icons
+- Copyright: Centered at bottom
+
+## 5. Global Patterns
+- Container max-width: 1200px
+- Section padding: 64px vertical
+- Card style: Subtle shadows, 8px border-radius
+- Color scheme: Light mode
+- Typography: Sans-serif (modern)
+
+## 6. Responsive Hints
+- Navigation collapses to hamburger on mobile
+- Grid sections stack vertically
+- Padding reduces on smaller screens
+
+## 7. BEM Class Suggestions
+- header, header__container, header__logo, header__nav, header__cta
+- hero, hero__container, hero__title, hero__subtitle, hero__cta
+- features, features__grid, feature-card, feature-card__icon, feature-card__title
+- footer, footer__container, footer__column, footer__links
+"""
+
+
+def get_api_key():
+    """Get Gemini API key from environment (supports GEMINI_API_KEY or GOOGLE_API_KEY)."""
+    return resolve_env('GEMINI_API_KEY') or resolve_env('GOOGLE_API_KEY')
+
+
+def load_dimensions(output_dir: str) -> dict:
+    """Load extracted dimensions summary if available.
+
+    Args:
+        output_dir: Directory containing dimensions-summary.json
+
+    Returns:
+        Dimensions dict or None if not found
+    """
+    summary_path = Path(output_dir) / "dimensions-summary.json"
+    if summary_path.exists():
+        try:
+            with open(summary_path, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError) as e:
+            print(f"Warning: Failed to load dimensions: {e}", file=sys.stderr)
+    return None
+
+
+def analyze_structure(
+    screenshot_path: str,
+    output_dir: str = None,
+    html_path: str = None,
+    css_path: str = None,
+    model: str = "gemini-2.5-flash",
+    verbose: bool = False
+) -> str:
+    """Analyze screenshot structure using Gemini Vision.
+
+    Args:
+        screenshot_path: Path to desktop screenshot
+        output_dir: Output directory (also reads dimensions-summary.json if present)
+        html_path: Optional path to source HTML (improves accuracy)
+        css_path: Optional path to filtered CSS (improves accuracy)
+        model: Gemini model to use
+        verbose: Enable verbose output
+
+    Returns:
+        Markdown structure analysis
+    """
+
+    api_key = get_api_key()
+    if not api_key:
+        if verbose:
+            print("Warning: GEMINI_API_KEY not found, using default structure")
+        return DEFAULT_STRUCTURE
+
+    screenshot = Path(screenshot_path)
+    if not screenshot.exists():
+        if verbose:
+            print(f"Warning: Screenshot not found: {screenshot_path}")
+        return DEFAULT_STRUCTURE
+
+    # Load extracted dimensions if available (highest priority)
+    dimensions = None
+    if output_dir:
+        dimensions = load_dimensions(output_dir)
+        if dimensions and verbose:
+            print(f"Loaded extracted dimensions from {output_dir}/dimensions-summary.json")
+
+    # Load HTML/CSS if provided
+    html_content = None
+    css_content = None
+
+    if html_path and Path(html_path).exists():
+        with open(html_path, 'r', encoding='utf-8') as f:
+            html_content = f.read()
+        if verbose:
+            print(f"Loaded HTML: {len(html_content)} chars")
+
+    if css_path and Path(css_path).exists():
+        with open(css_path, 'r', encoding='utf-8') as f:
+            css_content = f.read()
+        if verbose:
+            print(f"Loaded CSS: {len(css_content)} chars")
+
+    # Build prompt with context (dimensions have highest priority)
+    prompt = build_structure_prompt(html_content, css_content, dimensions)
+
+    if verbose:
+        if dimensions:
+            print("Using ENHANCED prompt with EXACT extracted dimensions")
+        elif html_content and css_content:
+            print("Using prompt with HTML/CSS context")
+
+    try:
+        client = genai.Client(api_key=api_key)
+
+        # Load image
+        with open(screenshot, 'rb') as f:
+            img_bytes = f.read()
+
+        content = [
+            prompt,
+            types.Part.from_bytes(data=img_bytes, mime_type='image/png')
+        ]
+
+        if verbose:
+            print(f"Analyzing structure with {model}...")
+
+        response = client.models.generate_content(
+            model=model,
+            contents=content
+        )
+
+        if hasattr(response, 'text') and response.text:
+            if verbose:
+                print("Structure analysis complete")
+            return response.text
+        else:
+            if verbose:
+                print("Warning: Empty response, using default structure")
+            return DEFAULT_STRUCTURE
+
+    except Exception as e:
+        if verbose:
+            print(f"Error during analysis: {e}")
+        return DEFAULT_STRUCTURE
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Analyze website screenshot structure using Gemini Vision"
+    )
+    parser.add_argument(
+        '--screenshot', '-s',
+        required=True,
+        help='Path to desktop screenshot'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        required=True,
+        help='Output directory for structure.md (also reads dimensions-summary.json if present)'
+    )
+    parser.add_argument(
+        '--html',
+        default=None,
+        help='Path to source HTML file (optional, improves accuracy)'
+    )
+    parser.add_argument(
+        '--css',
+        default=None,
+        help='Path to filtered CSS file (optional, improves accuracy)'
+    )
+    parser.add_argument(
+        '--model', '-m',
+        default='gemini-2.5-flash',
+        help='Gemini model to use (default: gemini-2.5-flash)'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+
+    args = parser.parse_args()
+
+    # Create output directory
+    output_path = Path(args.output)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    # Analyze structure (dimensions loaded automatically from output_dir)
+    structure = analyze_structure(
+        screenshot_path=args.screenshot,
+        output_dir=args.output,
+        html_path=args.html,
+        css_path=args.css,
+        model=args.model,
+        verbose=args.verbose
+    )
+
+    # Save structure.md
+    md_path = output_path / "structure.md"
+    with open(md_path, 'w') as f:
+        f.write(structure)
+
+    if args.verbose:
+        print(f"Saved: {md_path}")
+
+    # Output result as JSON
+    result = {
+        "success": True,
+        "structure_file": str(md_path),
+        "model": args.model
+    }
+
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == '__main__':
+    main()