Animation System Architecture Guide

Animation System Architecture Guide

Overview

The site's animation system has been completely reorganized into a modular, performance-optimized architecture. This system provides smooth GSAP-powered animations, ScrollTrigger effects, and seamless page transitions.

File Structure

Core Animation System (/assets/js/animation/)

animation-manager.js (Core Controller)

• Purpose: Central GSAP and ScrollTrigger management
• Features:
  • Performance optimization with frame throttling
  • Mobile detection and reduced animations
  • Memory cleanup and disposal
  • Intersection Observer integration
  • Responsive animation scaling

hero-animation.js (Hero Coordinator)

• Purpose: Simplified hero section animation coordination
• Features:
  • GSAP timeline management
  • Progressive enhancement
  • Error handling and fallbacks
  • Integration with existing hero systems

scroll-utils.js (ScrollTrigger Effects)

• Purpose: Advanced scroll-based animations
• Features:
  • Parallax effects with performance optimization
  • Reveal animations (fade, slide, scale)
  • Progress indicators
  • Smooth scroll implementation
  • Viewport-aware animation triggers

coordinator.js (System Controller)

• Purpose: Central coordination between all animation systems
• Features:
  • SWUP page transition integration
  • Component initialization coordination
  • State management
  • Performance monitoring
  • Cleanup orchestration

Integration with Existing Systems

Page Transitions (SWUP)

• Animations automatically reinitialize on page changes
• Smooth coordination between exit/enter animations
• Preserves scroll position and state

Gallery System

• Coordinated with Swiper animations
• Lightbox integration with smooth transitions
• Progressive loading with animation triggers

Theme System

• Animations respect user's motion preferences
• Performance scaling for different devices
• Dark/light theme transition support

Performance Features

Optimization Strategies

1. Frame Throttling: Limits animation updates to prevent performance issues
2. Intersection Observer: Only animate elements in viewport
3. Mobile Adaptation: Reduced complexity on mobile devices
4. Memory Management: Automatic cleanup of completed animations
5. Progressive Enhancement: Graceful fallbacks for older browsers

Loading Strategy

<!-- Load order in scripts.html -->
1. animation-manager.js (core system)
2. hero-animation.js (hero coordinator)
3. scroll-utils.js (scroll effects)
4. coordinator.js (system controller)

Usage Examples

Basic ScrollTrigger Animation

// Automatically handled by scroll-utils.js
<div class="animate-reveal" data-animation="fade-up">
  Content to animate
</div>

Custom Animation Integration

// Use the AnimationManager for custom animations
if (window.AnimationManager) {
  AnimationManager.createTimeline('custom-animation', {
    targets: '.my-element',
    duration: 1,
    ease: 'power2.out'
  });
}

Performance Monitoring

// Check animation performance
if (window.AnimationCoordinator) {
  const stats = AnimationCoordinator.getPerformanceStats();
  console.log('Active animations:', stats.activeCount);
}

Migration from Old System

Replaced Files

• animations-optimized.js → animation-manager.js + scroll-utils.js
• hero-animations.js → hero-animation.js (simplified)
• Scattered animation code → Centralized in /animation/ directory

Benefits of New Architecture

1. Modularity: Clear separation of concerns
2. Maintainability: Easier to debug and extend
3. Performance: Better optimization and cleanup
4. Scalability: Easy to add new animation types
5. Integration: Better coordination with other systems

Troubleshooting

Common Issues

1. Animations not triggering: Check if ScrollTrigger is properly initialized
2. Performance issues: Verify frame throttling is enabled
3. Mobile problems: Ensure mobile detection is working
4. Memory leaks: Check cleanup methods are being called

Debug Mode

Enable debug logging by adding to console:

window.AnimationManager.debug = true;

Future Enhancements

Planned Features

1. Animation Presets: Pre-built animation combinations
2. Visual Builder: GUI for creating complex animations
3. Performance Analytics: Real-time performance monitoring
4. A/B Testing: Animation variant testing system
5. Accessibility: Enhanced motion sensitivity controls

Extension Points

• Custom scroll effects in scroll-utils.js
• New animation types in animation-manager.js
• Integration hooks in coordinator.js

---

Last Updated: Animation system reorganization completion Related: CONTRAST-ZONES-GUIDE.md, CSS-README.md