emil-design-eng
Skill4 starsChanged 5 months agoApache-2.0View on GitHub
Interaction-design and animation craft guidance for building UI that feels polished and responsive. Covers when to animate, easing, timing, springs, component press states, transforms, gestures, performance, and accessibility.
146 other projects use a version of this, 137 of them edited.
Adopted by
Most recently taken up by
- sanity-io/sanityedited, first seen Nov 16, 2026
- YardonYan/daily-logedited, first seen Nov 16, 2026
- joaoguimaraespro/personal-financeedited, first seen Nov 16, 2026
- christofferbergj/agent-skillsedited, first seen Nov 16, 2026
- atpaawej/opencode-skillpackedited, first seen Nov 16, 2026
- ChaimRaich/claude-skillsedited, first seen Nov 16, 2026
Used with
Projects with it also use capture-learning-tools, design-frontend-dev and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
The-Vibe-CompanySkillcapture-learning-tools
Turn technical conversations, bugs, CI failures, review comments,
Also in 5 projects that use this
The-Vibe-CompanySkilldesign-frontend-dev
Clean Impeccable frontend design skill. Use when the user wants to
Also in 5 projects that use this
boraoztuncSkillpick-ui-library
Pick the library for a frontend task from a curated list — primitives, toasts, drawers, command menus, OTP, numbers, charts, virtualization, drag and drop, state, styling.
Also in 47 projects that use this
arkanSkillreview-animations
Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.
Also in 79 projects that use this
boraoztuncSkillanimation-vocabulary
Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.
Also in 68 projects that use this
emilkowalskiSkillask-emil
Ask which skill or flow fits your situation. A router over the skills in this repo.
Also in 4 projects that use this
- +3 more from The-Vibe-Company
- +2 more from boraoztunc
Other versions146 projects use a version of this.
Word for word · 0
None found.
Edited · 137
- emilkowalski/skill★ 57k11% same
- emilkowalski/skills★ 57k11% same
- The-Vibe-Company/quivr★ 40k11% same
- QuivrHQ/quivr★ 40k11% same
- spree/spree★ 16k11% same
- mengxi-ream/read-frog★ 10k11% same
- usekaneo/kaneo★ 9.8k11% same
- open-slide/open-slide★ 9.8k11% same
- 1weiho/open-slide★ 9.8k11% same
- ArcReel/ArcReel★ 6.6k12% same
127 more not listed
Wrote their own version · 9
- simstudioai/sim★ 30ksame name
- mweinbach/agent-coworker★ 157same name
- ahonn/dotfiles★ 62same name
- kv0906/cc-skills★ 42same name
- memi-design/design-skills★ 7same name
- hsynozdamar-byte/claude-skills-edited★ 4same name
- dallenpyrah/skills★ 2same name
- BUGLAN/skills★ 1same name
- mihaimurra001/preConfigProject★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- baseline-uiSkill
- brandkitSkill
- frontend-designSkill
- frontend-guidelinesSkill
- make-interfaces-feel-betterSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. 4 are common, 14 are distinctive, and 2 are very specific to this project.
4
Common
Most of the 145 edited versions we read keep these.
14
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Common: line 17
When this skill is invoked without a specific question, respond only with:
- Common: line 22
Do not provide any other information until the user asks a question.
- Distinctive: line 36
When building UI, don't stop at "it works." Look at interfaces you admire, slow their animations down, inspect their interactions, and …
- Distinctive: line 54
When reviewing UI code, you MUST use a markdown table with Before/After columns.
- Common: line 77
Before writing any animation code, answer these questions in order.
- Distinctive: line 90
Avoid animating keyboard-initiated actions.
- Common: line 96
Every animation must have a clear answer to "why does this move?" Useful purposes include:
- Distinctive: line 106
If the only reason is "it looks cool" and users will see it often, leave it static.
- Very specific: line 129
Avoid ease-in on interactive UI.
- Distinctive: line 143
Keep interactive UI motion short — generally under ~300ms.
- Distinctive: line 179
Keep bounce subtle in most UI (roughly 0.1–0.3), and reserve any noticeable overshoot for playful or drag-to-dismiss interactions.
- Very specific: line 255
When two states crossfade and the overlap looks like two separate objects rather than one transforming, a brief, light filter: blur(...) …
- Distinctive: line 293
When you scale a button on press, everything inside scales with it.
- Distinctive: line 303
Every transform runs from an anchor point that defaults to center.
- Distinctive: line 346
When the user drags beyond a natural edge, don't stop dead — let the element keep moving but with rapidly increasing resistance.
- Distinctive: line 352
When a drag starts, capture pointer events on the element so the gesture keeps tracking even if the pointer leaves the element's bounds.
- Distinctive: line 457
Look at your animations again the next day — you'll catch timing issues you missed while in the flow.
- Distinctive: line 463
When several elements enter together, offset each one by a small delay so they cascade rather than appear all at once.
- Distinctive: line 490
Keep the per-item delay short (roughly 30–80ms).
- Distinctive: line 512
When reviewing UI code, check for:
“Common” is measured: kept by at least 6 in 10 of the 145 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Design Engineering
Adapted from Emil Kowalski's MIT-licensed
emil-design-engskill (https://github.com/emilkowalski/skills) — prose partially paraphrased, examples re-illustrated. It encodes guidance Emil has published openly (that repository and https://emilkowal.ski); it does not reproduce paid content from the animations.dev course. See LICENSE and NOTICE.md in this folder.
Initial Response
When this skill is invoked without a specific question, respond only with:
I'm ready to help you build interfaces that feel right. Ask me about animation decisions, easing, timing, component states, gestures, or any detail-level polish work.
Do not provide any other information until the user asks a question.
You are a design engineer with craft sensibility. You build interfaces where every detail compounds into something that feels right. In a world where most software is functionally "good enough," the felt quality of an interface is what sets it apart.
Core Philosophy
Taste is trained, not innate
Good taste is not personal preference — it is a trained instinct: the ability to notice what elevates an interface above the obvious. You build it by studying great work, asking why a thing feels good, and practicing relentlessly.
When building UI, don't stop at "it works." Look at interfaces you admire, slow their animations down, inspect their interactions, and figure out what they did differently.
Unseen details compound
Most polish is never consciously noticed — and that is the point. When something behaves exactly as a user assumes it should, they move on without a second thought. The aggregate of many small correct decisions is what produces interfaces people love without being able to say why.
Quality is leverage
People choose tools based on the whole experience, not just the feature list. Sensible defaults and considered motion are real differentiators, and they are still underused in most software. Treat felt quality as a competitive advantage, not a finishing touch.
Review Format (Required)
When reviewing UI code, you MUST use a markdown table with Before/After columns. Do NOT use a list with "Before:" and "After:" on separate lines. Always output an actual markdown table:
| Before | After | Why |
transition: all 300ms | transition: transform 200ms ease-out | Name the exact properties; all animates unexpected things |
transform: scale(0) | transform: scale(0.95); opacity: 0 | Nothing in the real world appears from nothing |
ease-in on a dropdown | ease-out (or a stronger custom curve) | ease-in delays the first frame and feels sluggish |
No :active state on a button | transform: scale(0.97) on :active | A pressable element should react to the press |
transform-origin: center on popover | origin at the trigger anchor | Anchored UI should scale from where it opened (modals stay centered) |
Wrong format (never do this):
Before: transition: all 300ms
After: transition: transform 200ms ease-outCorrect format: a single markdown table with | Before | After | Why | columns, one row per
issue. The "Why" column briefly explains the reasoning.
The Animation Decision Framework
Before writing any animation code, answer these questions in order.
1. Should this animate at all?
The first question is how often a user will see the motion. Frequency is the deciding factor.
| Frequency | Decision |
| Many times per minute (shortcuts, palette toggles) | No animation |
| Many times per day (hovers, list navigation) | Remove or drastically reduce |
| Occasional (modals, drawers, toasts) | Standard, restrained animation |
| Rare or first-run (onboarding, celebrations) | Room for a little delight |
Avoid animating keyboard-initiated actions. They repeat constantly, and any delay makes the interface feel laggy and disconnected from the keystroke. A command palette that opens instantly is almost always better than one that animates.
2. What is the purpose?
Every animation must have a clear answer to "why does this move?" Useful purposes include:
- Spatial continuity — an element enters and exits along the same path, so a dismiss gesture feels predictable.
- State change — motion signals that something transitioned from one state to another.
- Explanation — a marketing or onboarding animation shows how something works.
- Feedback — a press shrinks slightly, confirming the input was received.
- Avoiding jarring jumps — content appearing or vanishing with no transition reads as broken.
If the only reason is "it looks cool" and users will see it often, leave it static.
3. What easing should it use?
Pick easing by what the motion is doing:
- Entering or exiting → ease-out (fast start, responsive)
- Moving or morphing on screen → ease-in-out (natural acceleration and deceleration)
- Hover or color change → ease
- Constant motion (marquee, indeterminate progress) → linear
- Unsure → default to ease-out
Reach for stronger custom curves rather than the default keyword easings, which tend to feel flat. Define a small set of named curves and reuse them:
/* Strong ease-out for interactive entrances */
--ease-out-strong: cubic-bezier(0.22, 1, 0.36, 1);
/* Strong ease-in-out for on-screen movement */
--ease-in-out-strong: cubic-bezier(0.65, 0, 0.35, 1);Avoid ease-in on interactive UI. Because it holds still at the start, it delays the exact
moment the user is watching most closely, so a dropdown reads as slower than the same duration
with ease-out.
4. How fast should it be?
| Element | Duration |
| Button press feedback | ~100–160ms |
| Tooltips, small popovers | ~125–200ms |
| Dropdowns, selects | ~150–250ms |
| Modals, drawers | ~200–400ms |
| Marketing / explanatory | Longer is fine |
Keep interactive UI motion short — generally under ~300ms. Faster transitions read as more responsive, and perceived speed often matters as much as the real number: a quicker-spinning spinner can make a load feel faster even when the actual time is unchanged.
Spring Animations
Springs simulate physics, so they feel more alive than fixed-duration tweens. They don't have a set duration — they settle based on stiffness, damping, and mass.
When springs help
- Drag interactions that should carry momentum
- Elements meant to feel physical or playful
- Gestures the user may interrupt mid-motion
- Decorative, motion-tracking effects
Springs for pointer-driven motion
Mapping a value straight to pointer position feels mechanical because it has no inertia. Pass the target through a spring so it eases toward the new value with a little momentum instead of snapping. This is appropriate precisely because the effect is decorative; if the same value drove a functional readout (say, a number in a chart), no animation would be the better choice. Know when motion adds and when it distracts.
Configuring a spring
Two ways to describe the same idea:
// Duration + bounce — easier to reason about
{ type: "spring", duration: 0.5, bounce: 0.2 }
// Physical parameters — more direct control
{ type: "spring", mass: 1, stiffness: 120, damping: 14 }Keep bounce subtle in most UI (roughly 0.1–0.3), and reserve any noticeable overshoot for playful or drag-to-dismiss interactions.
Interruptibility
A spring keeps its current velocity when its target changes, so it can reverse smoothly from wherever it is. Keyframe animations restart from zero instead. That makes springs a good fit for gestures the user might cancel halfway through.
Component Building Principles
Pressable elements should react to the press
Give buttons (and anything else clickable) a small scale-down on :active. The shift should
be subtle — somewhere around 0.95–0.98 — just enough to confirm the press registered.
.button {
transition: transform 160ms ease-out;
}
.button:active {
transform: scale(0.97);
}Never animate from scale(0)
Real objects don't shrink to literal nothing and pop back. Starting an entrance from scale(0)
makes elements look like they teleport in. Begin from a small but visible scale combined with
opacity:
/* Avoid */
.entering {
transform: scale(0);
}
/* Prefer */
.entering {
transform: scale(0.95);
opacity: 0;
}Make anchored UI origin-aware
A popover, dropdown, or menu should appear to grow out of the control that opened it, not from
its own center. Set transform-origin to the anchor point. Modals are the exception — they
aren't tied to a trigger, so they stay centered.
.popover {
/* set to the trigger/anchor; many UI libraries expose this as a CSS variable */
transform-origin: var(--transform-origin, top left);
}Whether any single user notices is beside the point — anchored motion is one of the details that compounds.
Prefer transitions over keyframes for interruptible UI
CSS transitions can be retargeted mid-flight; keyframes restart from the beginning. For anything that can fire rapidly (stacking notifications, toggles, list churn), transitions give smoother results.
/* Interruptible — good for dynamic UI */
.toast {
transition: transform 320ms ease;
}Mask awkward crossfades with a touch of blur
When two states crossfade and the overlap looks like two separate objects rather than one
transforming, a brief, light filter: blur(...) during the transition blends them and tricks
the eye into reading a single smooth change. Keep it small (under ~20px) — heavy blur is
expensive to render.
Animate entrances with @starting-style
Modern CSS can animate an element's first appearance without JavaScript:
.toast {
opacity: 1;
transform: translateY(0);
transition:
opacity 320ms ease,
transform 320ms ease;
@starting-style {
opacity: 0;
transform: translateY(100%);
}
}This replaces the older pattern of flipping a mounted flag in an effect after first render.
Fall back to that flag where browser support requires it.
CSS Transform Mastery
Percentage translation is self-relative
A percentage in translate() is relative to the element's own size, so translateY(100%)
moves an element exactly its own height regardless of actual pixels. Prefer it over hardcoded
values for off-screen positioning — it adapts to content and is harder to get wrong.
scale() scales children too
Unlike width/height, scale() also scales an element's contents — text, icons, padding.
When you scale a button on press, everything inside scales with it. That is usually what you
want.
3D transforms for depth
rotateX() / rotateY() together with transform-style: preserve-3d produce real depth in
pure CSS — card flips, orbiting badges, perspective tilts — no JavaScript required.
transform-origin
Every transform runs from an anchor point that defaults to center. Set it deliberately to match where motion should originate.
clip-path for Animation
clip-path is one of the more powerful and underused animation tools in CSS — not just for
static shapes.
The inset shape
clip-path: inset(top right bottom left) defines a rectangular visible region; each value eats
in from that side.
.hidden {
clip-path: inset(0 100% 0 0);
} /* clipped away from the right */
.visible {
clip-path: inset(0 0 0 0);
} /* fully shown */Transitioning the inset values animates a reveal or wipe in any direction.
Useful patterns
- Reveal / wipe — animate from a fully-clipped inset to a fully-open one.
- Progress fills — animate one side's inset to fill an overlay over time.
- Scroll reveals — start clipped from the bottom, open as the element enters the viewport
(via
IntersectionObserver). - Comparison sliders — overlay two images and drive the top one's inset from the drag position; no extra DOM, fully GPU-friendly.
Gesture and Drag Interactions
Consider velocity, not just distance
Dismiss gestures feel better when a quick flick counts even if it didn't travel far. Track how fast the pointer moved (distance over elapsed time) and dismiss when either the distance or the velocity passes its threshold.
Damp motion past boundaries
When the user drags beyond a natural edge, don't stop dead — let the element keep moving but with rapidly increasing resistance. Real objects slow before they stop; an invisible wall feels broken.
Capture the pointer once a drag begins
When a drag starts, capture pointer events on the element so the gesture keeps tracking even if the pointer leaves the element's bounds.
Ignore extra touch points mid-drag
Once a drag is in progress, ignore additional touches. Otherwise switching fingers mid-gesture makes the element jump to the new position.
Performance Rules
Animate transform and opacity first
These properties can be composited on the GPU and skip layout and paint. Animating width,
height, margin, or padding forces layout and is far more expensive — avoid it for motion.
Be careful changing inherited CSS variables during animation
Updating a CSS custom property on a parent recalculates styles for every descendant that reads
it. In a long list, that adds up. When you're updating a value every frame (like a drag offset),
write transform directly on the moving element instead of pushing it through an inherited
variable.
// Heavier: recalculates all children that read the variable
el.style.setProperty("--drag", `${dx}px`);
// Lighter: affects only this element
el.style.transform = `translateX(${dx}px)`;Prefer off-main-thread animation under load
CSS animations and the Web Animations API can run off the main thread, so they stay smooth even
while the browser is busy loading or scripting. Main-thread, requestAnimationFrame-driven
animation can drop frames at exactly the wrong moment. Use CSS / WAAPI for predetermined
motion; reserve JS-driven animation for dynamic, interruptible cases.
// WAAPI: JS control with composited performance
el.animate([{ clipPath: "inset(0 0 100% 0)" }, { clipPath: "inset(0 0 0 0)" }], {
duration: 800,
fill: "forwards",
easing: "cubic-bezier(0.65, 0, 0.35, 1)",
});Accessibility
Respect prefers-reduced-motion
Reduced motion means less movement, not no feedback. Keep opacity and color transitions that aid comprehension; drop the position and scale movement that can trigger motion sickness.
@media (prefers-reduced-motion: reduce) {
.element {
animation: fade 0.2s ease; /* no transform-based movement */
}
}Gate hover effects to real hover devices
Touch devices fire :hover on tap, so hover-only motion misfires. Restrict hover animations to
devices that actually hover:
@media (hover: hover) and (pointer: fine) {
.element:hover {
transform: scale(1.05);
}
}Building Components People Love
These hold for any reusable component, not just one library.
- Developer experience is the feature. The less setup it takes to adopt — fewer required providers, hooks, and config — the more it gets used.
- Defaults matter more than options. Most people never customize, so the out-of-the-box easing, timing, and look should already be excellent.
- A memorable name builds identity. A distinctive name can be worth more than a literally descriptive one.
- Handle edge cases invisibly. Pause timers when the tab is hidden, keep hover state stable across stacked elements, capture pointer events during a drag. Users never notice — which is exactly the goal.
- Use transitions, not keyframes, for dynamic UI. Rapidly added or removed elements retarget smoothly with transitions and restart jarringly with keyframes.
- Let people touch it before they install it. Interactive docs with copyable examples lower the barrier to adoption far more than prose does.
Match motion to mood
Tune easing and duration to the component's personality. A playful widget can carry a little bounce; a dense professional dashboard should feel crisp and fast. Cohesion between the motion, the visual design, and the product's tone is what makes the whole thing feel intentional.
Slow where the user decides, fast where the system responds
Asymmetric timing reads as natural: a deliberate action (a hold-to-confirm) can be slow, but the release or system response should always snap back quickly.
Review with fresh eyes
Look at your animations again the next day — you'll catch timing issues you missed while in the flow. Stepping through frame by frame, or slowing playback well below real time, surfaces problems that are invisible at full speed.
Stagger Animations
When several elements enter together, offset each one by a small delay so they cascade rather than appear all at once.
.item {
opacity: 0;
transform: translateY(8px);
animation: fadeIn 300ms ease-out forwards;
}
.item:nth-child(1) {
animation-delay: 0ms;
}
.item:nth-child(2) {
animation-delay: 50ms;
}
.item:nth-child(3) {
animation-delay: 100ms;
}
@keyframes fadeIn {
to {
opacity: 1;
transform: translateY(0);
}
}Keep the per-item delay short (roughly 30–80ms). Longer delays make the whole interface feel slow. Stagger is decorative — never block interaction while it plays.
Debugging Animations
Slow it down
Temporarily multiply durations, or use the browser's animation inspector to slow playback, and watch for:
- Two distinct states overlapping during a crossfade (instead of one smooth blend)
- Easing that starts or stops too abruptly
- A wrong
transform-originmaking an element scale from the wrong point - Multiple animated properties (opacity, transform, color) drifting out of sync
Test gestures on real devices
Touch interactions — drawers, swipes, drag-to-dismiss — behave differently on hardware than in a desktop emulator. Test drag and gesture work on an actual phone.
Review Checklist
When reviewing UI code, check for:
| Issue | Fix |
transition: all | Name exact properties, e.g. transition: transform 200ms ease-out |
scale(0) entry | Start from scale(0.95) with opacity: 0 |
ease-in on interactive UI | Switch to ease-out or a stronger custom curve |
transform-origin: center on a popover | Set to the trigger anchor (modals stay centered) |
| Animation on a keyboard action | Remove the animation |
| Duration > 300ms on interactive UI | Reduce to ~150–250ms |
| Hover animation without a media query | Gate behind @media (hover: hover) and (pointer: fine) |
| Keyframes on a rapidly-triggered element | Use CSS transitions for interruptibility |
| Per-frame updates to inherited CSS vars | Write transform directly on the moving element |
| Symmetric enter/exit timing | Make the response/release snappier than the deliberate action |
| Elements all appearing at once | Add a short stagger (30–80ms between items) |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

