design-clone 1.0.0

package/.env.example

@@ -0,0 +1,14 @@
+# Design Clone Skill - Environment Variables
+# Copy to .env and fill in your values
+
+# Gemini API Key (optional but recommended)
+# Get from: https://aistudio.google.com/apikey
+# Enables AI structure analysis and design token extraction
+GEMINI_API_KEY=your-api-key-here
+
+# Chrome Path (optional - auto-detected on most systems)
+# Set if Chrome is installed in non-standard location
+# CHROME_PATH=/path/to/chrome
+
+# Puppeteer Options (optional)
+# PUPPETEER_NO_SANDBOX=1  # Required for Docker/CI

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

package/README.md

@@ -0,0 +1,166 @@
+# Design Clone Skill for Claude Code
+
+Clone website designs with multi-viewport screenshots, HTML/CSS extraction, and Gemini AI analysis.
+
+[![npm](https://img.shields.io/npm/v/design-clone)](https://www.npmjs.com/package/design-clone)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+## Features
+
+- **Multi-viewport screenshots**: Desktop (1920px), Tablet (768px), Mobile (375px)
+- **HTML/CSS extraction**: Clean source files with unused CSS removal
+- **AI structure analysis**: Gemini Vision analyzes page layout (optional)
+- **Asset extraction**: Downloads images, fonts, icons
+- **Menu verification**: Tests responsive navigation functionality
+
+## Installation
+
+### Option 1: npm (Recommended)
+
+```bash
+npm install -g design-clone
+design-clone init
+```
+
+### Option 2: Manual
+
+```bash
+git clone https://github.com/bienhoang/design-clone.git
+cp -r design-clone ~/.claude/skills/design-clone
+cd ~/.claude/skills/design-clone
+npm install
+pip install -r requirements.txt
+```
+
+### Verify Installation
+
+```bash
+design-clone verify
+```
+
+## Quick Start
+
+In Claude Code, use:
+
+```
+/design:clone https://example.com
+```
+
+For pixel-perfect clone with full asset extraction:
+
+```
+/design:clone-px https://example.com
+```
+
+## Commands
+
+### design:clone
+
+Basic design capture:
+- Screenshots at 3 viewports (desktop, tablet, mobile)
+- HTML extraction (scripts removed, cleaned)
+- CSS extraction with unused selector removal
+
+### design:clone-px
+
+Full pixel-perfect clone:
+- All basic clone features
+- Asset extraction (images, fonts, icons)
+- AI structure analysis (requires GEMINI_API_KEY)
+- Menu verification
+- Design token extraction
+
+## Output Structure
+
+```
+cloned-design/
+├── desktop.png           # 1920x1080 screenshot
+├── tablet.png            # 768x1024 screenshot
+├── mobile.png            # 375x812 screenshot
+├── source.html           # Cleaned HTML
+├── source.css            # Filtered CSS
+├── source-raw.css        # Original CSS (unfiltered)
+├── structure.md          # AI analysis (if GEMINI_API_KEY set)
+├── tokens.json           # Extracted design tokens
+└── assets/
+    ├── images/
+    ├── fonts/
+    └── icons/
+```
+
+## Environment Variables
+
+```bash
+# Optional: enables AI structure analysis
+GEMINI_API_KEY=your-api-key
+
+# Add to ~/.claude/.env for persistent config
+```
+
+Get your API key at: https://aistudio.google.com/apikey
+
+## Requirements
+
+- Node.js 18+
+- Python 3.9+ (for AI analysis)
+- Chrome or Chromium (auto-detected)
+
+## CLI Commands
+
+```bash
+design-clone init [--force]   # Install skill to ~/.claude/skills/
+design-clone verify           # Check installation status
+design-clone help             # Show usage help
+```
+
+## Troubleshooting
+
+### Chrome not found
+
+```bash
+# macOS
+brew install --cask google-chrome
+
+# Ubuntu
+sudo apt install chromium-browser
+
+# Or set path manually
+export CHROME_PATH="/path/to/chrome"
+```
+
+### Python dependencies fail
+
+```bash
+pip install google-genai
+# Or with Python 3
+pip3 install -r requirements.txt
+```
+
+### Puppeteer issues
+
+```bash
+# Install Puppeteer if not present
+npm install puppeteer
+
+# For Docker/CI environments
+export PUPPETEER_NO_SANDBOX=1
+```
+
+See full troubleshooting guide: [docs/troubleshooting.md](docs/troubleshooting.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+MIT - See [LICENSE](LICENSE)
+
+## Credits
+
+Built for use with [Claude Code](https://claude.ai/code) by Anthropic.

package/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: design-clone
+description: Clone website designs via multi-viewport screenshots, HTML/CSS extraction, and Gemini AI analysis. Generates production HTML/CSS with Font Awesome icons, direct Unsplash images, and Japanese design principles. Commands - design:clone (basic), design:clone-px (pixel-perfect).
+---
+
+# Design Clone Skill
+
+Clone website designs with multi-viewport screenshots, HTML/CSS extraction, CSS filtering, and Gemini AI structure analysis.
+
+## Features
+
+- **Font Awesome 6 Icons** - All icons use Font Awesome CDN (no inline SVG)
+- **Direct Unsplash Images** - Real images without API key needed
+- **Japanese Design Principles** - Ma, Kanso, Shibui, Seijaku for elegant designs
+- **Multi-viewport Screenshots** - Desktop, tablet, mobile captures
+- **Gemini Vision Analysis** - AI-powered design token extraction
+- **ui-ux-pro-max Quality Check** - Accessibility, hover states, contrast validation
+
+## Prerequisites
+
+- Node.js 18+ with npm
+- Python 3.9+ (for AI analysis)
+- Chrome/Chromium browser
+
+## Quick Setup
+
+```bash
+npm install
+pip install -r requirements.txt
+# Optional: Set GEMINI_API_KEY in .env for AI analysis
+```
+
+## Project Structure
+
+```
+design-clone/
+├── bin/                    # CLI entry point
+│   ├── cli.js
+│   ├── commands/           # CLI commands
+│   └── utils/              # CLI utilities
+├── src/
+│   ├── core/               # Core extraction scripts
+│   │   ├── screenshot.js   # Multi-viewport screenshots
+│   │   ├── filter-css.js   # CSS filtering
+│   │   └── extract-assets.js
+│   ├── ai/                 # AI analysis scripts
+│   │   ├── analyze-structure.py
+│   │   └── extract-design-tokens.py
+│   ├── verification/       # Verification scripts
+│   │   ├── verify-menu.js
+│   │   └── verify-layout.js
+│   ├── utils/              # Shared utilities
+│   │   ├── browser.js
+│   │   ├── puppeteer.js
+│   │   ├── env.js
+│   │   └── env.py
+│   └── post-process/       # Post-processing
+│       ├── fetch-images.js
+│       ├── inject-icons.js
+│       └── enhance-assets.js
+├── tests/                  # Test files
+├── templates/              # HTML/CSS templates
+├── docs/                   # Documentation
+└── package.json
+```
+
+## Commands
+
+### design:clone
+
+Basic design capture with Font Awesome icons and Unsplash images.
+
+```bash
+/design:clone https://example.com
+```
+
+**Workflow:**
+```bash
+# Step 1: Capture screenshots + HTML/CSS
+node src/core/screenshot.js \
+  --url "URL" \
+  --output ./output \
+  --extract-html \
+  --extract-css
+
+# Step 2: Filter unused CSS
+node src/core/filter-css.js \
+  --html ./output/source.html \
+  --css ./output/source-raw.css \
+  --output ./output/source.css
+
+# Step 3: Quality Check with ui-ux-pro-max (REQUIRED)
+python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux
+python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "animation hover" --domain ux
+```
+
+**Key Features:**
+- Screenshots + HTML/CSS extraction
+- Font Awesome 6 CDN icons
+- Direct Unsplash image URLs (no API)
+- Japanese design principles (Ma, Kanso, Shibui, Seijaku)
+- Mobile-first responsive CSS
+- **ui-ux-pro-max quality validation**
+
+**Output:** desktop.png, tablet.png, mobile.png, source.html, source.css, source-raw.css
+
+### design:clone-px
+
+Pixel-perfect clone with full asset extraction and AI analysis.
+
+**Full Workflow:**
+
+```bash
+# Step 1: Capture + Extract
+node src/core/screenshot.js \
+  --url "URL" \
+  --output ./output \
+  --extract-html --extract-css \
+  --full-page
+
+# Step 2: Filter CSS
+node src/core/filter-css.js \
+  --html ./output/source.html \
+  --css ./output/source-raw.css \
+  --output ./output/source.css
+
+# Step 3: Extract Assets (images, fonts, icons)
+node src/core/extract-assets.js \
+  --url "URL" \
+  --output ./output
+
+# Step 4: AI Structure Analysis (requires GEMINI_API_KEY)
+python src/ai/analyze-structure.py \
+  -s ./output/desktop.png \
+  -o ./output \
+  --html ./output/source.html \
+  --css ./output/source.css
+
+# Step 5: Extract Design Tokens
+python src/ai/extract-design-tokens.py \
+  -s ./output/desktop.png \
+  -o ./output
+
+# Step 6: Verify Menu
+node src/verification/verify-menu.js \
+  --html ./output/source.html
+
+# Step 7: Quality Check with ui-ux-pro-max (REQUIRED)
+python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux
+python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "animation hover" --domain ux
+python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "z-index" --domain ux
+```
+
+## Quality Checklist (ui-ux-pro-max)
+
+After generating HTML/CSS, verify these items using `ui-ux-pro-max` skill:
+
+### Visual Quality
+- [ ] No emojis used as icons (use Font Awesome instead)
+- [ ] All icons from Font Awesome 6 (consistent sizing)
+- [ ] Hover states don't cause layout shift
+
+### Interaction
+- [ ] All clickable elements have `cursor-pointer`
+- [ ] Hover states provide clear visual feedback
+- [ ] Transitions are smooth (150-300ms)
+
+### Accessibility
+- [ ] All images have alt text
+- [ ] Form inputs have labels
+- [ ] Color is not the only indicator
+- [ ] Sufficient text contrast (4.5:1 minimum)
+
+### Layout
+- [ ] Floating elements have proper spacing
+- [ ] No content hidden behind fixed navbars
+- [ ] Responsive at 320px, 768px, 1024px, 1440px
+
+## Icon Usage (Font Awesome 6)
+
+```html
+<!-- CDN in <head> -->
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
+
+<!-- Icons -->
+<i class="fa-solid fa-house"></i>
+<i class="fa-solid fa-envelope"></i>
+<i class="fa-brands fa-x-twitter"></i>
+<i class="fa-brands fa-line"></i>
+```
+
+## Image Usage (Direct Unsplash)
+
+```html
+<!-- No API needed - direct URL format -->
+<img src="https://images.unsplash.com/photo-{PHOTO_ID}?w={WIDTH}&h={HEIGHT}&fit=crop&q=80" alt="Description">
+
+<!-- Example -->
+<img src="https://images.unsplash.com/photo-1523050854058-8df90110c9f1?w=800&h=600&fit=crop&q=80" alt="Students">
+```
+
+## Japanese Design Principles
+
+| Principle | Description | CSS Implementation |
+|-----------|-------------|-------------------|
+| Ma (間) | Negative space | Generous padding/margins |
+| Kanso (簡素) | Simplicity | Limited colors, clean typography |
+| Shibui (渋い) | Subtle elegance | Soft shadows, gentle transitions |
+| Seijaku (静寂) | Tranquility | Calm colors, visual harmony |
+
+## Environment Variables
+
+Create `.env` file (see `.env.example`):
+
+```bash
+GEMINI_API_KEY=your-key    # Optional: enables AI structure analysis
+```
+
+## Script Reference
+
+| Script | Location | Purpose |
+|--------|----------|---------|
+| screenshot.js | src/core/ | Capture screenshots + extract HTML/CSS |
+| filter-css.js | src/core/ | Filter unused CSS rules |
+| extract-assets.js | src/core/ | Download images, fonts, icons |
+| analyze-structure.py | src/ai/ | AI-powered structure analysis |
+| extract-design-tokens.py | src/ai/ | Extract colors, typography, spacing |
+| verify-menu.js | src/verification/ | Validate navigation structure |
+| verify-layout.js | src/verification/ | Verify layout consistency |
+| fetch-images.js | src/post-process/ | Fetch and optimize images |
+| inject-icons.js | src/post-process/ | Replace icons with Font Awesome |
+| enhance-assets.js | src/post-process/ | Enhance extracted assets |
+
+## References
+
+- [Basic Clone](docs/basic-clone.md) - Step-by-step basic workflow
+- [Pixel Perfect](docs/pixel-perfect.md) - Full pixel-perfect workflow
+- [CLI Reference](docs/cli-reference.md) - All script options
+- [Troubleshooting](docs/troubleshooting.md) - Common issues and fixes

package/bin/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Design Clone Skill CLI
+ *
+ * Usage:
+ *   design-clone init [--force]  Install skill to ~/.claude/skills/
+ *   design-clone verify          Check installation status
+ *   design-clone help            Show help
+ */
+
+import { init } from './commands/init.js';
+import { verify } from './commands/verify.js';
+import { help } from './commands/help.js';
+
+const [,, command, ...args] = process.argv;
+
+async function main() {
+  try {
+    switch (command) {
+      case 'init':
+      case 'install':
+        await init(args);
+        break;
+      case 'verify':
+      case 'check':
+        await verify();
+        break;
+      case 'help':
+      case '--help':
+      case '-h':
+      case undefined:
+        help();
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.error('Run "design-clone help" for usage');
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/commands/help.js

@@ -0,0 +1,29 @@
+/**
+ * Help command - display usage information
+ */
+
+export function help() {
+  console.log(`
+design-clone - Claude Code skill for website design cloning
+
+Usage:
+  design-clone init [options]   Install skill to ~/.claude/skills/
+  design-clone verify           Check installation status
+  design-clone help             Show this help
+
+Options:
+  --force, -f    Overwrite existing installation
+  --skip-deps    Skip dependency installation
+
+Examples:
+  design-clone init              # Install skill
+  design-clone init --force      # Reinstall, overwrite existing
+  design-clone verify            # Check if installed correctly
+
+After installation:
+  1. Set GEMINI_API_KEY in ~/.claude/.env (optional, for AI analysis)
+  2. Use /design:clone or /design:clone-px in Claude Code
+
+For more info: https://github.com/bienhoang/design-clone
+`);
+}

package/bin/commands/init.js

@@ -0,0 +1,126 @@
+/**
+ * Init command - install skill to ~/.claude/skills/
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { exec as execCallback } from 'child_process';
+import { promisify } from 'util';
+import { copyRecursive, exists } from '../utils/copy.js';
+import { runAllChecks } from '../utils/validate.js';
+
+const exec = promisify(execCallback);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Source: package root (where SKILL.md is)
+const SKILL_SOURCE = path.resolve(__dirname, '../..');
+// Destination: ~/.claude/skills/design-clone
+const getSkillDest = () => path.join(process.env.HOME || process.env.USERPROFILE || '', '.claude/skills/design-clone');
+
+/**
+ * Install skill to Claude Code skills directory
+ * @param {string[]} args - CLI arguments
+ */
+export async function init(args) {
+  const force = args.includes('--force') || args.includes('-f');
+  const skipDeps = args.includes('--skip-deps');
+  const SKILL_DEST = getSkillDest();
+
+  console.log('design-clone skill installer\n');
+
+  // Pre-flight checks
+  console.log('Checking requirements...');
+  const checks = await runAllChecks();
+
+  console.log(`  Node.js: ${checks.node.ok ? '✓' : '✗'} ${checks.node.message}`);
+  console.log(`  Python:  ${checks.python.ok ? '✓' : '✗'} ${checks.python.message}`);
+  console.log(`  Chrome:  ${checks.chrome.ok ? '✓' : '✗'} ${checks.chrome.message}`);
+  console.log('');
+
+  if (!checks.node.ok) {
+    console.error('Error: Node.js 18+ is required');
+    process.exit(1);
+  }
+
+  if (!checks.python.ok) {
+    console.warn('Warning: Python 3.9+ not found. AI analysis features will be unavailable.');
+  }
+
+  if (!checks.chrome.ok) {
+    console.warn('Warning: Chrome not found. Screenshots may not work without Puppeteer\'s bundled Chromium.');
+  }
+
+  // Check existing installation
+  const alreadyExists = await exists(SKILL_DEST);
+  if (alreadyExists && !force) {
+    console.log(`Skill already installed at: ${SKILL_DEST}`);
+    console.log('Use --force to overwrite existing installation.');
+    return;
+  }
+
+  // Copy skill files
+  console.log('Installing skill files...');
+  try {
+    // Ensure parent directory exists
+    await fs.mkdir(path.dirname(SKILL_DEST), { recursive: true });
+
+    // Remove existing if force
+    if (alreadyExists && force) {
+      await fs.rm(SKILL_DEST, { recursive: true, force: true });
+    }
+
+    // Copy files (excluding test files and node_modules)
+    await copyRecursive(SKILL_SOURCE, SKILL_DEST, {
+      exclude: [
+        'node_modules',
+        '.git',
+        '__pycache__',
+        'test-*.js',
+        'test-*.py',
+        'run-all-tests.js',
+        '.DS_Store',
+        '*.log',
+        'cloned-designs',
+        'test-output',
+        'icons'
+      ]
+    });
+
+    console.log(`  Copied to: ${SKILL_DEST}`);
+  } catch (error) {
+    console.error(`Error copying files: ${error.message}`);
+    process.exit(1);
+  }
+
+  // Install dependencies
+  if (!skipDeps) {
+    // Node.js dependencies
+    console.log('Installing Node.js dependencies...');
+    try {
+      await exec('npm install --omit=dev', { cwd: SKILL_DEST });
+      console.log('  npm packages installed');
+    } catch (error) {
+      console.warn(`  Warning: npm install failed: ${error.message}`);
+    }
+
+    // Python dependencies
+    if (checks.python.ok) {
+      console.log('Installing Python dependencies...');
+      try {
+        await exec('pip install -r requirements.txt', { cwd: SKILL_DEST });
+        console.log('  Python packages installed');
+      } catch (error) {
+        console.warn(`  Warning: pip install failed: ${error.message}`);
+        console.warn('  Try: pip install google-genai');
+      }
+    }
+  }
+
+  // Success
+  console.log('\n✓ design-clone skill installed successfully!\n');
+  console.log('Next steps:');
+  console.log('  1. (Optional) Set GEMINI_API_KEY in ~/.claude/.env for AI analysis');
+  console.log('  2. Use /design:clone or /design:clone-px in Claude Code');
+  console.log('\nRun "design-clone verify" to check installation status.');
+}