Skip to content

MOTION_SYSTEM_GUIDE.md

Latest commit

 

History

History
216 lines (157 loc) · 6.71 KB

MOTION_SYSTEM_GUIDE.md

File metadata and controls

216 lines (157 loc) · 6.71 KB
Raw

Motion System Implementation Summary

What Was Created

1. Motion Presets Library (src/lib/motion-presets.ts)

A comprehensive, centralized animation system with:

  • 6 animation categories: entrance, exit, promote, remove, confirm, danger
  • 25+ named presets covering common UI patterns
  • Automatic reduced-motion support - respects prefers-reduced-motion system setting
  • Type-safe Framer Motion integration - works seamlessly with existing animations
  • Duration and easing presets for consistency
  • Combined patterns for common UI workflows (modals, notifications, sidebars, etc.)

2. Motion Gallery Route (src/routes/motion-gallery.tsx)

A development-only QA panel accessible at /motion-gallery (dev mode only) featuring:

  • Interactive preview of all animation presets
  • Reduced-motion simulation toggle for accessibility testing
  • Live animation replay controls
  • Usage code examples for each preset
  • Implementation patterns with copy-able code
  • Accessibility guidelines and best practices
  • Documentation links to full reference

3. Comprehensive Documentation

  • src/lib/MOTION_PRESETS.md - Full API reference with examples
  • src/features/design-system/README.md - Updated with motion system overview
  • JSDoc comments on all presets with usage guidance

Quick Start

For Component Authors

import { motionPresets } from "@/lib/motion-presets";
import { motion, AnimatePresence } from "framer-motion";

// Simple entrance animation
<motion.div {...motionPresets.entrance.slideUp()}>
  Content slides up with fade
</motion.div>

// Interactive hover effect
<motion.button {...motionPresets.promote.scale(1.04)}>
  Click me
</motion.button>

// Paired entrance/exit with AnimatePresence
<AnimatePresence>
  {isOpen && (
    <motion.div
      {...motionPresets.entrance.slideUp()}
      exit={motionPresets.exit.slideDown()}
    >
      Modal content
    </motion.div>
  )}
</AnimatePresence>

View the Gallery

In development mode, visit:

http://localhost:5173/motion-gallery

This provides an interactive reference for all available animations without needing to trigger workflows manually.

Animation Categories

Category Purpose Examples
entrance Elements appearing/entering slideUp, fadeIn, scaleIn, slideLeft, slideRight
exit Elements disappearing/leaving slideDown, fadeOut, scaleOut, slideToLeft, slideToRight
promote Drawing attention scale, lift, glow (use with whileHover/whileTap)
remove Removal emphasis spinOut, collapse, slideAwayRight
confirm Success feedback bounce, pulse, checkmark
danger Error/warning feedback shake, pulse, spinWarn

Key Features

✅ Accessibility First

  • All presets respect prefers-reduced-motion preference
  • Reduced motion reduces durations to ~0.01ms
  • Works with keyboard navigation focus states

✅ Consistent & Testable

  • Named presets prevent hardcoding animation values
  • Gallery allows QA to review all animations
  • Spring physics provides natural, responsive motion

✅ Developer Friendly

  • TypeScript support with full type safety
  • JSDoc documentation on every preset
  • Copy-paste code examples in gallery
  • Minimal API surface - easy to learn

✅ Production Ready

  • Dev-only gallery doesn't affect production builds
  • Zero runtime overhead beyond Framer Motion
  • Follows existing design system patterns

File Structure

src/
├── lib/
│   ├── motion-presets.ts          # Main motion system (400+ lines)
│   └── MOTION_PRESETS.md          # Full documentation
├── routes/
│   └── motion-gallery.tsx         # Dev-only QA panel
└── features/
    └── design-system/
        └── README.md              # Updated with motion docs

Usage Patterns

Modal Dialog

<motion.div {...motionPresets.patterns.modal.backdrop} />
<motion.div {...motionPresets.patterns.modal.content} />

Toast Notification

<motion.div {...motionPresets.patterns.notification.entrance} />
<motion.div {...motionPresets.patterns.notification.exit} />

Sidebar Panel

<motion.div {...motionPresets.patterns.sidePanel.backdrop} />
<motion.div {...motionPresets.patterns.sidePanel.panel} />

List Item with Removal

<motion.div {...motionPresets.patterns.listItem.entrance} />
<motion.div {...motionPresets.patterns.listItem.exit} />

Development Workflow

  1. Design & Test - Use /motion-gallery to preview animations
  2. Implement - Import presets and apply to components
  3. Review - Verify animations in context
  4. Iterate - Adjust preset parameters if needed
  5. QA - Test with reduced-motion toggle enabled

Accessibility Compliance

  • ✅ Respects system prefers-reduced-motion setting
  • ✅ All animations are optional (content remains accessible)
  • ✅ No animations block user interaction
  • ✅ Works with keyboard navigation
  • ✅ Compatible with screen readers (motion doesn't interfere)

Performance Considerations

  • Spring animations use GPU acceleration
  • Transitions are kept under 500ms for responsiveness
  • Multiple simultaneous animations are limited
  • Animations respect browser frame rate (60fps target)

Next Steps

Common Implementations

  1. Modals - Use patterns.modal for consistent appearance/disappearance
  2. Notifications - Use patterns.notification for toast patterns
  3. Forms - Use confirm presets for success states, danger for errors
  4. Lists - Use entrance.slideUp with staggered delays for list items
  5. Navigation - Use promote.scale for interactive buttons

Testing the System

# Start dev server
npm run dev

# Visit gallery
http://localhost:5173/motion-gallery

# Toggle "Reduced Motion" to test accessibility
# Click "Replay" to review animations repeatedly

References

Questions?

Refer to:

  1. Gallery - /motion-gallery for visual examples
  2. Full Docs - src/lib/MOTION_PRESETS.md for API reference
  3. Examples - Implementation patterns in gallery "Implementation Examples" section