Design Motion Principles: an audit mode for AI-generated interface animation

Three lenses that are supposed to disagree

design-motion-principles is a motion and interaction design skill with two modes, build or audit, and the design idea at its centre is that motion taste is not a single thing.

The skill applies three distinct motion-design philosophies, weighted by your project's context. Each lens has a named guiding question and a stated best fit.

Emil Kowalski's lens is restraint and speed, its question is Should this animate at all?, and it is aimed at productivity tools and high-frequency interactions. Jakub Krehel's lens is production polish, its question is Is this subtle enough?, and it fits shipped consumer apps and professional refinement. Jhey Tompkins's lens is creative experimentation, its question is What could this become?, and it is aimed at kids apps, portfolios and playful contexts.

The reasoning behind having three is stated more directly than most design writing manages. The point is not a single set of rules, it is the productive tension between three lenses that genuinely disagree. The example given is that Emil would cut an animation Jhey would add. So the skill weights the lenses to your context rather than applying one philosophy everywhere.

That is a genuinely different approach from a motion guideline document, which usually resolves its internal disagreements by picking a house style and calling it a principle. Here the disagreements are preserved and made into the mechanism.

The skill is distilled from the publicly published work of Emil Kowalski, Jakub Krehel and Jhey Tompkins, and it carries a detailed credits section naming each designer's site, courses and open source projects.

Build mode produces components, audit mode produces a report

The two modes are the visible part of the skill, and the skill detects which one you want from your request, asking if it is ambiguous.

Create mode builds interactive components with motion baked in. It runs a light discovery covering the project context and which lenses to weight, then generates the component in React, Framer Motion, CSS or HTML, applying the right recipes along with accessibility and performance defaults.

Audit mode reviews existing motion design, and its workflow is longer. It does reconnaissance on your project, runs a motion-gap analysis, checks the code against the anti-AI-slop checklist, proposes a per-lens weighting, and delivers the report.

The motion gap analysis is the part that looks for motion that should be there and is not. It searches for conditional UI that should be animated but is not, specifically conditional renders without AnimatePresence, dynamic styles without transitions, and instant state swaps. Those are the three patterns that make an interface feel like it is teleporting between states.

The default audit output is a branded HTML report, a self-contained file with auto-looping CSS demos beside each Critical and Important finding, so you can see the recommended motion instead of reading code. It writes to motion-audits/ and opens in your browser. Passing --terminal falls back to an inline markdown report for headless and CI use.

The example output shows the discovery step in practice. For a kids educational app, a mobile-first PWA with spring animations at 500 to 600 milliseconds and framer-motion, it reports 4 motion gaps, which are conditional renders without AnimatePresence, and proposes Jakub Krehel as primary for production polish, Jhey Tompkins as secondary for playful experimentation, and Emil Kowalski as selective for high frequency game interactions. Then it asks whether that weighting looks right before proceeding.

The anti-AI-slop checklist with frequency heuristics

The checklist is the part of the skill that reads as a response to a specific and current problem, and it is worth describing precisely because the frequency heuristic is what makes it usable.

It is described as a quality gate that flags the recognizable motion fingerprints of AI-generated interfaces. The listed categories are pulsing indicators, blur-everywhere entrances, hover-scale-on-everything, stagger-spam, bouncy springs on utility actions, uniform fade-ins, and motion-on-mount for static content.

Every one of those is a defensible choice in isolation. A pulsing indicator is exactly right for a recording state. A scale transition on a card is a legitimate design choice. The problem is the pattern, where the same motion decision gets applied to everything because the model reached for it by default.

That is what the frequency heuristic is for. Each category has one, so a single intentional use does not trip the gate. Without it, the checklist would flag every pulse and every scale, and a rule you have to ignore every time is a rule that does not get followed.

There is a matching set of creation gotchas for the other mode, described as a built-in self-check against the common failure modes of AI-generated motion. Those are the specific implementation mistakes rather than the taste-level ones: decorative-by-default animation, scale(0) starts, bare ease, and a missing prefers-reduced-motion query.

The distinction between the two lists is useful. The gotchas are things a code reviewer can check mechanically. The slop categories are judgements about frequency and context, which is why they are heuristics rather than rules.

The file layout is a router plus a reference library

The repository is small, with only a CHANGELOG.md, a LICENSE, a README.md and a skills/ directory at the top level, and everything lives under skills/design-motion-principles/.

SKILL.md at the root of the skill is the router, handling mode detection and the shared principles. Under workflows/ there are two files, create.md for building interactive components and audit.md for reviewing existing motion design. Everything else is under references/.

The references directory is where the substance sits. motion-cookbook.md is described as a single consolidated recipe library and the single source of truth, covering enter and exit animations, easing, springs, clip-path, @property, shared-layout and FLIP, and scroll-driven animation. creation-gotchas.md holds the failure modes when generating motion, audit-checklist.md the structured audit criteria, and anti-checklist.md the quality gate with its AI-slop categories and anti-patterns.

Then there are the implementation templates. demo-shell.html is a minimal single-card template for the demos in the HTML report, and report-template.html is a full worked-example audit report serving as the output reference. output-format.md covers the report template for both the HTML and terminal modes.

The three lens files, emil-kowalski.md, jakub-krehel.md and jhey-tompkins.md, each hold that designer's philosophy and decision frameworks. Then accessibility.md covers motion accessibility guidelines, and performance.md covers performance best practices.

That structure is deliberate in a way worth noting. The cookbook is a single file rather than several, which means a lookup of how to do a particular animation is one read rather than an index of indexes. And the lens files being separate means the weighting mechanism can swap the guidance without rewriting it.

Installing it into whichever assistant you use

The installation is a single command, and it uses the skills CLI rather than a package manager of its own:

npx skills add kylezantos/design-motion-principles

That installs the skill for Claude Code, Cursor, Windsurf and other AI coding assistants, and once installed you just ask in natural language. To build, the examples are requests like adding a polished enter and exit animation to a modal, or building an animated toast component for a dashboard. To audit, the request is something like auditing the motion design in a codebase or reviewing the animations in a component.

If you would rather not use the CLI, the manual route is a clone plus a copy:

git clone https://github.com/kylezantos/design-motion-principles.git
cp -r design-motion-principles/skills/design-motion-principles ~/.claude/skills/

And for Cursor the target directory differs:

cp -r design-motion-principles/skills/design-motion-principles ~/.cursor/skills/

The copy target is the assistant's own skills directory, which is the mechanism assistants use to discover prompt material. Nothing is compiled and nothing is linked, because the deliverable is a set of markdown instructions and two HTML templates that the assistant reads when it is doing motion work.

The package version is 2.1.0, released on 2026-05-21, with a title that describes the release as HTML audit reports and the anti-AI-slop checklist. Before that came 2.0.0 for Create mode and the dual-mode skill, and 1.2.0 for structural cleanup and progressive disclosure, so the project has moved quickly through a small number of substantial versions.

The licence is MIT and the repository is not archived, with the last push on 2026-05-30.

What this is not, and where the boundaries are

The clearest thing to say about this project is what it is not. It is not a motion design system. There are no components, no tokens, no easing library and no build step. The deliverable is prompt material that an AI assistant reads and applies while it writes or reviews code.

That distinction matters because the quality bar is different. A component library can be tested, versioned and depended on. A skill is a set of instructions whose output quality depends on the model following them and on your codebase, and whose behaviour changes when the underlying model changes. The skill itself cannot be unit tested in any meaningful sense.

The second boundary is the audit output. The HTML report with auto-looping CSS demos is a genuinely good artifact for a design conversation, because a designer can react to a demo in a way they cannot react to a line of CSS. But it is a report, not a patch. Nothing in the audit mode changes your code, and the report's findings are only as good as the reconnaissance behind them. The gap analysis looks for specific patterns such as conditional renders without AnimatePresence, which means it will find gaps of that shape reliably and will not find a motion problem that does not match one of the listed patterns.

The third is the credit line, and it is unusually well handled. The skill is an interpretation and distillation of motion-design principles from the publicly published work of the three designers, and the credits section states that the three-lens weighting framework and the "through X's lens" framing are the skill's own synthesis, named in tribute. It also states plainly that the skill is not authored or endorsed by the designers listed, and points to their actual work. That is the correct way to build on other people's ideas, and it means you should not describe the output as approved by them.

One more practical limitation: the weights are proposed, not derived. The skill asks whether the weighting looks right before it proceeds, which is a good checkpoint, but the mapping from project type to lens is the author's judgement, and the example output shows it being applied to a kids app without any explanation of how that mapping was reached.

Editorial conclusion

design-motion-principles is a good pick for a team that ships AI-assisted interface code and has noticed the same fingerprints in every generated component, because the anti-AI-slop checklist with frequency heuristics gives you a way to say that a pulsing indicator is fine in one place and wrong in three, and the HTML audit report lets a designer argue from demos rather than from a diff; it is the wrong pick if you want a motion design system with components and tokens, since this is prompt material rather than a library, and before you install it you should read the credits section, because the three-lens framing is the author's own synthesis built on other people's published work and is explicitly not endorsed by them.

Frequently asked questions

Official sources

1. Issues
2. kylezantos/design-motion-principles on GitHub
3. License: MIT
4. README
5. Releases