tribunal-kit 3.0.0 → 4.0.0

package/.agent/skills/mobile-design/SKILL.md

@@ -1,219 +1,213 @@
----
-name: mobile-design
-description: Mobile-first and Spatial computing design thinking for iOS, Android, Foldables, and WebXR. Touch interaction, advanced haptics, on-device AI patterns, performance extremis. Teaches principles, not fixed values.
-allowed-tools: Read, Glob, Grep, Bash
-version: 1.0.0
-last-updated: 2026-03-12
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
----
-
-# Mobile & Spatial Design System (Pro-Max Level)
-
-> **Philosophy:** Touch-first. Battery-conscious. Platform-respectful. Contextually aware.
-> **Core Principle:** Mobile is NOT a small desktop. It is a sensor-rich, context-aware extension of the user. THINK constraints, EXPECT hardware diversity.
-
----
-
-## 🔧 Runtime Scripts
-
-**Execute these for validation (don't read, just run):**
-
-| Script | Purpose | Usage |
-|--------|---------|-------|
-| `scripts/mobile_audit.py` | Mobile UX & Touch Audit | `python scripts/mobile_audit.py <project_path>` |
-
----
-
-## 🔴 MANDATORY: Read Reference Files Before Working!
-
-**⛔ DO NOT start development until you read the relevant files:**
-
-### Universal (Always Read)
-
-| File | Content | Status |
-|------|---------|--------|
-| **[mobile-design-thinking.md](mobile-design-thinking.md)** | **⚠️ ANTI-MEMORIZATION: Forces thinking, prevents AI defaults** | **⬜ CRITICAL FIRST** |
-| **[spatial-and-foldables.md](spatial-and-foldables.md)** | **Foldable screens, WebXR, dynamic viewports** | **⬜ CRITICAL** |
-| **[on-device-ai.md](on-device-ai.md)** | **Streaming UI, local models, zero-wait states** | **⬜ CRITICAL** |
-| **[touch-psychology.md](touch-psychology.md)** | **Advanced haptics, Fitts' Law, magnetic touch targets** | **⬜ CRITICAL** |
-| **[mobile-performance.md](mobile-performance.md)** | **React Native/Flutter rendering at 120Hz** | **⬜ CRITICAL** |
-| [mobile-navigation.md](mobile-navigation.md) | Tab/Stack/Drawer, deep linking, spatial z-axis nav | ⬜ Read |
-| [decision-trees.md](decision-trees.md) | Framework/state/storage selection | ⬜ Read |
-
-> 🧠 **mobile-design-thinking.md is PRIORITY!** This file ensures AI thinks instead of using memorized patterns.
-
----
-
-## ⚠️ CRITICAL: ASK BEFORE ASSUMING (MANDATORY)
-
-> **STOP! If the user's request is open-ended, DO NOT default to your favorites.**
-
-### You MUST Ask If Not Specified:
-
-| Aspect | Ask | Why |
-|--------|-----|-----|
-| **Form Factor** | "Standard mobile only, or support for Foldables/Tablets?" | Affects fluid layout geometry |
-| **Performance** | "Is this targeting 60Hz or 120Hz ProMotion displays?" | Determines animation physics |
-| **AI Integration**| "Are we streaming LLM responses to the UI?" | Defines loading vs streaming patterns |
-| **Platform** | "iOS, Android, Spatial (VisionOS/WebXR), or cross-platform?" | Affects EVERY design decision |
-
-### ⛔ AI MOBILE ANTI-PATTERNS (YASAK LİSTESİ)
-
-> 🚫 **These are AI default tendencies that MUST be avoided!**
-
-#### Performance & Display Sins
-| ❌ NEVER DO | Why It's Wrong | ✅ ALWAYS DO |
-|-------------|----------------|--------------|
-| **Pure White Backgrounds** | Blinds users at night, drains battery | OLED True Black (`#000`) or off-white (`#FAFAFA`) |
-| **Linear Animations** | Feels robotic and cheap | Spring physics (`stiffness`, `damping`) |
-| **ScrollView for long lists** | Renders ALL items, memory explodes | Use `FlashList` / `ListView.builder` / Virtualization |
-| **console.log in production** | Blocks JS thread severely | Remove before release build |
-
-#### Touch & UX Sins
-| ❌ NEVER DO | Why It's Wrong | ✅ ALWAYS DO |
-|-------------|----------------|--------------|
-| **Touch target < 48px** | Frustrating, violates modern Fitts' Law | Min 48px (iOS/Android), mathematically enforced |
-| **Silent Interactions** | Breaks the illusion of tactility | Bind visual state changes to Advanced Haptic Feedback |
-| **Blocking Spinners for AI** | "Thinking..." spinners cause abandonment | Stream skeleton → partial text → layout |
-| **Gesture-only interactions** | Motor impaired users excluded | Always provide button alternative |
-
----
-
-## 📱 Hardware & Context Adaptation
-
-### 1. The Foldable & Dynamic Screen Era
-Phones fold. Tablets resize. UIs must be perfectly fluid, not reliant on fixed breakpoints.
-- **TwoPane Layouts:** List-Detail views that dynamically collapse into single stacks.
-- **Hinge Awareness:** Do not place critical interactive elements across the physical hinge of a foldable device.
-
-### 2. Advanced Haptics (Tactile UI)
-Visuals are only half the UI. Mobile relies on touch.
-- Bind `Haptics.impactAsync('light')` to micro-interactions (e.g., toggling a switch).
-- Bind `Haptics.notificationAsync('success')` to state completions.
-- *Never* overuse haptics. They must mean something.
-
-### 3. Spatial Z-Axis & Depth
-Modern OSs (iOS 18+, Android 15+) heavily utilize depth and blur.
-- Utilize native `BlurView` or `VisualEffectView` materials for absolutely positioned overlays (tab bars, headers).
-- Shadows must have multi-layered dispersion, not harsh CSS `box-shadow` single drops.
-
----
-
-## 🧠 Mobile Extreme UX Psychology
-
-### Fitts' Law for Touch & Magnetic Targets
-Touch screens are wildly imprecise. 
-- Touch targets MUST be >48px minimum.
-- Important actions map to the THUMB ZONE (bottom arc).
-- **Magnetic Padding:** Visual size can be small (24px icon), but the *hitbox* padding must expand to 48px.
-
-### On-Device AI UX Patterns
-- **Zero-Wait Illusion:** When a model is running, immediately populate the UI with contextual guesses or streaming tokens.
-- **Progressive Disclosure of Confidence:** If AI confidence is low, the UI should reflect uncertainty visually (softer colors, explicit confirmation required).
-
----
-
-## 📏 UI Building Accuracy
-
-- **Mathematical Layouts:** Mobile layouts require mathematical precision to prevent layout shifts. You MUST use exact spacing multiples (e.g., 4px/8px grids).
-- **Strict Containers:** Explicitly define `flex-1`, `align-items`, and `justify-content` on every view layer. Never let RN guess the intrinsic size.
-
-## ⚡ Performance Extremis (Quick Reference)
-
-### 120Hz Animation Mandate
-If your animation drops below 120fps on modern hardware, it's failed.
-- GPU-accelerated ONLY: `transform` (translate, scale, rotate) and `opacity`.
-- CPU-bound AVOID: `width`, `height`, `margin`, `top/left/bottom/right`.
-- React Native: MUST use Reanimated 3+ worklets for all motion; `Animated` API is legacy.
-
-### React Native Critical Rules
-```typescript
-// ✅ CORRECT: FlashList for extreme performance
-<FlashList
-  data={items}
-  renderItem={renderItem}
-  estimatedItemSize={100} // CRITICAL for FlashList
-  keyExtractor={(item) => item.id}
-/>
-```
-
----
-
-## 📝 CHECKPOINT (MANDATORY Before Any Mobile Work)
-
-> **Before writing ANY mobile code, you MUST complete this checkpoint:**
-
-```
-🧠 CHECKPOINT:
-
-Platform target:   [ iOS / Android / Foldable / Spatial ]
-Hardware expectation:[ 60Hz / 120Hz ]
-Haptic Strategy:   [ Define trigger points ]
-
-3 Extreme Principles I Will Apply:
-1. _______________
-2. _______________
-3. _______________
-```
-
-> **Remember:** You are designing for a piece of glass that people stare at for 6 hours a day. Battery life, touch precision, and 120Hz fluidity are not optional features; they are the medium itself.
-
----
-
-## Output Format
-
-When this skill produces a recommendation or design decision, structure your output as:
-
-```
-━━━ Mobile Design Recommendation ━━━━━━━━━━━━━━━━
-Decision:    [what was chosen / proposed]
-Rationale:   [why — one concise line]
-Trade-offs:  [what is consciously accepted]
-Next action: [concrete next step for the user]
-─────────────────────────────────────────────────
-Pre-Flight:  ✅ All checks passed
-             or ❌ [blocking item that must be resolved first]
-```
-
-
-
----
-
-## 🤖 LLM-Specific Traps
-
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
-
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
-
----
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before confirming output:
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **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.
+---
+name: mobile-design
+description: Mobile-first design for iOS, Android, Foldables, React Native, Flutter. Touch interaction, haptics, 120Hz performance, on-device AI, spatial UI, Reanimated 3. Use when building mobile UI, animations, or cross-platform apps.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 3.1.0
+last-updated: 2026-04-06
+---
+
+# Mobile Design — Dense Reference
+
+## Hallucination Traps (Read First)
+- ❌ `Animated.View` for any animation → ✅ `Reanimated 3` worklets (Animated API is legacy, runs on JS thread)
+- ❌ `ScrollView` for lists → ✅ `FlashList` (Shopify) — ScrollView renders ALL items at once
+- ❌ `estimatedItemSize` optional in FlashList → ✅ **REQUIRED** or you get 0-height items
+- ❌ White backgrounds (`#FFFFFF`) → ✅ OLED: `#000000` true black; off-white: `#FAFAFA`
+- ❌ Linear animations (`easing: linear`) → ✅ Spring physics (`stiffness`, `damping`)
+- ❌ Touch targets < 48px → ✅ Min 48px hitbox (visual size can be smaller via padding)
+- ❌ `useAnimatedStyle` in worklet without `'worklet'` directive → crashes on native thread
+- ❌ iOS: `useSafeAreaInsets()` optional → ✅ Required — screen content goes under dynamic island/home indicator
+- ❌ Android: hardcoded status bar height (24dp) → ✅ `StatusBar.currentHeight` (varies per device)
+- ❌ Platform-specific code with `if (platform === 'ios')` scattered everywhere → ✅ centralize in platform/ files
+- ❌ `console.log` in production → ✅ blocks JS thread — remove before release
+
+---
+
+## React Native Performance
+
+### FlashList (Required for Lists)
+```tsx
+import { FlashList } from "@shopify/flash-list";
+<FlashList
+  data={items}
+  renderItem={({ item }) => <ItemCard item={item} />}
+  estimatedItemSize={100}          // REQUIRED — measure actual item height first
+  keyExtractor={(item) => item.id}
+  getItemType={(item) => item.type} // multi-type optimization
+/>
+// ❌ NEVER: <ScrollView>{items.map(...)}</ScrollView> for lists
+// ❌ NEVER: <FlatList> for perf-critical lists — FlashList is 5-10x faster
+```
+
+### Reanimated 3 — Worklet Animations (Required for 120Hz)
+```tsx
+import { useSharedValue, useAnimatedStyle, withSpring, withTiming, runOnJS } from 'react-native-reanimated';
+
+// Shared values run on the UI thread — never on JS thread
+const scale = useSharedValue(1);
+const opacity = useSharedValue(0);
+
+// Animated style — computed on UI thread (no bridge crossing)
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: scale.value }],
+  opacity: opacity.value,
+}));
+
+// Triggers
+const onPress = () => {
+  scale.value = withSpring(0.95, { stiffness: 400, damping: 15 });
+  opacity.value = withTiming(1, { duration: 200 });
+};
+
+// Call JS function from worklet
+const onComplete = () => runOnJS(setVisible)(true);
+scale.value = withSpring(1, {}, onComplete);
+
+// ❌ TRAP: Accessing shared value with .value inside useAnimatedStyle is fine — but inside a gesture handler callback, you need runOnJS to call React setState
+```
+
+### 120Hz Animation Rules
+- ✅ Animate ONLY: `transform` (translateX/Y, scale, rotate), `opacity` — all GPU composited
+- ❌ Never animate: `width`, `height`, `margin`, `padding`, `top/left/bottom/right` — causes layout recalc at 60 times per second → janky, battery draining
+- ✅ Use `withSpring` for all UI interactions (feel alive) — `withTiming` only for intentional timed animations
+- ✅ `Gesture.Pan()` / `Gesture.Tap()` from `react-native-gesture-handler` v2 (not `PanResponder`)
+
+---
+
+## Haptics
+```tsx
+import * as Haptics from 'expo-haptics';
+// light → switch toggle, tap feedback
+// medium → selection change, confirm
+// heavy → destructive action, strong confirm
+// notificationAsync('success' | 'warning' | 'error') → operation outcomes
+Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);  // tap, toggle
+Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success); // save complete
+// ❌ Never overuse — haptics must mean something
+// ❌ Haptics not supported on Android emulators — test on device
+```
+
+---
+
+## Safe Areas & Platform Layout
+```tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { Platform, StatusBar } from 'react-native';
+
+function Screen() {
+  const insets = useSafeAreaInsets();
+  return (
+    <View style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
+      {/* Content safe from Dynamic Island, home indicator, status bar */}
+    </View>
+  );
+}
+// Android status bar
+const STATUS_BAR_HEIGHT = Platform.OS === 'android' ? StatusBar.currentHeight ?? 24 : 0;
+
+// Foldable/tablet — dual pane
+import { useWindowDimensions } from 'react-native';
+function AdaptiveLayout() {
+  const { width } = useWindowDimensions();
+  const isTablet = width >= 600;
+  return isTablet ? <TwoPaneView /> : <SinglePaneView />;
+}
+```
+
+---
+
+## Touch Psychology & Thumb Zones
+- **Thumb zone**: Bottom 40% of screen = primary actions, FABs, CTAs
+- **Dead zone**: Top 25% = destructive/rare actions only
+- **48px minimum hitbox**: Visual icon can be 24px, padding expands hitbox to 48px
+  ```tsx
+  // Magnetic padding — visually small, touch-friendly
+  <TouchableOpacity style={{ padding: 12, margin: -4 }}>
+    <Icon size={24} />
+  </TouchableOpacity>
+  ```
+- **Coyote time**: Allow 100–150ms buffer after button intent registers before processing — prevents mis-taps
+
+---
+
+## Navigation (Expo Router / React Navigation)
+```tsx
+// Expo Router v3+ (file-based, recommended)
+// app/(tabs)/_layout.tsx — tab navigator
+// app/[id].tsx — dynamic segment
+// app/(modal)/settings.tsx — modal group
+
+// Stack navigation with gesture
+import { Stack } from 'expo-router';
+<Stack screenOptions={{ headerShown: false, animation: 'slide_from_right' }}>
+  <Stack.Screen name="(tabs)" />
+  <Stack.Screen name="[id]" options={{ presentation: 'modal' }} />
+</Stack>
+
+// Deep linking (Expo Router handles automatically via app.json scheme)
+// ❌ TRAP: Don't use react-navigation Link for deep links in Expo Router — use expo-router Link
+import { Link, useRouter } from 'expo-router';
+const router = useRouter();
+router.push('/user/42');
+```
+
+---
+
+## On-Device AI UX Patterns
+- **Zero-wait illusion**: When model runs → immediately show contextual skeleton/partial tokens
+- **Progressive disclosure**: Low confidence → softer UI, soft colors, require confirmation
+- **Streaming UI**: `useEffect` + SSE or `StreamingText` component appending tokens
+- **Local models** (MediaPipe, Core ML, ONNX): always wrap in try/catch — device capability varies
+
+---
+
+## Color & Typography
+```tsx
+// OLED-safe dark mode
+const colors = {
+  background: '#000000',    // true black — OLED pixel off
+  surface: '#0A0A0A',       // cards
+  surfaceAlt: '#121212',    // elevated surfaces
+  border: '#1F1F1F',
+  text: '#FFFFFF',
+  textMuted: '#8E8E93',     // iOS system gray
+};
+// Dynamic type (iOS) — always use system font with scalesWithContentSizeCategory
+import { Text } from 'react-native';
+<Text style={{ fontSize: 16, fontFamily: Platform.OS === 'ios' ? 'System' : 'Roboto' }}>
+```
+
+---
+
+## Performance Checklist
+| Issue | Fix |
+|-------|-----|
+| JS thread jank | Move ALL animations to Reanimated worklets |
+| Slow list | Replace ScrollView/FlatList with FlashList |
+| Image flicker | `Image` from `expo-image` (faster cache, blurhash) |
+| Re-render cascade | `React.memo` + stable callbacks + Zustand selectors |
+| Large bundle | Dynamic imports + Metro tree shaking |
+| Memory leak | `useEffect` cleanup + cancel animation on unmount |
+
+```tsx
+// Cancel animation on unmount
+useEffect(() => {
+  opacity.value = withTiming(1);
+  return () => cancelAnimation(opacity); // ← critical
+}, []);
+```
+
+---
+
+## iOS-Specific
+- **BlurView**: Use `@react-native-community/blur` for frosted glass nav bars/modals
+- **SF Symbols**: Use `@expo/vector-icons/Ionicons` for system-native icons
+- **Haptics**: `expo-haptics` — rich feedback on iOS, limited on Android
+- **Dynamic Island**: Check `insets.top > 50` for Dynamic Island devices
+- **Sheet presentations**: `presentation: 'formSheet'` in Expo Router for iOS bottom sheet native feel
+
+## Android-Specific
+- **Material You**: Use `react-native-paper` for M3 dynamic color theming
+- **Edge-to-edge**: Set `android:windowLayoutInDisplayCutoutMode="shortEdges"` in AndroidManifest
+- **Back gesture prediction**: Wrap routes in `GestureHandlerRootView` at root
+- **Splash**: Use `expo-splash-screen` — never hardcode a delay

package/.agent/skills/motion-engineering/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: motion-engineering
+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.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 4.0.0
+last-updated: 2026-04-07
+applies-to-model: gemini-3-1-pro, claude-3-7-sonnet
+---
+
+# Motion Engineering (2026) — Comprehensive Reference
+
+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. 
+
+## Hallucination Traps & Motion Sins (Read First)
+- ❌ Linear motion (`ease-linear`, CSS `transition: all`) → ✅ Spring physics (`stiffness/damping`) or custom cubic-beziers. Linear looks robotic.
+- ❌ Animating layout properties (`width`, `margin`, `top`) → ✅ ONLY animate `transform` and `opacity` to maintain 120fps GPU compositing.
+- ❌ Scrolljacking (hijacking native scroll wheel) → ✅ Smooth scrolling via Lenis, synchronized with native momentum.
+- ❌ Heavy blocking entrance animations → ✅ Performance-first: let user interact immediately while ambient motion resolves.
+- ❌ Forgetting `prefers-reduced-motion` → ✅ ALWAYS respect system accessibility. Fall back to instant opacity transitions.
+- ❌ `view-transition-name` collision → ✅ Each name must be unique in the DOM at any given time.
+- ❌ `element.animate()` (WAAPI) without `fill: "forwards"` → ✅ Animation resets on completion — add `fill: "forwards"` or commit state.
+
+---
+
+## Master Library Decision Matrix (20 Animation Categories)
+
+| Category / Style | Recommended Technology | Why / Use Case |
+|:---|:---|:---|
+| **Tier 1: Core UX (High Frequency)** | | |
+| 1. Micro-interactions | Framer Motion / CSS Springs | Fast feedback, hover states, buttons |
+| 2. Scroll-based | GSAP ScrollTrigger + Lenis | Parallax, timelines, storytelling |
+| 3. Page Transitions | View Transitions API + Framer | SPA route navigation, modal expands |
+| 4. Loading & Skeleton | CSS @keyframes / SVGs / Lottie | Non-blocking waits, shimmer, spinners |
+| **Tier 2: Narrative & Immersive (Medium Frequency)** | | |
+| 5. 3D & Immersive | React Three Fiber / WebGL | Interactive scenes, models, depth |
+| 7. Kinetic Typography | GSAP SplitText / Framer | Emphasize headlines, word-by-word reveal |
+| 8. Background Animations | CSS Gradients / WebGL Shaders | Ambient noise, particles, mesh gradients |
+| 9. Illustration/Characters | Lottie / Rive | Mascots, onboarding storytelling |
+| **Tier 3: Advanced & Emerging (Situational)** | | |
+| 6. State Transitions | Framer Motion `layout` | Expanding cards, drag-and-drop |
+| 10. Physics-based | Matter.js / Framer Springs | Bouncy, elastic real-world mimics |
+| 11. Morphing & Shape | GSAP MorphSVG | Liquid motion, blobs, SVG path morphs |
+| 12. Glassmorphism UI | CSS backdrop-filter + motion | Soft shadows, refraction on hover |
+| 13. Cursor-based | Custom JS + CSS variables | Magnetic buttons, cursor trails |
+| 14. AI-driven Adaptive | Headless logic + Framer | Context-aware, usage-based animation |
+| 15. Gamified/Interactive | Canvas / React Three Fiber | Reward animations, mini-games |
+| **Tier 4: Specialized (Niche/Structural)** | | |
+| 16. Video + Motion | Scroll-sync Video (GSAP) | Cinematic hero sections |
+| 17. Experimental | Custom shaders / Brutalist CSS | Glitch effects, collage |
+| 18. Navigation | Framer `AnimatePresence` | Mega menus, magnetic nav |
+| 19. Data Visualization | D3.js + Framer Motion | Animated charts, live updates |
+| 20. Performance-first | CSS only (`opacity`, `transform`) | Ultra-minimal subtle fade-ins |
+
+---
+
+## TIER 1: Core UX Motion (Dense Implementation)
+
+*These are the foundational motions used in 80%+ of 2026 web applications.*
+
+### 1. Micro-interactions
+Used for immediate feedback, clarifying actions, and improving perceived responsiveness.
+```tsx
+// Framer Motion — button with spring micro-interaction
+<motion.button
+  whileHover={{ scale: 1.02, filter: "brightness(1.08)" }}
+  whileTap={{ scale: 0.97 }}
+  transition={{ type: "spring", stiffness: 400, damping: 17 }}
+>Submit</motion.button>
+```
+
+### 2. Scroll-based Animations (Most used in 2026)
+Triggers narrative flow and depth based on user scrolling.
+```javascript
+// GSAP ScrollTrigger — industry standard
+gsap.from(".reveal-section", {
+  scrollTrigger: { trigger: ".reveal-section", start: "top 80%", scrub: 1 },
+  y: 60, opacity: 0, stagger: 0.1
+});
+
+// Lenis — smooth scroll compatible with GSAP
+import Lenis from "lenis";
+const lenis = new Lenis({ lerp: 0.1, wheelMultiplier: 0.8 });
+lenis.on("scroll", ScrollTrigger.update);
+gsap.ticker.add((time) => lenis.raf(time * 1000));
+gsap.ticker.lagSmoothing(0);
+```
+
+### 3. Page Transitions (View Transitions API)
+```css
+/* CSS — define shared elements */
+.card-image { view-transition-name: active-image; } /* MUST BE UNIQUE */
+::view-transition-old(active-image) { animation: fade-out 0.3s ease; }
+::view-transition-new(active-image) { animation: scale-in 0.3s ease; }
+```
+
+### 4. Loading & Skeleton Animations
+Never block the UI entirely. Use structural loading.
+```css
+/* Shimmer structural animation */
+.skeleton { 
+  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+  background-size: 200% 100%; 
+  animation: shimmer 1.5s infinite linear; 
+}
+@keyframes shimmer { 100% { background-position: -200% 0; } }
+```
+
+---
+
+## TIER 2: Narrative & Immersive (Medium Implementation)
+
+*Used for brand storytelling, heroes, and engagement.*
+
+### 5. 3D & Immersive Animations
+The leading trend of 2026. Use React Three Fiber.
+```tsx
+// WebGL Scene basics
+import { Canvas, useFrame } from '@react-three/fiber'
+function RotatingCube() {
+  const meshRef = useRef();
+  useFrame((state, delta) => (meshRef.current.rotation.x += delta));
+  return <mesh ref={meshRef}><boxGeometry /><meshStandardMaterial color="hotpink" /></mesh>;
+}
+```
+
+### 7. Kinetic Typography
+```tsx
+// Word-by-word spring reveal (Framer Motion)
+const words = "Immersive storytelling".split(" ");
+const wordVariants = { hidden: { opacity: 0, y: 20 }, visible: { opacity: 1, y: 0 } };
+
+<motion.h1 transition={{ staggerChildren: 0.05 }} initial="hidden" whileInView="visible" viewport={{ once: true }}>
+  {words.map((w, i) => <motion.span key={i} variants={wordVariants}>{w} </motion.span>)}
+</motion.h1>
+```
+
+### 8. Background Animations & 9. Illustrations
+- **Backgrounds:** Use CSS `@keyframes` on pseudo-elements with `filter: blur()` for ambient gradients, avoiding repaints.
+- **Illustrations:** Use Rive for interactive state machines, or Lottie via `lottie-react` for simple timeline playback.
+
+---
+
+## TIER 3: Advanced & Emerging (Concepts & Tools)
+
+*Highly interactive components elevating standard UI.*
+
+- **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>`.
+- **10. Physics-based:** Animate like real-world objects. Instead of `duration`, define `mass`, `stiffness`, and `damping` in physics springs to simulate gravity and tension.
+- **11. Morphing & Shape:** GSAP `MorphSVGPlugin`. Requires SVGs with comparable path points or GSAP will interpolate poorly. Alternatively, animate CSS `border-radius` for fluid blobs.
+- **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.
+- **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.
+- **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.
+- **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.
+
+---
+
+## TIER 4: Specialized (Rules & Fallbacks)
+
+*Niche requirements where performance or specific constraints dominate.*
+
+- **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.
+- **17. Experimental:** Glitch effects via overlapping CSS `clip-path` animations. High processing cost.
+- **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.
+- **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.
+- **20. Performance-first Subtle Motion:** Strictly `opacity`, `transform`, CSS-only. Use `@starting-style` for popovers and dialogs to avoid JS intervention.
+
+---
+
+## Accessibility & Performance Invariants (Global Rules)
+
+1. **The WCAG 2.2 AA Motion Rule:**
+```tsx
+import { useReducedMotion } from "framer-motion";
+const reduce = useReducedMotion();
+// Safe: opacity, color
+// Conditional: translate, scale, rotate
+<motion.div animate={{ x: reduce ? 0 : 100, opacity: 1 }} transition={{ duration: reduce ? 0 : 0.5 }} />
+```
+
+2. **The 120fps GPU Rule:**
+Never animate `width`, `height`, `left`, `top`, `margin`, or `padding`. This triggers layout recalculation algorithms. Use `transform: scale()` or `transform: translate()` instead.
+
+3. **The Cleanup Rule:**
+Any GSAP ScrollTrigger timeline must use `ScrollTrigger.killAll()` or React's `useGSAP` cleanup functions to avoid memory leaks on SPA route changes.