design-clone 1.2.0 → 2.1.0

package/README.md

@@ -1,10 +1,15 @@
-# 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
 
@@ -112,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
 
@@ -145,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)
@@ -172,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/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 };
 }

package/docs/cli-reference.md

@@ -25,11 +25,49 @@ node src/core/screenshot.js [options]
 | --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 |
+| --no-semantic | bool | false | Disable WordPress semantic HTML enhancement (Phase 3) |
 | --verbose | bool | false | Verbose logging |
 
 *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.
+**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. When semantic enhancement is enabled (default), output includes `semanticStats` with enhancement details (sections enhanced, IDs/classes/roles added).
+
+### Semantic HTML Enhancement (Phase 3)
+
+Semantic HTML enhancement is enabled by default when extracting HTML. It injects WordPress-compatible semantic IDs, classes, and ARIA roles into the extracted HTML.
+
+**What's Added**:
+- **IDs**: `site-header`, `main-content`, `site-footer`, `site-navigation`, `primary-sidebar`, `hero-section`
+- **Classes**: `site-header`, `main-navigation`, `nav-menu`, `site-main`, `content-area`, `widget-area`, `sidebar`, `site-footer`, `hero`
+- **ARIA Roles**: `banner` (header), `navigation` (nav), `main`, `complementary` (sidebar), `contentinfo` (footer)
+
+**Detection Priority**:
+1. Semantic HTML tags (`<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>`)
+2. ARIA role attributes (`banner`, `navigation`, `main`, `complementary`, `contentinfo`)
+3. Class patterns (header, nav, main, sidebar, footer, hero)
+
+**Usage**:
+```bash
+# Enable semantic enhancement (default)
+node src/core/screenshot.js --url https://example.com --output ./out --extract-html
+
+# Disable semantic enhancement
+node src/core/screenshot.js --url https://example.com --output ./out --extract-html --no-semantic
+```
+
+**Example Output Metadata**:
+```json
+{
+  "html": "path/to/source.html",
+  "semanticStats": {
+    "sectionsEnhanced": 5,
+    "idsAdded": 3,
+    "classesAdded": 4,
+    "rolesAdded": 2,
+    "warnings": []
+  }
+}
+```
 
 ## filter-css.js
 
@@ -86,9 +124,62 @@ node src/core/extract-assets.js --url URL --output DIR
 Validate navigation structure.
 
 ```bash
-node src/verification/verify-menu.js --html FILE
+node src/verification/verify-menu.js --html FILE [--url URL] [--output DIR] [--verbose]
+```
+
+| Option | Description |
+|--------|-------------|
+| --html | Path to HTML file |
+| --url | URL to test (alternative to --html) |
+| --output | Output directory for screenshots |
+| --verbose | Show detailed progress |
+
+## verify-header.js
+
+Verify header components (Phase 1).
+
+```bash
+node src/verification/verify-header.js --html FILE [--url URL] [--output DIR] [--verbose]
+```
+
+Tests: logo presence, navigation visibility, CTA buttons, sticky/fixed behavior, z-index layering, height consistency.
+
+## verify-footer.js
+
+Verify footer components (Phase 1).
+
+```bash
+node src/verification/verify-footer.js --html FILE [--url URL] [--output DIR] [--verbose]
+```
+
+Tests: position at bottom, multi-column layout, link sections, copyright text, social icons, background contrast.
+
+## verify-slider.js
+
+Verify slider/carousel components (Phase 1).
+
+```bash
+node src/verification/verify-slider.js --html FILE [--url URL] [--output DIR] [--verbose]
+```
+
+Tests: library detection (Swiper, Slick, Owl, native), navigation arrows, pagination dots, autoplay behavior, current slide indicator.
+
+## generate-audit-report.js
+
+Aggregate verification results into consolidated report (Phase 1).
+
+```bash
+node src/verification/generate-audit-report.js --dir DIR [--output FILE] [--verbose]
 ```
 
+| Option | Description |
+|--------|-------------|
+| --dir | Directory containing verification JSON results |
+| --output | Output path for report (default: component-audit.md) |
+| --verbose | Show detailed progress |
+
+Output: Markdown report with summary table, side-by-side screenshots, responsive analysis, CSS suggestions.
+
 ## verify-layout.js
 
 Verify layout consistency.
@@ -116,3 +207,110 @@ Used internally by screenshot.js with `--capture-hover` flag.
 - Automatic screenshot pair generation (normal + hover states)
 - CSS rule generation from detected style changes
 - Validates selectors and skips hidden/invisible elements
+
+## ux-audit.js
+
+UX quality assessment using Gemini Vision AI (Phase 2).
+
+```bash
+node src/ai/ux-audit.js --screenshots <dir> [--output <dir>] [--url <url>] [--verbose]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| --screenshots | yes | Directory containing viewport screenshots (desktop.png, tablet.png, mobile.png) |
+| --output | no | Output directory for report and JSON results (default: same as screenshots) |
+| --url | no | Original URL (for report metadata) |
+| --verbose | no | Show detailed progress |
+
+**Requires**: GEMINI_API_KEY or GOOGLE_API_KEY environment variable
+
+**Output**:
+- `ux-audit.md`: Markdown report with scores, issues, and recommendations
+- `ux-audit.json`: Structured results (aggregated scores, viewport breakdown, issues, recommendations)
+
+**Evaluation Categories** (0-100 score each):
+1. Visual Hierarchy - Content prominence, scanning patterns, call-to-action visibility
+2. Navigation - Touch targets, menu discoverability, current page indicator
+3. Typography - Text size, line height, contrast ratio, readability
+4. Spacing - Padding/margins, element breathing room, touch target spacing
+5. Interactive Elements - Button affordance, link distinguishability, focus states
+6. Responsive - Content reflow, no horizontal scroll, text truncation, breakpoint transitions
+
+**Viewport Analysis**: Evaluates all three viewports (desktop: 1920×1080, tablet: 768×1024, mobile: 375×812) and generates weighted scores (desktop 40%, tablet 30%, mobile 30%).
+
+**Issue Severity Levels**:
+- Critical (0-30 score): Blocks tasks or causes confusion
+- Major (31-60 score): Degrades experience significantly
+- Minor (61-80 score): Polish improvements
+
+**Scoring Scale**:
+- 90-100: Excellent, industry-leading UX
+- 70-89: Good, meets modern standards
+- 50-69: Adequate, room for improvement
+- 30-49: Poor, significant issues
+- 0-29: Critical, requires immediate attention
+
+## clone-site.js
+
+Clone multiple pages from website with integrated UX audit (Phase 2).
+
+```bash
+design-clone clone-site <url> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| --pages <paths> | Comma-separated paths (e.g., /,/about,/contact) |
+| --max-pages <n> | Maximum pages to auto-discover (default: 10) |
+| --viewports <list> | Viewport list (default: desktop,tablet,mobile) |
+| --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) |
+| --yes, -y | Skip confirmation prompt |
+
+**Integrated Workflow** (when using --ux-audit):
+1. Discover or use manual pages
+2. Capture screenshots across viewports
+3. Merge CSS files
+4. Extract design tokens (with --ai)
+5. **Run UX audit** (with --ux-audit) - Analyzes homepage screenshots via Gemini Vision
+6. Rewrite links
+7. Generate manifest
+
+**UX Audit Output**: When enabled, generates `analysis/ux-audit.md` and `analysis/ux-audit.json` in output directory.
+
+**Examples**:
+```bash
+design-clone clone-site https://example.com --ux-audit
+design-clone clone-site https://example.com --pages /,/about,/contact --ux-audit
+design-clone clone-site https://example.com --ai --ux-audit
+```
+
+## ux_audit.py
+
+Python module providing UX audit prompts for Gemini Vision integration.
+
+```python
+from src.ai.prompts.ux_audit import build_ux_audit_prompt, build_aggregation_prompt
+
+# Build viewport-specific prompt
+prompt = build_ux_audit_prompt(viewport='mobile')
+
+# Build aggregation prompt for multiple viewports
+aggregation = build_aggregation_prompt(desktop_results, tablet_results, mobile_results)
+```
+
+**Functions**:
+- `build_ux_audit_prompt(viewport)` - Build prompt with viewport-specific checks (mobile/tablet/desktop)
+- `build_aggregation_prompt(desktop, tablet, mobile)` - Combine viewport results into unified assessment
+
+**Constants**:
+- `UX_AUDIT_PROMPT` - Base UX evaluation prompt (6 categories)
+- `VIEWPORT_CONTEXT` - Dictionary of viewport-specific evaluation criteria
+- `AGGREGATION_PROMPT` - Template for combining viewport results with weighted averaging
+
+**Viewport Weighting**:
+- Desktop: 40% (primary interaction model)
+- Tablet: 30% (hybrid interaction)
+- Mobile: 30% (touch-first)