@musashishao/agent-kit 1.0.0

package/.agent/skills/frontend-design/motion-graphics.md

@@ -0,0 +1,306 @@
+# Motion Graphics Reference
+
+> Advanced animation techniques for premium web experiences - Lottie, GSAP, SVG, 3D, Particles.
+> **Learn the principles, create WOW effects.**
+
+---
+
+## 1. Lottie Animations
+
+### What is Lottie?
+
+```
+JSON-based vector animations:
+├── Exported from After Effects via Bodymovin
+├── Lightweight (smaller than GIF/video)
+├── Scalable (vector-based, no pixelation)
+├── Interactive (control playback, segments)
+└── Cross-platform (web, iOS, Android, React Native)
+```
+
+### When to Use Lottie
+
+| Use Case | Why Lottie? |
+|----------|-------------|
+| **Loading animations** | Branded, smooth, lightweight |
+| **Empty states** | Engaging illustrations |
+| **Onboarding flows** | Complex multi-step animations |
+| **Success/Error feedback** | Delightful micro-interactions |
+| **Animated icons** | Consistent cross-platform |
+
+### Principles
+
+- Keep file size under 100KB for performance
+- Use loop sparingly (avoid distraction)
+- Provide static fallback for reduced-motion
+- Lazy load animation files when possible
+
+### Sources
+
+- LottieFiles.com (free library)
+- After Effects + Bodymovin (custom)
+- Figma plugins (export from design)
+
+---
+
+## 2. GSAP (GreenSock)
+
+### What Makes GSAP Different
+
+```
+Professional timeline-based animation:
+├── Precise control over sequences
+├── ScrollTrigger for scroll-driven animations
+├── MorphSVG for shape transitions
+├── Physics-based easing
+└── Works with any DOM element
+```
+
+### Core Concepts
+
+| Concept | Purpose |
+|---------|---------|
+| **Tween** | Single A→B animation |
+| **Timeline** | Sequenced/overlapping animations |
+| **ScrollTrigger** | Scroll position controls playback |
+| **Stagger** | Cascade effect across elements |
+
+### When to Use GSAP
+
+- ✅ Complex sequenced animations
+- ✅ Scroll-triggered reveals
+- ✅ Precise timing control needed
+- ✅ SVG morphing effects
+- ❌ Simple hover/focus effects (use CSS)
+- ❌ Performance-critical mobile (heavier)
+
+### Principles
+
+- Use timeline for orchestration (not individual tweens)
+- Stagger delay: 0.05-0.15s between items
+- ScrollTrigger: start at 70-80% viewport entry
+- Kill animations on unmount (prevent memory leaks)
+
+---
+
+## 3. SVG Animations
+
+### Types of SVG Animation
+
+| Type | Technique | Use Case |
+|------|-----------|----------|
+| **Line Drawing** | stroke-dashoffset | Logo reveals, signatures |
+| **Morph** | Path interpolation | Icon transitions |
+| **Transform** | rotate, scale, translate | Interactive icons |
+| **Color** | fill/stroke transition | State changes |
+
+### Line Drawing Principles
+
+```
+How stroke-dashoffset drawing works:
+├── Set dasharray to path length
+├── Set dashoffset equal to dasharray (hidden)
+├── Animate dashoffset to 0 (revealed)
+└── Create "drawing" effect
+```
+
+### When to Use SVG Animations
+
+- ✅ Logo reveals, brand moments
+- ✅ Icon state transitions (hamburger ↔ X)
+- ✅ Infographics, data visualization
+- ✅ Interactive illustrations
+- ❌ Photo-realistic content (use video)
+- ❌ Very complex scenes (performance)
+
+### Principles
+
+- Get path length dynamically for accuracy
+- Duration: 1-3s for full drawings
+- Easing: ease-out for natural feel
+- Simple fills complement, don't compete
+
+---
+
+## 4. 3D CSS Transforms
+
+### Core Properties
+
+```
+CSS 3D Space:
+├── perspective: depth of 3D field (500-1500px typical)
+├── transform-style: preserve-3d (enable children 3D)
+├── rotateX/Y/Z: rotation per axis
+├── translateZ: move toward/away from viewer
+└── backface-visibility: show/hide back side
+```
+
+### Common 3D Patterns
+
+| Pattern | Use Case |
+|---------|----------|
+| **Card flip** | Reveals, flashcards, product views |
+| **Tilt on hover** | Interactive cards, 3D depth |
+| **Parallax layers** | Hero sections, immersive scrolling |
+| **3D carousel** | Image galleries, sliders |
+
+### Principles
+
+- Perspective: 800-1200px for subtle, 400-600px for dramatic
+- Keep transforms simple (rotate + translate)
+- Ensure backface-visibility: hidden for flips
+- Test on Safari (different rendering)
+
+---
+
+## 5. Particle Effects
+
+### Types of Particle Systems
+
+| Type | Feel | Use Case |
+|------|------|----------|
+| **Geometric** | Tech, network | SaaS, tech sites |
+| **Confetti** | Celebration | Success moments |
+| **Snow/Rain** | Atmospheric | Seasonal, mood |
+| **Dust/Bokeh** | Dreamy | Photography, luxury |
+| **Fireflies** | Magical | Games, fantasy |
+
+### Libraries
+
+| Library | Best For |
+|---------|----------|
+| **tsParticles** | Configurable, lightweight |
+| **particles.js** | Simple backgrounds |
+| **Canvas API** | Custom, maximum control |
+| **Three.js** | Complex 3D particles |
+
+### Principles
+
+- Default: 30-50 particles (not overwhelming)
+- Movement: slow, organic (speed 0.5-2)
+- Opacity: 0.3-0.6 (don't compete with content)
+- Connections: subtle lines for "network" feel
+- ⚠️ Disable or reduce on mobile
+
+### When to Use
+
+- ✅ Hero backgrounds (atmospheric)
+- ✅ Success celebrations (confetti burst)
+- ✅ Tech visualization (connected nodes)
+- ❌ Content-heavy pages (distraction)
+- ❌ Low-powered devices (battery drain)
+
+---
+
+## 6. Scroll-Driven Animations
+
+### Native CSS (Modern)
+
+```
+CSS Scroll Timelines:
+├── animation-timeline: scroll() - document scroll
+├── animation-timeline: view() - element in viewport
+├── animation-range: entry/exit thresholds
+└── No JavaScript required
+```
+
+### Principles
+
+| Trigger Point | Use Case |
+|---------------|----------|
+| **Entry 0%** | When element starts entering |
+| **Entry 50%** | When half visible |
+| **Cover 50%** | When centered in viewport |
+| **Exit 100%** | When fully exited |
+
+### Best Practices
+
+- Reveal animations: start at ~25% entry
+- Parallax: continuous scroll progress
+- Sticky elements: use cover range
+- Always test scroll performance
+
+---
+
+## 7. Performance Principles
+
+### GPU vs CPU Animation
+
+```
+CHEAP (GPU-accelerated):
+├── transform (translate, scale, rotate)
+├── opacity
+└── filter (use sparingly)
+
+EXPENSIVE (triggers reflow):
+├── width, height
+├── top, left, right, bottom
+├── padding, margin
+└── complex box-shadow
+```
+
+### Optimization Checklist
+
+- [ ] Animate only transform/opacity
+- [ ] Use `will-change` before heavy animations (remove after)
+- [ ] Test on low-end devices
+- [ ] Implement `prefers-reduced-motion`
+- [ ] Lazy load animation libraries
+- [ ] Throttle scroll-based calculations
+
+---
+
+## 8. Motion Graphics Decision Tree
+
+```
+What animation do you need?
+│
+├── Complex branded animation?
+│   └── Lottie (After Effects export)
+│
+├── Sequenced scroll-triggered?
+│   └── GSAP + ScrollTrigger
+│
+├── Logo/icon animation?
+│   └── SVG animation (stroke or morph)
+│
+├── Interactive 3D effect?
+│   └── CSS 3D Transforms (simple) or Three.js (complex)
+│
+├── Atmospheric background?
+│   └── tsParticles or Canvas
+│
+└── Simple entrance/hover?
+    └── CSS @keyframes or Framer Motion
+```
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Animate everything at once | Stagger and sequence |
+| Use heavy libraries for simple effects | Start with CSS |
+| Ignore reduced-motion | Always provide fallback |
+| Block main thread | Optimize for 60fps |
+| Same particles every project | Match brand/context |
+| Complex effects on mobile | Feature detection |
+
+---
+
+## 10. Quick Reference
+
+| Effect | Tool | Performance |
+|--------|------|-------------|
+| Loading spinner | CSS/Lottie | Light |
+| Staggered reveal | GSAP/Framer | Medium |
+| SVG path draw | CSS stroke | Light |
+| 3D card flip | CSS transforms | Light |
+| Particle background | tsParticles | Heavy |
+| Scroll parallax | GSAP ScrollTrigger | Medium |
+| Shape morphing | GSAP MorphSVG | Medium |
+
+---
+
+> **Remember**: Motion graphics should enhance, not distract. Every animation must serve a PURPOSE—feedback, guidance, delight, or storytelling.

package/.agent/skills/frontend-design/scripts/accessibility_checker.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+Accessibility Checker - WCAG compliance audit
+Checks HTML files for accessibility issues.
+
+Usage:
+    python accessibility_checker.py <project_path>
+
+Checks:
+    - Form labels
+    - ARIA attributes
+    - Color contrast hints
+    - Keyboard navigation
+    - Semantic HTML
+"""
+
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+
+def find_html_files(project_path: Path) -> list:
+    """Find all HTML/JSX/TSX files."""
+    patterns = ['**/*.html', '**/*.jsx', '**/*.tsx']
+    skip_dirs = {'node_modules', '.next', 'dist', 'build', '.git'}
+    
+    files = []
+    for pattern in patterns:
+        for f in project_path.glob(pattern):
+            if not any(skip in f.parts for skip in skip_dirs):
+                files.append(f)
+    
+    return files[:50]
+
+
+def check_accessibility(file_path: Path) -> list:
+    """Check a single file for accessibility issues."""
+    issues = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8', errors='ignore')
+        
+        # Check for form inputs without labels
+        inputs = re.findall(r'<input[^>]*>', content, re.IGNORECASE)
+        for inp in inputs:
+            if 'type="hidden"' not in inp.lower():
+                if 'aria-label' not in inp.lower() and 'id=' not in inp.lower():
+                    issues.append("Input without label or aria-label")
+                    break
+        
+        # Check for buttons without accessible text
+        buttons = re.findall(r'<button[^>]*>[^<]*</button>', content, re.IGNORECASE)
+        for btn in buttons:
+            # Check if button has text content or aria-label
+            if 'aria-label' not in btn.lower():
+                text = re.sub(r'<[^>]+>', '', btn)
+                if not text.strip():
+                    issues.append("Button without accessible text")
+                    break
+        
+        # Check for missing lang attribute
+        if '<html' in content.lower() and 'lang=' not in content.lower():
+            issues.append("Missing lang attribute on <html>")
+        
+        # Check for missing skip link
+        if '<main' in content.lower() or '<body' in content.lower():
+            if 'skip' not in content.lower() and '#main' not in content.lower():
+                issues.append("Consider adding skip-to-main-content link")
+        
+        # Check for click handlers without keyboard support
+        onclick_count = content.lower().count('onclick=')
+        onkeydown_count = content.lower().count('onkeydown=') + content.lower().count('onkeyup=')
+        if onclick_count > 0 and onkeydown_count == 0:
+            issues.append("onClick without keyboard handler (onKeyDown)")
+        
+        # Check for tabIndex misuse
+        if 'tabindex=' in content.lower():
+            if 'tabindex="-1"' not in content.lower() and 'tabindex="0"' not in content.lower():
+                positive_tabindex = re.findall(r'tabindex="([1-9]\d*)"', content, re.IGNORECASE)
+                if positive_tabindex:
+                    issues.append("Avoid positive tabIndex values")
+        
+        # Check for autoplay media
+        if 'autoplay' in content.lower():
+            if 'muted' not in content.lower():
+                issues.append("Autoplay media should be muted")
+        
+        # Check for role usage
+        if 'role="button"' in content.lower():
+            # Divs with role button should have tabindex
+            div_buttons = re.findall(r'<div[^>]*role="button"[^>]*>', content, re.IGNORECASE)
+            for div in div_buttons:
+                if 'tabindex' not in div.lower():
+                    issues.append("role='button' without tabindex")
+                    break
+        
+    except Exception as e:
+        issues.append(f"Error reading file: {str(e)[:50]}")
+    
+    return issues
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"[ACCESSIBILITY CHECKER] WCAG Compliance Audit")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("-"*60)
+    
+    # Find HTML files
+    files = find_html_files(project_path)
+    print(f"Found {len(files)} HTML/JSX/TSX files")
+    
+    if not files:
+        output = {
+            "script": "accessibility_checker",
+            "project": str(project_path),
+            "files_checked": 0,
+            "issues_found": 0,
+            "passed": True,
+            "message": "No HTML files found"
+        }
+        print(json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    # Check each file
+    all_issues = []
+    
+    for f in files:
+        issues = check_accessibility(f)
+        if issues:
+            all_issues.append({
+                "file": str(f.name),
+                "issues": issues
+            })
+    
+    # Summary
+    print("\n" + "="*60)
+    print("ACCESSIBILITY ISSUES")
+    print("="*60)
+    
+    if all_issues:
+        for item in all_issues[:10]:
+            print(f"\n{item['file']}:")
+            for issue in item["issues"]:
+                print(f"  - {issue}")
+        
+        if len(all_issues) > 10:
+            print(f"\n... and {len(all_issues) - 10} more files with issues")
+    else:
+        print("No accessibility issues found!")
+    
+    total_issues = sum(len(item["issues"]) for item in all_issues)
+    # Accessibility issues are important but not blocking
+    passed = total_issues < 5  # Allow minor issues
+    
+    output = {
+        "script": "accessibility_checker",
+        "project": str(project_path),
+        "files_checked": len(files),
+        "files_with_issues": len(all_issues),
+        "issues_found": total_issues,
+        "passed": passed
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+    main()