design-clone 1.1.0 → 1.2.0

package/README.md

@@ -10,6 +10,7 @@ Clone website designs with multi-viewport screenshots, HTML/CSS extraction, and
 
 - **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 +76,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/

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/init.js

@@ -17,6 +17,8 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 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');
+// Commands destination: ~/.claude/commands/design/
+const getCommandsDest = () => path.join(process.env.HOME || process.env.USERPROFILE || '', '.claude/commands/design');
 
 /**
  * Install skill to Claude Code skills directory
@@ -93,6 +95,29 @@ export async function init(args) {
     process.exit(1);
   }
 
+  // Copy slash commands to ~/.claude/commands/design/
+  console.log('Installing slash commands...');
+  try {
+    const COMMANDS_DEST = getCommandsDest();
+    const COMMANDS_SOURCE = path.join(SKILL_SOURCE, 'commands/design');
+
+    // Ensure commands directory exists
+    await fs.mkdir(COMMANDS_DEST, { recursive: true });
+
+    // Copy command files
+    const commandFiles = await fs.readdir(COMMANDS_SOURCE).catch(() => []);
+    for (const file of commandFiles) {
+      if (file.endsWith('.md')) {
+        const src = path.join(COMMANDS_SOURCE, file);
+        const dest = path.join(COMMANDS_DEST, file);
+        await fs.copyFile(src, dest);
+        console.log(`  Installed: /design:${file.replace('.md', '')}`);
+      }
+    }
+  } catch (error) {
+    console.warn(`  Warning: Could not install slash commands: ${error.message}`);
+  }
+
   // Install dependencies
   if (!skipDeps) {
     // Node.js dependencies
@@ -156,6 +181,9 @@ export async function init(args) {
   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('  2. Use slash commands in Claude Code:');
+  console.log('     /design:clone      - Clone single page');
+  console.log('     /design:clone-site - Clone multiple pages');
+  console.log('     /design:clone-px   - Pixel-perfect clone');
   console.log('\nRun "design-clone verify" to check installation status.');
 }

package/commands/design/clone-site.md

@@ -0,0 +1,135 @@
+---
+description: Clone multiple pages from a website with shared CSS and navigation
+argument-hint: [url] [--max-pages N] [--ai]
+---
+
+Clone multiple pages from this website with shared CSS and working navigation:
+<url>$ARGUMENTS</url>
+
+## Required Skills (Priority Order)
+1. **`chrome-devtools`** - Multi-viewport screenshot capture
+2. **`ai-multimodal`** - Gemini Vision for design token extraction (with --ai flag)
+
+## Pipeline Overview
+
+```
+URL -> Page Discovery -> Multi-page Capture -> CSS Filtering & Merge -> Link Rewriting -> [AI Tokens] -> Output
+```
+
+## Workflow
+
+### STEP 1: Run Clone-Site Command
+
+Use the design-clone CLI to clone multiple pages:
+
+```bash
+# Basic usage - auto-discovers pages from navigation
+design-clone clone-site "$ARGUMENTS"
+
+# With options
+design-clone clone-site "$ARGUMENTS" --max-pages 5
+
+# Specific pages
+design-clone clone-site "$ARGUMENTS" --pages /,/about,/contact
+
+# With AI design token extraction (requires GEMINI_API_KEY)
+design-clone clone-site "$ARGUMENTS" --ai
+```
+
+### CLI Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--pages <paths>` | auto | Comma-separated paths (e.g., /,/about,/contact) |
+| `--max-pages <n>` | 10 | Maximum pages to auto-discover |
+| `--viewports <list>` | desktop,tablet,mobile | Viewport list |
+| `--yes` | false | Skip confirmation prompt |
+| `--output <dir>` | ./cloned-designs/{timestamp}-{domain} | Custom output directory |
+| `--ai` | false | Extract design tokens using Gemini AI |
+
+### STEP 2: Process Flow (Automatic)
+
+The command executes these steps automatically:
+
+1. **Page Discovery** - Crawls navigation links, respects same-domain
+2. **Multi-page Capture** - Screenshots + HTML/CSS for each page
+3. **CSS Merge** - Combines filtered CSS with deduplication (15-30% reduction)
+4. **Link Rewriting** - Updates internal links to local .html files
+5. **Token Extraction** (if --ai) - Gemini Vision extracts design tokens
+6. **Manifest Generation** - Creates manifest.json with page metadata
+
+### Output Structure
+
+```
+cloned-designs/{timestamp}-{domain}/
+├── analysis/           # Screenshots by viewport
+│   ├── desktop/
+│   │   ├── index.png
+│   │   ├── about.png
+│   │   └── contact.png
+│   ├── tablet/
+│   └── mobile/
+├── html/               # Raw extracted HTML (source)
+├── css/                # Per-page CSS (raw + filtered)
+├── pages/              # HTML with rewritten links
+│   ├── index.html      # Links to ../styles.css
+│   ├── about.html
+│   └── contact.html
+├── styles.css          # Merged + deduplicated CSS
+├── tokens.css          # Design tokens (if --ai)
+├── design-tokens.json  # Token data (if --ai)
+├── manifest.json       # Page metadata + mapping
+└── capture-results.json
+```
+
+### STEP 3: Review & Edit
+
+After cloning:
+
+1. **Test navigation** - Open `pages/index.html` in browser
+2. **Verify CSS** - Check that styles.css covers all pages
+3. **Check screenshots** - Review analysis/ for visual reference
+4. **Edit tokens** (if --ai) - Modify tokens.css to customize design
+
+## Features
+
+- **Auto-discovers pages** from navigation (SPA-aware)
+- **Shared CSS** with deduplication (15-30% reduction)
+- **Filtered CSS** - Uses per-page filtered CSS, not raw
+- **Working internal links** - Rewrites to local .html files
+- **Progress reporting** - Shows capture progress
+- **Graceful errors** - Continues on individual page failures
+- **AI tokens** (optional) - Gemini Vision design token extraction
+
+## Environment Variables
+
+```bash
+# Optional: For AI token extraction with --ai flag
+GEMINI_API_KEY=your-key
+```
+
+## Examples
+
+```bash
+# Clone with auto-discovery (up to 10 pages)
+/design:clone-site https://example.com
+
+# Clone specific pages only
+/design:clone-site https://example.com --pages /,/about,/pricing
+
+# Clone with AI token extraction
+/design:clone-site https://example.com --ai --max-pages 5
+
+# Clone to custom directory
+/design:clone-site https://example.com --output ./my-clone
+```
+
+## Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Page fails to load | Continues with other pages, logs warning |
+| No navigation found | Falls back to homepage only |
+| CSS extraction fails | Uses raw CSS fallback |
+| No GEMINI_API_KEY | Skips token extraction, logs hint |
+| Python not found | Skips AI features, continues |

package/docs/cli-reference.md

@@ -22,10 +22,14 @@ node src/core/screenshot.js [options]
 | --close | bool | false | Close browser after capture (false keeps session) |
 | --extract-html | bool | false | Extract cleaned HTML |
 | --extract-css | bool | false | Extract all CSS from page |
+| --extract-animations | bool | true* | Extract @keyframes and transitions (enabled with --extract-css) |
 | --filter-unused | bool | true | Filter CSS to remove unused selectors |
+| --capture-hover | bool | false | Capture hover state screenshots and generate :hover CSS |
 | --verbose | bool | false | Verbose logging |
 
-**Output**: JSON with screenshot paths and metadata. Includes `browserRestarts` count tracking for stability monitoring.
+*Default true when --extract-css is enabled, can be disabled with `--extract-animations false`
+
+**Output**: JSON with screenshot paths and metadata. Includes `browserRestarts` count tracking for stability monitoring. When `--capture-hover` is enabled, also includes hover state results in output.
 
 ## filter-css.js
 
@@ -92,3 +96,23 @@ Verify layout consistency.
 ```bash
 node src/verification/verify-layout.js --html FILE
 ```
+
+## state-capture.js
+
+Capture hover states for interactive elements.
+
+Used internally by screenshot.js with `--capture-hover` flag.
+
+| Export | Description |
+|--------|-------------|
+| `captureAllHoverStates(page, cssString, outputDir)` | Detect interactive elements and capture normal/hover screenshots |
+| `captureHoverState(page, selector, outputDir, index)` | Capture hover state for a single element |
+| `generateHoverCss(results)` | Generate `:hover` CSS rules from captured style diffs |
+| `detectInteractiveElements(page, cssString)` | Detect interactive elements via CSS analysis and DOM query |
+
+**Key Features:**
+- Dual detection: CSS-based (`:hover` selectors) and DOM-based (interactive elements, transitions)
+- Per-element style diff capture (backgroundColor, color, transform, boxShadow, etc.)
+- Automatic screenshot pair generation (normal + hover states)
+- CSS rule generation from detected style changes
+- Validates selectors and skips hidden/invisible elements

package/docs/design-clone-architecture.md

@@ -131,6 +131,8 @@ Both Node.js and Python share same resolution order:
 | Script | Location | Language | Purpose |
 |--------|----------|----------|---------|
 | screenshot.js | src/core/ | Node.js | Screenshot capture, HTML/CSS extraction |
+| animation-extractor.js | src/core/ | Node.js | Extract @keyframes, transitions, animation properties |
+| state-capture.js | src/core/ | Node.js | Capture hover states for interactive elements |
 | filter-css.js | src/core/ | Node.js | Remove unused CSS selectors |
 | extract-assets.js | src/core/ | Node.js | Download images, fonts, icons |
 | analyze-structure.py | src/ai/ | Python | Gemini AI structure analysis |
@@ -179,42 +181,68 @@ bin/
 ### design:clone
 
 ```
-URL → src/core/screenshot.js → Screenshots (3 viewports)
-                              → source.html (cleaned)
-                              → source-raw.css
-    → src/core/filter-css.js  → source.css (filtered)
+URL → src/core/screenshot.js       → Screenshots (3 viewports)
+                                   → source.html (cleaned)
+                                   → source-raw.css
+    → src/core/filter-css.js       → source.css (filtered)
+    → src/core/animation-extractor → animations.css
+                                   → animation-tokens.json
+    → src/core/state-capture.js*   → hover-states/ (hover screenshots)
+                                   → hover.css (generated :hover rules)
 ```
 
+*Enabled with `--capture-hover true` flag
+
 ### design:clone-px
 
 ```
-URL → src/core/screenshot.js      → Screenshots + HTML/CSS
-    → src/core/filter-css.js      → Filtered CSS
-    → src/core/extract-assets.js  → assets/ (images, fonts, icons)
-    → src/ai/analyze-structure.py → structure.md (AI analysis)
-    → src/ai/extract-design-tokens.py → tokens.json, tokens.css
-    → src/verification/verify-menu.js → Menu validation report
+URL → src/core/screenshot.js           → Screenshots + HTML/CSS
+    → src/core/filter-css.js           → Filtered CSS
+    → src/core/animation-extractor     → animations.css, animation-tokens.json
+    → src/core/state-capture.js*       → hover-states/, hover.css
+    → src/core/extract-assets.js       → assets/ (images, fonts, icons)
+    → src/ai/analyze-structure.py      → structure.md (AI analysis)
+    → src/ai/extract-design-tokens.py  → tokens.json, tokens.css
+    → src/verification/verify-menu.js  → Menu validation report
 ```
 
+*Hover state capture enabled by default in design:clone-px workflow
+
 ## Output Structure
 
 ```
 cloned-design/
-├── desktop.png           # 1920x1080
-├── tablet.png            # 768x1024
-├── mobile.png            # 375x812
-├── source.html           # Cleaned HTML
-├── source.css            # Filtered CSS
-├── source-raw.css        # Original CSS
-├── structure.md          # AI analysis (optional)
-├── tokens.json           # Design tokens
-├── tokens.css            # CSS variables
+├── desktop.png              # 1920x1080
+├── tablet.png               # 768x1024
+├── mobile.png               # 375x812
+├── source.html              # Cleaned HTML
+├── source.css               # Filtered CSS
+├── source-raw.css           # Original CSS
+├── animations.css           # Extracted @keyframes definitions
+├── animation-tokens.json    # Animation metadata (keyframes, transitions, timings)
+├── hover.css                # Generated :hover CSS rules (when --capture-hover)
+├── structure.md             # AI analysis (optional)
+├── tokens.json              # Design tokens
+├── tokens.css               # CSS variables
+├── hover-states/            # Hover state captures (when --capture-hover)
+│   ├── hover-0-normal.png   # Element before hover
+│   ├── hover-0-hover.png    # Element during hover
+│   ├── hover-1-normal.png   # ...
+│   ├── hover-1-hover.png
+│   └── hover-diff.json      # Summary of detected and captured elements
 └── assets/
     ├── images/
     ├── fonts/
     └── icons/
 ```
 
+**Hover State Output** (when `--capture-hover true`):
+- `hover-states/`: Directory containing hover state captures
+  - `hover-N-normal.png`: Screenshot of element in normal state
+  - `hover-N-hover.png`: Screenshot of element with hover state applied
+  - `hover-diff.json`: Summary with detected count, captured count, and style differences for each element
+- `hover.css`: Generated CSS rules with `:hover` selectors extracted from style diffs
+
 ## Dependencies
 
 ### Node.js (package.json)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-clone",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Claude Code skill for cloning website designs via multi-viewport screenshots, HTML/CSS extraction, and Gemini AI analysis",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "bin/",
     "src/",
+    "commands/",
     "templates/",
     "docs/",
     "SKILL.md",
@@ -53,5 +54,9 @@
     "puppeteer": {
       "optional": true
     }
+  },
+  "optionalDependencies": {
+    "fluent-ffmpeg": "^2.1.2",
+    "@ffmpeg-installer/ffmpeg": "^1.1.0"
   }
 }