design-clone 1.1.1 → 2.1.0

package/README.md

@@ -1,15 +1,21 @@
-# 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)
+<div align="center">
+  <img src="logo.svg" alt="design-clone" width="120" height="120">
+  <h1>Design Clone</h1>
+  <p><strong>Clone website designs with multi-viewport screenshots, HTML/CSS extraction, and Gemini AI analysis.</strong></p>
+  <p>
+    <a href="https://www.npmjs.com/package/design-clone"><img src="https://img.shields.io/npm/v/design-clone" alt="npm"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node"></a>
+  </p>
+</div>
+
+---
 
 ## Features
 
 - **Multi-viewport screenshots**: Desktop (1920px), Tablet (768px), Mobile (375px)
 - **HTML/CSS extraction**: Clean source files with unused CSS removal
+- **Hover state capture**: Screenshots and CSS for interactive element states (phase 2)
 - **AI structure analysis**: Gemini Vision analyzes page layout (optional)
 - **Asset extraction**: Downloads images, fonts, icons
 - **Menu verification**: Tests responsive navigation functionality
@@ -75,14 +81,21 @@ Full pixel-perfect clone:
 
 ```
 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
+├── 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)
+├── animations.css           # Extracted @keyframes definitions
+├── animation-tokens.json    # Animation metadata (keyframes, transitions, timings)
+├── hover.css                # Generated :hover CSS rules (with --capture-hover)
+├── structure.md             # AI analysis (if GEMINI_API_KEY set)
+├── tokens.json              # Extracted design tokens
+├── hover-states/            # Hover state captures (with --capture-hover)
+│   ├── hover-N-normal.png   # Element before hover
+│   ├── hover-N-hover.png    # Element during hover
+│   └── hover-diff.json      # Captured element summary
 └── assets/
     ├── images/
     ├── fonts/
@@ -104,7 +117,7 @@ Get your API key at: https://aistudio.google.com/apikey
 
 - Node.js 18+
 - Python 3.9+ (for AI analysis)
-- Chrome or Chromium (auto-detected)
+- Playwright (auto-installed with browsers)
 
 ## CLI Commands
 
@@ -137,14 +150,17 @@ pip install google-genai
 pip3 install -r requirements.txt
 ```
 
-### Puppeteer issues
+### Playwright issues
 
 ```bash
-# Install Puppeteer if not present
-npm install puppeteer
+# Install Playwright if not present
+npm install playwright
+
+# Install browsers
+npx playwright install chromium
 
 # For Docker/CI environments
-export PUPPETEER_NO_SANDBOX=1
+export PLAYWRIGHT_BROWSERS_PATH=/tmp/pw-browsers
 ```
 
 See full troubleshooting guide: [docs/troubleshooting.md](docs/troubleshooting.md)
@@ -164,3 +180,9 @@ MIT - See [LICENSE](LICENSE)
 ## Credits
 
 Built for use with [Claude Code](https://claude.ai/code) by Anthropic.
+
+---
+
+<div align="center">
+  <sub>Made with ❤️ for the Claude Code community</sub>
+</div>

package/SKILL.md

@@ -13,6 +13,7 @@ Clone website designs with multi-viewport screenshots, HTML/CSS extraction, CSS
 - **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
+- **Hover State Capture** - Interactive element screenshots and :hover CSS generation
 - **Gemini Vision Analysis** - AI-powered design token extraction
 - **ui-ux-pro-max Quality Check** - Accessibility, hover states, contrast validation
 
@@ -164,6 +165,7 @@ node src/core/screenshot.js \
   --url "URL" \
   --output ./output \
   --extract-html --extract-css \
+  --capture-hover true \
   --full-page
 
 # Step 2: Filter CSS
@@ -199,6 +201,8 @@ python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "animation hover" -
 python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "z-index" --domain ux
 ```
 
+**Note:** Step 1 includes `--capture-hover true` to capture interactive element states and generate `:hover` CSS rules. Outputs include `hover-states/` directory and `hover.css`.
+
 ## Quality Checklist (ui-ux-pro-max)
 
 After generating HTML/CSS, verify these items using `ui-ux-pro-max` skill:
@@ -256,6 +260,73 @@ After generating HTML/CSS, verify these items using `ui-ux-pro-max` skill:
 | Shibui (渋い) | Subtle elegance | Soft shadows, gentle transitions |
 | Seijaku (静寂) | Tranquility | Calm colors, visual harmony |
 
+## Animation & Interaction Capture (v1.2+)
+
+### CSS Animations
+
+Automatically extracts @keyframes and transition properties when using `--extract-css`:
+
+```bash
+node src/core/screenshot.js --url https://example.com --output ./out --extract-css true
+```
+
+**Output:**
+- `animations.css` - All @keyframes definitions with frame data
+- `animation-tokens.json` - Detailed animation metadata (durations, timing functions)
+
+### Hover State Capture
+
+Capture interactive element hover states:
+
+```bash
+node src/core/screenshot.js --url https://example.com --output ./out --capture-hover
+```
+
+**Output:**
+- `hover-states/` - Before/after screenshots for each interactive element
+- `hover.css` - Generated :hover rules from computed style differences
+- `hover-diff.json` - Style diff data
+
+**Detection Methods:**
+1. CSS-based: Parses :hover selectors from extracted CSS
+2. DOM-based: Queries buttons, links, and interactive elements
+
+### Video Recording
+
+Record scroll preview video (opt-in due to 3-5x capture time increase):
+
+```bash
+# WebM (native, no extra deps)
+node src/core/screenshot.js --url https://example.com --output ./out --video
+
+# MP4 (requires ffmpeg)
+node src/core/screenshot.js --url https://example.com --output ./out --video --video-format mp4
+
+# GIF (requires ffmpeg)
+node src/core/screenshot.js --url https://example.com --output ./out --video --video-format gif
+
+# Custom duration (default: 12000ms)
+node src/core/screenshot.js --url https://example.com --output ./out --video --video-duration 8000
+```
+
+**Output:**
+- `preview.webm` (default) or `preview.mp4` / `preview.gif`
+
+**ffmpeg Setup (for MP4/GIF):**
+```bash
+npm install fluent-ffmpeg @ffmpeg-installer/ffmpeg
+```
+
+### Feature Flags Reference
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--extract-animations` | true (with --extract-css) | Extract @keyframes and transitions |
+| `--capture-hover` | false | Capture hover state screenshots |
+| `--video` | false | Record scroll preview video |
+| `--video-format` | webm | Video format: webm, mp4, gif |
+| `--video-duration` | 12000 | Video duration in ms |
+
 ## Environment Variables
 
 Create `.env` file (see `.env.example`):
@@ -270,6 +341,9 @@ GEMINI_API_KEY=your-key    # Optional: enables AI structure analysis
 |--------|----------|---------|
 | screenshot.js | src/core/ | Capture screenshots + extract HTML/CSS |
 | filter-css.js | src/core/ | Filter unused CSS rules |
+| animation-extractor.js | src/core/ | Extract @keyframes and transitions from CSS |
+| state-capture.js | src/core/ | Capture hover states for interactive elements |
+| video-capture.js | src/core/ | Record scroll preview video with optional ffmpeg conversion |
 | extract-assets.js | src/core/ | Download images, fonts, icons |
 | discover-pages.js | src/core/ | Discover navigation links |
 | multi-page-screenshot.js | src/core/ | Capture multiple pages |

package/bin/commands/clone-site.js

@@ -12,6 +12,7 @@
  *   --viewports <list>  Viewport list (default: desktop,tablet,mobile)
  *   --yes               Skip confirmation prompt
  *   --output <dir>      Custom output directory
+ *   --ux-audit          Run UX audit using Gemini Vision (requires GEMINI_API_KEY)
  */
 
 import fs from 'fs/promises';
@@ -23,6 +24,7 @@ import { captureMultiplePages } from '../../src/core/multi-page-screenshot.js';
 import { mergeCssFiles } from '../../src/core/merge-css.js';
 import { rewriteLinks, createPageManifest, rewriteAllLinks } from '../../src/core/rewrite-links.js';
 import { extractDesignTokens } from '../../src/core/design-tokens.js';
+import { runUXAudit } from '../../src/ai/ux-audit.js';
 
 /**
  * Generate output directory name
@@ -53,7 +55,8 @@ export function parseArgs(args) {
     viewports: ['desktop', 'tablet', 'mobile'],
     skipConfirm: false,
     output: null,
-    ai: false
+    ai: false,
+    uxAudit: false
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -71,6 +74,8 @@ export function parseArgs(args) {
       options.output = args[++i];
     } else if (arg === '--ai') {
       options.ai = true;
+    } else if (arg === '--ux-audit') {
+      options.uxAudit = true;
     } else if (!arg.startsWith('--') && !options.url) {
       options.url = arg;
     }
@@ -93,7 +98,8 @@ export async function cloneSite(url, options = {}) {
     viewports = ['desktop', 'tablet', 'mobile'],
     skipConfirm = false,
     output,
-    ai = false
+    ai = false,
+    uxAudit = false
   } = options;
 
   // Validate URL
@@ -111,7 +117,7 @@ export async function cloneSite(url, options = {}) {
   console.error(`[clone-site] Output: ${outputDir}`);
 
   // Step 1: Discover or use manual pages
-  console.error('\n[1/6] Discovering pages...');
+  console.error('\n[1/7] Discovering pages...');
 
   let pageList;
   if (manualPages && manualPages.length > 0) {
@@ -141,7 +147,7 @@ export async function cloneSite(url, options = {}) {
   }
 
   // Step 2: Capture all pages
-  console.error('\n[2/6] Capturing pages...');
+  console.error('\n[2/7] Capturing pages...');
 
   const captureResult = await captureMultiplePages(pageList.pages, {
     outputDir,
@@ -159,7 +165,7 @@ export async function cloneSite(url, options = {}) {
   console.error(`   Screenshots: ${captureResult.stats.totalScreenshots}`);
 
   // Step 3: Merge CSS files (prefer filtered CSS)
-  console.error('\n[3/6] Merging CSS...');
+  console.error('\n[3/7] Merging CSS...');
 
   const mergedCssPath = path.join(outputDir, 'styles.css');
   let mergeResult = { success: false };
@@ -184,7 +190,7 @@ export async function cloneSite(url, options = {}) {
   }
 
   // Step 4: Extract design tokens (if --ai flag)
-  console.error('\n[4/6] Extracting design tokens...');
+  console.error('\n[4/7] Extracting design tokens...');
 
   let hasTokens = false;
   if (ai) {
@@ -207,8 +213,64 @@ export async function cloneSite(url, options = {}) {
     console.error('   Skipped (use --ai flag to enable)');
   }
 
-  // Step 5: Rewrite links
-  console.error('\n[5/6] Rewriting links...');
+  // Step 5: UX Audit (if --ux-audit flag)
+  console.error('\n[5/7] Running UX audit...');
+
+  let uxAuditResult = null;
+  if (uxAudit) {
+    if (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY) {
+      // Find homepage screenshots for audit
+      const screenshotDir = path.join(outputDir, 'screenshots');
+      const screenshotPaths = {};
+
+      for (const viewport of viewports) {
+        const screenshotPath = path.join(screenshotDir, `index-${viewport}.png`);
+        try {
+          await fs.access(screenshotPath);
+          screenshotPaths[viewport] = screenshotPath;
+        } catch {
+          // Try alternative naming
+          const altPath = path.join(screenshotDir, `${viewport}.png`);
+          try {
+            await fs.access(altPath);
+            screenshotPaths[viewport] = altPath;
+          } catch {
+            // Skip this viewport
+          }
+        }
+      }
+
+      if (Object.keys(screenshotPaths).length > 0) {
+        const analysisDir = path.join(outputDir, 'analysis');
+        await fs.mkdir(analysisDir, { recursive: true });
+
+        uxAuditResult = await runUXAudit(screenshotPaths, {
+          output: analysisDir,
+          verbose: true,
+          url
+        });
+
+        if (uxAuditResult.success) {
+          console.error(`   UX Score: ${uxAuditResult.summary.uxScore}%`);
+          console.error(`   Accessibility: ${uxAuditResult.summary.accessibilityScore}%`);
+          console.error(`   Issues: ${uxAuditResult.summary.issueCount} (${uxAuditResult.summary.criticalCount} critical)`);
+          console.error(`   Report: analysis/ux-audit.md`);
+        } else {
+          console.error(`   Warning: UX audit failed - ${uxAuditResult.error}`);
+        }
+      } else {
+        console.error('   Skipped: No screenshots found for audit');
+      }
+    } else {
+      console.error('   Skipped: GEMINI_API_KEY not set');
+      console.error('   Hint: Set GEMINI_API_KEY in ~/.claude/.env for UX audit');
+    }
+  } else {
+    console.error('   Skipped (use --ux-audit flag to enable)');
+  }
+
+  // Step 6: Rewrite links
+  console.error('\n[6/7] Rewriting links...');
 
   const manifest = createPageManifest(pageList.pages, {
     hasTokens,
@@ -241,8 +303,8 @@ export async function cloneSite(url, options = {}) {
     }
   }
 
-  // Step 6: Generate manifest
-  console.error('\n[6/6] Generating manifest...');
+  // Step 7: Generate manifest
+  console.error('\n[7/7] Generating manifest...');
 
   const manifestPath = path.join(outputDir, 'manifest.json');
   await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
@@ -261,6 +323,7 @@ export async function cloneSite(url, options = {}) {
     manifest,
     captureResult,
     mergeResult,
+    uxAuditResult,
     totalTimeMs: totalTime
   };
 }
@@ -281,12 +344,14 @@ Options:
   --yes               Skip confirmation prompt
   --output <dir>      Custom output directory
   --ai                Extract design tokens using Gemini AI (requires GEMINI_API_KEY)
+  --ux-audit          Run UX audit using Gemini Vision (requires GEMINI_API_KEY)
 
 Examples:
   design-clone clone-site https://example.com
   design-clone clone-site https://example.com --max-pages 5
   design-clone clone-site https://example.com --pages /,/about,/contact
   design-clone clone-site https://example.com --ai
+  design-clone clone-site https://example.com --ux-audit
 `);
 }
 

package/bin/commands/init.js

@@ -50,7 +50,7 @@ export async function init(args) {
   }
 
   if (!checks.chrome.ok) {
-    console.warn('Warning: Chrome not found. Screenshots may not work without Puppeteer\'s bundled Chromium.');
+    console.warn('Warning: Chrome not found. Playwright will download Chromium during installation.');
   }
 
   // Check existing installation
@@ -129,6 +129,38 @@ export async function init(args) {
       console.warn(`  Warning: npm install failed: ${error.message}`);
     }
 
+    // Install Playwright
+    console.log('Installing Playwright...');
+    try {
+      // Check if playwright is already installed
+      let playwrightInstalled = false;
+      try {
+        await exec('node -e "require.resolve(\'playwright\')"', { cwd: SKILL_DEST });
+        playwrightInstalled = true;
+        console.log('  Playwright already installed');
+      } catch {
+        // Need to install
+      }
+
+      if (!playwrightInstalled) {
+        await exec('npm install playwright', { cwd: SKILL_DEST });
+        console.log('  Playwright installed');
+      }
+
+      // Install Playwright browsers (chromium only for smaller footprint)
+      console.log('Installing Playwright browsers...');
+      try {
+        await exec('npx playwright install chromium', { cwd: SKILL_DEST, timeout: 300000 });
+        console.log('  Chromium browser installed');
+      } catch (browserError) {
+        console.warn(`  Warning: Browser install failed: ${browserError.message}`);
+        console.warn('  Run manually: npx playwright install chromium');
+      }
+    } catch (error) {
+      console.warn(`  Warning: Playwright install failed: ${error.message}`);
+      console.warn('  Run manually: npm install playwright && npx playwright install chromium');
+    }
+
     // Python dependencies
     if (checks.python.ok) {
       console.log('Installing Python dependencies...');

package/bin/commands/verify.js

@@ -63,11 +63,13 @@ export async function verify() {
   console.log('\nEnvironment:');
   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(`  Node.js:    ${checks.node.ok ? '✓' : '✗'} ${checks.node.message}`);
+  console.log(`  Python:     ${checks.python.ok ? '✓' : '✗'} ${checks.python.message}`);
+  console.log(`  Playwright: ${checks.playwright.ok ? '✓' : '✗'} ${checks.playwright.message}`);
+  console.log(`  Chrome:     ${checks.chrome.ok ? '✓' : '○'} ${checks.chrome.message}${checks.playwright.ok ? ' (optional with Playwright)' : ''}`);
 
   if (!checks.node.ok) allOk = false;
+  if (!checks.playwright.ok && !checks.chrome.ok) allOk = false;
 
   // Check Gemini API key
   console.log('\nOptional:');

package/bin/utils/validate.js

@@ -94,15 +94,31 @@ export async function checkChrome() {
 }
 
 /**
- * Check Puppeteer
+ * Check Playwright
  * @returns {Promise<{ok: boolean, message: string}>}
  */
-export async function checkPuppeteer() {
+export async function checkPlaywright() {
   try {
-    await import('puppeteer');
-    return { ok: true, message: 'Puppeteer installed' };
+    const playwright = await import('playwright');
+    // Check if browsers are installed by checking chromium executable
+    if (playwright.chromium?.executablePath) {
+      try {
+        const fs = await import('fs/promises');
+        await fs.access(playwright.chromium.executablePath());
+        return { ok: true, message: 'Playwright installed with browsers' };
+      } catch {
+        return { ok: true, message: 'Playwright installed (browsers may need install)' };
+      }
+    }
+    return { ok: true, message: 'Playwright installed' };
   } catch {
-    return { ok: false, message: 'Puppeteer not installed (optional)' };
+    // Try playwright-core
+    try {
+      await import('playwright-core');
+      return { ok: true, message: 'playwright-core installed (needs Chrome)' };
+    } catch {
+      return { ok: false, message: 'Playwright not installed' };
+    }
   }
 }
 
@@ -111,12 +127,12 @@ export async function checkPuppeteer() {
  * @returns {Promise<Object>}
  */
 export async function runAllChecks() {
-  const [node, python, chrome, puppeteer] = await Promise.all([
+  const [node, python, chrome, playwright] = await Promise.all([
     checkNode(),
     checkPython(),
     checkChrome(),
-    checkPuppeteer()
+    checkPlaywright()
   ]);
 
-  return { node, python, chrome, puppeteer };
+  return { node, python, chrome, playwright };
 }