How emilkowalski/skills Handles Complex UI Animation Sequences: A Complete Design-First Workflow

The emilkowalski/skills repository encodes a complete markdown-based workflow that manages complex UI animation sequences through strict design standards, automated review skills, and systematic prototyping capabilities.

Managing intricate motion in modern interfaces requires more than just implementation code—it demands a systematic approach to validation and iteration. The emilkowalski/skills repository provides a comprehensive framework for handling complex UI animation sequences through opinionated markdown-based "skills" that guide both human developers and AI agents through every stage of animation engineering. Rather than containing executable animation libraries, this repository defines the rules, review processes, and prototyping workflows necessary to implement purposeful, performant motion.

Design-First Standards in STANDARDS.md

All animation decisions in the emilkowalski/skills workflow originate from STANDARDS.md, which establishes non-negotiable craft rules for motion design. These standards ensure that every animation serves a specific purpose while respecting performance and accessibility constraints.

Duration Constraints and Frequency-Based Motion

According to STANDARDS.md, every animation must stay under 300 ms to maintain interface responsiveness. The standards enforce a frequency-based motion hierarchy: actions used more than 100 times per day receive no animation, while occasional actions like modals and toasts receive standard animation treatments. This approach prevents motion fatigue in high-frequency interactions while preserving feedback for important state changes.

Accessibility and Input Modality Requirements

The standards mandate strict prefers-reduced-motion support for all animations and gate hover effects behind @media (hover: hover) and (pointer: fine). This prevents motion-triggered accessibility issues on touch devices and ensures that hover-dependent animations only activate on appropriate input modalities.

Automated Review with review-animations SKILL

The review-animations SKILL provides diff-level inspection that enforces standards compliance automatically, acting as a gatekeeper for animation quality.

Purpose-Driven Motion Validation

Every animation must declare a clear purpose from predefined categories: spatial consistency, state indication, feedback, or similar justifications. The reviewer flags any motion lacking explicit purpose documentation, ensuring that complex UI animation sequences are never gratuitous.

Technique Selection Guidance

The skill enforces appropriate technique selection based on motion characteristics:

• CSS transitions for interruptible motion
• CSS keyframes for deterministic sequences that can run off the main thread
• Framer Motion (via the motion library) for spring-based or layout animations

Auditing and Improvement Workflows

Beyond reactive review, the repository provides proactive skills for codebase improvement and technical debt remediation.

Severity-Based Categorization in improve-animations

The improve-animations SKILL performs comprehensive codebase scans using greps for transition, animation, @keyframes, motion., and useSpring. It categorizes findings by severity (HIGH, MEDIUM, LOW) based on impact. For example, using ease-in easing on a UI dropdown receives HIGH severity because it creates perceived sluggishness that degrades user experience.

Self-Contained Execution Plans

Violations generate remediation plans following PLAN-TEMPLATE.md, which provides deterministic implementation instructions including exact CSS/JS snippets. These plans are designed for execution by less-capable models without additional context, ensuring that audit findings translate directly into fixes.

Prototyping Complex Sequences

The prototype SKILL and PICKER.md define a systematic approach to visual iteration that validates animation choices before production implementation.

The Picker UI Pattern

The prototype system renders multiple component variants (toasts, cards, buttons) full-size in realistic contexts. Developers define variants as an array of components, and the picker displays them for immediate visual comparison, ensuring that complex sequences meet design intent.

Instant Variant Switching and Replay Logic

Following the frequency rule, switching between variants occurs instantly without animation. When a variant includes entrance animations, a replay button remounts the component to restart the animation sequence, enabling side-by-side comparison without introducing motion pollution during the selection process.

Implementation Techniques for Complex Sequences

The repository guides implementation of complex multi-step sequences through two primary technical approaches documented in the pick-ui-library SKILL.

For deterministic sequences that can run off the main thread, use CSS keyframes:

/* File: component.css */
.item {
  opacity: 0;
  transform: translateY(8px);
  animation: fadeIn 300ms ease-out forwards;
}
.item:nth-child(2) { animation-delay: 50ms; }
.item:nth-child(3) { animation-delay: 100ms; }

/* Keyframe definition */
@keyframes fadeIn {
  to { opacity: 1; transform: none; }
}

For dynamic, interruptible, or spring-based behavior, use Framer Motion:

import { motion } from "motion";

export const Toggle = () => (
  <motion.button
    whileTap={{ scale: 0.9 }}
    animate={{ rotate: isOn ? 180 : 0 }}
    transition={{ type: "spring", stiffness: 300, damping: 20 }}
  >
    {isOn ? "On" : "Off"}
  </motion.button>
);

The prototyping system enables rapid iteration on these implementations:

import { ProtoPicker } from "./PICKER";

const variants = [
  { name: "Default", component: <ToastDefault /> },
  { name: "Slide‑In", component: <ToastSlideIn /> },
  { name: "Fade‑In", component: <ToastFadeIn /> },
];

export const ToastPrototype = () => (
  <ProtoPicker variants={variants} />
);

Summary

• The emilkowalski/skills repository handles complex UI animation sequences through markdown-based skills rather than executable code libraries.
• STANDARDS.md enforces strict 300ms duration limits, frequency-based motion rules, and mandatory prefers-reduced-motion accessibility support.
• The review-animations SKILL validates diffs against standards, ensuring every animation has justified purpose and uses appropriate technical techniques.
• improve-animations performs codebase audits with severity categorization (HIGH, MEDIUM, LOW) and generates self-contained execution plans via PLAN-TEMPLATE.md.
• The prototype SKILL and PICKER.md enable rapid visual iteration with instant variant switching and component remounting for animation replay.
• Complex sequences should use CSS keyframes for deterministic, off-main-thread motion or Framer Motion for spring-based, interruptible animations.

Frequently Asked Questions

What is the maximum duration allowed for UI animations in emilkowalski/skills?

According to STANDARDS.md, all UI animations must stay under 300 milliseconds. This rule ensures that interface motion feels responsive and doesn't impede user workflow, particularly for frequently accessed actions where motion could create fatigue.

How does the review-animations SKILL determine which animation technique to use?

The SKILL enforces a specific technique mapping based on motion requirements: CSS transitions for interruptible state changes, CSS keyframes for deterministic sequences, and Framer Motion (via the motion library) for spring physics or layout animations. The reviewer flags violations when complex sequences use inappropriate techniques, such as keyframes for interruptible user interactions.

What happens when the improve-animations SKILL finds inappropriate easing functions?

The SKILL categorizes such findings by severity—using ease-in on UI elements like dropdowns typically receives HIGH severity because it creates a sluggish feel that violates the responsive motion principle. The audit generates a concrete remediation plan following PLAN-TEMPLATE.md with exact code replacements and integration steps.

How does the prototype system handle animation replay without violating the frequency rules?

The PICKER.md specification requires variant switching to be instant (no animation) to respect the frequency-based motion guidelines. For entrance animations, a dedicated replay button remounts the component entirely, restarting the animation sequence only when explicitly requested and preventing motion pollution during visual comparison.

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