michaelschiemer/docs/modules/animation-system-migration.md

Animation System Migration Guide

Complete Migration Guide from Old Scroll Animation Modules to Unified Animation System

This guide helps you migrate from the old scroll animation modules to the new unified Animation System.

---

Overview

The Animation System consolidates 8 separate modules into one unified system:

• scrollfx → AnimationSystem (fade-in, zoom-in)
• parallax → AnimationSystem (parallax)
• scroll-timeline → AnimationSystem (timeline)
• scroll-loop → AnimationSystem (timeline with loop)
• scroll-dependent → AnimationSystem (dependent animations)
• sticky-fade → AnimationSystem (sticky-fade)
• sticky-steps → AnimationSystem (sticky-steps)
• smooth-scroll → Keep separate (different purpose)

---

Migration Steps

1. Update Imports

Before:

import { createTrigger } from './modules/scrollfx/index.js';
import { init as initParallax } from './modules/parallax/index.js';

After:

import { AnimationSystem } from './modules/animation-system/index.js';

2. Update Initialization

Before:

createTrigger({ element: '.fade-in', offset: 0.85 });
initParallax({ selector: '.parallax' });

After:

const system = AnimationSystem.create();
// Auto-initializes based on HTML attributes
// Or manually:
document.querySelectorAll('.fade-in').forEach(el => {
    system.registerAnimation(el, { type: 'fade-in', offset: 0.85 });
});

3. Update HTML Attributes

Most HTML attributes remain compatible, but you can use new unified attributes:

Before:

<div class="fade-in-on-scroll" data-offset="0.85">Content</div>
<div class="parallax" data-speed="0.5">Content</div>

After (still works, or use new format):

<div data-animate="fade-in" data-offset="0.85">Content</div>
<div data-parallax data-speed="0.5">Content</div>

---

Module-Specific Migrations

scrollfx → AnimationSystem

Before:

import { createTrigger } from './modules/scrollfx/index.js';
createTrigger({
    element: '.fade-in',
    offset: 0.85,
    baseDelay: 0.05,
    once: true
});

After:

import { AnimationSystem } from './modules/animation-system/index.js';
const system = AnimationSystem.create();
document.querySelectorAll('.fade-in').forEach((el, index) => {
    system.registerAnimation(el, {
        type: 'fade-in',
        offset: 0.85,
        delay: index * 0.05,
        once: true
    });
});

parallax → AnimationSystem

Before:

import { init } from './modules/parallax/index.js';
init({ selector: '.parallax', speed: 0.5 });

After:

import { AnimationSystem } from './modules/animation-system/index.js';
const system = AnimationSystem.create();
document.querySelectorAll('.parallax').forEach(el => {
    system.registerAnimation(el, {
        type: 'parallax',
        speed: 0.5
    });
});

scroll-timeline → AnimationSystem

Before:

import { init } from './modules/scroll-timeline/index.js';
init({ attribute: 'data-scroll-step', triggerPoint: 0.4 });

After:

import { AnimationSystem } from './modules/animation-system/index.js';
const system = AnimationSystem.create();
document.querySelectorAll('[data-scroll-step]').forEach(el => {
    system.registerAnimation(el, {
        type: 'timeline',
        steps: parseInt(el.dataset.scrollSteps) || null,
        triggerPoint: 0.4
    });
});

---

Backward Compatibility

The Animation System maintains backward compatibility with existing HTML:

• Old CSS classes still work: .fade-in-on-scroll, .zoom-in, .parallax
• Old data attributes still work: data-parallax, data-scroll-step, etc.
• Old module initialization still works (but deprecated)

---

Breaking Changes

1. Module Exports - Old module exports are deprecated
2. JavaScript API - Some APIs have changed (see migration examples)
3. Configuration - Some config options have been renamed

---

Testing Checklist

• All fade-in animations work
• All parallax effects work
• All timeline animations work
• All sticky animations work
• Performance is acceptable
• No console errors
• Backward compatibility maintained

---

Support

For issues or questions, see the main Animation System documentation.