Animation Decision Framework in the Skills Repository: A 7-Step Gate-Based Process

The animation decision framework is a rigorous, step-by-step gate-based process defined in skills/animate/SKILL.md that determines whether UI elements should animate, what properties to use, and how to implement them to pass strict code review standards.

This framework serves as the single source of truth for all motion decisions in the emilkowalski/skills repository. It provides senior design engineers with a systematic approach to evaluating animation necessity, selecting appropriate technical implementations, and ensuring accessibility compliance before any code reaches production.

The 7-Step Gate-Based Evaluation Process

The framework operates as a sequential decision tree where early gates can halt the process entirely. According to the source documentation, "Steps 1 and 2 gate everything"—if either fails, the skill stops immediately and returns a non-animated fallback.

Step 1: Evaluate Usage Frequency

The first gate examines how often users interact with the UI element per day. High-frequency actions—such as keyboard shortcuts used 100+ times daily—must never animate. Low-frequency or first-time interactions receive a "delight" budget permitting motion.

Step 2: Define the Functional Purpose

If frequency permits animation, the engineer must select one predefined intent word: Feedback, Spatial consistency, State indication, Prevent jarring change, Explanation, or Delight. This requirement guarantees that every animation has a functional rationale rather than existing merely because "it looks cool."

Step 3: Select the Cheapest Appropriate Tool

The framework mandates a specific hierarchy for implementation technology. Engineers must choose the first tool in this sequence that satisfies the requirement:

1. CSS transition
2. CSS @starting-style
3. CSS animation
4. Web Animations API (WAAPI)
5. Motion library

This progression prevents needless library bloat and keeps implementations as lightweight as possible.

Step 4: Restrict to GPU-Accelerated Properties

Performance constraints limit valid animated properties to transform and opacity, with optional clip-path. The framework strictly prohibits animating layout-affecting properties such as width, height, or margin, ensuring all motion remains GPU-accelerated.

Step 5: Apply Standardized Easing and Duration

The framework provides lookup tables for motion parameters. Enter and exit animations use ease-out; hover states use ease. Duration tables specify ranges like 150–250ms for dropdowns. For gesture-based interactions, engineers substitute these values with spring configurations using the Motion library.

Step 6: Plan for Interruption and Exit Behavior

Engineers must design for mid-animation interruption. CSS transitions handle rapidly-triggered UI best, while springs suit gesture interactions. The framework requires that exit animations reverse the entrance transform exactly, guaranteeing predictable, interrupt-friendly motion.

Step 7: Implement Reduced-Motion and Pointer Gating

Every animation must ship with accessibility guards: a prefers-reduced-motion media query variant and @media (hover: hover) checks for hover-dependent styles. These are not afterthoughts—they are mandatory components of the initial implementation.

Hard Rules Enforcing the Framework

Beyond the sequential gates, three immutable rules govern all animation code in the repository:

• No approximated values — Every curve, duration, or spring configuration must come directly from the framework's tables.
• Extend existing tokens — Reuse established variables like --ease-out or tokenized durations; never create parallel timing systems.
• Accessibility ships with the animation — Reduced-motion variants and hover gating must be included in the initial pull request, not added later.

Integration with the Skills Ecosystem

The animation decision framework does not exist in isolation. It functions as the central protocol coordinating multiple specialized skills:

• skills/animate/SKILL.md — The producer skill that generates motion code following the framework.
• skills/review-animations/SKILL.md — The consumer skill that enforces the same gates during code review, rejecting implementations that skip steps.
• skills/improve-animations/SKILL.md — Audits existing codebases against framework rules, flagging approximated values or missing accessibility guards.
• skills/find-animation-opportunities/SKILL.md — Uses the "purpose" list from Step 2 to identify UI elements that lack motion but meet the criteria for it.

This architecture ensures the framework acts as the definitive reference across all motion-related work in the repository.

Practical Implementation Examples

Example 1: Dropdown Animation (Full Framework Compliance)

This CSS implementation follows Steps 3 through 7, having passed the frequency check (occasional use) and purpose selection (spatial consistency) in earlier gates:

/* Tool: CSS transition (Step 3)
   Properties: transform + opacity (Step 4)
   Easing: ease-out, 200ms (Step 5)
   Exit: Reverse transform (Step 6)
   Reduced-motion: Included (Step 7) */
.dropdown {
  transform: translateY(-4px);
  opacity: 0;
  transition: transform 200ms var(--ease-out),
              opacity 200ms var(--ease-out);
}

.dropdown[data-open] {
  transform: translateY(0);
  opacity: 1;
}

@media (prefers-reduced-motion: reduce) {
  .dropdown {
    transition: none;
    opacity: 1;
  }
}

Example 2: Keyboard Shortcut Blocked at Gate 1

When handling a high-frequency keyboard shortcut (Cmd+K used 100+ times daily), the framework halts after Step 1:

// Frequency check: High-frequency keyboard shortcut
// Framework decision: No animation. Ever.
function togglePanel() {
  panel.hidden = !panel.hidden; // Instant state change only
}

The skill returns a short rationale documenting why motion was rejected and falls back to instant state toggling.

Example 3: Gesture-Based Spring Animation

For drag-to-dismiss interactions, the framework progresses through the tool hierarchy to Motion (Step 3) and selects spring physics (Step 5):

import { animate } from "motion";

function startDismissDrag(node) {
  // Gesture detected → Motion library selected
  // Spring configuration for natural feel
  animate(node, { y: 0 }, {
    type: "spring",
    bounce: 0.2,
    duration: 0.5,
  });
}

Summary

• The animation decision framework lives in skills/animate/SKILL.md and provides a 7-step gate-based process for evaluating UI motion.
• Steps 1 and 2 (frequency and purpose) act as hard gates that can block animation entirely.
• The framework enforces a strict tool hierarchy (CSS → WAAPI → Motion) and restricts properties to transform and opacity for GPU acceleration.
• Accessibility requirements including prefers-reduced-motion and hover gating are mandatory, not optional.
• Related skills (review-animations, improve-animations, find-animation-opportunities) consume and enforce this framework across the repository.

Frequently Asked Questions

Where is the animation decision framework documented?

The complete framework is defined in skills/animate/SKILL.md within the emilkowalski/skills repository. This file contains the full decision trees, easing tables, duration specifications, and hard rules. Supplementary implementations for common components (dropdowns, toasts, modals) reside in skills/animate/RECIPES.md.

What stops an animation from being approved under this framework?

Two primary gates block animation: high usage frequency (elements used many times per day, like keyboard shortcuts) and lack of functional purpose (animations that don't serve Feedback, Spatial consistency, State indication, Prevent jarring change, Explanation, or Delight). Additionally, violating hard rules—such as using approximated timing values instead of tokenized durations or omitting reduced-motion guards—results in rejection during the review-animations phase.

How does the framework handle accessibility concerns?

Accessibility is integrated at Step 7 of the decision process and enforced through hard rules. Every animation must include a prefers-reduced-motion media query that provides an instant state change alternative, and @media (hover: hover) guards for hover-dependent effects. These measures ensure users with vestibular disorders or pointer precision limitations receive a fully functional, non-motion interface.

Which animation tools does the framework recommend and in what order?

The framework mandates selecting the cheapest tool that works from this ordered hierarchy: CSS transitions first, then CSS @starting-style, followed by CSS animations, then the Web Animations API (WAAPI), and finally the Motion library only for complex gestures requiring springs. This sequence prevents unnecessary JavaScript bundles and keeps animations performant by defaulting to CSS-based solutions.

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