design-clone 1.2.0 → 2.3.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "design-clone",
-  "version": "1.2.0",
+  "version": "2.3.0",
   "type": "module",
-  "description": "Claude Code skill for cloning website designs via multi-viewport screenshots, HTML/CSS extraction, and Gemini AI analysis",
+  "description": "Claude Code skill for cloning website designs via multi-viewport screenshots, HTML/CSS extraction, and AI analysis",
   "bin": {
     "design-clone": "./bin/cli.js"
   },
@@ -13,16 +13,19 @@
     "templates/",
     "docs/",
     "SKILL.md",
-    "requirements.txt",
     ".env.example"
   ],
   "scripts": {
-    "screenshot": "node src/core/screenshot.js",
-    "filter-css": "node src/core/filter-css.js",
-    "extract-assets": "node src/core/extract-assets.js",
+    "screenshot": "node src/core/capture/screenshot.js",
+    "filter-css": "node src/core/css/filter-css.js",
+    "extract-assets": "node src/core/media/extract-assets.js",
     "verify-menu": "node src/verification/verify-menu.js",
     "verify-layout": "node src/verification/verify-layout.js",
-    "test": "node tests/run-all-tests.js"
+    "test": "c8 node tests/run-all-tests.js",
+    "test:no-coverage": "node tests/run-all-tests.js",
+    "docs:dev": "npm run docs:dev --prefix docs",
+    "docs:build": "npm run docs:build --prefix docs",
+    "docs:preview": "npm run docs:preview --prefix docs"
   },
   "keywords": [
     "claude",
@@ -31,8 +34,7 @@
     "design",
     "clone",
     "screenshot",
-    "puppeteer",
-    "gemini",
+    "playwright",
     "website"
   ],
   "author": "",
@@ -45,18 +47,15 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "css-tree": "^2.3.1"
-  },
-  "peerDependencies": {
-    "puppeteer": ">=21.0.0"
-  },
-  "peerDependenciesMeta": {
-    "puppeteer": {
-      "optional": true
-    }
+    "css-tree": "^2.3.1",
+    "playwright": "^1.58.1",
+    "sharp": "^0.34.5"
   },
   "optionalDependencies": {
-    "fluent-ffmpeg": "^2.1.2",
-    "@ffmpeg-installer/ffmpeg": "^1.1.0"
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "fluent-ffmpeg": "^2.1.2"
+  },
+  "devDependencies": {
+    "c8": "^10.1.3"
   }
-}
+}

package/src/ai/prompts/design-tokens/basic.md

@@ -0,0 +1,80 @@
+# Design Token Extraction Prompt (Basic)
+
+Analyze these website screenshots (desktop, tablet, mobile) and extract design tokens.
+
+Return ONLY valid JSON in this exact format:
+
+```json
+{
+  "colors": {
+    "primary": "#hex",
+    "secondary": "#hex",
+    "accent": "#hex",
+    "background": "#hex",
+    "surface": "#hex",
+    "text": {
+      "primary": "#hex",
+      "secondary": "#hex",
+      "muted": "#hex"
+    },
+    "border": "#hex"
+  },
+  "typography": {
+    "fontFamily": {
+      "heading": "Font Name, sans-serif",
+      "body": "Font Name, sans-serif"
+    },
+    "fontSize": {
+      "xs": "12px",
+      "sm": "14px",
+      "base": "16px",
+      "lg": "18px",
+      "xl": "20px",
+      "2xl": "24px",
+      "3xl": "30px",
+      "4xl": "36px"
+    },
+    "fontWeight": {
+      "normal": 400,
+      "medium": 500,
+      "semibold": 600,
+      "bold": 700
+    },
+    "lineHeight": {
+      "tight": 1.25,
+      "normal": 1.5,
+      "relaxed": 1.75
+    }
+  },
+  "spacing": {
+    "1": "4px",
+    "2": "8px",
+    "3": "12px",
+    "4": "16px",
+    "6": "24px",
+    "8": "32px",
+    "12": "48px",
+    "16": "64px"
+  },
+  "borderRadius": {
+    "sm": "4px",
+    "md": "8px",
+    "lg": "16px",
+    "full": "9999px"
+  },
+  "shadows": {
+    "sm": "0 1px 2px rgba(0,0,0,0.05)",
+    "md": "0 4px 6px rgba(0,0,0,0.1)",
+    "lg": "0 10px 15px rgba(0,0,0,0.1)"
+  },
+  "notes": []
+}
+```
+
+RULES:
+1. Use exact 6-digit hex codes (#RRGGBB), not color names
+2. Identify Google Fonts: Inter, Roboto, Open Sans, Poppins, Montserrat, Lato, Nunito, Raleway, Playfair Display, Merriweather
+3. If font unknown, use reasonable fallback (sans-serif or serif)
+4. Extract observed values; use sensible defaults if unclear
+5. Detect spacing patterns (8px grid common)
+6. Add any observations or accessibility concerns to notes array

package/src/ai/prompts/design-tokens/section-with-css.md

@@ -0,0 +1,41 @@
+# Design Token Extraction Prompt (Section-Specific With CSS)
+
+Analyze the section screenshot you are currently viewing, using the CSS context you read above.
+
+Extract design tokens visible in THIS section. Use EXACT values from CSS when possible.
+
+Return ONLY valid JSON:
+
+```json
+{
+  "colors": {
+    "background": "#exact-hex from CSS or screenshot",
+    "text": "#exact-hex for text color",
+    "heading": "#exact-hex for heading color",
+    "accent": "#exact-hex for accent/CTA",
+    "border": "#exact-hex if borders visible"
+  },
+  "typography": {
+    "fontFamily": "exact font-family from CSS",
+    "headingSize": "exact font-size for headings",
+    "bodySize": "exact body font-size",
+    "fontWeight": {
+      "heading": "exact weight from CSS",
+      "body": "exact weight from CSS"
+    }
+  },
+  "spacing": {
+    "sectionPadding": "exact padding from CSS",
+    "elementGap": "exact gap/margin",
+    "containerPadding": "exact container padding"
+  },
+  "borderRadius": "exact radius from CSS or null",
+  "shadow": "exact box-shadow from CSS or null",
+  "notes": ["list any CSS custom properties found"]
+}
+```
+
+RULES:
+1. Extract EXACT hex codes from CSS
+2. Use null for values not visible in this section
+3. Note any CSS variables (--color-*, --space-*)

package/src/ai/prompts/design-tokens/section.md

@@ -0,0 +1,48 @@
+# Design Token Extraction Prompt (Section-Specific)
+
+Analyze the section screenshot you are currently viewing and extract design tokens.
+
+Focus on elements visible in THIS section only:
+- Background colors and gradients
+- Text colors (headings, body, links)
+- Typography (font family, sizes, weights)
+- Spacing patterns (padding, margins, gaps)
+- Border radius and shadows
+- Any accent or highlight colors
+
+Return ONLY valid JSON:
+
+```json
+{
+  "colors": {
+    "background": "#hex or null if transparent",
+    "text": "#hex for main text",
+    "heading": "#hex for headings",
+    "accent": "#hex for buttons/links/highlights",
+    "border": "#hex if borders visible"
+  },
+  "typography": {
+    "fontFamily": "observed font or best guess",
+    "headingSize": "largest heading size in px",
+    "bodySize": "body text size in px",
+    "fontWeight": {
+      "heading": 700,
+      "body": 400
+    }
+  },
+  "spacing": {
+    "sectionPadding": "vertical padding estimate",
+    "elementGap": "gap between elements",
+    "containerPadding": "horizontal padding"
+  },
+  "borderRadius": "observed radius or null",
+  "shadow": "observed shadow or null",
+  "notes": ["observations about this section"]
+}
+```
+
+RULES:
+1. Use exact 6-digit hex codes (#RRGGBB)
+2. If a value is not visible/applicable, use null
+3. Focus only on what's visible in this section image
+4. Add section-specific observations to notes

package/src/ai/prompts/design-tokens/with-css.md

@@ -0,0 +1,87 @@
+# Design Token Extraction Prompt (With CSS Context)
+
+Extract design tokens from the provided CSS and screenshots.
+
+You have access to:
+1. Screenshots showing the visual design
+2. The actual CSS from `source.css` you read above
+
+CRITICAL: Extract EXACT values from the CSS. Do not estimate colors or fonts.
+
+---
+
+Based on the CSS above, return ONLY valid JSON:
+
+```json
+{
+  "colors": {
+    "primary": "[exact hex from CSS, look for primary/brand colors]",
+    "secondary": "[exact hex from CSS]",
+    "accent": "[exact hex for accent/highlight colors]",
+    "background": "[exact hex, usually body background]",
+    "surface": "[exact hex for cards/sections]",
+    "text": {
+      "primary": "[exact hex, usually body color]",
+      "secondary": "[exact hex for muted text]",
+      "muted": "[exact hex for very light text]"
+    },
+    "border": "[exact hex for borders]"
+  },
+  "typography": {
+    "fontFamily": {
+      "heading": "[exact font-family from CSS h1-h6 rules]",
+      "body": "[exact font-family from CSS body rule]"
+    },
+    "fontSize": {
+      "xs": "[smallest font-size from CSS]",
+      "sm": "[small font-size]",
+      "base": "[body font-size]",
+      "lg": "[larger font-size]",
+      "xl": "[heading font-size]",
+      "2xl": "[h3 font-size]",
+      "3xl": "[h2 font-size]",
+      "4xl": "[h1 font-size]"
+    },
+    "fontWeight": {
+      "normal": "[normal weight from CSS]",
+      "medium": "[medium weight]",
+      "semibold": "[semibold weight]",
+      "bold": "[bold weight from CSS]"
+    },
+    "lineHeight": {
+      "tight": "[tight line-height, usually 1.2-1.3]",
+      "normal": "[normal line-height, usually 1.5-1.6]",
+      "relaxed": "[relaxed line-height, usually 1.7-1.8]"
+    }
+  },
+  "spacing": {
+    "1": "[4px or smallest spacing]",
+    "2": "[8px]",
+    "3": "[12px]",
+    "4": "[16px - common padding]",
+    "6": "[24px]",
+    "8": "[32px]",
+    "12": "[48px - section padding]",
+    "16": "[64px - large section padding]"
+  },
+  "borderRadius": {
+    "sm": "[small radius from CSS]",
+    "md": "[medium radius]",
+    "lg": "[large radius]",
+    "full": "9999px"
+  },
+  "shadows": {
+    "sm": "[small shadow from CSS box-shadow]",
+    "md": "[medium shadow]",
+    "lg": "[large shadow]"
+  },
+  "notes": ["List exact CSS custom properties/variables if found", "Note any @import URLs"]
+}
+```
+
+RULES:
+1. Extract EXACT hex codes from CSS, not approximate
+2. Copy font-family values exactly as written
+3. Extract actual px/rem values, convert rem to px if needed (1rem = 16px)
+4. Look for CSS custom properties (--color-*, --font-*, --space-*)
+5. If a value isn't in CSS, use screenshot to estimate

package/src/ai/prompts/structure-analysis/basic.md

@@ -0,0 +1,55 @@
+# Structure Analysis Prompt (Basic)
+
+Analyze this website screenshot and describe the page structure in detail.
+
+Output a markdown document with the following sections:
+
+# Page Structure Analysis
+
+## 1. Header Section
+- Logo: [position, size, type (text/image)]
+- Navigation: [number of items, layout (horizontal/vertical)]
+- CTA Button: [text, position, style]
+- Mobile menu: [hamburger icon visible?]
+
+## 2. Hero Section
+- Layout: [centered/left-aligned/split]
+- Headline: [estimated font size, weight, color]
+- Subheadline: [if present, describe]
+- Primary CTA: [button text, style]
+- Secondary CTA: [if present]
+- Background: [solid color/gradient/image]
+- Visual elements: [images, illustrations, icons]
+
+## 3. Content Sections
+For each distinct section, describe:
+- Section name/purpose: [features, testimonials, pricing, etc.]
+- Layout pattern: [grid columns, cards, alternating left-right]
+- Number of items: [e.g., 3 feature cards, 4 testimonials]
+- Key components: [icons, images, headings, descriptions]
+
+## 4. Footer Section
+- Layout: [columns, stacked]
+- Content blocks: [logo, links, social, newsletter]
+- Copyright: [position, content]
+
+## 5. Global Patterns
+- Container max-width: [estimated px]
+- Section padding: [estimated vertical spacing]
+- Card/component style: [shadows, borders, rounded corners]
+- Color scheme: [light/dark mode, accent colors]
+- Typography style: [modern/classic, serif/sans-serif]
+
+## 6. Responsive Hints
+- Mobile-friendly indicators
+- Collapsible elements
+- Stack vs grid on small screens
+
+## 7. BEM Class Suggestions
+Suggest semantic BEM class names for main components:
+- header, header__logo, header__nav, header__cta
+- hero, hero__title, hero__subtitle, hero__cta
+- section--features, feature-card, feature-card__icon
+- footer, footer__links, footer__social
+
+Be specific and detailed. This analysis will be used to generate HTML/CSS.

package/src/ai/prompts/structure-analysis/with-context.md

@@ -0,0 +1,59 @@
+# Structure Analysis Prompt (With HTML/CSS Context)
+
+Analyze this website using the screenshot AND the provided source HTML/CSS.
+
+You have access to:
+1. A screenshot showing the visual design
+2. The actual HTML structure of the page (from `source.html` you read above)
+3. The CSS rules used on the page (from `source.css` you read above)
+
+IMPORTANT: Use the actual HTML/CSS to provide ACCURATE information, not estimates.
+
+---
+
+Based on the above context, output a markdown document:
+
+# Page Structure Analysis
+
+## 1. Header Section
+- Logo: [exact class/id from HTML, position from CSS]
+- Navigation: [exact nav structure from HTML]
+- CTA Button: [exact button text and classes]
+- Mobile menu: [presence and class name if exists]
+
+## 2. Hero Section
+- Layout: [from CSS flexbox/grid rules]
+- Headline: [exact text and classes from HTML]
+- Subheadline: [exact text if present]
+- Primary CTA: [exact button text and styles]
+- Background: [from CSS background rules]
+- Visual elements: [images/icons from HTML]
+
+## 3. Content Sections
+For each section found in HTML, describe:
+- Section class/id: [exact from HTML]
+- Layout: [from CSS grid/flex rules]
+- Items: [exact count from HTML]
+- Components: [exact structure]
+
+## 4. Footer Section
+- Layout: [from CSS]
+- Content blocks: [exact from HTML]
+- Links: [exact href patterns]
+
+## 5. Actual CSS Values (from source)
+- Container max-width: [exact from CSS]
+- Section padding: [exact from CSS]
+- Border-radius values: [exact from CSS]
+- Primary color: [exact hex from CSS]
+- Font-family: [exact from CSS]
+- Font-sizes: [exact from CSS]
+
+## 6. Responsive Breakpoints (from CSS @media queries)
+- Breakpoint values: [exact from CSS]
+- Layout changes: [what changes at each breakpoint]
+
+## 7. Recommended BEM Classes
+Based on the actual HTML structure, suggest clean BEM names that map to existing classes.
+
+CRITICAL: Extract EXACT values from the CSS where possible. Do not estimate.

package/src/ai/prompts/structure-analysis/with-dimensions.md

@@ -0,0 +1,63 @@
+# Structure Analysis Prompt (With Extracted Dimensions)
+
+Analyze this website screenshot using the EXACT extracted dimensions from `dimensions-summary.json` you read above.
+
+## CRITICAL INSTRUCTIONS
+1. USE ONLY the exact values from `dimensions-summary.json` - DO NOT estimate or approximate
+2. All measurements were extracted from the actual DOM via getBoundingClientRect + getComputedStyle
+3. When describing layout, reference these exact numbers
+4. Section 5 MUST repeat these exact values verbatim
+
+Use the following fields from `dimensions-summary.json`:
+- `EXACT_DIMENSIONS.container_max_width` for container width
+- `EXACT_DIMENSIONS.section_padding` for section padding
+- `EXACT_DIMENSIONS.gap` for element gaps
+- `EXACT_DIMENSIONS.card_dimensions.width/height/padding` for card measurements
+- `EXACT_TYPOGRAPHY.h1/h2/h3/body` for font sizes
+- `RESPONSIVE.desktop_breakpoint/tablet_breakpoint/mobile_breakpoint` for breakpoints
+- `RESPONSIVE.typography_scaling` for responsive font scaling
+
+---
+
+Now output a markdown document following this structure.
+IMPORTANT: In section 5, you MUST repeat the exact values from the JSON - do not change them.
+
+# Page Structure Analysis
+
+## 1. Header Section
+- Logo: [describe position and layout]
+- Navigation: [describe navigation structure]
+- CTA Button: [if present]
+- Mobile menu: [hamburger toggle if visible]
+
+## 2. Hero Section
+- Layout: [describe arrangement]
+- Headline: font-size from EXACT_TYPOGRAPHY.h1 (EXACT), [describe style]
+- Subheadline: [if present]
+- Primary CTA: [button description]
+- Background: [describe]
+
+## 3. Content Sections
+For each section describe:
+- Section name/purpose
+- Layout pattern using the EXACT gap value from EXACT_DIMENSIONS.gap
+- Card dimensions from EXACT_DIMENSIONS.card_dimensions (EXACT)
+- Components within
+
+## 4. Footer Section
+- Layout: [describe]
+- Content blocks
+
+## 5. EXACT CSS Values (use these for generation - DO NOT MODIFY)
+Copy ALL values directly from `dimensions-summary.json`:
+- Container max-width, section padding, card dimensions, card padding, gap
+- H1, H2, H3, body font sizes
+- Desktop, tablet, mobile breakpoints
+
+## 6. Responsive Behavior
+- At tablet breakpoint: [describe layout changes]
+- At mobile breakpoint: [describe layout changes]
+- Typography scales from RESPONSIVE.typography_scaling
+
+## 7. BEM Class Suggestions
+[Suggest semantic class names for main components]

package/src/ai/prompts/structure-analysis/with-hierarchy.md

@@ -0,0 +1,73 @@
+# Structure Analysis Prompt (With DOM Hierarchy)
+
+Analyze this website screenshot using the EXACT extracted dimensions and DOM hierarchy.
+
+## CRITICAL INSTRUCTIONS
+1. USE ONLY the exact values from the JSON files you read above - DO NOT estimate
+2. All measurements are from actual DOM via getBoundingClientRect + getComputedStyle
+3. Typography varies BY SECTION - use section-specific values from TYPOGRAPHY_BY_SECTION
+4. Reference DOM hierarchy from `dom-hierarchy.json` for nesting structure
+
+Use data from `dom-hierarchy.json`:
+- `landmarks` for header, main, footer, aside, nav detection
+- `headingTree` for heading hierarchy by section
+- `root` for DOM nesting structure
+
+Use data from `dimensions-summary.json`:
+- `EXACT_DIMENSIONS` for container, section, gap, card measurements
+- `TYPOGRAPHY_BY_SECTION.hero` for hero-specific typography
+- `TYPOGRAPHY_BY_SECTION.content` for content-specific typography
+- `TYPOGRAPHY_BY_SECTION.footer` for footer-specific typography
+- `RESPONSIVE` for breakpoints and typography scaling
+
+---
+
+Output a markdown document following this structure.
+IMPORTANT: Use section-specific typography values. Hero H1 differs from Content H1.
+
+# Page Structure Analysis
+
+## 1. Header Section
+- Logo: [describe position and layout]
+- Navigation: [count items from hierarchy]
+- CTA: [if present]
+
+## 2. Hero Section
+- Layout: [from section structure]
+- Headline: font-size from TYPOGRAPHY_BY_SECTION.hero.h1 (EXACT)
+- Subheadline: [if present]
+- CTA: [button description]
+
+## 3. Content Sections
+For each section in the hierarchy:
+- Heading sizes: Use CONTENT section typography (content.h2, content.h3)
+- Layout: Reference section structure
+- Card dimensions from EXACT_DIMENSIONS with gap
+- Components: [describe]
+
+## 4. Footer Section
+- Layout: [from hierarchy]
+- Typography: footer body text size from TYPOGRAPHY_BY_SECTION.footer
+
+## 5. EXACT CSS Values (DO NOT MODIFY)
+### Layout
+- Container max-width, section padding, card dimensions, card padding, gap
+
+### Typography per Section
+- Hero H1, Hero H2
+- Content H2, Content H3, Content Body
+- Footer Body
+
+### Breakpoints
+- Desktop, Tablet, Mobile breakpoints
+
+## 6. Responsive Behavior
+- At tablet breakpoint: [describe layout changes]
+- At mobile breakpoint: [describe layout changes]
+- Typography scales from RESPONSIVE.typography_scaling
+
+## 7. DOM Nesting Structure
+Reproduce the exact nesting from `dom-hierarchy.json` root in generated HTML.
+
+## 8. BEM Class Suggestions
+[Based on hierarchy, suggest semantic names]

package/src/ai/prompts/ux-audit/aggregation.md

@@ -0,0 +1,42 @@
+# UX Audit Aggregation Prompt
+
+Combine the viewport-specific UX audit results you produced above into a final assessment.
+
+Using the desktop, tablet, and mobile audit JSON results from your prior analysis steps, create a unified report that:
+
+1. Averages scores across viewports (weighted: desktop 40%, tablet 30%, mobile 30%)
+2. Prioritizes issues by severity and viewport impact
+3. Consolidates duplicate issues
+4. Ranks recommendations by impact
+
+Return ONLY valid JSON:
+
+```json
+{
+  "overall_scores": {
+    "visual_hierarchy": 0,
+    "navigation": 0,
+    "typography": 0,
+    "spacing": 0,
+    "interactivity": 0,
+    "responsive": 0
+  },
+  "overall_ux_score": 0,
+  "accessibility_score": 0,
+  "viewport_breakdown": {
+    "desktop": 0,
+    "tablet": 0,
+    "mobile": 0
+  },
+  "top_issues": [
+    {
+      "category": "<category>",
+      "severity": "<severity>",
+      "issue": "<description>",
+      "fix": "<suggestion>",
+      "viewports_affected": ["<viewport>"]
+    }
+  ],
+  "prioritized_recommendations": ["<ranked by impact>"]
+}
+```