design-clone 1.1.1 → 2.1.0

package/src/ai/prompts/structure_analysis.py

@@ -220,16 +220,335 @@ For each section describe:
 [Suggest semantic class names for main components]"""
 
 
-def build_structure_prompt(html_content: str = None, css_content: str = None, dimensions: dict = None) -> str:
+# Enhanced prompt when DOM hierarchy is available (highest accuracy)
+STRUCTURE_PROMPT_WITH_HIERARCHY = """Analyze this website screenshot using the EXACT extracted dimensions and DOM hierarchy below.
+
+## CRITICAL INSTRUCTIONS
+1. USE ONLY the exact values provided - DO NOT estimate
+2. All measurements are from actual DOM via getBoundingClientRect + getComputedStyle
+3. Typography varies BY SECTION - use section-specific values
+4. Reference DOM hierarchy for nesting structure
+
+## EXTRACTED DOM HIERARCHY
+
+### Landmarks Found
+- Header: {header_found}
+- Main content: {main_found}
+- Footer: {footer_found}
+- Sidebars: {sidebar_count}
+- Nav elements: {nav_count}
+
+### Heading Hierarchy (by section)
+{heading_hierarchy}
+
+### Section Structure
+{section_structure}
+
+## EXACT DIMENSIONS
+
+### Container Layout
+- Max container width: {container_max_width}
+- Section padding: {section_padding}
+- Element gap: {gap}
+
+### Cards
+- Card width: {card_width}
+- Card height: {card_height}
+- Card padding: {card_padding}
+
+### Typography BY SECTION (use these exact values per context)
+
+#### Hero Section
+- H1: {hero_h1}
+- H2: {hero_h2}
+- Body: {hero_body}
+
+#### Content Section
+- H2: {content_h2}
+- H3: {content_h3}
+- Body: {content_body}
+
+#### Footer Section
+- Body: {footer_body}
+
+### Responsive Breakpoints
+- Desktop: {desktop_breakpoint}
+- Tablet: {tablet_breakpoint}
+- Mobile: {mobile_breakpoint}
+
+### Typography Scaling
+- H1: {hero_h1} → {h1_tablet} (tablet) → {h1_mobile} (mobile)
+- H2: {content_h2} → {h2_tablet} (tablet) → {h2_mobile} (mobile)
+
+---
+
+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 {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: {card_width} x {card_height} with gap {gap}
+- Components: [describe]
+
+## 4. Footer Section
+- Layout: [from hierarchy]
+- Typography: {footer_body} body text
+
+## 5. EXACT CSS Values (DO NOT MODIFY)
+### Layout
+- Container max-width: {container_max_width}
+- Section padding: {section_padding}
+- Card dimensions: {card_width} x {card_height}
+- Card padding: {card_padding}
+- Gap: {gap}
+
+### Typography per Section
+- Hero H1: {hero_h1}
+- Hero H2: {hero_h2}
+- Content H2: {content_h2}
+- Content H3: {content_h3}
+- Content Body: {content_body}
+- Footer Body: {footer_body}
+
+### Breakpoints
+- Desktop: {desktop_breakpoint}
+- Tablet: {tablet_breakpoint}
+- Mobile: {mobile_breakpoint}
+
+## 6. Responsive Behavior
+- At {tablet_breakpoint}: [describe layout changes]
+- At {mobile_breakpoint}: [describe layout changes]
+- Typography scales: H1 {hero_h1} → {h1_tablet} → {h1_mobile}
+
+## 7. DOM Nesting Structure
+Reproduce this exact nesting in generated HTML:
+{dom_nesting}
+
+## 8. BEM Class Suggestions
+[Based on hierarchy, suggest semantic names]"""
+
+
+def format_heading_hierarchy(heading_tree: list) -> str:
+    """Format heading tree for prompt.
+
+    Args:
+        heading_tree: List of heading objects with level, section, text
+
+    Returns:
+        Formatted string showing heading hierarchy
+    """
+    if not heading_tree:
+        return "No headings detected"
+
+    lines = []
+    for h in heading_tree[:10]:  # Limit for token efficiency
+        indent = '  ' * (h.get('level', 1) - 1)
+        section = h.get('section', 'content')
+        text = h.get('text', '')[:30] if h.get('text') else ''
+        lines.append(f"{indent}- H{h.get('level', 1)} ({section}): \"{text}...\"")
+
+    return '\n'.join(lines)
+
+
+def format_section_structure(landmarks: dict, sections: dict) -> str:
+    """Format section structure for prompt.
+
+    Args:
+        landmarks: W3C landmarks from DOM hierarchy
+        sections: Section info from dimensions
+
+    Returns:
+        Formatted string showing section structure
+    """
+    lines = []
+
+    if landmarks.get('header'):
+        lines.append("- Header: Present (semantic <header>)")
+    if sections.get('hero', {}).get('found'):
+        width = sections['hero'].get('containerWidth', 'unknown')
+        lines.append(f"- Hero: Present (container width: {width}px)")
+    if landmarks.get('main'):
+        lines.append("- Main: Present (semantic <main>)")
+    if sections.get('content', {}).get('found'):
+        width = sections['content'].get('containerWidth', 'unknown')
+        lines.append(f"- Content: Present (container width: {width}px)")
+    if landmarks.get('aside'):
+        lines.append(f"- Sidebars: {len(landmarks['aside'])} detected")
+    if landmarks.get('footer'):
+        lines.append("- Footer: Present (semantic <footer>)")
+
+    return '\n'.join(lines) if lines else "No sections detected"
+
+
+def format_dom_nesting(root: dict, max_depth: int = 4) -> str:
+    """Format simplified DOM nesting for prompt.
+
+    Args:
+        root: Root node from DOM hierarchy
+        max_depth: Maximum depth to traverse
+
+    Returns:
+        Formatted string showing DOM nesting structure
+    """
+    if not root:
+        return "No DOM structure available"
+
+    lines = []
+
+    def walk(node, depth):
+        if depth > max_depth or not node:
+            return
+        if not node.get('role'):
+            # Skip non-semantic nodes in output
+            for child in node.get('children', [])[:5]:
+                walk(child, depth)
+            return
+
+        indent = '  ' * depth
+        tag = node.get('tagName', 'div')
+        role = node.get('role', '')
+        lines.append(f"{indent}<{tag}> <!-- {role} -->")
+
+        for child in node.get('children', [])[:5]:  # Limit children
+            walk(child, depth + 1)
+
+    walk(root, 0)
+    return '\n'.join(lines[:30])  # Limit total lines
+
+
+def build_hierarchy_prompt(dimensions: dict, hierarchy: dict) -> str:
+    """Build prompt with DOM hierarchy context.
+
+    Args:
+        dimensions: Extracted dimensions summary
+        hierarchy: DOM hierarchy data
+
+    Returns:
+        Formatted prompt string with hierarchy context
+    """
+    exact = dimensions.get('EXACT_DIMENSIONS', {})
+    typo = dimensions.get('EXACT_TYPOGRAPHY', {})
+    typo_by_section = dimensions.get('TYPOGRAPHY_BY_SECTION', {})
+    resp = dimensions.get('RESPONSIVE', {})
+    sections = dimensions.get('SECTIONS', {})
+    card = exact.get('card_dimensions', {})
+    scaling = resp.get('typography_scaling', {})
+
+    # Extract hierarchy data
+    landmarks = hierarchy.get('landmarks', {})
+    heading_tree = hierarchy.get('headingTree', [])
+
+    # Format heading hierarchy
+    heading_hierarchy = format_heading_hierarchy(heading_tree)
+
+    # Format section structure
+    section_structure = format_section_structure(landmarks, sections)
+
+    # Format DOM nesting (simplified)
+    dom_nesting = format_dom_nesting(hierarchy.get('root'))
+
+    # Get section-specific typography
+    hero_typo = typo_by_section.get('hero', {})
+    content_typo = typo_by_section.get('content', {})
+    footer_typo = typo_by_section.get('footer', {})
+
+    return STRUCTURE_PROMPT_WITH_HIERARCHY.format(
+        # Landmarks
+        header_found='Yes' if landmarks.get('header') else 'No',
+        main_found='Yes' if landmarks.get('main') else 'No',
+        footer_found='Yes' if landmarks.get('footer') else 'No',
+        sidebar_count=len(landmarks.get('aside', [])),
+        nav_count=len(landmarks.get('nav', [])),
+
+        # Heading hierarchy
+        heading_hierarchy=heading_hierarchy,
+        section_structure=section_structure,
+
+        # Dimensions
+        container_max_width=exact.get('container_max_width', '1200px'),
+        section_padding=exact.get('section_padding', '64px 0'),
+        gap=exact.get('gap', '24px'),
+        card_width=card.get('width', '380px') if isinstance(card, dict) else '380px',
+        card_height=card.get('height', 'auto') if isinstance(card, dict) else 'auto',
+        card_padding=card.get('padding', '24px') if isinstance(card, dict) else '24px',
+
+        # Typography by section
+        hero_h1=hero_typo.get('h1', typo.get('h1', '64px')),
+        hero_h2=hero_typo.get('h2', typo.get('h2', '48px')),
+        hero_body=hero_typo.get('p', typo.get('body', '18px')),
+        content_h2=content_typo.get('h2', typo.get('h2', '32px')),
+        content_h3=content_typo.get('h3', typo.get('h3', '24px')),
+        content_body=content_typo.get('p', typo.get('body', '16px')),
+        footer_body=footer_typo.get('p', '14px'),
+
+        # Breakpoints
+        desktop_breakpoint=resp.get('desktop_breakpoint', '1440px'),
+        tablet_breakpoint=resp.get('tablet_breakpoint', '768px'),
+        mobile_breakpoint=resp.get('mobile_breakpoint', '375px'),
+
+        # Typography scaling
+        h1_tablet=scaling.get('h1', {}).get('tablet', '36px') if isinstance(scaling.get('h1'), dict) else '36px',
+        h1_mobile=scaling.get('h1', {}).get('mobile', '28px') if isinstance(scaling.get('h1'), dict) else '28px',
+        h2_tablet=scaling.get('h2', {}).get('tablet', '28px') if isinstance(scaling.get('h2'), dict) else '28px',
+        h2_mobile=scaling.get('h2', {}).get('mobile', '24px') if isinstance(scaling.get('h2'), dict) else '24px',
+
+        # DOM nesting
+        dom_nesting=dom_nesting
+    )
+
+
+def build_structure_prompt(
+    html_content: str = None,
+    css_content: str = None,
+    dimensions: dict = None,
+    content_summary: str = None,
+    hierarchy: dict = None
+) -> str:
     """Build the appropriate prompt based on available context.
 
     Priority:
-    1. With dimensions (most accurate - uses exact extracted values)
-    2. With HTML/CSS (accurate - extracts from source)
-    3. Screenshot only (least accurate - estimates)
+    1. With hierarchy + dimensions (most accurate - full DOM context)
+    2. With dimensions (accurate - uses exact extracted values)
+    3. With HTML/CSS (accurate - extracts from source)
+    4. Screenshot only (least accurate - estimates)
+
+    Args:
+        html_content: Source HTML (optional)
+        css_content: Source CSS (optional)
+        dimensions: Extracted dimensions summary (optional)
+        content_summary: Content counts markdown (optional)
+        hierarchy: DOM hierarchy data (optional)
+
+    Returns:
+        Appropriate prompt string based on available context
     """
 
-    # Priority 1: Use dimensions if available (highest accuracy)
+    # Helper to append content summary
+    def append_content_counts(prompt: str) -> str:
+        if content_summary:
+            return prompt + "\n\n---\n\n" + content_summary + "\n\nIMPORTANT: Use the EXACT item counts above when describing sections. Do NOT estimate."
+        return prompt
+
+    # Priority 1: Use hierarchy + dimensions if available (highest accuracy)
+    if hierarchy and dimensions:
+        return append_content_counts(build_hierarchy_prompt(dimensions, hierarchy))
+
+    # Priority 2: Use dimensions if available
     if dimensions:
         exact = dimensions.get('EXACT_DIMENSIONS', {})
         typo = dimensions.get('EXACT_TYPOGRAPHY', {})
@@ -237,7 +556,7 @@ def build_structure_prompt(html_content: str = None, css_content: str = None, di
         card = exact.get('card_dimensions', {})
         scaling = resp.get('typography_scaling', {})
 
-        return STRUCTURE_PROMPT_WITH_DIMENSIONS.format(
+        return append_content_counts(STRUCTURE_PROMPT_WITH_DIMENSIONS.format(
             container_max_width=exact.get('container_max_width', '1200px'),
             section_padding=exact.get('section_padding', '64px 0'),
             gap=exact.get('gap', '24px'),
@@ -255,7 +574,7 @@ def build_structure_prompt(html_content: str = None, css_content: str = None, di
             h1_mobile=scaling.get('h1', {}).get('mobile', '28px') if isinstance(scaling.get('h1'), dict) else '28px',
             h2_tablet=scaling.get('h2', {}).get('tablet', '28px') if isinstance(scaling.get('h2'), dict) else '28px',
             h2_mobile=scaling.get('h2', {}).get('mobile', '24px') if isinstance(scaling.get('h2'), dict) else '24px'
-        )
+        ))
 
     # Priority 2: Use HTML/CSS if available
     if html_content and css_content:
@@ -264,10 +583,10 @@ def build_structure_prompt(html_content: str = None, css_content: str = None, di
         html_snippet = html_content[:100000] if len(html_content) > 100000 else html_content
         css_snippet = css_content[:100000] if len(css_content) > 100000 else css_content
 
-        return STRUCTURE_PROMPT_WITH_CONTEXT.format(
+        return append_content_counts(STRUCTURE_PROMPT_WITH_CONTEXT.format(
             html_snippet=html_snippet,
             css_snippet=css_snippet
-        )
+        ))
 
     # Priority 3: Screenshot only (fallback)
-    return STRUCTURE_PROMPT
+    return append_content_counts(STRUCTURE_PROMPT)

package/src/ai/prompts/ux_audit.py

@@ -0,0 +1,198 @@
+"""
+UX Audit Prompts
+
+Prompts for analyzing screenshots with Gemini Vision for UX quality assessment.
+Evaluates visual hierarchy, navigation, typography, spacing, interactivity, and responsive design.
+"""
+
+# Main UX audit prompt
+UX_AUDIT_PROMPT = """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:
+{
+  "viewport": "<mobile|tablet|desktop>",
+  "scores": {
+    "visual_hierarchy": <0-100>,
+    "navigation": <0-100>,
+    "typography": <0-100>,
+    "spacing": <0-100>,
+    "interactivity": <0-100>,
+    "responsive": <0-100>
+  },
+  "overall_ux_score": <0-100>,
+  "accessibility_score": <0-100>,
+  "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"""
+
+
+# Viewport-specific prompt suffix
+VIEWPORT_CONTEXT = {
+    'mobile': """
+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""",
+
+    'tablet': """
+TABLET-SPECIFIC CHECKS:
+- Two-column layout utilization
+- Touch and mouse input support
+- Landscape/portrait adaptability
+- Sidebar vs content balance
+- Split-view readiness""",
+
+    'desktop': """
+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"""
+}
+
+
+def build_ux_audit_prompt(viewport: str = 'desktop') -> str:
+    """Build viewport-specific UX audit prompt.
+
+    Args:
+        viewport: 'mobile', 'tablet', or 'desktop'
+
+    Returns:
+        Complete prompt string with viewport-specific checks
+    """
+    base_prompt = UX_AUDIT_PROMPT
+
+    viewport_lower = viewport.lower()
+    if viewport_lower in VIEWPORT_CONTEXT:
+        base_prompt += f"\n\n{VIEWPORT_CONTEXT[viewport_lower]}"
+
+    return base_prompt
+
+
+# Aggregation prompt for combining viewport results
+AGGREGATION_PROMPT = """Combine these viewport-specific UX audit results into a final assessment.
+
+Desktop results: {desktop_results}
+Tablet results: {tablet_results}
+Mobile results: {mobile_results}
+
+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 JSON:
+{
+  "overall_scores": {
+    "visual_hierarchy": <weighted_avg>,
+    "navigation": <weighted_avg>,
+    "typography": <weighted_avg>,
+    "spacing": <weighted_avg>,
+    "interactivity": <weighted_avg>,
+    "responsive": <weighted_avg>
+  },
+  "overall_ux_score": <weighted_avg>,
+  "accessibility_score": <weighted_avg>,
+  "viewport_breakdown": {
+    "desktop": <ux_score>,
+    "tablet": <ux_score>,
+    "mobile": <ux_score>
+  },
+  "top_issues": [
+    {
+      "category": "<category>",
+      "severity": "<severity>",
+      "issue": "<description>",
+      "fix": "<suggestion>",
+      "viewports_affected": ["<viewport>"]
+    }
+  ],
+  "prioritized_recommendations": ["<ranked by impact>"]
+}"""
+
+
+def build_aggregation_prompt(desktop: dict, tablet: dict, mobile: dict) -> str:
+    """Build prompt for aggregating viewport results.
+
+    Args:
+        desktop: Desktop viewport audit results
+        tablet: Tablet viewport audit results
+        mobile: Mobile viewport audit results
+
+    Returns:
+        Aggregation prompt with results embedded
+    """
+    import json
+    return AGGREGATION_PROMPT.format(
+        desktop_results=json.dumps(desktop, indent=2) if desktop else "Not available",
+        tablet_results=json.dumps(tablet, indent=2) if tablet else "Not available",
+        mobile_results=json.dumps(mobile, indent=2) if mobile else "Not available"
+    )