@maestro-ai/mcp-server 1.0.0 → 1.1.0

package/dist/content/content/skills/frontend-design/scripts/ux_audit.py

@@ -1,722 +0,0 @@
-#!/usr/bin/env python3
-"""
-UX Audit Script - Full Frontend Design Coverage
-
-Analyzes code for compliance with:
-
-1. CORE PSYCHOLOGY LAWS:
-   - Hick's Law (nav items, form complexity)
-   - Fitts' Law (target sizes, touch targets)
-   - Miller's Law (chunking, memory limits)
-   - Von Restorff Effect (primary CTA visibility)
-   - Serial Position Effect (important items at start/end)
-
-2. EMOTIONAL DESIGN (Don Norman):
-   - Visceral (first impressions, gradients, animations)
-   - Behavioral (feedback, usability, performance)
-   - Reflective (brand story, values, identity)
-
-3. TRUST BUILDING:
-   - Security signals (SSL, encryption on forms)
-   - Social proof (testimonials, reviews, logos)
-   - Authority indicators (certifications, awards, media)
-
-4. COGNITIVE LOAD MANAGEMENT:
-   - Progressive disclosure (accordion, tabs, "Advanced")
-   - Visual noise (too many colors/borders)
-   - Familiar patterns (labels, standard conventions)
-
-5. PERSUASIVE DESIGN (Ethical):
-   - Smart defaults (pre-selected options)
-   - Anchoring (original vs discount price)
-   - Social proof (live indicators, numbers)
-   - Progress indicators (progress bars, steps)
-
-6. TYPOGRAPHY SYSTEM (9 sections):
-   - Font Pairing (max 3 families)
-   - Line Length (45-75ch)
-   - Line Height (proper ratios)
-   - Letter Spacing (uppercase, display text)
-   - Weight and Emphasis (contrast levels)
-   - Responsive Typography (clamp())
-   - Hierarchy (sequential headings)
-   - Modular Scale (consistent ratios)
-   - Readability (chunking, subheadings)
-
-7. VISUAL EFFECTS (10 sections):
-   - Glassmorphism (blur + transparency)
-   - Neomorphism (dual shadows, inset)
-   - Shadow Hierarchy (elevation levels)
-   - Gradients (usage, overuse)
-   - Border Effects (complexity check)
-   - Glow Effects (text-shadow, box-shadow)
-   - Overlay Techniques (image text readability)
-   - GPU Acceleration (transform/opacity vs layout)
-   - Performance (will-change usage)
-   - Effect Selection (purpose over decoration)
-
-8. COLOR SYSTEM (7 sections):
-   - PURPLE BAN (Critical Maestro rule - #8B5CF6, #A855F7, etc.)
-   - 60-30-10 Rule (dominant, secondary, accent)
-   - Color Scheme Patterns (monochromatic, analogous)
-   - Dark Mode Compliance (no pure black/white)
-   - WCAG Contrast (low-contrast detection)
-   - Color Psychology Context (food + blue = bad)
-   - HSL-Based Palettes (recommended approach)
-
-9. ANIMATION GUIDE (6 sections):
-   - Duration Appropriateness (50ms minimum, 1s max transitions)
-   - Easing Functions (ease-out for entry, ease-in for exit)
-   - Micro-interactions (hover/focus feedback)
-   - Loading States (skeleton, spinner, progress)
-   - Page Transitions (fade/slide for routing)
-   - Scroll Animation Performance (no layout properties)
-
-10. MOTION GRAPHICS (7 sections):
-   - Lottie Animations (reduced motion fallbacks)
-   - GSAP Memory Leaks (kill/revert on unmount)
-   - SVG Animation Performance (stroke-dashoffset sparingly)
-   - 3D Transforms (perspective parent, mobile warning)
-   - Particle Effects (mobile fallback)
-   - Scroll-Driven Animations (throttle with rAF)
-   - Motion Decision Tree (functional vs decorative)
-
-11. ACCESSIBILITY:
-   - Alt text for images
-   - Reduced motion checks
-   - Form labels
-
-Total: 80+ checks across all design principles
-"""
-
-import sys
-import os
-import re
-import json
-from pathlib import Path
-
-class UXAuditor:
-    def __init__(self):
-        self.issues = []
-        self.warnings = []
-        self.passed_count = 0
-        self.files_checked = 0
-    
-    def audit_file(self, filepath: str) -> None:
-        try:
-            with open(filepath, 'r', encoding='utf-8', errors='replace') as f:
-                content = f.read()
-        except: return
-        
-        self.files_checked += 1
-        filename = os.path.basename(filepath)
-
-        # Pre-calculate common flags
-        has_long_text = bool(re.search(r'<p|<div.*class=.*text|article|<span.*text', content, re.IGNORECASE))
-        has_form = bool(re.search(r'<form|<input|password|credit|card|payment', content, re.IGNORECASE))
-        complex_elements = len(re.findall(r'<input|<select|<textarea|<option', content, re.IGNORECASE))
-
-        # --- 1. PSYCHOLOGY LAWS ---
-        # Hick's Law
-        nav_items = len(re.findall(r'<NavLink|<Link|<a\s+href|nav-item', content, re.IGNORECASE))
-        if nav_items > 7:
-            self.issues.append(f"[Hick's Law] {filename}: {nav_items} nav items (Max 7)")
-        
-        # Fitts' Law
-        if re.search(r'height:\s*([0-3]\d)px', content) or re.search(r'h-[1-9]\b|h-10\b', content):
-            self.warnings.append(f"[Fitts' Law] {filename}: Small targets (< 44px)")
-        
-        # Miller's Law
-        form_fields = len(re.findall(r'<input|<select|<textarea', content, re.IGNORECASE))
-        if form_fields > 7 and not re.search(r'step|wizard|stage', content, re.IGNORECASE):
-            self.warnings.append(f"[Miller's Law] {filename}: Complex form ({form_fields} fields)")
-            
-        # Von Restorff
-        if 'button' in content.lower() and not re.search(r'primary|bg-primary|Button.*primary|variant=["\']primary', content, re.IGNORECASE):
-            self.warnings.append(f"[Von Restorff] {filename}: No primary CTA")
-
-        # Serial Position Effect - Important items at beginning/end
-        if nav_items > 3:
-            # Check if last nav item is important (contact, login, etc.)
-            nav_content = re.findall(r'<NavLink|<Link|<a\s+href[^>]*>([^<]+)</a>', content, re.IGNORECASE)
-            if nav_content and len(nav_content) > 2:
-                last_item = nav_content[-1].lower() if nav_content else ''
-                if not any(x in last_item for x in ['contact', 'login', 'sign', 'get started', 'cta', 'button']):
-                    self.warnings.append(f"[Serial Position] {filename}: Last nav item may not be important. Place key actions at start/end.")
-
-        # --- 1.5 EMOTIONAL DESIGN (Don Norman) ---
-
-        # Visceral: First impressions (aesthetics, gradients, animations)
-        has_hero = bool(re.search(r'hero|<h1|banner', content, re.IGNORECASE))
-        if has_hero:
-            # Check for visual appeal elements
-            has_gradient = bool(re.search(r'gradient|linear-gradient|radial-gradient', content))
-            has_animation = bool(re.search(r'@keyframes|transition:|animate-', content))
-            has_visual_interest = has_gradient or has_animation
-
-            if not has_visual_interest and not re.search(r'background:|bg-', content):
-                self.warnings.append(f"[Visceral] {filename}: Hero section lacks visual appeal. Consider gradients or subtle animations.")
-
-        # Behavioral: Instant feedback and usability
-        if 'onClick' in content or '@click' in content or 'onclick' in content:
-            has_feedback = re.search(r'transition|animate|hover:|focus:|disabled|loading|spinner', content, re.IGNORECASE)
-            has_state_change = re.search(r'setState|useState|disabled|loading', content)
-
-            if not has_feedback and not has_state_change:
-                self.warnings.append(f"[Behavioral] {filename}: Interactive elements lack immediate feedback. Add hover/focus/disabled states.")
-
-        # Reflective: Brand story, values, identity
-        has_reflective = bool(re.search(r'about|story|mission|values|why we|our journey|testimonials', content, re.IGNORECASE))
-        if has_long_text and not has_reflective:
-            self.warnings.append(f"[Reflective] {filename}: Long-form content without brand story/values. Add 'About' or 'Why We Exist' section.")
-
-        # --- 1.6 TRUST BUILDING (Enhanced) ---
-
-        # Security signals
-        if has_form:
-            security_signals = re.findall(r'ssl|secure|encrypt|lock|padlock|https', content, re.IGNORECASE)
-            if len(security_signals) == 0 and not re.search(r'checkout|payment', content, re.IGNORECASE):
-                self.warnings.append(f"[Trust] {filename}: Form without security indicators. Add 'SSL Secure' or lock icon.")
-
-        # Social proof elements
-        social_proof = re.findall(r'review|testimonial|rating|star|trust|trusted by|customer|logo', content, re.IGNORECASE)
-        if len(social_proof) > 0:
-            self.passed_count += 1
-        else:
-            if has_long_text:
-                self.warnings.append(f"[Trust] {filename}: No social proof detected. Consider adding testimonials, ratings, or 'Trusted by' logos.")
-
-        # Authority indicators
-        has_footer = bool(re.search(r'footer|<footer', content, re.IGNORECASE))
-        if has_footer:
-            authority = re.findall(r'certif|award|media|press|featured|as seen in', content, re.IGNORECASE)
-            if len(authority) == 0:
-                self.warnings.append(f"[Trust] {filename}: Footer lacks authority signals. Add certifications, awards, or media mentions.")
-
-        # --- 1.7 COGNITIVE LOAD MANAGEMENT ---
-
-        # Progressive disclosure
-        if complex_elements > 5:
-            has_progressive = re.search(r'step|wizard|stage|accordion|collapsible|tab|more\.\.\.|advanced|show more', content, re.IGNORECASE)
-            if not has_progressive:
-                self.warnings.append(f"[Cognitive Load] {filename}: Many form elements without progressive disclosure. Consider accordion, tabs, or 'Advanced' toggle.")
-
-        # Visual noise check
-        has_many_colors = len(re.findall(r'#[0-9a-fA-F]{3,6}|rgb|hsl', content)) > 15
-        has_many_borders = len(re.findall(r'border:|border-', content)) > 10
-        if has_many_colors and has_many_borders:
-            self.warnings.append(f"[Cognitive Load] {filename}: High visual noise detected. Many colors and borders increase cognitive load.")
-
-        # Familiar patterns
-        if has_form:
-            has_standard_labels = bool(re.search(r'<label|placeholder|aria-label', content, re.IGNORECASE))
-            if not has_standard_labels:
-                self.issues.append(f"[Cognitive Load] {filename}: Form inputs without labels. Use <label> for accessibility and clarity.")
-
-        # --- 1.8 PERSUASIVE DESIGN (Ethical) ---
-
-        # Smart defaults
-        if has_form:
-            has_defaults = bool(re.search(r'checked|selected|default|value=["\'].*["\']', content))
-            radio_inputs = len(re.findall(r'type=["\']radio', content, re.IGNORECASE))
-            if radio_inputs > 0 and not has_defaults:
-                self.warnings.append(f"[Persuasion] {filename}: Radio buttons without default selection. Pre-select recommended option.")
-
-        # Anchoring (showing original price)
-        if re.search(r'price|pricing|cost|\$\d+', content, re.IGNORECASE):
-            has_anchor = bool(re.search(r'original|was|strike|del|save \d+%', content, re.IGNORECASE))
-            if not has_anchor:
-                self.warnings.append(f"[Persuasion] {filename}: Prices without anchoring. Show original price to frame discount value.")
-
-        # Social proof live indicators
-        has_social = bool(re.search(r'join|subscriber|member|user', content, re.IGNORECASE))
-        if has_social:
-            has_count = bool(re.findall(r'\d+[+kmb]|\d+,\d+', content))
-            if not has_count:
-                self.warnings.append(f"[Persuasion] {filename}: Social proof without specific numbers. Use 'Join 10,000+' format.")
-
-        # Progress indicators
-        if has_form:
-            has_progress = bool(re.search(r'progress|step \d+|complete|%|bar', content, re.IGNORECASE))
-            if complex_elements > 5 and not has_progress:
-                self.warnings.append(f"[Persuasion] {filename}: Long form without progress indicator. Add progress bar or 'Step X of Y'.")
-
-        # --- 2. TYPOGRAPHY SYSTEM (Complete Coverage) ---
-
-        # 2.1 Font Pairing - Too many font families
-        font_families = set()
-        # Check for @font-face, Google Fonts, font-family declarations
-        font_faces = re.findall(r'@font-face\s*\{[^}]*family:\s*["\']?([^;"\'\s}]+)', content, re.IGNORECASE)
-        google_fonts = re.findall(r'fonts\.googleapis\.com[^"\']*family=([^"&]+)', content, re.IGNORECASE)
-        font_family_css = re.findall(r'font-family:\s*([^;]+)', content, re.IGNORECASE)
-
-        for font in font_faces: font_families.add(font.strip().lower())
-        for font in google_fonts:
-            for f in font.replace('+', ' ').split('|'):
-                font_families.add(f.split(':')[0].strip().lower())
-        for family in font_family_css:
-            # Extract first font from stack
-            first_font = family.split(',')[0].strip().strip('"\'')
-
-            if first_font.lower() not in {'sans-serif', 'serif', 'monospace', 'cursive', 'fantasy', 'system-ui', 'inherit', 'arial', 'georgia', 'times new roman', 'courier new', 'verdana', 'helvetica', 'tahoma'}:
-                font_families.add(first_font.lower())
-
-        if len(font_families) > 3:
-            self.issues.append(f"[Typography] {filename}: {len(font_families)} font families detected. Limit to 2-3 for cohesion.")
-
-        # 2.2 Line Length - Character-based width
-        if has_long_text and not re.search(r'max-w-(?:prose|[\[\\]?\d+ch[\]\\]?)|max-width:\s*\d+ch', content):
-            self.warnings.append(f"[Typography] {filename}: No line length constraint (45-75ch). Use max-w-prose or max-w-[65ch].")
-
-        # 2.3 Line Height - Proper leading ratios
-        # Check for text without proper line-height
-        text_elements = len(re.findall(r'<p|<span|<div.*text|<h[1-6]', content, re.IGNORECASE))
-        if text_elements > 0 and not re.search(r'leading-|line-height:', content):
-            self.warnings.append(f"[Typography] {filename}: Text elements found without line-height. Body: 1.4-1.6, Headings: 1.1-1.3")
-
-        # Check for heading-specific line height issues
-        if re.search(r'<h[1-6]|text-(?:xl|2xl|3xl|4xl|5xl|6xl)', content, re.IGNORECASE):
-            # Extract line-height values
-            line_heights = re.findall(r'(?:leading-|line-height:\s*)([\d.]+)', content)
-            for lh in line_heights:
-                if float(lh) > 1.5:
-                    self.warnings.append(f"[Typography] {filename}: Heading has line-height {lh} (>1.3). Headings should be tighter (1.1-1.3).")
-
-        # 2.4 Letter Spacing (Tracking)
-        # Uppercase without tracking
-        if re.search(r'uppercase|text-transform:\s*uppercase', content, re.IGNORECASE):
-            if not re.search(r'tracking-|letter-spacing:', content):
-                self.warnings.append(f"[Typography] {filename}: Uppercase text without tracking. ALL CAPS needs +5-10% spacing.")
-
-        # Large text (display/hero) should have negative tracking
-        if re.search(r'text-(?:4xl|5xl|6xl|7xl|8xl|9xl)|font-size:\s*[3-9]\dpx', content):
-            if not re.search(r'tracking-tight|letter-spacing:\s*-[0-9]', content):
-                self.warnings.append(f"[Typography] {filename}: Large display text without tracking-tight. Big text needs -1% to -4% spacing.")
-
-        # 2.5 Weight and Emphasis - Contrast levels
-        # Check for adjacent weight levels (poor contrast)
-        weights = re.findall(r'font-weight:\s*(\d+)|font-(?:thin|extralight|light|normal|medium|semibold|bold|extrabold|black)|fw-(\d+)', content, re.IGNORECASE)
-        weight_values = []
-        for w in weights:
-            val = w[0] or w[1]
-            if val:
-                # Map named weights to numbers
-                weight_map = {'thin': '100', 'extralight': '200', 'light': '300', 'normal': '400', 'medium': '500', 'semibold': '600', 'bold': '700', 'extrabold': '800', 'black': '900'}
-                val = weight_map.get(val.lower(), val)
-                try:
-                    weight_values.append(int(val))
-                except: pass
-
-        # Check for adjacent weights (400/500, 500/600, etc.)
-        for i in range(len(weight_values) - 1):
-            diff = abs(weight_values[i] - weight_values[i+1])
-            if diff == 100:
-                self.warnings.append(f"[Typography] {filename}: Adjacent font weights ({weight_values[i]}/{weight_values[i+1]}). Skip at least 2 levels for contrast.")
-
-        # Too many weight levels
-        unique_weights = set(weight_values)
-        if len(unique_weights) > 4:
-            self.warnings.append(f"[Typography] {filename}: {len(unique_weights)} font weights. Limit to 3-4 per page.")
-
-        # 2.6 Responsive Typography - Fluid sizing with clamp()
-        has_font_sizes = bool(re.search(r'font-size:|text-(?:xs|sm|base|lg|xl|2xl)', content))
-        if has_font_sizes and not re.search(r'clamp\(|responsive:', content):
-            self.warnings.append(f"[Typography] {filename}: Fixed font sizes without clamp(). Consider fluid typography: clamp(MIN, PREFERRED, MAX)")
-
-        # 2.7 Hierarchy - Heading structure
-        headings = re.findall(r'<(h[1-6])', content, re.IGNORECASE)
-        if headings:
-            # Check for skipped levels (h1 -> h3)
-            for i in range(len(headings) - 1):
-                curr = int(headings[i][1])
-                next_h = int(headings[i+1][1])
-                if next_h > curr + 1:
-                    self.warnings.append(f"[Typography] {filename}: Skipped heading level (h{curr} -> h{next_h}). Maintain sequential hierarchy.")
-
-            # Check if h1 exists for main content
-            if 'h1' not in [h.lower() for h in headings] and has_long_text:
-                self.warnings.append(f"[Typography] {filename}: No h1 found. Each page should have one primary heading.")
-
-        # 2.8 Modular Scale - Consistent sizing
-        # Extract font-size values
-        font_sizes = re.findall(r'font-size:\s*(\d+(?:\.\d+)?)(px|rem|em)', content)
-        size_values = []
-        for size, unit in font_sizes:
-            if unit == 'rem' or unit == 'em':
-                size_values.append(float(size))
-            elif unit == 'px':
-                size_values.append(float(size) / 16)  # Normalize to rem
-
-        if len(size_values) > 2:
-            # Check if sizes follow a modular scale roughly
-            sorted_sizes = sorted(set(size_values))
-            ratios = []
-            for i in range(1, len(sorted_sizes)):
-                if sorted_sizes[i-1] > 0:
-                    ratios.append(sorted_sizes[i] / sorted_sizes[i-1])
-
-            # Common scale ratios: 1.067, 1.125, 1.2, 1.25, 1.333, 1.5, 1.618
-            common_ratios = {1.067, 1.125, 1.2, 1.25, 1.333, 1.5, 1.618}
-            for ratio in ratios[:3]:  # Check first 3 ratios
-                if not any(abs(ratio - cr) < 0.05 for cr in common_ratios):
-                    self.warnings.append(f"[Typography] {filename}: Font sizes may not follow modular scale (ratio: {ratio:.2f}). Consider consistent ratio like 1.25 (Major Third).")
-                    break
-
-        # 2.9 Readability - Content chunking
-        # Check for very long paragraphs (>5 lines estimated)
-        paragraphs = re.findall(r'<p[^>]*>([^<]+)</p>', content, re.IGNORECASE)
-        for p in paragraphs:
-            word_count = len(p.split())
-            if word_count > 100:  # ~5-6 lines
-                self.warnings.append(f"[Typography] {filename}: Long paragraph detected ({word_count} words). Break into 3-4 line chunks for readability.")
-
-        # Check for missing subheadings in long content
-        if len(paragraphs) > 5:
-            subheadings = len(re.findall(r'<h[2-6]', content, re.IGNORECASE))
-            if subheadings == 0:
-                self.warnings.append(f"[Typography] {filename}: Long content without subheadings. Add h2/h3 to break up text.")
-
-        # --- 3. VISUAL EFFECTS (visual-effects.md) ---
-        
-        # Glassmorphism Check
-        if 'backdrop-filter' in content or 'blur(' in content:
-            if not re.search(r'background:\s*rgba|bg-opacity|bg-[a-z0-9]+\/\d+', content):
-                self.warnings.append(f"[Visual] {filename}: Blur used without semi-transparent background (Glassmorphism fail)")
-        
-        # GPU Acceleration / Performance
-        if re.search(r'@keyframes|transition:', content):
-            expensive_props = re.findall(r'width|height|top|left|right|bottom|margin|padding', content)
-            if expensive_props:
-                self.warnings.append(f"[Performance] {filename}: Animating expensive properties ({', '.join(set(expensive_props))}). Use transform/opacity where possible.")
-            
-            # Reduced Motion
-            if not re.search(r'prefers-reduced-motion', content):
-                self.warnings.append(f"[Accessibility] {filename}: Animations found without prefers-reduced-motion check")
-
-        # Natural Shadows
-        shadows = re.findall(r'box-shadow:\s*([^;]+)', content)
-        for shadow in shadows:
-            # Check if natural (Y > X) or multiple layers
-            if ',' not in shadow and not re.search(r'\d+px\s+[1-9]\d*px', shadow): # Simple heuristic for Y-offset
-                 self.warnings.append(f"[Visual] {filename}: Simple/Unnatural shadow detected. Consider multiple layers or Y > X offset for realism.")
-
-        # --- 3.1 NEOMORPHISM CHECK ---
-        # Check for neomorphism patterns (dual shadows with opposite directions)
-        neo_shadows = re.findall(r'box-shadow:\s*([^;]+)', content)
-        for shadow in neo_shadows:
-            # Neomorphism has two shadows: positive offset + negative offset
-            if ',' in shadow and '-' in shadow:
-                # Check for inset pattern (pressed state)
-                if 'inset' in shadow:
-                    self.warnings.append(f"[Visual] {filename}: Neomorphism inset detected. Ensure adequate contrast for accessibility.")
-
-        # --- 3.2 SHADOW HIERARCHY ---
-        # Count shadow levels to check for elevation consistency
-        shadow_count = len(shadows)
-        if shadow_count > 0:
-            # Check for shadow opacity levels (should indicate hierarchy)
-            opacities = re.findall(r'rgba?\([^)]+,\s*([\d.]+)\)', content)
-            shadow_opacities = [float(o) for o in opacities if float(o) < 0.5]
-            if shadow_count >= 3 and len(shadow_opacities) > 0:
-                # Check if there's variety in shadow opacities for different elevations
-                unique_opacities = len(set(shadow_opacities))
-                if unique_opacities < 2:
-                    self.warnings.append(f"[Visual] {filename}: All shadows at same opacity level. Vary shadow intensity for elevation hierarchy.")
-
-        # --- 3.3 GRADIENT CHECKS ---
-        # Check for gradient usage
-        has_gradient = bool(re.search(r'gradient|linear-gradient|radial-gradient|conic-gradient', content))
-        if has_gradient:
-            # Warn about mesh/aurora gradients (can be overused)
-            gradient_count = len(re.findall(r'gradient', content, re.IGNORECASE))
-            if gradient_count > 5:
-                self.warnings.append(f"[Visual] {filename}: Many gradients detected ({gradient_count}). Ensure this serves purpose, not decoration.")
-        else:
-            # Check if hero section exists without gradient
-            if has_hero and not re.search(r'background:|bg-', content):
-                self.warnings.append(f"[Visual] {filename}: Hero section without visual interest. Consider gradient for depth.")
-
-        # --- 3.4 BORDER EFFECTS ---
-        # Check for gradient borders or animated borders
-        has_border = bool(re.search(r'border:|border-', content))
-        if has_border:
-            # Check for overly complex borders
-            border_count = len(re.findall(r'border:', content))
-            if border_count > 8:
-                self.warnings.append(f"[Visual] {filename}: Many border declarations ({border_count}). Simplify for cleaner look.")
-
-        # --- 3.5 GLOW EFFECTS ---
-        # Check for text-shadow or multiple box-shadow layers (glow effects)
-        text_shadows = re.findall(r'text-shadow:', content)
-        for ts in text_shadows:
-            # Multiple text-shadow layers indicate glow
-            if ',' in ts:
-                self.warnings.append(f"[Visual] {filename}: Text glow effect detected. Ensure readability is maintained.")
-
-        # Check for box-shadow glow (multiple layers with 0 offset)
-        glow_shadows = re.findall(r'box-shadow:\s*[^;]*0\s+0\s+', content)
-        if len(glow_shadows) > 2:
-            self.warnings.append(f"[Visual] {filename}: Multiple glow effects detected. Use sparingly for emphasis only.")
-
-        # --- 3.6 OVERLAY TECHNIQUES ---
-        # Check for image overlays (for readability)
-        has_images = bool(re.search(r'<img|background-image:|bg-\[url', content))
-        if has_images and has_long_text:
-            has_overlay = bool(re.search(r'overlay|rgba\(0|gradient.*transparent|::after|::before', content))
-            if not has_overlay:
-                self.warnings.append(f"[Visual] {filename}: Text over image without overlay. Add gradient overlay for readability.")
-
-        # --- 3.7 PERFORMANCE: will-change ---
-        # Check for will-change usage
-        if re.search(r'will-change:', content):
-            will_change_props = re.findall(r'will-change:\s*([^;]+)', content)
-            for prop in will_change_props:
-                prop = prop.strip().lower()
-                if prop in ['width', 'height', 'top', 'left', 'right', 'bottom', 'margin', 'padding']:
-                    self.issues.append(f"[Performance] {filename}: will-change on '{prop}' (layout property). Use only for transform/opacity.")
-
-        # Check for excessive will-change usage
-        will_change_count = len(re.findall(r'will-change:', content))
-        if will_change_count > 3:
-            self.warnings.append(f"[Performance] {filename}: Many will-change declarations ({will_change_count}). Use sparingly, only for heavy animations.")
-
-        # --- 3.8 EFFECT SELECTION ---
-        # Check for effect overuse (too many visual effects)
-        effect_count = (
-            (1 if has_gradient else 0) +
-            shadow_count +
-            len(re.findall(r'backdrop-filter|blur\(', content)) +
-            len(re.findall(r'text-shadow:', content))
-        )
-        if effect_count > 10:
-            self.warnings.append(f"[Visual] {filename}: Many visual effects ({effect_count}). Ensure effects serve purpose, not decoration.")
-
-        # Check for static/flat design (no depth)
-        if has_long_text and effect_count == 0:
-            self.warnings.append(f"[Visual] {filename}: Flat design with no depth. Consider shadows or subtle gradients for hierarchy.")
-
-        # --- 4. COLOR SYSTEM (color-system.md) ---
-
-        # 4.1 PURPLE BAN - Critical check from color-system.md
-        purple_hexes = ['#8B5CF6', '#A855F7', '#9333EA', '#7C3AED', '#6D28D9',
-                        '#8B5CF6', '#A78BFA', '#C4B5FD', '#DDD6FE', '#EDE9FE',
-                        '#8b5cf6', '#a855f7', '#9333ea', '#7c3aed', '#6d28d9',
-                        'purple', 'violet', 'fuchsia', 'magenta', 'lavender']
-        for purple in purple_hexes:
-            if purple.lower() in content.lower():
-                self.issues.append(f"[Color] {filename}: PURPLE DETECTED ('{purple}'). Banned by Maestro rules. Use Teal/Cyan/Emerald instead.")
-                break
-
-        # 4.2 60-30-10 Rule check
-        # Count color usage to estimate ratio
-        color_hex_count = len(re.findall(r'#[0-9a-fA-F]{3,6}', content))
-        hsl_count = len(re.findall(r'hsl\(', content))
-        total_colors = color_hex_count + hsl_count
-        if total_colors > 3:
-            # Check for dominant colors (should be ~60%)
-            bg_declarations = re.findall(r'(?:background|bg-|bg\[)([^;}\s]+)', content)
-            text_declarations = re.findall(r'(?:color|text-)([^;}\s]+)', content)
-            if len(bg_declarations) > 0 and len(text_declarations) > 0:
-                # Just warn if too many distinct colors
-                unique_hexes = set(re.findall(r'#[0-9a-fA-F]{6}', content))
-                if len(unique_hexes) > 5:
-                    self.warnings.append(f"[Color] {filename}: {len(unique_hexes)} distinct colors. Consider 60-30-10 rule: dominant (60%), secondary (30%), accent (10%).")
-
-        # 4.3 Color Scheme Pattern Detection
-        # Detect monochromatic (same hue, different lightness)
-        hsl_matches = re.findall(r'hsl\((\d+),\s*\d+%,\s*\d+%\)', content)
-        if len(hsl_matches) >= 3:
-            hues = [int(h) for h in hsl_matches]
-            hue_range = max(hues) - min(hues)
-            if hue_range < 10:
-                self.warnings.append(f"[Color] {filename}: Monochromatic palette detected (hue variance: {hue_range}deg). Ensure adequate contrast.")
-
-        # 4.4 Dark Mode Compliance
-        # Check for pure black (#000000) or pure white (#FFFFFF) text (forbidden)
-        if re.search(r'color:\s*#000000|#000\b', content):
-            self.warnings.append(f"[Color] {filename}: Pure black (#000000) detected. Use #1a1a1a or darker grays for better dark mode.")
-        if re.search(r'background:\s*#ffffff|#fff\b', content) and re.search(r'dark:\s*|dark:', content):
-            self.warnings.append(f"[Color] {filename}: Pure white background in dark mode context. Use slight off-white (#f9fafb) for reduced eye strain.")
-
-        # 4.5 WCAG Contrast Pattern Check
-        # Look for potential low-contrast combinations
-        light_bg_light_text = bool(re.search(r'bg-(?:gray|slate|zinc)-50|bg-white.*text-(?:gray|slate)-[12]', content))
-        dark_bg_dark_text = bool(re.search(r'bg-(?:gray|slate|zinct)-9|bg-black.*text-(?:gray|slate)-[89]', content))
-        if light_bg_light_text or dark_bg_dark_text:
-            self.warnings.append(f"[Color] {filename}: Possible low-contrast combination detected. Verify WCAG AA (4.5:1 for text).")
-
-        # 4.6 Color Psychology Context Check
-        # Warn if blue used for food/restaurant context
-        has_blue = bool(re.search(r'bg-blue|text-blue|from-blue|#[0-9a-fA-F]*00[0-9A-Fa-f]{2}|#[0-9a-fA-F]*1[0-9A-Fa-f]{2}', content))
-        has_food_context = bool(re.search(r'restaurant|food|cooking|recipe|menu|dish|meal', content, re.IGNORECASE))
-        if has_blue and has_food_context:
-            self.warnings.append(f"[Color] {filename}: Blue color in food context. Blue suppresses appetite; consider warm colors (red, orange, yellow).")
-
-        # 4.7 HSL-Based Palette Detection
-        # Check if using HSL for palette (recommended in color-system.md)
-        has_color_vars = bool(re.search(r'--color-|color-|primary-|secondary-', content))
-        if has_color_vars and not re.search(r'hsl\(', content):
-            self.warnings.append(f"[Color] {filename}: Color variables without HSL. Consider HSL for easier palette adjustment (Hue, Saturation, Lightness).")
-
-        # --- 5. ANIMATION GUIDE (animation-guide.md) ---
-
-        # 5.1 Duration Appropriateness
-        # Check for excessively long or short animations
-        durations = re.findall(r'(?:duration|animation-duration|transition-duration):\s*([\d.]+)(s|ms)', content)
-        for duration, unit in durations:
-            duration_ms = float(duration) * (1000 if unit == 's' else 1)
-            if duration_ms < 50:
-                self.warnings.append(f"[Animation] {filename}: Very fast animation ({duration}{unit}). Minimum 50ms for visibility.")
-            elif duration_ms > 1000 and 'transition' in content.lower():
-                self.warnings.append(f"[Animation] {filename}: Long transition ({duration}{unit}). Transitions should be 100-300ms for responsiveness.")
-
-        # 5.2 Easing Function Correctness
-        # Check for incorrect easing patterns
-        if re.search(r'ease-in\s+.*entry|fade-in.*ease-in', content):
-            self.warnings.append(f"[Animation] {filename}: Entry animation with ease-in. Entry should use ease-out for snappy feel.")
-        if re.search(r'ease-out\s+.*exit|fade-out.*ease-out', content):
-            self.warnings.append(f"[Animation] {filename}: Exit animation with ease-out. Exit should use ease-in for natural feel.")
-
-        # 5.3 Micro-interaction Feedback Patterns
-        # Check for interactive elements without hover/focus states
-        interactive_elements = len(re.findall(r'<button|<a\s+href|onClick|@click', content))
-        has_hover_focus = bool(re.search(r'hover:|focus:|:hover|:focus', content))
-        if interactive_elements > 2 and not has_hover_focus:
-            self.warnings.append(f"[Animation] {filename}: Interactive elements without hover/focus states. Add micro-interactions for feedback.")
-
-        # 5.4 Loading State Indicators
-        # Check for loading patterns
-        has_async = bool(re.search(r'async|await|fetch|axios|loading|isLoading', content))
-        has_loading_indicator = bool(re.search(r'skeleton|spinner|progress|loading|<circle.*animate', content))
-        if has_async and not has_loading_indicator:
-            self.warnings.append(f"[Animation] {filename}: Async operations without loading indicator. Add skeleton or spinner for perceived performance.")
-
-        # 5.5 Page Transition Patterns
-        # Check for page/view transitions
-        has_routing = bool(re.search(r'router|navigate|Link.*to|useHistory', content))
-        has_page_transition = bool(re.search(r'AnimatePresence|motion\.|transition.*page|fade.*route', content))
-        if has_routing and not has_page_transition:
-            self.warnings.append(f"[Animation] {filename}: Routing detected without page transitions. Consider fade/slide for context continuity.")
-
-        # 5.6 Scroll Animation Performance
-        # Check for scroll-driven animations
-        has_scroll_anim = bool(re.search(r'onScroll|scroll.*trigger|IntersectionObserver', content))
-        if has_scroll_anim:
-            # Check if using expensive properties in scroll handlers
-            if re.search(r'onScroll.*[^\w](width|height|top|left)', content):
-                self.issues.append(f"[Animation] {filename}: Scroll handler animating layout properties. Use transform/opacity for 60fps.")
-
-        # --- 6. MOTION GRAPHICS (motion-graphics.md) ---
-
-        # 6.1 Lottie Animation Checks
-        has_lottie = bool(re.search(r'lottie|Lottie|@lottie-react', content))
-        if has_lottie:
-            # Check for reduced motion fallback
-            has_lottie_fallback = bool(re.search(r'prefers-reduced-motion.*lottie|lottie.*isPaused|lottie.*stop', content))
-            if not has_lottie_fallback:
-                self.warnings.append(f"[Motion] {filename}: Lottie animation without reduced-motion fallback. Add pause/stop for accessibility.")
-
-        # 6.2 GSAP Memory Leak Risks
-        has_gsap = bool(re.search(r'gsap|ScrollTrigger|from\(.*gsap', content))
-        if has_gsap:
-            # Check for cleanup patterns
-            has_gsap_cleanup = bool(re.search(r'kill\(|revert\(|useEffect.*return.*gsap', content))
-            if not has_gsap_cleanup:
-                self.issues.append(f"[Motion] {filename}: GSAP animation without cleanup (kill/revert). Memory leak risk on unmount.")
-
-        # 6.3 SVG Animation Performance
-        svg_animations = re.findall(r'<animate|<animateTransform|stroke-dasharray|stroke-dashoffset', content)
-        if len(svg_animations) > 3:
-            self.warnings.append(f"[Motion] {filename}: Multiple SVG animations detected. Ensure stroke-dashoffset is used sparingly for mobile performance.")
-
-        # 6.4 3D Transform Performance
-        has_3d_transform = bool(re.search(r'transform3d|perspective\(|rotate3d|translate3d', content))
-        if has_3d_transform:
-            # Check for perspective on parent
-            has_perspective_parent = bool(re.search(r'perspective:\s*\d+px|perspective\s*\(', content))
-            if not has_perspective_parent:
-                self.warnings.append(f"[Motion] {filename}: 3D transform without perspective parent. Add perspective: 1000px for realistic depth.")
-
-            # Warn about mobile performance
-            self.warnings.append(f"[Motion] {filename}: 3D transforms detected. Test on mobile; can impact performance on low-end devices.")
-
-        # 6.5 Particle Effect Warnings
-        # Check for canvas/WebGL particle systems
-        has_particles = bool(re.search(r'particle|canvas.*loop|requestAnimationFrame.*draw|Three\.js', content))
-        if has_particles:
-            self.warnings.append(f"[Motion] {filename}: Particle effects detected. Ensure fallback or reduced-quality option for mobile devices.")
-
-        # 6.6 Scroll-Driven Animation Performance
-        has_scroll_driven = bool(re.search(r'IntersectionObserver.*animate|scroll.*progress|view-timeline', content))
-        if has_scroll_driven:
-            # Check for throttling/debouncing
-            has_throttle = bool(re.search(r'throttle|debounce|requestAnimationFrame', content))
-            if not has_throttle:
-                self.issues.append(f"[Motion] {filename}: Scroll-driven animation without throttling. Add requestAnimationFrame for 60fps.")
-
-        # 6.7 Motion Decision Tree - Context Check
-        # Check if animation serves purpose (not just decoration)
-        total_animations = (
-            len(re.findall(r'@keyframes|transition:|animate-', content)) +
-            (1 if has_lottie else 0) +
-            (1 if has_gsap else 0)
-        )
-        if total_animations > 5:
-            # Check if animations are functional
-            functional_animations = len(re.findall(r'hover:|focus:|disabled|loading|error|success', content))
-            if functional_animations < total_animations / 2:
-                self.warnings.append(f"[Motion] {filename}: Many animations ({total_animations}). Ensure majority serve functional purpose (feedback, guidance), not decoration.")
-
-        # --- 7. ACCESSIBILITY ---
-        if re.search(r'<img(?![^>]*alt=)[^>]*>', content):
-            self.issues.append(f"[Accessibility] {filename}: Missing img alt text")
-
-    def audit_directory(self, directory: str) -> None:
-        extensions = {'.tsx', '.jsx', '.html', '.vue', '.svelte', '.css'}
-        for root, dirs, files in os.walk(directory):
-            dirs[:] = [d for d in dirs if d not in {'node_modules', '.git', 'dist', 'build', '.next'}]
-            for file in files:
-                if Path(file).suffix in extensions:
-                    self.audit_file(os.path.join(root, file))
-
-    def get_report(self):
-        return {
-            "files_checked": self.files_checked,
-            "issues": self.issues,
-            "warnings": self.warnings,
-            "passed_checks": self.passed_count,
-            "compliant": len(self.issues) == 0
-        }
-
-def main():
-    if len(sys.argv) < 2: sys.exit(1)
-    
-    path = sys.argv[1]
-    is_json = "--json" in sys.argv
-    
-    auditor = UXAuditor()
-    if os.path.isfile(path): auditor.audit_file(path)
-    else: auditor.audit_directory(path)
-    
-    report = auditor.get_report()
-    
-    if is_json:
-        print(json.dumps(report))
-    else:
-        # Use ASCII-safe output for Windows console compatibility
-        print(f"\n[UX AUDIT] {report['files_checked']} files checked")
-        print("-" * 50)
-        if report['issues']:
-            print(f"[!] ISSUES ({len(report['issues'])}):")
-            for i in report['issues'][:10]: print(f"  - {i}")
-        if report['warnings']:
-            print(f"[*] WARNINGS ({len(report['warnings'])}):")
-            for w in report['warnings'][:15]: print(f"  - {w}")
-        print(f"[+] PASSED CHECKS: {report['passed_checks']}")
-        status = "PASS" if report['compliant'] else "FAIL"
-        print(f"STATUS: {status}")
-
-    sys.exit(0 if report['compliant'] else 1)
-
-if __name__ == "__main__":
-    main()