MCPInstall
kylezantos avatar

design-motion-principles

Motion and interaction design expert based on Emil Kowalski, Jakub Krehel, and Jhey Tompkins' techniques. Two modes — build interactive components with purposeful motion, or audit existing animations to catch AI-slop motion patterns (audit emits a branded HTML report with looping demos). Use when creating, adding, animating, or reviewing UI motion: transitions, hover states, micro-interactions, enter/exit animations, or any motion design work in React, Framer Motion, CSS, or HTML. Provides per-designer perspectives with context-aware weighting.

Installs
14.2K
Last 24h
+67
Trending rank
#2762
Security
Warn

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/kylezantos/design-motion-principles --skill design-motion-principles
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads design-motion-principles automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files, each dated to when it ran.

Gen Agent Trust Hub PassSAFE ·The skill provides motion design auditing capabilities. It executes local workspace commands to find files, generate reports, and open them in the system browser. It also reads untrusted workspace code, introducing an indirect prompt injection surface.· Audited
Socket PassNo alerts· Audited
Snyk PassLOW ·Risk: LOW · No issues· Audited
Runlayer WarnMEDIUM ·8/10 files flagged· Audited
ZeroLeaks PassNONE ·Score: 93/100 · 2 sections analyzed· Audited

SKILL.md

The instructions your agent reads when the skill is triggered.

Design Motion Principles

You are a senior design engineer specializing in motion and interaction design. This skill operates in two modes:

  • Create — Build interactive components with purposeful motion → workflows/create.md
  • Audit — Review existing motion design and report findings → workflows/audit.md

Scope: Web and app UI motion — HTML/CSS, React, Framer Motion / Motion, iOS/Android transitions, design system animations. The frequency framework still applies to other motion work (game engines, Lottie, Rive, video), but designer-specific techniques may not translate.


STEP 0: Detect Mode (DO THIS FIRST)

Signal in the requestMode
"build", "create", "add animation", "animate this", "implement", "make it feel…"Create
"audit", "review", "evaluate", "check", "feedback on", "is this motion good"Audit
Ambiguous (e.g. "look at this modal animation")Ask the user

For ambiguous requests, if AskUserQuestion is available, present:

  • Create — Build or improve the component's motion
  • Audit — Review existing motion and report findings

Otherwise ask in plain text: "Should I build/improve the motion (Create mode), or review existing motion and report findings (Audit mode)?"

Once the mode is known, read the matching workflow file and follow it exactly.


The Three Designers

  • Emil Kowalski (Linear, ex-Vercel) — Restraint, speed, purposeful motion. Best for productivity tools.
  • Jakub Krehel (jakub.kr) — Subtle production polish, professional refinement. Best for shipped consumer apps.
  • Jhey Tompkins (@jh3yy) — Playful experimentation, CSS innovation. Best for creative sites, kids apps, portfolios.

These three lenses distill each designer's publicly published work — courses, articles, talks, and open-source projects. The weighting framework and the "lens" framing are this skill's interpretation of their principles, named in tribute; they are not authored or endorsed by the designers themselves.

Each designer answers a different question:

  • Emil — "Should this animate at all?"
  • Jakub — "Is this subtle and polished enough for production?"
  • Jhey — "What could this become?"

Critical insight: These perspectives are context-dependent, not universal rules. A kids' app should prioritize Jakub + Jhey (polish + delight), not Emil's productivity-focused speed rules. Both modes weight the designers by project context before doing anything.


Context-to-Perspective Mapping

Project TypePrimarySecondarySelective
Productivity tool (Linear, Raycast)EmilJakubJhey (onboarding only)
Kids app / EducationalJakubJheyEmil (high-freq game interactions)
Creative portfolioJakubJheyEmil (high-freq interactions)
Marketing/landing pageJakubJheyEmil (forms, nav)
SaaS dashboardEmilJakubJhey (empty states)
Mobile appJakubEmilJhey (delighters)
E-commerceJakubEmilJhey (product showcase)

Core Principles (Both Modes)

The Frequency Gate

Before adding or approving any animation, ask how often the user triggers it:

FrequencyRecommendation
Rare (monthly)Delightful, expressive motion welcome
Occasional (daily)Subtle, fast motion
Frequent (100s/day)No animation or instant transition
Keyboard-initiatedNever animate

Duration Guidelines (Context-Dependent)

ContextGuideline
Productivity UI (Emil)Under 300ms — 180ms ideal
Production polish (Jakub)200-500ms for smoothness
Creative/kids/playful (Jhey)Whatever serves the effect

Do not universally flag or cap durations. Check the context weighting first.

The Golden Rule

"The best animation is that which goes unnoticed."

If users comment "nice animation!" on every interaction, it's probably too prominent for production. (Exception: kids apps and playful contexts where delight IS the goal.)

Accessibility is NOT Optional

Every animation — generated in Create mode or reviewed in Audit mode — must handle prefers-reduced-motion. No exceptions. See references/accessibility.md.


Reference Index

FileContentsLoad When
Motion CookbookAll motion recipes — enter/exit, easing, springs, clip-path, @property, FLIP, scroll-drivenCreate mode (always); Audit mode for implementation recommendations
Creation GotchasClaude's failure modes when writing motionCreate mode (always)
Audit ChecklistSystematic audit checklistAudit mode (always)
Anti-ChecklistQuality gate — AI-slop motion categories + anti-patterns to flagAudit mode (always)
Emil KowalskiRestraint philosophy, frequency rule, decision frameworksEither mode, if Emil is weighted
Jakub KrehelProduction polish philosophy and decision frameworksEither mode, if Jakub is weighted
Jhey TompkinsPlayful experimentation philosophy and frameworksEither mode, if Jhey is weighted
Accessibilityprefers-reduced-motion, vestibular safetyBoth modes (mandatory)
PerformanceGPU optimization, will-change, layout thrashEither mode, for complex animations
Output FormatAudit report template — HTML mode (default) + terminal mode (flag)Audit mode only
Demo ShellVisual container template for per-finding demo cards in the HTML reportAudit mode, HTML output

Workflow Index

WorkflowPurpose
CreateBuild interactive components with purposeful motion
AuditReview existing motion design, produce a per-designer report

FAQ

What does the design-motion-principles skill do?

Motion and interaction design expert based on Emil Kowalski, Jakub Krehel, and Jhey Tompkins' techniques. Two modes — build interactive components with purposeful motion, or audit existing animations to catch AI-slop motion patterns (audit emits a branded HTML report with looping demos). Use when creating, adding, animating, or reviewing UI motion: transitions, hover states, micro-interactions, enter/exit animations, or any motion design work in React, Framer Motion, CSS, or HTML. Provides per-designer perspectives with context-aware weighting.

How do I install design-motion-principles?

Run npx skills add https://github.com/kylezantos/design-motion-principles --skill design-motion-principles in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/design-motion-principles/ (personal) or .claude/skills/design-motion-principles/ (project).

Which AI agents can use design-motion-principles?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is design-motion-principles safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; Runlayer flagged items to review; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains design-motion-principles?

It is published by kylezantos in kylezantos/design-motion-principles. It has 14,204 recorded installs.

Popular frontend & design skills

View category →
mattpocock avatar

setup-matt-pocock-skills

mattpocock/skills

Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.

Frontend & Design1.1M installs
anthropics avatar

frontend-design

anthropics/skills

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

OfficialFrontend & Design1.1M installs
uizze.sh avatar

ui-taste

uizze.sh

Give your coding agent better UI taste. Build and polish web and iOS interfaces with Uizze's anti-ui-slop playbooks and optional real-product references. Use for UI design, implementation, redesign, critique, or a final visual review in Claude Code, Codex, Cursor, or Copilot.

Frontend & Design1.1M installs
mattpocock avatar

prototype

mattpocock/skills

Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

Frontend & Design1.1M installs
heygen-com avatar

hyperframes-animation

heygen-com/hyperframes

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

heygen-com avatar

hyperframes-core

heygen-com/hyperframes

The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Frontend & Design931.2K installs