Skip to content
Back to search

ui-motion-principles

AI agent skill to audit & polish web UI against 20 motion principles & UX laws. For Claude Code, Gemini CLI, Cursor, and skills.sh.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jigneshis--ui-motion-principles/badge.svg)](/listings/jigneshis--ui-motion-principles)

HTML

<a href="/listings/jigneshis--ui-motion-principles"><img src="/api/listings/jigneshis--ui-motion-principles/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Via [skills.sh](https://skills.sh) / `skills` CLI (Universal)

Works across dozens of AI assistants:

npx skills add jigneshis/ui-motion-principles

2. Claude Code

Install directly or activate via slash command:

npx skills add jigneshis/ui-motion-principles -a claude-code

Inside Claude Code:

/ui-motion-principles

3. Gemini CLI

gemini skills install https://github.com/jigneshis/ui-motion-principles --path skills/ui-motion-principles

Activate by asking: > *"Use the ui-motion-principles skill to audit my site's UI."*

4. Cursor & Windsurf

Drop this repository into your workspace, or copy `.cursor/rules/ui-motion-principles.mdc` into your project's `.cursor/rules/` directory.

5. Manual Installation

Copy the `skills/ui-motion-principles/` directory into your agent's skills location: - Claude Code: `~/.claude/skills/ui-motion-principles/` - Gemini CLI: `~/.gemini/skills/ui-motion-principles/` - Universal Agent Path: `.agents/skills/ui-motion-principles/`

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 243 lines
  1. # UI Motion Principles
  2. <p align="center">
  3. <a href="https://skills.sh/jigneshis/ui-motion-principles/ui-motion-principles">
  4. <img src="https://img.shields.io/badge/skills.sh-ui--motion--principles-111111?style=for-the-badge&logo=vercel&logoColor=white" alt="skills.sh registry" />
  5. </a>
  6. <a href="https://www.npmjs.com/package/skills">
  7. <img src="https://img.shields.io/badge/npx%20skills-add%20jigneshis%2Fui--motion--principles-000000?style=for-the-badge&logo=npm" alt="npx skills install" />
  8. </a>
  9. <a href="LICENSE">
  10. <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License" />
  11. </a>
  12. <a href="https://github.com/jigneshis/ui-motion-principles/stargazers">
  13. <img src="https://img.shields.io/github/stars/jigneshis/ui-motion-principles?style=for-the-badge&color=gold" alt="GitHub Stars" />
  14. </a>
  15. </p>
  16. <p align="center">
  17. <strong>An open-source AI agent skill that audits your web or mobile UI against 20 classic animation principles and UX laws, announces a defensible plan with concrete values, waits for your approval, and applies the code fixes.</strong>
  18. </p>
  19. <p align="center">
  20. Works with <strong>Claude Code</strong>, <strong>Gemini CLI</strong>, <strong>Cursor</strong>, <strong>Windsurf</strong>, <strong>Antigravity</strong>, and any assistant supporting the <a href="https://skills.sh">Agent Skills specification</a>.
  21. </p>
  22. ---
  23. ## Why UI Motion Principles?
  24. Most AI-generated animations look generic or sluggish—defaulting to `transition: all 0.3s ease`, scaling modals from screen center, or animating high-frequency interactions that should feel instantaneous.
  25. **UI Motion Principles** brings intentionality back to modern frontend interfaces:
  26. - **Defensible Decisions:** Every transition explains *what happened* and *where it came from*.
  27. - **Grounded Physics:** Origin awareness, anticipatory nudges, non-linear easing curves, and natural spring dampening.
  28. - **Cognitive Ergonomics:** Guided by classic UX laws (Doherty threshold, Fitts's law, Hick's law, Von Restorff effect, peak-end rule).
  29. - **Zero Surprises:** Strict **Audit ➔ Announce ➔ Approve ➔ Apply** workflow. The agent will **never** edit your code without your approval.
  30. ---
  31. ## The 4-Stage Workflow
  32. ```mermaid
  33. flowchart LR
  34. A[1. Audit] -->|Inspects UI source code & live DOM| B[2. Announce]
  35. B -->|Defensible plan with values & easings| C[3. Approve]
  36. C -->|Zero edits before explicit OK| D[4. Apply]
  37. D -->|Framework-native fixes in your stack| E[Done]
  38. ```
  39. 1. **Audit:** Reads your component code, Tailwind configuration, CSS, and animation definitions. If a live URL is provided and browser tools are active, inspects real runtime interactions.
  40. 2. **Announce:** Lists each proposed change as `I will apply [principle] to [place]: [change]` with exact values (durations in ms, cubic-bezier curves, target sizes in px).
  41. 3. **Approve:** Pauses and waits for your review. You decide whether to apply all changes, select a subset, or adjust the plan.
  42. 4. **Apply:** Implements only approved changes using your project's existing libraries (Tailwind, Framer Motion, Vanilla CSS, etc.) without introducing bloat.
  43. ---
  44. ## Quick Install
  45. ### 1. Via [skills.sh](https://skills.sh) / `skills` CLI (Universal)
  46. Works across dozens of AI assistants:
  47. ```bash
  48. npx skills add jigneshis/ui-motion-principles
  49. ```
  50. ### 2. Claude Code
  51. Install directly or activate via slash command:
  52. ```bash
  53. npx skills add jigneshis/ui-motion-principles -a claude-code
  54. ```
  55. Inside Claude Code:
  56. ```text
  57. /ui-motion-principles
  58. ```
  59. ### 3. Gemini CLI
  60. ```bash
  61. gemini skills install https://github.com/jigneshis/ui-motion-principles --path skills/ui-motion-principles
  62. ```
  63. Activate by asking:
  64. > *"Use the ui-motion-principles skill to audit my site's UI."*
  65. ### 4. Cursor & Windsurf
  66. Drop this repository into your workspace, or copy `.cursor/rules/ui-motion-principles.mdc` into your project's `.cursor/rules/` directory.
  67. ### 5. Manual Installation
  68. Copy the `skills/ui-motion-principles/` directory into your agent's skills location:
  69. - Claude Code: `~/.claude/skills/ui-motion-principles/`
  70. - Gemini CLI: `~/.gemini/skills/ui-motion-principles/`
  71. - Universal Agent Path: `.agents/skills/ui-motion-principles/`
  72. ---
  73. ## The 20 Principles at a Glance
  74. ### 13 Animation Principles
  75. | Principle | Core Rule | Typical Recipe |
  76. | :--- | :--- | :--- |
  77. | **Origin Awareness** | Elements emerge from their trigger, not screen center | `transform-origin: top left;` or anchor position |
  78. | **Anticipation** | Brief preparatory motion before the main action fires | Scale `0.97` on `:active` button click |
  79. | **Squash & Stretch** | Compress along collision axis; expand perpendicular | 5–8% deformation scale; preserve volume |
  80. | **Slow In, Slow Out** | Natural acceleration & deceleration; eliminate linear ease | `cubic-bezier(0.16, 1, 0.3, 1)` for entrances |
  81. | **Arcs** | Multi-axis translations bow along curved trajectories | Split x/y durations or independent easings |
  82. | **Timing** | Duration scales with distance travelled & perceived mass | Tokens: `120ms` (fast), `200ms` (base), `320ms` (slow) |
  83. | **Exaggeration** | Push critical beats beyond realism for immediate legibility | Error shake (3–4 oscillations of 6–10px over 300ms) |
  84. | **Follow Through** | Moving elements overshoot slightly and settle naturally | Spring physics: `stiffness: 400, damping: 28` |
  85. | **Secondary Action** | Subtle accompanying motion that reinforces primary action | Checkmark path draw during button fill |
  86. | **Staggering** | Sequential entrance cascade for lists and grids | 20–60ms delay per child; total cap < 400ms |
  87. | **Rubber Banding** | Elastic boundary resistance at limits rather than hard stop | Overscroll / sheet drag resistance damping (0.3–0.5) |
  88. | **Interruptible Motion** | Mid-flight animations retarget immediately on new input | CSS transitions over fixed keyframes; velocity springs |
  89. | **Solid Drawing** | Physically consistent light source, elevation, and radii | Elevation-matched `box-shadow` + directional Y lift |
  90. ### 6 UX Laws & The Golden Frequency Rule
  91. | UX Law | Impact on UI Design | Guideline |
  92. | :--- | :--- | :--- |
  93. | **Frequency of Use** | *The Master Override Rule.* Repetition breeds fatigue | High-frequency: ≤100ms or instant. Low-frequency: expressive |
  94. | **Doherty Threshold** | Response budget < 400ms maintains conversational flow | Immediate feedback (<100ms); optimistic UI over spinners |
  95. | **Fitts's Law** | Target acquisition speed = distance / target size | Touch targets ≥ 44×44px (iOS) / 48×48px (Material) |
  96. | **Hick's Law** | Decision time increases with number of options | Group choices; progressive disclosure; recommend 1 default |
  97. | **Von Restorff Effect** | Distinct items command attention and memory | Single primary CTA per view; preserve accent contrast |
  98. | **Peak-End Rule** | Users judge experiences by peak intensity and conclusion | Invest delight budget in success states and flow completion |
  99. ---
  100. ## Conflict Resolution Hierarchy
  101. When principles collide, resolve them using this strict priority order:
  102. ```text
  103. Accessibility (prefers-reduced-motion, contrast, tap targets)
  104. └── Frequency of Use (high-frequency actions beat decorative flourish)
  105. └── Doherty Threshold (speed budget beats prolonged animation)
  106. └── Hick's & Fitts's Laws (reduce choices, then make key actions large)
  107. └── Von Restorff Effect (baseline calm before emphasis)
  108. └── Animation Aesthetics (timing, arcs, springs)
  109. ```
  110. ---
  111. ## Example Before & After
  112. ### Generic Unconsidered Button
  113. ```css
  114. /* ❌ Sluggish, linear, ungrounded */
  115. .button {
  116. transition: all 0.3s ease;
  117. }
  118. .button:hover {
  119. opacity: 0.8;
  120. }
  121. ```
  122. ### Intentional UI Motion Principles
  123. ```css
  124. /* ✅ Tactile, responsive, physically grounded */
  125. .button {
  126. transform-origin: center;
  127. transition: transform 120ms cubic-bezier(0.2, 0.8, 0.2, 1),
  128. box-shadow 160ms cubic-bezier(0.16, 1, 0.3, 1),
  129. background-color 140ms ease;
  130. }
  131. .button:hover {
  132. transform: translateY(-1px);
  133. box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
  134. }
  135. .button:active {
  136. /* Anticipation & Squash */
  137. transform: translateY(0px) scale(0.98);
  138. box-shadow: 0 2px 4px rgba(0, 0, 0, 0.04);
  139. }
  140. @media (prefers-reduced-motion: reduce) {
  141. .button { transition: none; transform: none; }
  142. }
  143. ```
  144. ---
  145. ## Example Prompts
  146. Copy-paste any of these prompts into your agent:
  147. ```text
  148. Audit the checkout form in src/components/Checkout.tsx with ui-motion-principles.
  149. Focus on Fitts's law tap targets and the Doherty threshold.
  150. ```
  151. ```text
  152. Use ui-motion-principles to review our mobile navigation drawer.
  153. Check origin awareness, rubber banding, and interruptibility.
  154. ```
  155. ```text
  156. Review our pricing table using Hick's law and the Von Restorff effect.
  157. Propose concrete visual hierarchy adjustments before editing.
  158. ```
  159. ```text
  160. Check the dropdown menus and modals in src/components/Nav.tsx.
  161. Ensure origin awareness and natural spring easing curves.
  162. ```
  163. ---
  164. ## Generative Engine Optimization (GEO) & Machine Access
  165. This repository adheres to the `llms.txt` standard for automated indexing by AI agents and LLM search engines:
  166. - [`/llms.txt`](llms.txt) — Concise overview and endpoint manifest for LLM crawlers.
  167. - [`/llms-full.txt`](llms-full.txt) — Comprehensive consolidated documentation and reference recipes for direct agent context loading.
  168. ---
  169. ## Repository Structure
  170. ```
  171. .
  172. ├── .cursor/rules/
  173. │ └── ui-motion-principles.mdc # Cursor IDE rule configuration
  174. ├── .github/workflows/
  175. │ └── validate.yml # Automated skill structure validation
  176. ├── skills/
  177. │ └── ui-motion-principles/
  178. │ ├── SKILL.md # Core agent instructions & workflow
  179. │ └── references/
  180. │ ├── motion.md # The 13 animation principles + CSS/Framer recipes
  181. │ └── ux-laws.md # The 6 UX laws & conflict resolution rules
  182. ├── CONTRIBUTING.md # Guidelines for contributing new recipes
  183. ├── LICENSE # MIT License
  184. ├── README.md # Project documentation
  185. ├── SECURITY.md # Security disclosures
  186. ├── llms.txt # AI context index
  187. └── llms-full.txt # Full reference corpus for LLMs
  188. ```
  189. ---
  190. ## Contributing
  191. We welcome community contributions! Please read our [Contributing Guide](CONTRIBUTING.md) to add framework recipes for Svelte, Vue, React Native, or SwiftUI.
  192. ---
  193. ## License
  194. [MIT](LICENSE) © [jigneshis](https://github.com/jigneshis)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.