Animation implementation specification

Animation Implementation Guidelines

Animations play a vital role in modern web development. Well-implemented animation guidelines enhance user experience and ensure performance. CSS animations should adhere to the principles of maintainability, high performance, and progressive enhancement while maintaining code consistency and readability.

Animation Type Selection

Prefer CSS animations over JavaScript animations unless complex logic control is required. CSS animations perform better, as browsers can optimize their execution.

/* Recommended: Use CSS animations */  
@keyframes fadeIn {  
  from { opacity: 0; }  
  to { opacity: 1; }  
}  

.fade-in {  
  animation: fadeIn 0.3s ease-out;  
}  

/* Not recommended: Using JavaScript for the same effect */  
element.animate([  
  { opacity: 0 },  
  { opacity: 1 }  
], {  
  duration: 300,  
  easing: 'ease-out'  
});  

Animation Performance Optimization

Avoid animating properties that trigger reflows. Prioritize compositor-friendly properties like transform and opacity.

/* Good performance: Use transform */  
.move {  
  transition: transform 0.2s ease;  
  transform: translateX(100px);  
}  

/* Poor performance: Triggers reflow */  
.move-poor {  
  transition: left 0.2s ease;  
  left: 100px;  
}  

Animation Duration Guidelines

Set appropriate durations based on animation purpose:

• Micro-interactions: 100–300ms
• Moderate transitions: 300–500ms
• Complex animations: 500–1000ms

/* Button hover effect */  
.button {  
  transition: background-color 0.15s ease;  
}  

/* Modal appearance */  
.modal {  
  animation: slideIn 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94);  
}  

Easing Function Usage

Avoid linear easing. Choose appropriate easing functions based on animation type:

/* Entrance animations use ease-out */  
.enter {  
  animation: fadeIn 0.3s ease-out;  
}  

/* Exit animations use ease-in */  
.exit {  
  animation: fadeOut 0.3s ease-in;  
}  

/* Elastic animations */  
.bounce {  
  animation: bounce 0.5s cubic-bezier(0.68, -0.55, 0.27, 1.55);  
}  

Animation Naming Conventions

Use semantic animation names following BEM naming conventions:

/* Good naming */  
@keyframes modal-slide-in-from-top {  
  from { transform: translateY(-100%); }  
  to { transform: translateY(0); }  
}  

/* Avoid naming like this */  
@keyframes animation1 {  
  0% { opacity: 0; }  
  100% { opacity: 1; }  
}  

Responsive Animation Handling

Adjust animation parameters for different devices. Simplify animations on mobile:

/* Base animation */  
.element {  
  transition: transform 0.3s ease;  
}  

/* Simplified for mobile */  
@media (max-width: 768px) {  
  .element {  
    transition: opacity 0.2s ease;  
    transform: none !important;  
  }  
}  

Animation Fallback Handling

Ensure content remains accessible if animations are disabled:

/* Critical styles not dependent on animations */  
.dropdown__menu {  
  max-height: 0;  
  overflow: hidden;  
}  

/* Animation as enhancement */  
@media (prefers-reduced-motion: no-preference) {  
  .dropdown__menu {  
    transition: max-height 0.3s ease;  
  }  
}  

Animation and JavaScript Interaction

Use CSS custom properties when interacting with JavaScript:

:root {  
  --progress: 0;  
}  

.progress-bar {  
  width: calc(var(--progress) * 1%);  
  transition: width 0.2s linear;  
}  

// JavaScript control  
document.documentElement.style.setProperty('--progress', newValue);  

Composite Animation Handling

When applying multiple animations, stagger their timing:

/* Stagger animation timing */  
.item {  
  animation: fadeIn 0.3s ease-out forwards;  
}  

.item:nth-child(1) { animation-delay: 0.1s; }  
.item:nth-child(2) { animation-delay: 0.2s; }  
.item:nth-child(3) { animation-delay: 0.3s; }  

Animation Performance Monitoring

Use will-change to inform the browser of upcoming changes:

/* Inform the browser in advance */  
.animated-element {  
  will-change: transform, opacity;  
}  

/* Reset after animation */  
.animated-element.animated {  
  will-change: auto;  
}  

Animation Debugging Tips

Add debugging classes during development to identify issues:

.debug-animation * {  
  animation-duration: 1s !important;  
  animation-delay: 0s !important;  
  animation-iteration-count: 1 !important;  
  transition-duration: 1s !important;  
  transition-delay: 0s !important;  
}  

Animation Documentation Guidelines

Add comments to explain complex animations:

/**  
 * Add-to-cart animation  
 * 1. Product thumbnail flies to cart  
 * 2. Cart icon bounces slightly  
 * 3. Counter increment effect  
 */  
@keyframes add-to-cart {  
  /* Keyframe details */  
}