fluid-tactile-motion

Files (1)

• SKILL.md

SKILL.md (first lines)

# Universal Fluid & Tactile Motion Engineering Standard

## 1. The Core Philosophy: Physical Realism & Instant Feedback

Interfaces feel slow and cheap when they either:
1. **Use Linear CSS Easing (`transition: all 0.3s ease`)**: In the real physical world, mass and inertia prevent instant linear stops. Human eyes expect **spring physics** with natural momentum, deceleration, and settling.
2. **Block on Network Latency (The Spinner Trap)**: Forcing a user to wait 500ms–2000ms for a database roundtrip before showing a state change feels sluggish and heavy.

Big-Tech interfaces feel "butter-smooth" because:
- Every touch target physically compresses and springs back.
- State changes update **optimistically in < 16ms** (1 frame) while synchronization occurs silently in the background.
- Motion runs on the **GPU compositor thread** with zero layout thrashing.

---

## 2. Spring Physics Tokens (Framer Motion / Physics Engines)

Never use stiff, arbitrary duration curves. Standardize on these 4 battle-tested spring physics curves:

```ts
import { Transition, Variants } from 'framer-motion';

// 1. Snappy (Buttons, Toggles, Small Icons, Tabs)
export const springSnappy: Transition = {
  type: 'spring',
  stiffness: 420,
  damping: 30,
};

// 2. Jelly / Bouncy (Active selection pills, Celebration badges, XP counters)
export const springJelly: Transition = {
  type: 'spring',
  stiffness: 350,
  damping: 22,
  mass: 0.8,
};

// 3. Dialog / Modal (Center popups, Alert dialogs)
export const springModal: Transition = {
  type: 'spring',
  stiffness: 340,
  damping: 28,
  mass: 0.9,
};

// 4. Sheet / Drawer (Mobile bottom sheets, Navigation drawers)
export const springSheet: Transition = {
  type: 'spring',
  stiffness: 300,
  damping: 32,
  mass: 0.95,
};
```

---

## 3. Tactile Tap Micro-Interactions

Every interactive element must provide tactile visual compression to confirm human input:

```ts
export const tapScale = {
  button: {
    whileTap: { scale: 0.96 },
    transition: springSnappy,
  },
  icon: {
    whileTap: { scale: 0.88 },
    transition: springSnappy,
  },
  card: {
    whileHover: { scale: 1.01 },
    whileTap: { scale: 0.98 },
    transition: springSnappy,
  },
  pill: {
    whileTap: { scale: 0.95 },
    transition: springSnappy,
  },
};
```

* **Tailwind Pure CSS Fallback**: When not using Framer Motion, implement:
  ```css
  .active-scale {
    transition: transform 0.15s cubic-bezier(0.34, 1.56, 0.64, 1);
  }
  .active-scale:active {
    transform: scale(0.97);
  }
  ```

---

## 4. The Optimistic UI Architecture (Instant Response Loop)

Do not block user interactions behind network roundtrips. Decouple the visual interface from backend operations:

```
User Action (Tap Button)
   │
   ├───> [PHASE 1: < 16ms] Immediate Local State Mutation (UI updates, closes, or transitions instantly)
   │
   └───> [PHASE 2: Background Async] Send Network Mutation to Database / API
            │
            ├── Succeeded ──> Silent pass. User is already in their desired state.
            │
            └── Failed ──────> Revert local state + Present informative non-blocking recovery toast.
```

### Golden Implementation Pattern:
```ts
const handleAction = async (itemId: string) => {
  // 1. Snapshot previous state for rollback
  const previousState = [...items];
  
  // 2. Mutate state optimistically in memory (<16ms)
  setItems(prev => prev.filter(item => item.id !== itemId));

From hemanth17r/ahr-workflow, MIT.

More from hemanth17r/ahr-workflow