design-clone 2.1.0 → 2.3.0

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

@@ -0,0 +1,92 @@
+# UX Audit Prompt (Desktop Viewport)
+
+Analyze this website screenshot for UX quality.
+
+Evaluate these categories (score 0-100 each):
+
+1. VISUAL HIERARCHY
+   - Primary content prominence
+   - Clear scanning patterns (F/Z pattern)
+   - Call-to-action visibility
+   - Information grouping and prioritization
+   - White space utilization
+
+2. NAVIGATION
+   - Tappable area size (44x44px minimum for mobile)
+   - Current page indicator clarity
+   - Menu discoverability
+   - Breadcrumb/location awareness
+   - Navigation consistency
+
+3. TYPOGRAPHY
+   - Body text size (16px+ recommended)
+   - Line height (1.4-1.6 ideal)
+   - Contrast ratio (WCAG AA: 4.5:1 for text)
+   - Font hierarchy clarity
+   - Readability at viewport size
+
+4. SPACING
+   - Consistent padding/margins
+   - Element breathing room
+   - Touch target spacing (8px minimum between)
+   - Grid alignment
+   - Section separation
+
+5. INTERACTIVE ELEMENTS
+   - Button affordance (looks clickable)
+   - Link distinguishability
+   - Focus state visibility
+   - Hover state indication
+   - Form field clarity
+
+6. RESPONSIVE
+   - Content reflow appropriateness
+   - No horizontal scroll
+   - Image scaling quality
+   - Text truncation handling
+   - Breakpoint transitions
+
+Return ONLY valid JSON in this exact format:
+```json
+{
+  "viewport": "desktop",
+  "scores": {
+    "visual_hierarchy": 0,
+    "navigation": 0,
+    "typography": 0,
+    "spacing": 0,
+    "interactivity": 0,
+    "responsive": 0
+  },
+  "overall_ux_score": 0,
+  "accessibility_score": 0,
+  "issues": [
+    {
+      "category": "<visual_hierarchy|navigation|typography|spacing|interactivity|responsive>",
+      "severity": "<critical|major|minor>",
+      "issue": "<concise description>",
+      "fix": "<actionable suggestion>"
+    }
+  ],
+  "recommendations": ["<actionable improvement item>"]
+}
+```
+
+SEVERITY GUIDELINES:
+- critical: Blocks user tasks or causes confusion (0-30 score range issues)
+- major: Degrades experience significantly (31-60 score range issues)
+- minor: Polish improvements (61-80 score range issues)
+
+SCORING GUIDELINES:
+- 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
+
+DESKTOP-SPECIFIC CHECKS:
+- Maximum content width (1200-1440px ideal)
+- Multi-column layout efficiency
+- Hover states and micro-interactions
+- Keyboard navigation support
+- Large screen real estate utilization

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

@@ -0,0 +1,93 @@
+# UX Audit Prompt (Mobile Viewport)
+
+Analyze this website screenshot for UX quality.
+
+Evaluate these categories (score 0-100 each):
+
+1. VISUAL HIERARCHY
+   - Primary content prominence
+   - Clear scanning patterns (F/Z pattern)
+   - Call-to-action visibility
+   - Information grouping and prioritization
+   - White space utilization
+
+2. NAVIGATION
+   - Tappable area size (44x44px minimum for mobile)
+   - Current page indicator clarity
+   - Menu discoverability
+   - Breadcrumb/location awareness
+   - Navigation consistency
+
+3. TYPOGRAPHY
+   - Body text size (16px+ recommended)
+   - Line height (1.4-1.6 ideal)
+   - Contrast ratio (WCAG AA: 4.5:1 for text)
+   - Font hierarchy clarity
+   - Readability at viewport size
+
+4. SPACING
+   - Consistent padding/margins
+   - Element breathing room
+   - Touch target spacing (8px minimum between)
+   - Grid alignment
+   - Section separation
+
+5. INTERACTIVE ELEMENTS
+   - Button affordance (looks clickable)
+   - Link distinguishability
+   - Focus state visibility
+   - Hover state indication
+   - Form field clarity
+
+6. RESPONSIVE
+   - Content reflow appropriateness
+   - No horizontal scroll
+   - Image scaling quality
+   - Text truncation handling
+   - Breakpoint transitions
+
+Return ONLY valid JSON in this exact format:
+```json
+{
+  "viewport": "mobile",
+  "scores": {
+    "visual_hierarchy": 0,
+    "navigation": 0,
+    "typography": 0,
+    "spacing": 0,
+    "interactivity": 0,
+    "responsive": 0
+  },
+  "overall_ux_score": 0,
+  "accessibility_score": 0,
+  "issues": [
+    {
+      "category": "<visual_hierarchy|navigation|typography|spacing|interactivity|responsive>",
+      "severity": "<critical|major|minor>",
+      "issue": "<concise description>",
+      "fix": "<actionable suggestion>"
+    }
+  ],
+  "recommendations": ["<actionable improvement item>"]
+}
+```
+
+SEVERITY GUIDELINES:
+- critical: Blocks user tasks or causes confusion (0-30 score range issues)
+- major: Degrades experience significantly (31-60 score range issues)
+- minor: Polish improvements (61-80 score range issues)
+
+SCORING GUIDELINES:
+- 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
+
+MOBILE-SPECIFIC CHECKS:
+- Touch targets minimum 44x44px
+- Thumb zone accessibility
+- Single-column layout efficiency
+- Mobile navigation pattern (hamburger/tab bar)
+- Text readable without zooming
+- Forms optimized for mobile input

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

@@ -0,0 +1,92 @@
+# UX Audit Prompt (Tablet Viewport)
+
+Analyze this website screenshot for UX quality.
+
+Evaluate these categories (score 0-100 each):
+
+1. VISUAL HIERARCHY
+   - Primary content prominence
+   - Clear scanning patterns (F/Z pattern)
+   - Call-to-action visibility
+   - Information grouping and prioritization
+   - White space utilization
+
+2. NAVIGATION
+   - Tappable area size (44x44px minimum for mobile)
+   - Current page indicator clarity
+   - Menu discoverability
+   - Breadcrumb/location awareness
+   - Navigation consistency
+
+3. TYPOGRAPHY
+   - Body text size (16px+ recommended)
+   - Line height (1.4-1.6 ideal)
+   - Contrast ratio (WCAG AA: 4.5:1 for text)
+   - Font hierarchy clarity
+   - Readability at viewport size
+
+4. SPACING
+   - Consistent padding/margins
+   - Element breathing room
+   - Touch target spacing (8px minimum between)
+   - Grid alignment
+   - Section separation
+
+5. INTERACTIVE ELEMENTS
+   - Button affordance (looks clickable)
+   - Link distinguishability
+   - Focus state visibility
+   - Hover state indication
+   - Form field clarity
+
+6. RESPONSIVE
+   - Content reflow appropriateness
+   - No horizontal scroll
+   - Image scaling quality
+   - Text truncation handling
+   - Breakpoint transitions
+
+Return ONLY valid JSON in this exact format:
+```json
+{
+  "viewport": "tablet",
+  "scores": {
+    "visual_hierarchy": 0,
+    "navigation": 0,
+    "typography": 0,
+    "spacing": 0,
+    "interactivity": 0,
+    "responsive": 0
+  },
+  "overall_ux_score": 0,
+  "accessibility_score": 0,
+  "issues": [
+    {
+      "category": "<visual_hierarchy|navigation|typography|spacing|interactivity|responsive>",
+      "severity": "<critical|major|minor>",
+      "issue": "<concise description>",
+      "fix": "<actionable suggestion>"
+    }
+  ],
+  "recommendations": ["<actionable improvement item>"]
+}
+```
+
+SEVERITY GUIDELINES:
+- critical: Blocks user tasks or causes confusion (0-30 score range issues)
+- major: Degrades experience significantly (31-60 score range issues)
+- minor: Polish improvements (61-80 score range issues)
+
+SCORING GUIDELINES:
+- 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
+
+TABLET-SPECIFIC CHECKS:
+- Two-column layout utilization
+- Touch and mouse input support
+- Landscape/portrait adaptability
+- Sidebar vs content balance
+- Split-view readiness

package/src/core/animation/animation-extractor-ast.js

@@ -0,0 +1,183 @@
+/**
+ * AST-based CSS animation extraction helpers.
+ *
+ * Single-pass css-tree AST walker that extracts @keyframes definitions,
+ * transition properties, and animation properties from parsed CSS.
+ * Used by animation-extractor.js (main module).
+ */
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** CSS transition property names (standard + vendor prefixed) */
+export const TRANSITION_PROPERTIES = new Set([
+  'transition',
+  'transition-property',
+  'transition-duration',
+  'transition-timing-function',
+  'transition-delay',
+  '-webkit-transition'
+]);
+
+/** CSS animation property names (standard + vendor prefixed) */
+export const ANIMATION_PROPERTIES = new Set([
+  'animation',
+  'animation-name',
+  'animation-duration',
+  'animation-timing-function',
+  'animation-delay',
+  'animation-iteration-count',
+  'animation-direction',
+  'animation-fill-mode',
+  'animation-play-state',
+  '-webkit-animation',
+  '-webkit-animation-name'
+]);
+
+// ============================================================================
+// Single-Pass AST Extraction (Performance Optimized)
+// ============================================================================
+
+/**
+ * Extract all animation-related data in a single AST walk.
+ * Optimized O(n) traversal instead of O(3n) with separate walks.
+ *
+ * @param {Object} csstree - css-tree module reference
+ * @param {Object} cssAst - css-tree parsed AST
+ * @returns {{keyframes: Object, transitions: Array, animatedElements: Array}}
+ */
+export function extractAllFromAst(csstree, cssAst) {
+  const keyframes = {};
+  const transitions = [];
+  const animatedElements = [];
+
+  if (!csstree) {
+    return { keyframes, transitions, animatedElements };
+  }
+
+  csstree.walk(cssAst, {
+    enter(node) {
+      // Handle @keyframes rules
+      if (node.type === 'Atrule' &&
+          (node.name === 'keyframes' || node.name === '-webkit-keyframes')) {
+        const keyframeData = processKeyframeRule(csstree, node);
+        if (keyframeData) {
+          keyframes[keyframeData.name] = keyframeData.data;
+        }
+        return; // Don't descend into keyframes block
+      }
+
+      // Handle style rules (for transitions and animations)
+      if (node.type === 'Rule' && node.prelude && node.block) {
+        const ruleData = processStyleRule(csstree, node);
+        if (ruleData.transition) {
+          transitions.push(ruleData.transition);
+        }
+        if (ruleData.animation) {
+          animatedElements.push(ruleData.animation);
+        }
+      }
+    }
+  });
+
+  return { keyframes, transitions, animatedElements };
+}
+
+/**
+ * Process a @keyframes at-rule node.
+ *
+ * @param {Object} csstree - css-tree module reference
+ * @param {Object} node - css-tree Atrule node
+ * @returns {{name: string, data: import('./animation-extractor.js').KeyframeData}|null}
+ */
+export function processKeyframeRule(csstree, node) {
+  // Get keyframe name from prelude
+  let name = null;
+
+  if (node.prelude) {
+    if (node.prelude.type === 'AtrulePrelude') {
+      // Walk prelude to find first Identifier
+      csstree.walk(node.prelude, {
+        visit: 'Identifier',
+        enter(idNode) {
+          if (!name) name = idNode.name;
+        }
+      });
+    } else if (node.prelude.type === 'Raw') {
+      name = node.prelude.value?.trim();
+    }
+  }
+
+  if (!name || !node.block) return null;
+
+  // Extract frames from keyframe block
+  const frames = [];
+  csstree.walk(node.block, {
+    visit: 'Rule',
+    enter(frameNode) {
+      const offset = csstree.generate(frameNode.prelude);
+      const properties = {};
+
+      if (frameNode.block) {
+        csstree.walk(frameNode.block, {
+          visit: 'Declaration',
+          enter(declNode) {
+            properties[declNode.property] = csstree.generate(declNode.value);
+          }
+        });
+      }
+
+      if (Object.keys(properties).length > 0) {
+        frames.push({ offset, properties });
+      }
+    }
+  });
+
+  return {
+    name,
+    data: {
+      frames,
+      raw: csstree.generate(node),
+      vendorPrefixed: node.name === '-webkit-keyframes'
+    }
+  };
+}
+
+/**
+ * Process a style rule for transition and animation properties.
+ *
+ * @param {Object} csstree - css-tree module reference
+ * @param {Object} node - css-tree Rule node
+ * @returns {{transition: Object|null, animation: Object|null}}
+ */
+export function processStyleRule(csstree, node) {
+  const selector = csstree.generate(node.prelude);
+  const transitionProps = {};
+  const animationProps = {};
+
+  // Extract declarations in a single walk
+  csstree.walk(node.block, {
+    visit: 'Declaration',
+    enter(declNode) {
+      const prop = declNode.property;
+      const value = csstree.generate(declNode.value);
+
+      if (TRANSITION_PROPERTIES.has(prop)) {
+        transitionProps[prop] = value;
+      }
+      if (ANIMATION_PROPERTIES.has(prop)) {
+        animationProps[prop] = value;
+      }
+    }
+  });
+
+  return {
+    transition: Object.keys(transitionProps).length > 0
+      ? { selector, ...transitionProps }
+      : null,
+    animation: Object.keys(animationProps).length > 0
+      ? { selector, ...animationProps }
+      : null
+  };
+}

package/src/core/animation/animation-extractor-output.js

@@ -0,0 +1,152 @@
+/**
+ * CSS animation output generators.
+ *
+ * Generates animations.css content from extracted keyframes and
+ * produces animation design tokens (durations, timing functions)
+ * for design-tokens.json. Used by animation-extractor.js (main module).
+ */
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Pattern to extract duration values (e.g., "200ms", "1.5s") */
+const DURATION_PATTERN = /(\d+(?:\.\d+)?(?:ms|s))/g;
+
+/** Pattern to extract cubic-bezier timing functions */
+const CUBIC_BEZIER_PATTERN = /cubic-bezier\([^)]+\)/g;
+
+/** Common timing function keywords to detect in shorthand values */
+const TIMING_KEYWORDS = ['ease', 'linear', 'ease-in-out', 'ease-in', 'ease-out'];
+
+// ============================================================================
+// CSS Generation
+// ============================================================================
+
+/**
+ * Generate animations.css from extracted keyframes.
+ *
+ * @param {import('./animation-extractor.js').ExtractionResult} animationData - Result from extractAnimations()
+ * @returns {string} CSS string with @keyframes definitions
+ *
+ * @example
+ * const result = await extractAnimations(css);
+ * const animCss = generateAnimationsCss(result);
+ * fs.writeFileSync('animations.css', animCss);
+ */
+export function generateAnimationsCss(animationData) {
+  const { keyframes } = animationData || {};
+
+  if (!keyframes || Object.keys(keyframes).length === 0) {
+    return '/* No @keyframes found */\n';
+  }
+
+  const lines = [
+    '/**',
+    ' * Extracted CSS Animations',
+    ' * Generated by design-clone animation-extractor',
+    ' */\n'
+  ];
+
+  for (const [name, data] of Object.entries(keyframes)) {
+    const frameCount = data.frames?.length || 0;
+    lines.push(`/* Keyframes: ${name} (${frameCount} frames) */`);
+    lines.push(data.raw);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ============================================================================
+// Token Generation
+// ============================================================================
+
+/**
+ * Extract timing values from shorthand transition/animation strings.
+ *
+ * Limitations:
+ * - Only extracts first duration from shorthand (CSS allows multiple)
+ * - Timing function detection is keyword-based, may miss complex values
+ * - Does not resolve CSS variables (e.g., var(--duration))
+ *
+ * @param {string} shorthand - Shorthand property value
+ * @param {Set<string>} durations - Set to add durations to
+ * @param {Set<string>} timings - Set to add timing functions to
+ */
+export function extractTimingFromShorthand(shorthand, durations, timings) {
+  if (!shorthand) return;
+
+  // Extract all duration values
+  const durationMatches = shorthand.match(DURATION_PATTERN);
+  if (durationMatches) {
+    durationMatches.forEach(d => durations.add(d));
+  }
+
+  // Extract cubic-bezier functions
+  const bezierMatches = shorthand.match(CUBIC_BEZIER_PATTERN);
+  if (bezierMatches) {
+    bezierMatches.forEach(b => timings.add(b));
+  }
+
+  // Check for timing keywords
+  const lowerShorthand = shorthand.toLowerCase();
+  for (const keyword of TIMING_KEYWORDS) {
+    if (lowerShorthand.includes(keyword)) {
+      timings.add(keyword);
+    }
+  }
+}
+
+/**
+ * Generate animation tokens for design-tokens.json.
+ *
+ * @param {import('./animation-extractor.js').ExtractionResult} animationData - Result from extractAnimations()
+ * @returns {import('./animation-extractor.js').AnimationTokens} Animation tokens structure
+ *
+ * @example
+ * const result = await extractAnimations(css);
+ * const tokens = generateAnimationTokens(result);
+ * console.log(tokens.durations); // ['200ms', '300ms', '1s']
+ */
+export function generateAnimationTokens(animationData) {
+  const { keyframes = {}, transitions = [], animatedElements = [] } = animationData || {};
+
+  const durations = new Set();
+  const timings = new Set();
+
+  // Extract from transitions
+  for (const t of transitions) {
+    if (t['transition-duration']) {
+      t['transition-duration'].split(',').forEach(d => durations.add(d.trim()));
+    }
+    if (t['transition-timing-function']) {
+      t['transition-timing-function'].split(',').forEach(tf => timings.add(tf.trim()));
+    }
+    if (t.transition) {
+      extractTimingFromShorthand(t.transition, durations, timings);
+    }
+  }
+
+  // Extract from animated elements
+  for (const a of animatedElements) {
+    if (a['animation-duration']) {
+      a['animation-duration'].split(',').forEach(d => durations.add(d.trim()));
+    }
+    if (a['animation-timing-function']) {
+      a['animation-timing-function'].split(',').forEach(tf => timings.add(tf.trim()));
+    }
+    if (a.animation) {
+      extractTimingFromShorthand(a.animation, durations, timings);
+    }
+  }
+
+  return {
+    keyframes: Object.keys(keyframes),
+    keyframeCount: Object.keys(keyframes).length,
+    transitions: transitions.length,
+    animatedElements: animatedElements.length,
+    durations: [...durations].sort(),
+    timingFunctions: [...timings].sort()
+  };
+}