Fundamental Animation Principles in emil-design-eng: A Complete Guide

The emil-design-eng skill codifies ten core animation principles—spatial consistency, state indication, explanation, feedback, timing, momentum, interruptibility, and visual harmony—that power the Sonner toast library's polished motion design.

The emil-design-eng skill is the "design + engineering" discipline developed by Emil Kowalski for the emilkowalski/skills repository. It distills the motion patterns behind Sonner (13M+ weekly npm downloads) into reusable principles any React developer can apply to build fluid, responsive interfaces.

The Three Buckets of Animation Thinking

The principles in [skills/emil-design-eng/SKILL.md](https://github.com/emilkowalski/skills/blob/main/skills/emil-design-eng/SKILL.md) cluster into conceptual groups: spatial logic, behavioral feedback, and technical execution.

Spatial & Contextual Principles

Spatial consistency ensures UI elements enter and exit from the same direction. As documented at line 87, this prevents "teleporting" effects that disorient users during swipe-to-dismiss interactions.

Preventing jarring changes (line 91) mandates that elements never appear or disappear without transition. Abrupt visual jumps feel broken; every state change deserves motion.

Behavioral & Communicative Principles

State indication (line 88) uses morphing animations to signal transitions—like a button transforming into a loading spinner. The motion itself conveys meaning before the user reads any text.

Explanation (line 89) employs narrative animation to demonstrate how features work. Instead of static tooltips, motion tells the story.

Feedback (line 90) provides immediate, physical-sounding response to input—a button scaling down on press confirms the interface registered the action.

Technical & Perceptual Principles

Timing & perception (lines 141-143) treats duration and easing as perceived speed controls. Examples from the source: 180ms for select animations, instant tooltips, fast-spinning spinners all feel snappier than their actual clock time.

Momentum & physics (lines 153-155) adds weight and continuity. Components feel "alive" when motion continues naturally after user input stops, mimicking physical objects.

Interruptibility (lines 274-279) ensures animations can be halted or reversed mid-flight. UI remains responsive even when long-running transitions are active.

Gestural interaction (line 156) blends functional gestures with decorative motion—interruptible gestures and mouse-tracking effects keep control in the user's hands.

Visual harmony (lines 645-648) audits four properties: smooth color transitions, consistent easing curves, correct transform-origin points, and synchronized multi-property changes.

Code Examples: Principles in Practice

These React implementations demonstrate how emil-design-eng principles translate to code.

Spatial Consistency: Toast Entry/Exit

import { Transition } from '@headlessui/react';

export const Toast = ({ open, onClose, children }) => (
  <Transition
    show={open}
    enter="transform transition ease-out duration-200"
    enterFrom="-translate-x-full opacity-0"
    enterTo="translate-x-0 opacity-100"
    leave="transform transition ease-in duration-150"
    leaveFrom="translate-x-0 opacity-100"
    leaveTo="-translate-x-full opacity-0"
    as="div"
    className="fixed top-4 right-4"
    afterLeave={onClose}
  >
    {children}
  </Transition>
);

The same -translate-x-full direction for both enterFrom and leaveTo guarantees spatial consistency—users perceive the toast as a single object moving through space.

State Indication: Morphing Button

export const LoadingButton = ({ loading, children }) => (
  <button
    disabled={loading}
    className={`
      px-4 py-2 rounded
      bg-blue-600 text-white
      transition-all duration-200
      ${loading ? 'opacity-50 scale-95' : 'hover:scale-105'}
    `}
  >
    {loading ? <Spinner size={16} /> : children}
  </button>
);

The component morphs between label and spinner states, instantly signaling system status without requiring user attention to read text.

Momentum & Interruptibility: Draggable Card

import { useSpring, animated } from '@react-spring/web';
import { useGesture } from '@use-gesture/react';

export const DraggableCard = () => {
  const [{ x, y }, api] = useSpring(() => ({ x: 0, y: 0 }));
  
  const bind = useGesture({
    onDrag: ({ down, movement: [mx, my], velocity }) => {
      api.start({
        x: down ? mx : 0,
        y: down ? my : 0,
        config: { tension: 300, friction: 30, velocity }
      });
    },
  });

  return (
    <animated.div 
      {...bind()} 
      style={{ x, y }} 
      className="cursor-grab touch-none"
    >
      {/* Card content */}
    </animated.div>
  );
};

The velocity parameter carries momentum past release, while down conditionally snaps or follows—new drags interrupt any in-flight animation immediately.

Related Skills & Resources

The emil-design-eng principles connect to three companion files in the repository:

• skills/animation-vocabulary/SKILL.md — Glossary defining terms used throughout the principles
• skills/animate/SKILL.md — Implementation recipes and practical guidelines
• skills/review-animations/SKILL.md — Audit checklist for evaluating existing components

These four files form a complete knowledge base for designing, implementing, and reviewing animated UI according to the emil-design-eng standard.

Summary

• Spatial consistency and preventing jarring changes establish foundational motion logic
• State indication, explanation, and feedback make animation communicative
• Timing & perception, momentum & physics, interruptibility, and gestural interaction create responsive, physical-feeling interfaces
• Visual harmony provides the audit criteria to ensure cohesive execution
• All principles originate in [skills/emil-design-eng/SKILL.md](https://github.com/emilkowalski/skills/blob/main/skills/emil-design-eng/SKILL.md) and are designed for React + Tailwind implementations

Frequently Asked Questions

Where are the emil-design-eng animation principles documented?

The complete specification lives in skills/emil-design-eng/SKILL.md within the emilkowalski/skills repository. The file organizes principles by concept and provides line-numbered references to specific examples and rationale.

What makes emil-design-eng different from general animation guidelines?

Unlike generic motion principles, emil-design-eng is extracted from production code—specifically the Sonner toast library—and includes precise timing values (180ms, instant tooltips), interruptibility requirements, and React-specific implementation patterns that have been battle-tested at scale.

How does interruptibility work in practice?

According to lines 274-279 of the source, animations must accept new input mid-transition. The draggable card example demonstrates this: starting a new drag immediately cancels any ongoing spring animation, keeping the UI responsive to user intent rather than enforcing completion of obsolete transitions.

What stack are the code examples built for?

The examples use React with Tailwind CSS for styling, Headless UI for transitions, and React Spring with Use Gesture for physics-based interactions—matching the stack employed throughout the Sonner library and the broader emilkowalski ecosystem.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}