agentleFS
the-hyve-companythe-hyve-company/design-factory-app/skills/emil-design-eng/SKILL.md

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

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-CompanySkill

    capture-learning-tools

    Turn technical conversations, bugs, CI failures, review comments,

    Also in 5 projects that use this

  • The-Vibe-CompanySkill

    design-frontend-dev

    Clean Impeccable frontend design skill. Use when the user wants to

    Also in 5 projects that use this

  • boraoztuncSkill

    pick-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

  • arkanSkill

    review-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

  • boraoztuncSkill

    animation-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

  • emilkowalskiSkill

    ask-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

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
  1. Common:

    When this skill is invoked without a specific question, respond only with:

    line 17
  2. Common:

    Do not provide any other information until the user asks a question.

    line 22
  3. Distinctive:

    When building UI, don't stop at "it works." Look at interfaces you admire, slow their animations down, inspect their interactions, and …

    line 36
  4. Distinctive:

    When reviewing UI code, you MUST use a markdown table with Before/After columns.

    line 54
  5. Common:

    Before writing any animation code, answer these questions in order.

    line 77
  6. Distinctive:

    Avoid animating keyboard-initiated actions.

    line 90
  7. Common:

    Every animation must have a clear answer to "why does this move?" Useful purposes include:

    line 96
  8. Distinctive:

    If the only reason is "it looks cool" and users will see it often, leave it static.

    line 106
  9. Very specific:

    Avoid ease-in on interactive UI.

    line 129
  10. Distinctive:

    Keep interactive UI motion short — generally under ~300ms.

    line 143
  11. Distinctive:

    Keep bounce subtle in most UI (roughly 0.1–0.3), and reserve any noticeable overshoot for playful or drag-to-dismiss interactions.

    line 179
  12. Very specific:

    When two states crossfade and the overlap looks like two separate objects rather than one transforming, a brief, light filter: blur(...) …

    line 255
  13. Distinctive:

    When you scale a button on press, everything inside scales with it.

    line 293
  14. Distinctive:

    Every transform runs from an anchor point that defaults to center.

    line 303
  15. Distinctive:

    When the user drags beyond a natural edge, don't stop dead — let the element keep moving but with rapidly increasing resistance.

    line 346
  16. Distinctive:

    When a drag starts, capture pointer events on the element so the gesture keeps tracking even if the pointer leaves the element's bounds.

    line 352
  17. Distinctive:

    Look at your animations again the next day — you'll catch timing issues you missed while in the flow.

    line 457
  18. Distinctive:

    When several elements enter together, offset each one by a small delay so they cascade rather than appear all at once.

    line 463
  19. Distinctive:

    Keep the per-item delay short (roughly 30–80ms).

    line 490
  20. Distinctive:

    When reviewing UI code, check for:

    line 512

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Design Engineering

Adapted from Emil Kowalski's MIT-licensed emil-design-eng skill (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:

BeforeAfterWhy
transition: all 300mstransition: transform 200ms ease-outName the exact properties; all animates unexpected things
transform: scale(0)transform: scale(0.95); opacity: 0Nothing in the real world appears from nothing
ease-in on a dropdownease-out (or a stronger custom curve)ease-in delays the first frame and feels sluggish
No :active state on a buttontransform: scale(0.97) on :activeA pressable element should react to the press
transform-origin: center on popoverorigin at the trigger anchorAnchored UI should scale from where it opened (modals stay centered)

Wrong format (never do this):

Before: transition: all 300ms
After: transition: transform 200ms ease-out

Correct 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.

FrequencyDecision
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?

ElementDuration
Button press feedback~100–160ms
Tooltips, small popovers~125–200ms
Dropdowns, selects~150–250ms
Modals, drawers~200–400ms
Marketing / explanatoryLonger 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.

  1. Developer experience is the feature. The less setup it takes to adopt — fewer required providers, hooks, and config — the more it gets used.
  2. Defaults matter more than options. Most people never customize, so the out-of-the-box easing, timing, and look should already be excellent.
  3. A memorable name builds identity. A distinctive name can be worth more than a literally descriptive one.
  4. 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.
  5. Use transitions, not keyframes, for dynamic UI. Rapidly added or removed elements retarget smoothly with transitions and restart jarringly with keyframes.
  6. 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-origin making 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:

IssueFix
transition: allName exact properties, e.g. transition: transform 200ms ease-out
scale(0) entryStart from scale(0.95) with opacity: 0
ease-in on interactive UISwitch to ease-out or a stronger custom curve
transform-origin: center on a popoverSet to the trigger anchor (modals stay centered)
Animation on a keyboard actionRemove the animation
Duration > 300ms on interactive UIReduce to ~150–250ms
Hover animation without a media queryGate behind @media (hover: hover) and (pointer: fine)
Keyframes on a rapidly-triggered elementUse CSS transitions for interruptibility
Per-frame updates to inherited CSS varsWrite transform directly on the moving element
Symmetric enter/exit timingMake the response/release snappier than the deliberate action
Elements all appearing at onceAdd a short stagger (30–80ms between items)

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.