motion-principles

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 7196f765fc11 · 29 Oct 2026Report an issue or request a re-scan

• Publisherathevon GitHub userOwner of the repository this skill is read from
• Source folderathevon/genjutsu/skills/_jutsu/motion-principlesThe exact folder we audited
• LicenceNOASSERTIONAs the repository states it
• Commit pinned for this verdict7196f765fc11A new audit runs when the source changes
• Repository statusNot archivedLast push 23 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Motion design foundation - timing, easing, enter/exit patterns, accessibility, performance.

---
name: motion-principles
description: "Motion design foundation - timing, easing, enter/exit patterns, accessibility, performance."
metadata:
  internal: true
---

> **Version-sensitive.** Every API name, SDK gate and browser-support claim below was
> verified on **2026-09-08** against primary sources. What against, and when, is in
> `_jutsu/VERSIONS.md`. If that date is old, re-verify before acting on a version number.

# Motion Principles

> The foundation. Loaded by every creative skill invocation.
> Concise rules here. Deep-dive in `references/`.

---

## Timing Rules

| Context | Duration | Why |
|---|---|---|
| Micro-interaction (toggle, hover, focus) | 100-150ms | Instant feedback, no perceived delay |
| UI transition (modal, drawer, tab switch) | 200-300ms | Smooth but never sluggish |
| Page/route transition | 300-500ms | Establishes spatial narrative |
| Scroll-driven / 3D | Free (progress-based) | Tied to user input, no fixed duration |

**Frequency rule:** The more often an animation plays, the shorter and subtler it must be.
A button hover (1000x/day) = 100ms opacity. An onboarding reveal (1x ever) = 600ms+ full choreography.

---

## Easing Cheat Sheet

| Action | Easing | Why |
|---|---|---|
| Element enters | `ease-out` / spring | Decelerates into resting position (natural arrival) |
| Element exits | `ease-in` | Accelerates away (gets out of the way) |
| Element moves between states | `ease-in-out` | Smooth start and stop |
| Scroll-synced | `linear` / `none` | Matches 1:1 with input, no lag perception |
| Bouncy/playful | spring (underdamped) | Overshoot creates life |
| Snappy UI | `cubic-bezier(0.2, 0, 0, 1)` | Fast start, smooth land |

> **Exit is always more subtle than enter.**
> Enter: 300ms ease-out, full choreography. Exit: 200ms ease-in, opacity only.

### Native easing equivalents (cross-platform)

| Web (CSS / JS) | SwiftUI | Compose |
|---|---|---|
| `cubic-bezier(0.2, 0, 0, 1)` | `.spring(response: 0.4, dampingFraction: 0.85)` or `.snappy` | `spring(stiffness = Spring.StiffnessMedium, dampingRatio = 0.85f)` |
| `ease-out` | `.easeOut(duration: 0.3)` | `tween(durationMillis = 300, easing = LinearOutSlowInEasing)` |
| `ease-in` | `.easeIn(duration: 0.2)` | `tween(durationMillis = 200, easing = FastOutLinearInEasing)` |
| spring (bouncy) | `.bouncy` (iOS 17+) | `spring(stiffness = Spring.StiffnessLow, dampingRatio = Spring.DampingRatioMediumBouncy)` |
| spring (smooth) | `.smooth` (iOS 17+) | `spring(stiffness = Spring.StiffnessMedium, dampingRatio = Spring.DampingRatioNoBouncy)` |

---

## Accessibility (Non-Negotiable)

### Reduced motion - MANDATORY

Every animated component must respect the user's reduced-motion preference. No exceptions, regardless of platform.

| Platform | API |
|---|---|
| Web CSS | `@media (prefers-reduced-motion: reduce)` |
| Web JS | `window.matchMedia('(prefers-reduced-motion: reduce)')` |
| SwiftUI | `@Environment(\.accessibilityReduceMotion) var reduceMotion` |
| UIKit | `UIAccessibility.isReduceMotionEnabled` (+ `reduceMotionStatusDidChangeNotification`) |
| Compose | Custom helper using `Settings.Global.ANIMATOR_DURATION_SCALE` (deep-dive in `mobile-principles/references/accessibility-mobile.md`) |

**CSS:**
```css
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}
```

**SwiftUI:**
```swift
struct AnimatedView: View {
    @Environment(\.accessibilityReduceMotion) var reduceMotion
    @State var visible = false

    var body: some View {
        Text("Hello")
            .opacity(visible ? 1 : 0)
            .animation(reduceMotion ? .none : .spring(response: 0.4, dampingFraction: 0.85), value: visible)
    }
}
```

**Compose:**
```kotlin
@Composable
fun rememberReduceMotion(): Boolean {
    val context = LocalContext.current
    return remember {
        Settings.Global.getFloat(context.contentResolver, Settings.Global.ANIMATOR_DURATION_SCALE, 1f) == 0f
    }
}

@Composable
fun AnimatedComponent(visible: Boolean) {
    val reduce = rememberReduceMotion()
    val alpha by animateFloatAsState(
        targetValue = if (visible) 1f else 0f,
        animationSpec = if (reduce) snap() else spring(stiffness = Spring.StiffnessMedium)
    )
}
```

### Other a11y requirements
- Focus indicators must never be hidden by animations
- Animated content must meet WCAG contrast ratios at every frame (no mid-transition fading to invisible text)
- Looping animations: provide a pause mechanism

---

## Universal "Do Not" Rules

### 1. Never animate width/height/top/left

Triggers layout recalculation every frame = jank.

```css
/* BAD */
.drawer { transition: height 0.3s ease; }
.drawer.open { height: 400px; }

/* GOOD */
.drawer { transition: transform 0.3s ease-out; transform: translateY(100%); }
.drawer.open { transform: translateY(0); }
```

**SwiftUI equivalent (BAD vs GOOD):**
```swift
// BAD - animates frame (causes layout pass)
.frame(height: open ? 400 : 0)
.animation(.easeInOut, value: open)

// GOOD - animates transform via offset
.offset(y: open ? 0 : 400)
.animation(.spring(), value: open)
```

**Compose equivalent (BAD vs GOOD):**
```kotlin
// BAD - animates size (full layout pass)
val height by animateDpAsState(if (open) 400.dp else 0.dp)

// GOOD - animates Y offset via graphicsLayer
val translation by animateFloatAsState(if (open) 0f else 400f)
Box(modifier = Modifier.graphicsLayer { translationY = translation })
```

### 2. Never scale to 0

`scale(0)` causes elements to vanish in a black hole. Always keep a minimum.

```css
/* BAD */
.modal-exit { transform: scale(0); }

/* GOOD */
.modal-exit { transform: scale(0.95); opacity: 0; }
```

**SwiftUI equivalent:**
```swift
// BAD
.scaleEffect(visible ? 1.0 : 0.0)

// GOOD
.scaleEffect(visible ? 1.0 : 0.95)
.opacity(visible ? 1.0 : 0.0)
```

**Compose equivalent:**
```kotlin
// BAD
Modi

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/athevon/genjutsu
git -C genjutsu checkout 7196f765fc11

Works in

1. 2026-10-29
   ✓SAFE B 89 / 100

   first audit · source 7196f765fc11

Questions about motion-principles

• github.com/athevon/genjutsu/tree/main/skills/_jutsu/motion-princ — the audited source at commit 7196f765fc11 and every finding aboveObserved · 29 Oct 2026

Spotted something wrong? Report a correction · Methodology