tribunal-kit 4.5.1 → 4.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (214) hide show
  1. package/.agent/.shared/ui-ux-pro-max/README.md +4 -4
  2. package/.agent/ARCHITECTURE.md +282 -277
  3. package/.agent/agents/accessibility-reviewer.md +187 -187
  4. package/.agent/agents/ai-code-reviewer.md +199 -199
  5. package/.agent/agents/api-architect.md +71 -66
  6. package/.agent/agents/backend-specialist.md +219 -215
  7. package/.agent/agents/cloud-engineer.md +98 -0
  8. package/.agent/agents/code-archaeologist.md +168 -161
  9. package/.agent/agents/database-architect.md +184 -184
  10. package/.agent/agents/db-latency-auditor.md +213 -216
  11. package/.agent/agents/debugger.md +198 -191
  12. package/.agent/agents/dependency-reviewer.md +106 -103
  13. package/.agent/agents/devops-engineer.md +218 -218
  14. package/.agent/agents/documentation-writer.md +209 -201
  15. package/.agent/agents/explorer-agent.md +167 -160
  16. package/.agent/agents/frontend-reviewer.md +162 -160
  17. package/.agent/agents/frontend-specialist.md +257 -248
  18. package/.agent/agents/game-developer.md +48 -48
  19. package/.agent/agents/logic-reviewer.md +118 -116
  20. package/.agent/agents/mobile-developer.md +197 -200
  21. package/.agent/agents/mobile-reviewer.md +159 -162
  22. package/.agent/agents/orchestrator.md +187 -181
  23. package/.agent/agents/penetration-tester.md +160 -157
  24. package/.agent/agents/performance-optimizer.md +183 -183
  25. package/.agent/agents/performance-reviewer.md +178 -178
  26. package/.agent/agents/precedence-reviewer.md +251 -250
  27. package/.agent/agents/product-manager.md +149 -142
  28. package/.agent/agents/product-owner.md +81 -80
  29. package/.agent/agents/project-planner.md +152 -142
  30. package/.agent/agents/qa-automation-engineer.md +216 -225
  31. package/.agent/agents/resilience-reviewer.md +88 -88
  32. package/.agent/agents/schema-reviewer.md +67 -67
  33. package/.agent/agents/security-auditor.md +180 -174
  34. package/.agent/agents/seo-specialist.md +188 -193
  35. package/.agent/agents/sql-reviewer.md +159 -161
  36. package/.agent/agents/supervisor-agent.md +173 -184
  37. package/.agent/agents/swarm-worker-contracts.md +170 -166
  38. package/.agent/agents/swarm-worker-registry.md +92 -92
  39. package/.agent/agents/system-architect.md +85 -0
  40. package/.agent/agents/test-coverage-reviewer.md +158 -160
  41. package/.agent/agents/test-engineer.md +118 -118
  42. package/.agent/agents/throughput-optimizer.md +291 -299
  43. package/.agent/agents/type-safety-reviewer.md +182 -175
  44. package/.agent/agents/ui-ux-auditor.md +300 -292
  45. package/.agent/agents/vitals-reviewer.md +223 -223
  46. package/.agent/mcp_config.json +37 -40
  47. package/.agent/patterns/generator.md +11 -9
  48. package/.agent/patterns/inversion.md +14 -12
  49. package/.agent/patterns/pipeline.md +11 -9
  50. package/.agent/patterns/reviewer.md +15 -13
  51. package/.agent/patterns/tool-wrapper.md +11 -9
  52. package/.agent/routing_index.json +714 -0
  53. package/.agent/rules/GEMINI.md +359 -352
  54. package/.agent/scripts/compile_router.py +112 -0
  55. package/.agent/scripts/migrate_skills_frontmatter.py +64 -0
  56. package/.agent/scripts/strengthen_skills.js +1 -1
  57. package/.agent/skills/advanced-rag-pipelines/SKILL.md +56 -0
  58. package/.agent/skills/agent-organizer/SKILL.md +156 -150
  59. package/.agent/skills/agentic-patterns/SKILL.md +313 -315
  60. package/.agent/skills/ai-prompt-injection-defense/SKILL.md +190 -184
  61. package/.agent/skills/api-patterns/SKILL.md +253 -247
  62. package/.agent/skills/api-security-auditor/SKILL.md +195 -193
  63. package/.agent/skills/app-builder/SKILL.md +573 -572
  64. package/.agent/skills/app-builder/templates/SKILL.md +108 -115
  65. package/.agent/skills/app-builder/templates/astro-static/TEMPLATE.md +76 -76
  66. package/.agent/skills/app-builder/templates/chrome-extension/TEMPLATE.md +92 -92
  67. package/.agent/skills/app-builder/templates/cli-tool/TEMPLATE.md +88 -88
  68. package/.agent/skills/app-builder/templates/electron-desktop/TEMPLATE.md +88 -88
  69. package/.agent/skills/app-builder/templates/express-api/TEMPLATE.md +83 -83
  70. package/.agent/skills/app-builder/templates/flutter-app/TEMPLATE.md +90 -90
  71. package/.agent/skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md +90 -90
  72. package/.agent/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +126 -122
  73. package/.agent/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +127 -122
  74. package/.agent/skills/app-builder/templates/nextjs-static/TEMPLATE.md +172 -169
  75. package/.agent/skills/app-builder/templates/nuxt-app/TEMPLATE.md +139 -134
  76. package/.agent/skills/app-builder/templates/python-fastapi/TEMPLATE.md +83 -83
  77. package/.agent/skills/app-builder/templates/react-native-app/TEMPLATE.md +122 -119
  78. package/.agent/skills/appflow-wireframe/SKILL.md +146 -145
  79. package/.agent/skills/architecture/SKILL.md +226 -219
  80. package/.agent/skills/authentication-best-practices/SKILL.md +197 -189
  81. package/.agent/skills/backend-security-expert/SKILL.md +16 -2
  82. package/.agent/skills/bash-linux/SKILL.md +179 -179
  83. package/.agent/skills/behavioral-modes/SKILL.md +239 -223
  84. package/.agent/skills/brainstorming/SKILL.md +498 -486
  85. package/.agent/skills/browser-native-ai/SKILL.md +57 -4
  86. package/.agent/skills/building-native-ui/SKILL.md +202 -202
  87. package/.agent/skills/cicd-pro/SKILL.md +442 -0
  88. package/.agent/skills/clean-code/SKILL.md +400 -381
  89. package/.agent/skills/cloud-architect/SKILL.md +439 -0
  90. package/.agent/skills/code-review-checklist/SKILL.md +203 -194
  91. package/.agent/skills/config-validator/SKILL.md +165 -165
  92. package/.agent/skills/containerization-pro/SKILL.md +452 -0
  93. package/.agent/skills/csharp-developer/SKILL.md +518 -518
  94. package/.agent/skills/data-validation-schemas/SKILL.md +333 -328
  95. package/.agent/skills/database-design/SKILL.md +247 -240
  96. package/.agent/skills/deployment-procedures/SKILL.md +172 -169
  97. package/.agent/skills/devops-engineer/SKILL.md +345 -345
  98. package/.agent/skills/devops-incident-responder/SKILL.md +143 -137
  99. package/.agent/skills/documentation-templates/SKILL.md +291 -279
  100. package/.agent/skills/edge-computing/SKILL.md +183 -181
  101. package/.agent/skills/emil-design-eng/SKILL.md +147 -0
  102. package/.agent/skills/error-resilience/SKILL.md +411 -428
  103. package/.agent/skills/extract-design-system/SKILL.md +160 -158
  104. package/.agent/skills/framer-motion-expert/SKILL.md +253 -244
  105. package/.agent/skills/frontend-design/SKILL.md +208 -201
  106. package/.agent/skills/frontend-security-expert/SKILL.md +16 -3
  107. package/.agent/skills/game-design-expert/SKILL.md +132 -129
  108. package/.agent/skills/game-engineering-expert/SKILL.md +148 -146
  109. package/.agent/skills/generative-ui-expert/SKILL.md +57 -1
  110. package/.agent/skills/geo-fundamentals/SKILL.md +148 -147
  111. package/.agent/skills/git-pro/SKILL.md +435 -0
  112. package/.agent/skills/github-operations/SKILL.md +335 -329
  113. package/.agent/skills/gsap-core/SKILL.md +319 -308
  114. package/.agent/skills/gsap-frameworks/SKILL.md +213 -207
  115. package/.agent/skills/gsap-performance/SKILL.md +139 -133
  116. package/.agent/skills/gsap-plugins/SKILL.md +486 -480
  117. package/.agent/skills/gsap-react/SKILL.md +202 -189
  118. package/.agent/skills/gsap-scrolltrigger/SKILL.md +357 -350
  119. package/.agent/skills/gsap-timeline/SKILL.md +165 -161
  120. package/.agent/skills/gsap-utils/SKILL.md +344 -338
  121. package/.agent/skills/harness-protocol/SKILL.md +48 -0
  122. package/.agent/skills/i18n-localization/SKILL.md +174 -163
  123. package/.agent/skills/intelligent-routing/SKILL.md +202 -246
  124. package/.agent/skills/knowledge-graph/SKILL.md +60 -52
  125. package/.agent/skills/lint-and-validate/SKILL.md +261 -261
  126. package/.agent/skills/llm-engineering/SKILL.md +400 -394
  127. package/.agent/skills/local-first/SKILL.md +178 -178
  128. package/.agent/skills/mcp-builder/SKILL.md +143 -142
  129. package/.agent/skills/mobile-design/SKILL.md +272 -263
  130. package/.agent/skills/monorepo-management/SKILL.md +335 -334
  131. package/.agent/skills/motion-engineering/SKILL.md +266 -234
  132. package/.agent/skills/nextjs-react-expert/SKILL.md +236 -234
  133. package/.agent/skills/nodejs-best-practices/SKILL.md +547 -548
  134. package/.agent/skills/observability/SKILL.md +343 -343
  135. package/.agent/skills/parallel-agents/SKILL.md +143 -146
  136. package/.agent/skills/performance-profiling/SKILL.md +259 -267
  137. package/.agent/skills/plan-writing/SKILL.md +150 -142
  138. package/.agent/skills/platform-engineer/SKILL.md +148 -147
  139. package/.agent/skills/playwright-best-practices/SKILL.md +188 -187
  140. package/.agent/skills/powershell-windows/SKILL.md +162 -162
  141. package/.agent/skills/project-idioms/SKILL.md +137 -137
  142. package/.agent/skills/python-patterns/SKILL.md +260 -259
  143. package/.agent/skills/python-pro/SKILL.md +324 -323
  144. package/.agent/skills/react-specialist/SKILL.md +305 -277
  145. package/.agent/skills/readme-builder/SKILL.md +310 -300
  146. package/.agent/skills/realtime-patterns/SKILL.md +323 -319
  147. package/.agent/skills/red-team-tactics/SKILL.md +231 -218
  148. package/.agent/skills/review-animations/SKILL.md +72 -0
  149. package/.agent/skills/review-animations/STANDARDS.md +73 -0
  150. package/.agent/skills/rust-pro/SKILL.md +671 -673
  151. package/.agent/skills/seo-fundamentals/SKILL.md +179 -179
  152. package/.agent/skills/server-management/SKILL.md +218 -214
  153. package/.agent/skills/shadcn-ui-expert/SKILL.md +231 -231
  154. package/.agent/skills/skill-creator/SKILL.md +87 -86
  155. package/.agent/skills/sql-pro/SKILL.md +629 -629
  156. package/.agent/skills/supabase-postgres-best-practices/SKILL.md +97 -97
  157. package/.agent/skills/swiftui-expert/SKILL.md +204 -201
  158. package/.agent/skills/system-design-pro/SKILL.md +345 -0
  159. package/.agent/skills/systematic-debugging/SKILL.md +153 -142
  160. package/.agent/skills/tailwind-patterns/SKILL.md +610 -566
  161. package/.agent/skills/tdd-workflow/SKILL.md +169 -161
  162. package/.agent/skills/test-result-analyzer/SKILL.md +313 -309
  163. package/.agent/skills/testing-patterns/SKILL.md +566 -579
  164. package/.agent/skills/trend-researcher/SKILL.md +243 -237
  165. package/.agent/skills/typescript-advanced/SKILL.md +336 -335
  166. package/.agent/skills/ui-ux-pro-max/SKILL.md +590 -562
  167. package/.agent/skills/ui-ux-researcher/SKILL.md +244 -244
  168. package/.agent/skills/vue-expert/SKILL.md +294 -275
  169. package/.agent/skills/vulnerability-scanner/SKILL.md +416 -404
  170. package/.agent/skills/web-accessibility-auditor/SKILL.md +219 -218
  171. package/.agent/skills/web-design-guidelines/SKILL.md +192 -186
  172. package/.agent/skills/webapp-testing/SKILL.md +167 -169
  173. package/.agent/skills/webgpu-performance/SKILL.md +56 -2
  174. package/.agent/skills/whimsy-injector/SKILL.md +346 -325
  175. package/.agent/skills/workflow-optimizer/SKILL.md +231 -229
  176. package/.agent/workflows/acf.md +141 -0
  177. package/.agent/workflows/api-tester.md +176 -151
  178. package/.agent/workflows/audit.md +150 -127
  179. package/.agent/workflows/brainstorm.md +134 -110
  180. package/.agent/workflows/changelog.md +140 -112
  181. package/.agent/workflows/create.md +168 -124
  182. package/.agent/workflows/debug.md +190 -165
  183. package/.agent/workflows/deploy.md +201 -180
  184. package/.agent/workflows/enhance.md +154 -128
  185. package/.agent/workflows/fix.md +136 -114
  186. package/.agent/workflows/generate.md +198 -183
  187. package/.agent/workflows/marathon.md +37 -11
  188. package/.agent/workflows/migrate.md +184 -160
  189. package/.agent/workflows/orchestrate.md +192 -168
  190. package/.agent/workflows/performance-benchmarker.md +135 -114
  191. package/.agent/workflows/plan.md +196 -173
  192. package/.agent/workflows/preview.md +103 -80
  193. package/.agent/workflows/refactor.md +192 -161
  194. package/.agent/workflows/review-ai.md +125 -101
  195. package/.agent/workflows/review.md +141 -116
  196. package/.agent/workflows/session.md +122 -94
  197. package/.agent/workflows/status.md +101 -79
  198. package/.agent/workflows/strengthen-skills.md +164 -138
  199. package/.agent/workflows/super-prompt.md +24 -0
  200. package/.agent/workflows/swarm.md +193 -179
  201. package/.agent/workflows/test.md +211 -189
  202. package/.agent/workflows/tribunal-backend.md +136 -105
  203. package/.agent/workflows/tribunal-database.md +129 -95
  204. package/.agent/workflows/tribunal-frontend.md +140 -96
  205. package/.agent/workflows/tribunal-full.md +131 -100
  206. package/.agent/workflows/tribunal-mobile.md +129 -95
  207. package/.agent/workflows/tribunal-performance.md +136 -110
  208. package/.agent/workflows/tribunal-speed.md +209 -183
  209. package/.agent/workflows/ui-ux-pro-max.md +155 -122
  210. package/README.md +107 -55
  211. package/mcp_config.json +1 -3
  212. package/package.json +94 -94
  213. package/.agent/GEMINI.md +0 -121
  214. package/.agent/skills/doc.md +0 -177
@@ -1,238 +1,268 @@
1
- ---
2
- name: motion-engineering
3
- description: Motion Engineering mastery for 2026 web UI. Covers all 20 modern animation styles across 4 tiers (Core UX, Immersive, Advanced, Specialized). Use when designing motion strategy, choosing animation libraries (Framer, GSAP, WebGL, CSS), or implementing animated UI patterns.
4
- allowed-tools: Read, Write, Edit, Glob, Grep
5
- version: 4.0.0
6
- last-updated: 2026-04-07
7
- applies-to-model: gemini-3-1-pro, claude-3-7-sonnet
8
- ---
9
-
10
- # Motion Engineering (2026) — Comprehensive Reference
11
-
12
- You are the Motion Engineering Specialist. Your purpose is to bridge the gap between static UI and fluid, intuitive, and high-performance digital experiences. You understand that motion is not decoration; it is usability, narrative, and state communication.
13
-
14
- ## Hallucination Traps & Motion Sins (Read First)
15
- - Linear motion (`ease-linear`, CSS `transition: all`) Spring physics (`stiffness/damping`) or custom cubic-beziers. Linear looks robotic.
16
- - ❌ Animating layout properties (`width`, `margin`, `top`) → ✅ ONLY animate `transform` and `opacity` to maintain 120fps GPU compositing.
17
- - Scrolljacking (hijacking native scroll wheel) → ✅ Smooth scrolling via Lenis, synchronized with native momentum.
18
- - ❌ Heavy blocking entrance animations → ✅ Performance-first: let user interact immediately while ambient motion resolves.
19
- - ❌ Forgetting `prefers-reduced-motion` → ✅ ALWAYS respect system accessibility. Fall back to instant opacity transitions.
20
- - ❌ `view-transition-name` collision → ✅ Each name must be unique in the DOM at any given time.
21
- - ❌ `element.animate()` (WAAPI) without `fill: "forwards"` → ✅ Animation resets on completion add `fill: "forwards"` or commit state.
22
-
23
- ---
24
-
25
- ## Master Library Decision Matrix (20 Animation Categories)
26
-
27
- | Category / Style | Recommended Technology | Why / Use Case |
28
- |:---|:---|:---|
29
- | **Tier 1: Core UX (High Frequency)** | | |
30
- | 1. Micro-interactions | Framer Motion / CSS Springs | Fast feedback, hover states, buttons |
31
- | 2. Scroll-based | GSAP ScrollTrigger + Lenis | Parallax, timelines, storytelling |
32
- | 3. Page Transitions | View Transitions API + Framer | SPA route navigation, modal expands |
33
- | 4. Loading & Skeleton | CSS @keyframes / SVGs / Lottie | Non-blocking waits, shimmer, spinners |
34
- | **Tier 2: Narrative & Immersive (Medium Frequency)** | | |
35
- | 5. 3D & Immersive | React Three Fiber / WebGL | Interactive scenes, models, depth |
36
- | 7. Kinetic Typography | GSAP SplitText / Framer | Emphasize headlines, word-by-word reveal |
37
- | 8. Background Animations | CSS Gradients / WebGL Shaders | Ambient noise, particles, mesh gradients |
38
- | 9. Illustration/Characters | Lottie / Rive | Mascots, onboarding storytelling |
39
- | **Tier 3: Advanced & Emerging (Situational)** | | |
40
- | 6. State Transitions | Framer Motion `layout` | Expanding cards, drag-and-drop |
41
- | 10. Physics-based | Matter.js / Framer Springs | Bouncy, elastic real-world mimics |
42
- | 11. Morphing & Shape | GSAP MorphSVG | Liquid motion, blobs, SVG path morphs |
43
- | 12. Glassmorphism UI | CSS backdrop-filter + motion | Soft shadows, refraction on hover |
44
- | 13. Cursor-based | Custom JS + CSS variables | Magnetic buttons, cursor trails |
45
- | 14. AI-driven Adaptive | Headless logic + Framer | Context-aware, usage-based animation |
46
- | 15. Gamified/Interactive | Canvas / React Three Fiber | Reward animations, mini-games |
47
- | **Tier 4: Specialized (Niche/Structural)** | | |
48
- | 16. Video + Motion | Scroll-sync Video (GSAP) | Cinematic hero sections |
49
- | 17. Experimental | Custom shaders / Brutalist CSS | Glitch effects, collage |
50
- | 18. Navigation | Framer `AnimatePresence` | Mega menus, magnetic nav |
51
- | 19. Data Visualization | D3.js + Framer Motion | Animated charts, live updates |
52
- | 20. Performance-first | CSS only (`opacity`, `transform`) | Ultra-minimal subtle fade-ins |
53
-
54
- ---
55
-
56
- ## TIER 1: Core UX Motion (Dense Implementation)
57
-
58
- *These are the foundational motions used in 80%+ of 2026 web applications.*
59
-
60
- ### 1. Micro-interactions
61
- Used for immediate feedback, clarifying actions, and improving perceived responsiveness.
62
- ```tsx
63
- // Framer Motion — button with spring micro-interaction
64
- <motion.button
65
- whileHover={{ scale: 1.02, filter: "brightness(1.08)" }}
66
- whileTap={{ scale: 0.97 }}
67
- transition={{ type: "spring", stiffness: 400, damping: 17 }}
68
- >Submit</motion.button>
69
- ```
70
-
71
- ### 2. Scroll-based Animations (Most used in 2026)
72
- Triggers narrative flow and depth based on user scrolling.
73
- ```javascript
74
- // GSAP ScrollTrigger — industry standard
75
- gsap.from(".reveal-section", {
76
- scrollTrigger: { trigger: ".reveal-section", start: "top 80%", scrub: 1 },
77
- y: 60, opacity: 0, stagger: 0.1
78
- });
79
-
80
- // Lenissmooth scroll compatible with GSAP
81
- import Lenis from "lenis";
82
- const lenis = new Lenis({ lerp: 0.1, wheelMultiplier: 0.8 });
83
- lenis.on("scroll", ScrollTrigger.update);
84
- gsap.ticker.add((time) => lenis.raf(time * 1000));
85
- gsap.ticker.lagSmoothing(0);
86
- ```
87
-
88
- ### 3. Page Transitions (View Transitions API)
89
- ```css
90
- /* CSS define shared elements */
91
- .card-image { view-transition-name: active-image; } /* MUST BE UNIQUE */
92
- ::view-transition-old(active-image) { animation: fade-out 0.3s ease; }
93
- ::view-transition-new(active-image) { animation: scale-in 0.3s ease; }
94
- ```
95
-
96
- ### 4. Loading & Skeleton Animations
97
- Never block the UI entirely. Use structural loading.
98
- ```css
99
- /* Shimmer structural animation */
100
- .skeleton {
101
- background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
102
- background-size: 200% 100%;
103
- animation: shimmer 1.5s infinite linear;
104
- }
105
- @keyframes shimmer { 100% { background-position: -200% 0; } }
106
- ```
107
-
108
- ---
109
-
110
- ## TIER 2: Narrative & Immersive (Medium Implementation)
111
-
112
- *Used for brand storytelling, heroes, and engagement.*
113
-
114
- ### 5. 3D & Immersive Animations
115
- The leading trend of 2026. Use React Three Fiber.
116
- ```tsx
117
- // WebGL Scene basics
118
- import { Canvas, useFrame } from '@react-three/fiber'
119
- function RotatingCube() {
120
- const meshRef = useRef();
121
- useFrame((state, delta) => (meshRef.current.rotation.x += delta));
122
- return <mesh ref={meshRef}><boxGeometry /><meshStandardMaterial color="hotpink" /></mesh>;
123
- }
124
- ```
125
-
126
- ### 7. Kinetic Typography
127
- ```tsx
128
- // Word-by-word spring reveal (Framer Motion)
129
- const words = "Immersive storytelling".split(" ");
130
- const wordVariants = { hidden: { opacity: 0, y: 20 }, visible: { opacity: 1, y: 0 } };
131
-
132
- <motion.h1 transition={{ staggerChildren: 0.05 }} initial="hidden" whileInView="visible" viewport={{ once: true }}>
133
- {words.map((w, i) => <motion.span key={i} variants={wordVariants}>{w} </motion.span>)}
134
- </motion.h1>
135
- ```
136
-
137
- ### 8. Background Animations & 9. Illustrations
138
- - **Backgrounds:** Use CSS `@keyframes` on pseudo-elements with `filter: blur()` for ambient gradients, avoiding repaints.
139
- - **Illustrations:** Use Rive for interactive state machines, or Lottie via `lottie-react` for simple timeline playback.
140
-
141
- ---
142
-
143
- ## TIER 3: Advanced & Emerging (Concepts & Tools)
144
-
145
- *Highly interactive components elevating standard UI.*
146
-
147
- - **6. Motion UI & State Transitions:** Use Framer Motion's `layout` prop. Morphing a list item into a modal requires `<motion.div layoutId="item-1">` on both states. Wrap the app in `<LayoutGroup>`.
148
- - **10. Physics-based:** Animate like real-world objects. Instead of `duration`, define `mass`, `stiffness`, and `damping` in physics springs to simulate gravity and tension.
149
- - **11. Morphing & Shape:** GSAP `MorphSVGPlugin`. Requires SVGs with comparable path points or GSAP will interpolate poorly. Alternatively, animate CSS `border-radius` for fluid blobs.
150
- - **12. Glassmorphism:** Animate `backdrop-filter: blur(10px)` but beware of performance costs on mobile. Render shadows via `filter: drop-shadow()` combined with slight `translateY` on hover.
151
- - **13. Cursor-based:** Modern standard is CSS variables bound to mouse position. Calculate `clientX` relative to the element bounding box and update `--mouse-x` to drive `radial-gradient` masks.
152
- - **14. AI-driven Adaptive:** Motion that learns. If a user speeds through a form, UI transitions accelerate. If they linger, ambient motion plays. Controlled by tracking interaction deltas and mapping them to global spring configurations.
153
- - **15. Gamified:** Progress bars that burst on completion, haptic-synchronized checkmarks. Combine SVGs with explicit, highly exaggerated elastic overshoot scales (`scale: [1, 1.2, 0.9, 1]`) on reward thresholds.
154
-
155
- ---
156
-
157
- ## TIER 4: Specialized (Rules & Fallbacks)
158
-
159
- *Niche requirements where performance or specific constraints dominate.*
160
-
161
- - **16. Video + Motion Hybrid:** Scrubbing `<video>` tags with scroll. Requires pre-encoding video rapidly with keyframes every 1 frame, drawing frames to a `<canvas>` element via `requestAnimationFrame` linked to scroll progress.
162
- - **17. Experimental:** Glitch effects via overlapping CSS `clip-path` animations. High processing cost.
163
- - **18. Navigation:** Mega-menus must use `<AnimatePresence>` to prevent DOM unmount before the exit animation resolves. Include exit delays so users don't trigger flickering by rapidly moving the mouse off the nav.
164
- - **19. Data Visualization:** D3 handles math, React handles DOM, Framer/Spring handles interpolation between D3 datasets. Never let D3 mutate the DOM directly inside a React app.
165
- - **20. Performance-first Subtle Motion:** Strictly `opacity`, `transform`, CSS-only. Use `@starting-style` for popovers and dialogs to avoid JS intervention.
166
-
167
- ---
168
-
169
- ## Accessibility & Performance Invariants (Global Rules)
170
-
171
- 1. **The WCAG 2.2 AA Motion Rule:**
172
- ```tsx
173
- import { useReducedMotion } from "framer-motion";
174
- const reduce = useReducedMotion();
175
- // Safe: opacity, color
176
- // Conditional: translate, scale, rotate
177
- <motion.div animate={{ x: reduce ? 0 : 100, opacity: 1 }} transition={{ duration: reduce ? 0 : 0.5 }} />
178
- ```
179
-
180
- 2. **The 120fps GPU Rule:**
181
- Never animate `width`, `height`, `left`, `top`, `margin`, or `padding`. This triggers layout recalculation algorithms. Use `transform: scale()` or `transform: translate()` instead.
182
-
183
- 3. **The Cleanup Rule:**
184
- Any GSAP ScrollTrigger timeline must use `ScrollTrigger.killAll()` or React's `useGSAP` cleanup functions to avoid memory leaks on SPA route changes.
185
-
186
-
187
- ---
188
-
189
-
190
-
191
- AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
192
-
193
- 1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
194
- 2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
195
- 3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
196
- 4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
197
- 5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
198
-
199
- ---
200
-
201
-
202
-
203
- **Slash command: `/review` or `/tribunal-full`**
204
- **Active reviewers: `logic-reviewer` · `security-auditor`**
205
-
206
- ### ❌ Forbidden AI Tropes
207
-
208
- 1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
209
- 2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
210
- 3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
211
-
212
-
213
-
214
- Review these questions before confirming output:
215
- ```
216
- ✅ Did I rely ONLY on real, verified tools and methods?
217
- ✅ Is this solution appropriately scoped to the user's constraints?
218
- ✅ Did I handle potential failure modes and edge cases?
219
- ✅ Have I avoided generic boilerplate that doesn't add value?
220
- ```
221
-
222
- ### 🛑 Verification-Before-Completion (VBC) Protocol
223
-
224
- **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
225
- - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
226
- - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
227
-
228
-
229
- ## Pre-Flight Checklist
230
- - [ ] Have I reviewed the user's specific constraints and requests?
231
- - [ ] Have I checked the environment for relevant existing implementations?
232
-
233
- ## VBC Protocol (Verification-Before-Completion)
234
- You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
1
+ ---
2
+ name: motion-engineering
3
+ description: Motion Engineering mastery for 2026 web UI. Covers all 20 modern animation styles across 4 tiers (Core UX, Immersive, Advanced, Specialized). Use when designing motion strategy, choosing animation libraries (Framer, GSAP, WebGL, CSS), or implementing animated UI patterns.
4
+ allowed-tools: Read, Write, Edit, Glob, Grep
5
+ version: 4.0.0
6
+ last-updated: 2026-04-07
7
+ applies-to-model: gemini-3-1-pro, claude-3-7-sonnet
8
+ routing:
9
+ domain: general
10
+ tier: basic
11
+ ---
12
+
13
+ # Motion Engineering (2026) — Comprehensive Reference
14
+
15
+ You are the Motion Engineering Specialist. Your purpose is to bridge the gap between static UI and fluid, intuitive, and high-performance digital experiences. You understand that motion is not decoration; it is usability, narrative, and state communication.
16
+
17
+ ## Hallucination Traps & Motion Sins (Read First)
18
+
19
+ - ❌ Linear motion (`ease-linear`, CSS `transition: all`) → ✅ Spring physics (`stiffness/damping`) or custom cubic-beziers. Linear looks robotic.
20
+ - ❌ Animating layout properties (`width`, `margin`, `top`) → ✅ ONLY animate `transform` and `opacity` to maintain 120fps GPU compositing.
21
+ - ❌ Scrolljacking (hijacking native scroll wheel) → ✅ Smooth scrolling via Lenis, synchronized with native momentum.
22
+ - ❌ Heavy blocking entrance animations → ✅ Performance-first: let user interact immediately while ambient motion resolves.
23
+ - ❌ Forgetting `prefers-reduced-motion` → ✅ ALWAYS respect system accessibility. Fall back to instant opacity transitions.
24
+ - ❌ `view-transition-name` collision → ✅ Each name must be unique in the DOM at any given time.
25
+ - `element.animate()` (WAAPI) without `fill: "forwards"` → ✅ Animation resets on completion — add `fill: "forwards"` or commit state.
26
+
27
+ ---
28
+
29
+ ## Master Library Decision Matrix (20 Animation Categories)
30
+
31
+ | Category / Style | Recommended Technology | Why / Use Case |
32
+ | :--------------------------------------------------- | :-------------------------------- | :--------------------------------------- |
33
+ | **Tier 1: Core UX (High Frequency)** | | |
34
+ | 1. Micro-interactions | Framer Motion / CSS Springs | Fast feedback, hover states, buttons |
35
+ | 2. Scroll-based | GSAP ScrollTrigger + Lenis | Parallax, timelines, storytelling |
36
+ | 3. Page Transitions | View Transitions API + Framer | SPA route navigation, modal expands |
37
+ | 4. Loading & Skeleton | CSS @keyframes / SVGs / Lottie | Non-blocking waits, shimmer, spinners |
38
+ | **Tier 2: Narrative & Immersive (Medium Frequency)** | | |
39
+ | 5. 3D & Immersive | React Three Fiber / WebGL | Interactive scenes, models, depth |
40
+ | 7. Kinetic Typography | GSAP SplitText / Framer | Emphasize headlines, word-by-word reveal |
41
+ | 8. Background Animations | CSS Gradients / WebGL Shaders | Ambient noise, particles, mesh gradients |
42
+ | 9. Illustration/Characters | Lottie / Rive | Mascots, onboarding storytelling |
43
+ | **Tier 3: Advanced & Emerging (Situational)** | | |
44
+ | 6. State Transitions | Framer Motion `layout` | Expanding cards, drag-and-drop |
45
+ | 10. Physics-based | Matter.js / Framer Springs | Bouncy, elastic real-world mimics |
46
+ | 11. Morphing & Shape | GSAP MorphSVG | Liquid motion, blobs, SVG path morphs |
47
+ | 12. Glassmorphism UI | CSS backdrop-filter + motion | Soft shadows, refraction on hover |
48
+ | 13. Cursor-based | Custom JS + CSS variables | Magnetic buttons, cursor trails |
49
+ | 14. AI-driven Adaptive | Headless logic + Framer | Context-aware, usage-based animation |
50
+ | 15. Gamified/Interactive | Canvas / React Three Fiber | Reward animations, mini-games |
51
+ | **Tier 4: Specialized (Niche/Structural)** | | |
52
+ | 16. Video + Motion | Scroll-sync Video (GSAP) | Cinematic hero sections |
53
+ | 17. Experimental | Custom shaders / Brutalist CSS | Glitch effects, collage |
54
+ | 18. Navigation | Framer `AnimatePresence` | Mega menus, magnetic nav |
55
+ | 19. Data Visualization | D3.js + Framer Motion | Animated charts, live updates |
56
+ | 20. Performance-first | CSS only (`opacity`, `transform`) | Ultra-minimal subtle fade-ins |
57
+
58
+ ---
59
+
60
+ ## TIER 1: Core UX Motion (Dense Implementation)
61
+
62
+ _These are the foundational motions used in 80%+ of 2026 web applications._
63
+
64
+ ### 1. Micro-interactions
65
+
66
+ Used for immediate feedback, clarifying actions, and improving perceived responsiveness.
67
+
68
+ ```tsx
69
+ // Framer Motion — button with spring micro-interaction
70
+ <motion.button whileHover={{ scale: 1.02, filter: "brightness(1.08)" }} whileTap={{ scale: 0.97 }} transition={{ type: "spring", stiffness: 400, damping: 17 }}>
71
+ Submit
72
+ </motion.button>
73
+ ```
74
+
75
+ ### 2. Scroll-based Animations (Most used in 2026)
76
+
77
+ Triggers narrative flow and depth based on user scrolling.
78
+
79
+ ```javascript
80
+ // GSAP ScrollTrigger industry standard
81
+ gsap.from(".reveal-section", {
82
+ scrollTrigger: { trigger: ".reveal-section", start: "top 80%", scrub: 1 },
83
+ y: 60,
84
+ opacity: 0,
85
+ stagger: 0.1,
86
+ });
87
+
88
+ // Lenis smooth scroll compatible with GSAP
89
+ import Lenis from "lenis";
90
+ const lenis = new Lenis({ lerp: 0.1, wheelMultiplier: 0.8 });
91
+ lenis.on("scroll", ScrollTrigger.update);
92
+ gsap.ticker.add((time) => lenis.raf(time * 1000));
93
+ gsap.ticker.lagSmoothing(0);
94
+ ```
95
+
96
+ ### 3. Page Transitions (View Transitions API)
97
+
98
+ ```css
99
+ /* CSS define shared elements */
100
+ .card-image {
101
+ view-transition-name: active-image;
102
+ } /* MUST BE UNIQUE */
103
+ ::view-transition-old(active-image) {
104
+ animation: fade-out 0.3s ease;
105
+ }
106
+ ::view-transition-new(active-image) {
107
+ animation: scale-in 0.3s ease;
108
+ }
109
+ ```
110
+
111
+ ### 4. Loading & Skeleton Animations
112
+
113
+ Never block the UI entirely. Use structural loading.
114
+
115
+ ```css
116
+ /* Shimmer structural animation */
117
+ .skeleton {
118
+ background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
119
+ background-size: 200% 100%;
120
+ animation: shimmer 1.5s infinite linear;
121
+ }
122
+ @keyframes shimmer {
123
+ 100% {
124
+ background-position: -200% 0;
125
+ }
126
+ }
127
+ ```
128
+
129
+ ---
130
+
131
+ ## TIER 2: Narrative & Immersive (Medium Implementation)
132
+
133
+ _Used for brand storytelling, heroes, and engagement._
134
+
135
+ ### 5. 3D & Immersive Animations
136
+
137
+ The leading trend of 2026. Use React Three Fiber.
138
+
139
+ ```tsx
140
+ // WebGL Scene basics
141
+ import { Canvas, useFrame } from "@react-three/fiber";
142
+ function RotatingCube() {
143
+ const meshRef = useRef();
144
+ useFrame((state, delta) => (meshRef.current.rotation.x += delta));
145
+ return (
146
+ <mesh ref={meshRef}>
147
+ <boxGeometry />
148
+ <meshStandardMaterial color="hotpink" />
149
+ </mesh>
150
+ );
151
+ }
152
+ ```
153
+
154
+ ### 7. Kinetic Typography
155
+
156
+ ```tsx
157
+ // Word-by-word spring reveal (Framer Motion)
158
+ const words = "Immersive storytelling".split(" ");
159
+ const wordVariants = { hidden: { opacity: 0, y: 20 }, visible: { opacity: 1, y: 0 } };
160
+
161
+ <motion.h1 transition={{ staggerChildren: 0.05 }} initial="hidden" whileInView="visible" viewport={{ once: true }}>
162
+ {words.map((w, i) => (
163
+ <motion.span key={i} variants={wordVariants}>
164
+ {w}{" "}
165
+ </motion.span>
166
+ ))}
167
+ </motion.h1>;
168
+ ```
169
+
170
+ ### 8. Background Animations & 9. Illustrations
171
+
172
+ - **Backgrounds:** Use CSS `@keyframes` on pseudo-elements with `filter: blur()` for ambient gradients, avoiding repaints.
173
+ - **Illustrations:** Use Rive for interactive state machines, or Lottie via `lottie-react` for simple timeline playback.
174
+
175
+ ---
176
+
177
+ ## TIER 3: Advanced & Emerging (Concepts & Tools)
178
+
179
+ _Highly interactive components elevating standard UI._
180
+
181
+ - **6. Motion UI & State Transitions:** Use Framer Motion's `layout` prop. Morphing a list item into a modal requires `<motion.div layoutId="item-1">` on both states. Wrap the app in `<LayoutGroup>`.
182
+ - **10. Physics-based:** Animate like real-world objects. Instead of `duration`, define `mass`, `stiffness`, and `damping` in physics springs to simulate gravity and tension.
183
+ - **11. Morphing & Shape:** GSAP `MorphSVGPlugin`. Requires SVGs with comparable path points or GSAP will interpolate poorly. Alternatively, animate CSS `border-radius` for fluid blobs.
184
+ - **12. Glassmorphism:** Animate `backdrop-filter: blur(10px)` but beware of performance costs on mobile. Render shadows via `filter: drop-shadow()` combined with slight `translateY` on hover.
185
+ - **13. Cursor-based:** Modern standard is CSS variables bound to mouse position. Calculate `clientX` relative to the element bounding box and update `--mouse-x` to drive `radial-gradient` masks.
186
+ - **14. AI-driven Adaptive:** Motion that learns. If a user speeds through a form, UI transitions accelerate. If they linger, ambient motion plays. Controlled by tracking interaction deltas and mapping them to global spring configurations.
187
+ - **15. Gamified:** Progress bars that burst on completion, haptic-synchronized checkmarks. Combine SVGs with explicit, highly exaggerated elastic overshoot scales (`scale: [1, 1.2, 0.9, 1]`) on reward thresholds.
188
+
189
+ ---
190
+
191
+ ## TIER 4: Specialized (Rules & Fallbacks)
235
192
 
193
+ _Niche requirements where performance or specific constraints dominate._
194
+
195
+ - **16. Video + Motion Hybrid:** Scrubbing `<video>` tags with scroll. Requires pre-encoding video rapidly with keyframes every 1 frame, drawing frames to a `<canvas>` element via `requestAnimationFrame` linked to scroll progress.
196
+ - **17. Experimental:** Glitch effects via overlapping CSS `clip-path` animations. High processing cost.
197
+ - **18. Navigation:** Mega-menus must use `<AnimatePresence>` to prevent DOM unmount before the exit animation resolves. Include exit delays so users don't trigger flickering by rapidly moving the mouse off the nav.
198
+ - **19. Data Visualization:** D3 handles math, React handles DOM, Framer/Spring handles interpolation between D3 datasets. Never let D3 mutate the DOM directly inside a React app.
199
+ - **20. Performance-first Subtle Motion:** Strictly `opacity`, `transform`, CSS-only. Use `@starting-style` for popovers and dialogs to avoid JS intervention.
200
+
201
+ ---
202
+
203
+ ## Accessibility & Performance Invariants (Global Rules)
204
+
205
+ 1. **The WCAG 2.2 AA Motion Rule:**
206
+
207
+ ```tsx
208
+ import { useReducedMotion } from "framer-motion";
209
+ const reduce = useReducedMotion();
210
+ // Safe: opacity, color
211
+ // Conditional: translate, scale, rotate
212
+ <motion.div animate={{ x: reduce ? 0 : 100, opacity: 1 }} transition={{ duration: reduce ? 0 : 0.5 }} />;
213
+ ```
214
+
215
+ 2. **The 120fps GPU Rule:**
216
+ Never animate `width`, `height`, `left`, `top`, `margin`, or `padding`. This triggers layout recalculation algorithms. Use `transform: scale()` or `transform: translate()` instead.
217
+
218
+ 3. **The Cleanup Rule:**
219
+ Any GSAP ScrollTrigger timeline must use `ScrollTrigger.killAll()` or React's `useGSAP` cleanup functions to avoid memory leaks on SPA route changes.
220
+
221
+ ---
222
+
223
+ AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
224
+
225
+ 1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
226
+ 2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
227
+ 3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
228
+ 4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
229
+ 5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
230
+
231
+ ---
232
+
233
+ **Slash command: `/review` or `/tribunal-full`**
234
+ **Active reviewers: `logic-reviewer` · `security-auditor`**
235
+
236
+ ### ❌ Forbidden AI Tropes
237
+
238
+ 1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
239
+ 2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
240
+ 3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
241
+
242
+ Review these questions before confirming output:
243
+
244
+ ```
245
+ ✅ Did I rely ONLY on real, verified tools and methods?
246
+ ✅ Is this solution appropriately scoped to the user's constraints?
247
+ ✅ Did I handle potential failure modes and edge cases?
248
+ ✅ Have I avoided generic boilerplate that doesn't add value?
249
+ ```
250
+
251
+ ### 🛑 Verification-Before-Completion (VBC) Protocol
252
+
253
+ **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
254
+
255
+ - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
256
+ - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
257
+
258
+ ## Pre-Flight Checklist
259
+
260
+ - [ ] Have I reviewed the user's specific constraints and requests?
261
+ - [ ] Have I checked the environment for relevant existing implementations?
262
+
263
+ ## VBC Protocol (Verification-Before-Completion)
264
+
265
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
236
266
 
237
267
  ---
238
268
 
@@ -262,6 +292,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
262
292
  ### ✅ Pre-Flight Self-Audit
263
293
 
264
294
  Review these questions before confirming output:
295
+
265
296
  ```
266
297
  ✅ Did I rely ONLY on real, verified tools and methods?
267
298
  ✅ Is this solution appropriately scoped to the user's constraints?
@@ -272,5 +303,6 @@ Review these questions before confirming output:
272
303
  ### 🛑 Verification-Before-Completion (VBC) Protocol
273
304
 
274
305
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
306
+
275
307
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
276
308
  - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.