design-clone 1.1.1 → 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/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.1",
+  "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": {
@@ -54,5 +54,9 @@
     "puppeteer": {
       "optional": true
     }
+  },
+  "optionalDependencies": {
+    "fluent-ffmpeg": "^2.1.2",
+    "@ffmpeg-installer/ffmpeg": "^1.1.0"
   }
 }