agentleFS
muzimu217muzimu217/ui-design-agent-kit/.agents/skills/uak-design-thinking/SKILL.md

uak-design-thinking

Skill23 starsChanged 27 days agoApache-2.0View on GitHub

Design-thinking doctrine for this kit: the animation decision framework (frequency, purpose, easing, duration), component micro-interaction rules (press feedback, origin-aware popovers, interruptible transitions), a reverse-lookup motion glossary ("the bouncy thing when a popover opens" means Pop in), and a curated library-picks table (toasts, charts, drag and drop, virtualization, state, styling). Use for design-engineering polish judgment calls, naming a motion effect the user can only describe, or picking a library for a concrete component task.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask how often users will see it:

    line 38
  2. Distinctive:

    Never animate keyboard-initiated actions.

    line 47
  3. Distinctive:

    Every animation needs a one-line answer to "why does this animate": spatial consistency (enter/exit from the same direction), state …

    line 52
  4. Distinctive:

    Never ease-in for UI entrances: it delays the movement the user is watching.

    line 65
  5. Distinctive:

    Use custom curves; built-in keywords are too weak:

    line 66
  6. Distinctive:

    Keep UI animation under 300ms.

    line 84
  7. Very specific:

    Use springs for drag with momentum, interruptible gestures, and elements that should feel alive.

    line 92
  8. Very specific:

    Never enter from scale(0).

    line 103
  9. Very specific:

    Avoid per-frame CSS variable writes on a shared parent (style recalc on all children).

    line 129

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “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 Thinking(打磨判断 · 动效词汇 · 库选型)

One skill, three narrow jobs. Route by the question being asked, read only the part you need, and record which part informed the decision in the acceptance notes:

QuestionReadNot for
Should this animate, how fast, which easing? Component detail callsPart A belowReplacing a requested critique; broad redesign
"What is this effect called?" (user describes a motion vaguely)references/motion-glossary.mdDesigning or building an effect
"Which library for X?" (toasts, charts, drag and drop, …)references/library-picks.mdReplacing an already-working installed dependency

This skill serves the polish layer of the gate chain: it informs gate C/D artifacts (prototype and contract decisions) and the detail-critique inner loop. It never replaces a user gate: frequency/duration/easing values still go into DESIGN.md and the motion contract for the user to confirm.

Part A · Polish decision framework

A1. Should this animate at all?

Ask how often users will see it:

FrequencyDecision
100+ times/day (keyboard shortcuts, command palette toggle)No animation. Ever.
Tens of times/day (hover effects, list navigation)Remove or drastically reduce
Occasional (modals, drawers, toasts)Standard animation
Rare / first-time (onboarding, celebrations)May add delight

Never animate keyboard-initiated actions; repetition makes any delay feel like lag.

A2. What is the purpose?

Every animation needs a one-line answer to "why does this animate": spatial consistency (enter/exit from the same direction), state indication, explanation, feedback (press scale-down), or preventing jarring changes. "It looks cool" fails when frequency is high.

A3. Which easing?

  • Entering or exiting → ease-out (starts fast, feels responsive).
  • Moving/morphing on screen → ease-in-out.
  • Hover/color change → ease.
  • Constant motion (marquee, progress) → linear.
  • Default → ease-out.

Never ease-in for UI entrances: it delays the movement the user is watching. Use custom curves; built-in keywords are too weak:

--ease-out: cubic-bezier(0.23, 1, 0.32, 1);
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);

A4. How fast?

ElementDuration
Button press feedback100-160ms
Tooltips, small popovers125-200ms
Dropdowns, selects150-250ms
Modals, drawers200-500ms
Marketing/explanatoryMay be longer

Keep UI animation under 300ms. Perceived speed is real speed: a fast-spinning spinner reads as faster loading; instant sibling tooltips after the first one make a whole toolbar feel faster. Make exits faster than entrances, and presses deliberate only when the action itself is deliberate (hold-to-confirm), with release always snappy.

A5. Springs

Use springs for drag with momentum, interruptible gestures, and elements that should feel alive. Recommended parameterization: { type: "spring", duration: 0.5, bounce: 0.2 } (bounce 0.1-0.3, mostly avoid bounce outside playful/drag contexts). Springs carry velocity through interruption — CSS animations restart from zero — which is why rapidly-retargeted UI uses transitions or springs, never keyframes.

A6. Component rules

  • Press feedback: transform: scale(0.97) on :active (range 0.95-0.98) with a ~160ms ease-out transition on transform.
  • Never enter from scale(0); start at scale(0.95) or higher combined with opacity: 0.
  • Origin-aware popovers: scale from the trigger (transform-origin: var(--transform-origin)); modals are the exception and stay centered.
  • Tooltips delay on first hover, then open instantly (zero-duration transition) while moving between siblings.
  • CSS transitions over keyframes for anything rapidly triggered (toasts, state toggles): transitions retarget mid-flight.
  • @starting-style animates entry without JavaScript where supported; fall back to a mounted-attribute pattern.
  • A subtle filter: blur(2px) during crossfades blends two overlapping states into one perceived morph; keep blur under 20px (expensive in Safari).
  • Stagger list entrances 30-80ms per item, never block interaction on the stagger, and keep it decorative.
  • clip-path: inset(...) drives reveals, tab color wipes, hold-to-delete, image reveals, and comparison sliders with a single hardware-accelerated property.
  • Gestures: dismiss on velocity (|distance|/time > ~0.11) not just threshold; damp past boundaries instead of hard stops; capture the pointer on drag start; ignore extra touch points mid-drag.

A7. Performance and accessibility

  • Animate only transform and opacity; layout properties cause jank.
  • Avoid per-frame CSS variable writes on a shared parent (style recalc on all children); write transform on the element.
  • Library shorthand (x, y, scale props) runs on the main thread; the full transform string stays hardware-accelerated. Under load, CSS animations (off-main-thread) beat JS-driven ones; use WAAPI for programmatic control.
  • prefers-reduced-motion means fewer/gentler, not zero: keep opacity and color comprehension cues, remove movement.
  • Gate hover animation behind @media (hover: hover) and (pointer: fine) so touch devices do not get stuck hover states.

A8. Review checklist

IssueFix
transition: allSpecify exact properties
scale(0) entryscale(0.95) + opacity: 0
ease-in on UI elementease-out or custom curve
transform-origin: center on popoverTrigger origin (modals exempt)
Animation on keyboard actionRemove entirely
Duration > 300ms on UI elementReduce to 150-250ms
Hover animation without media queryAdd hover+pointer gate
Keyframes on rapidly-triggered elementCSS transitions
Same enter/exit speedExit faster than enter
Elements appear at onceStagger 30-80ms

Review output uses a single markdown table with Before / After / Why columns, one row per issue.

A9. Cohesion

Match motion personality to the product: playful surfaces may bounce, dense operational dashboards stay crisp and fast. Easing, duration, naming, and visual design should read as one voice — this kit anchors that voice in motion-contract.md presets and the user taste profile; when this part and the contract disagree, the contract and the user's confirmed taste win.

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.