luizhcrocha/design-engineering

Design engineering

Good interfaces are made of many small details that users never notice one by one. Each detail below has a reason. Apply it where the reason applies, and study why the interfaces you admire feel the way they do.

Pick the skill for the job

• One animation to build: animate.
• A diff whose motion needs a verdict: review-animations.
• A codebase's motion to audit and plan: improve-animations. Places that should start moving: find-animation-opportunities. Motion to take out: remove-animations.
• Several elements moving together: choreograph. An animation that drops frames: animation-performance.
• Drag, swipe and sheets on the web: gestures.
• A component to stress-test with worst-case data: break-ui.
• Gestures, springs, materials and type at Apple's level: apple-design.
• A web app that feels wrong on a phone: mobile-native.
• A component library to choose: pick-ui-library.
• Several directions for one piece of UI: prototype.

This skill covers the rest: component polish, and a UI review that looks at more than motion.

Rules that catch most problems

1. Decide whether it should animate at all. An action seen 100 or more times a day, or started from the keyboard, gets no animation.
2. Name exact properties. Never transition: all.
3. Enter and exit with ease-out or a strong custom curve, such as cubic-bezier(0.23, 1, 0.32, 1). Never ease-in on UI.
4. Keep UI animation under 300 ms. A dropdown takes 150 to 250 ms; press feedback takes 100 to 160 ms.
5. Give every pressable element an :active state, such as transform: scale(0.97).
6. Never enter from scale(0). Start from scale(0.95) with opacity: 0.
7. Popovers scale from their trigger (transform-origin: var(--transform-origin) in Base UI). Modals stay centered.
8. Use transitions, not keyframes, for anything a user can trigger again mid-flight. They retarget from the current value.
9. Animate transform and opacity only. In Motion, use the full transform string instead of the x and y shorthands.
10. Honor prefers-reduced-motion with gentler motion, not none, and put hover effects inside @media (hover: hover) and (pointer: fine).

When feel cannot be judged from code, say so. Play the animation at 2 to 5 times its duration or frame by frame in DevTools, test gestures on a real device, and look again the next day.

Review format

A UI review is one markdown table with the columns Before, After and Why, one row per issue. Never write "Before:" and "After:" on separate lines.

Before	After	Why
transition: all 300ms	transition: transform 200ms ease-out	Name the properties; all animates what you did not mean to
transform: scale(0)	transform: scale(0.95); opacity: 0	Nothing in the real world appears from nothing
No :active state on a button	transform: scale(0.97) on :active	A press needs instant feedback

The reference

For a quick fix to a common symptom (jittering numbers, a squished avatar, "1 members"), check references/ui-cheatsheet.md first.

Read references/craft.md for the reasons and the code behind each rule: the animation decision framework, springs, component principles (tooltips, blur over a crossfade, @starting-style), transforms, clip-path patterns (tabs, hold to delete, image reveals, comparison sliders), drag and gesture handling, performance, accessibility, principles for components people love, stagger, debugging, and the review checklist.