ai-engineering-loop 2.2.0 → 2.4.0

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 (133) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
  2. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -2
  3. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +3 -3
  4. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-review.md +3 -4
  6. package/.agents/skills/ai-engineering-loop/references/loop-risky.md +1 -0
  7. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
  8. package/.claude/agents/judge.md +5 -2
  9. package/.grok/agents/judge.md +5 -2
  10. package/CHANGELOG.md +60 -0
  11. package/README.md +1 -0
  12. package/THIRD_PARTY_NOTICES.md +11 -0
  13. package/adapters/spec/LICENSE +202 -0
  14. package/adapters/spec/NOTICE-AEL.md +26 -0
  15. package/adapters/spec/agents/ael-spec-codebase-details.md +71 -0
  16. package/adapters/spec/agents/ael-spec-comprehension.md +71 -0
  17. package/adapters/spec/agents/ael-spec-design.md +65 -0
  18. package/adapters/spec/agents/ael-spec-implementation-readiness.md +64 -0
  19. package/adapters/spec/agents/ael-spec-structural.md +67 -0
  20. package/adapters/spec/agents/ael-spec-style.md +68 -0
  21. package/adapters/spec/agents/ael-spec-synthesizer.md +73 -0
  22. package/adapters/spec/agents/ael-spec-zoom-out.md +76 -0
  23. package/adapters/spec/skills/ael-spec-brainstorm/SKILL.md +265 -0
  24. package/adapters/spec/skills/ael-spec-draft/SKILL.md +315 -0
  25. package/adapters/spec/skills/ael-spec-draft/references/design_doc.md +179 -0
  26. package/adapters/spec/skills/ael-spec-drift/SKILL.md +68 -0
  27. package/adapters/spec/skills/ael-spec-resolve/SKILL.md +188 -0
  28. package/adapters/spec/skills/ael-spec-review/SKILL.md +403 -0
  29. package/adapters/spec/skills/ael-spec-review-loop/SKILL.md +191 -0
  30. package/adapters/spec/standards/ael-spec-execution-instructions.md +36 -0
  31. package/adapters/spec/standards/ael-spec-feature-spec-standard.md +38 -0
  32. package/adapters/spec/standards/ael-spec-heilmeier-standard.md +32 -0
  33. package/adapters/spec/standards/ael-spec-implementation-readiness-standard.md +36 -0
  34. package/adapters/spec/standards/ael-spec-re-implementation-standard.md +39 -0
  35. package/adapters/spec/standards/ael-spec-zoom-out-standard.md +62 -0
  36. package/agents/maker.md +1 -1
  37. package/agents/shared/judge.body.md +5 -2
  38. package/bin/ai-engineering-loop.js +344 -78
  39. package/core/definition-of-done.md +2 -2
  40. package/core/escalation-policy.md +1 -1
  41. package/core/goal-contract.md +1 -1
  42. package/core/iteration-policy.md +2 -1
  43. package/core/judge-policy.md +10 -4
  44. package/core/orchestration-model.md +8 -7
  45. package/core/repo-config-schema.md +2 -2
  46. package/core/runtime-safety.md +3 -3
  47. package/core/spec-pack.md +47 -0
  48. package/lib/auto-update.js +8 -14
  49. package/lib/claimed-vs-reality.js +2 -2
  50. package/lib/cli-args.js +3 -1
  51. package/lib/design-ref.js +178 -0
  52. package/lib/docs.js +1 -1
  53. package/lib/doctor.js +0 -6
  54. package/lib/escalation.js +1 -1
  55. package/lib/fsutil.js +88 -0
  56. package/lib/gates.js +70 -27
  57. package/lib/generate-workflow.js +0 -29
  58. package/lib/goal-runtime.js +8 -2
  59. package/lib/guard-hooks.js +26 -7
  60. package/lib/guard.js +100 -10
  61. package/lib/hosts/doctor.js +17 -7
  62. package/lib/impact-map.js +31 -8
  63. package/lib/jsonl-ledger.js +104 -0
  64. package/lib/learn.js +4 -9
  65. package/lib/loop-groups.js +0 -25
  66. package/lib/migrations.js +1 -5
  67. package/lib/no-progress.js +119 -0
  68. package/lib/node-evidence.js +1 -5
  69. package/lib/orchestration.js +5 -361
  70. package/lib/personal-workflow.js +1 -1
  71. package/lib/quick.js +152 -0
  72. package/lib/receipt.js +13 -6
  73. package/lib/recipe-builder.js +3 -35
  74. package/lib/recipe-graph.js +2 -63
  75. package/lib/recipe.js +2 -4
  76. package/lib/review-ingest.js +116 -0
  77. package/lib/run-abandon.js +2 -1
  78. package/lib/run-compaction.js +4 -12
  79. package/lib/run-interactions.js +16 -71
  80. package/lib/run-lifecycle.js +25 -77
  81. package/lib/run-state.js +68 -17
  82. package/lib/run-watcher.js +11 -14
  83. package/lib/runtime-files.js +45 -1
  84. package/lib/safe-context.js +17 -6
  85. package/lib/sandbox.js +2 -1
  86. package/lib/smart-context.js +13 -14
  87. package/lib/spawn-command.js +94 -0
  88. package/lib/studio-layout.js +2 -8
  89. package/lib/studio-runtime.js +2 -1
  90. package/lib/studio-server.js +25 -5
  91. package/lib/sync-hosts.js +25 -2
  92. package/lib/tier.js +36 -10
  93. package/lib/user-state.js +2 -17
  94. package/lib/verification-lanes.js +115 -0
  95. package/lib/verification-recorder.js +110 -22
  96. package/lib/workflow-runtime.js +7 -4
  97. package/package.json +1 -2
  98. package/policies/review-budget.md +1 -1
  99. package/schemas/goal-contract.schema.json +87 -11
  100. package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
  101. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
  102. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
  103. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
  104. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
  105. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
  106. package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
  107. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  108. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  109. package/.claude/skills/animate/RECIPES.md +0 -324
  110. package/.claude/skills/animate/SKILL.md +0 -207
  111. package/.claude/skills/animate-expo/RECIPES.md +0 -385
  112. package/.claude/skills/animate-expo/SKILL.md +0 -263
  113. package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
  114. package/.claude/skills/apple-design/SKILL.md +0 -290
  115. package/.claude/skills/ask-sonner/API.md +0 -64
  116. package/.claude/skills/ask-sonner/SKILL.md +0 -88
  117. package/.claude/skills/backend-development/SKILL.md +0 -272
  118. package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
  119. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  120. package/.claude/skills/backend-development/references/security-checklist.md +0 -60
  121. package/.claude/skills/emil-design-eng/SKILL.md +0 -674
  122. package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
  123. package/.claude/skills/improve-animations/AUDIT.md +0 -115
  124. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  125. package/.claude/skills/improve-animations/SKILL.md +0 -109
  126. package/.claude/skills/mobile-native/SKILL.md +0 -311
  127. package/.claude/skills/pick-ui-library/SKILL.md +0 -85
  128. package/.claude/skills/prototype/PICKER.md +0 -197
  129. package/.claude/skills/prototype/SKILL.md +0 -98
  130. package/.claude/skills/review-animations/SKILL.md +0 -120
  131. package/.claude/skills/review-animations/STANDARDS.md +0 -187
  132. package/.claude/skills/write-swift/SKILL.md +0 -396
  133. package/lib/intern-catalog.js +0 -53
@@ -1,263 +0,0 @@
1
- ---
2
- name: animate-expo
3
- description: Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use `animate`.
4
- ---
5
-
6
- # Building Animations in Expo
7
-
8
- ## Initial Response
9
-
10
- When this skill is first invoked without a specific question, respond only with:
11
-
12
- > I'm ready to build animations in Expo and React Native that feel right on a real device, my knowledge comes from Emil Kowalski's animation philosophy.
13
-
14
- Do not provide any other information until the user asks a question.
15
-
16
- A construction skill for React Native. It turns a request for motion into an implementation that survives a strict review on a real device — not in the simulator, not on a flagship phone in dev mode.
17
-
18
- Mobile changes three things about animation, and everything in this skill follows from them:
19
-
20
- 1. **There is no hover.** Every affordance the web puts in hover has to live in press, position, or nothing.
21
- 2. **There are two runtimes.** Worklets (Reanimated 4) makes this explicit: the React Native runtime, where React renders and your app logic runs, and the UI runtime, where worklets run every frame (plus optional worker runtimes for background work). An animation that touches the RN runtime stutters the moment the app does anything else. The whole craft is keeping motion on the UI runtime.
22
- 3. **The user's finger is on the element.** Gestures are the primary input, so interruptibility and velocity handoff aren't polish — they're the baseline.
23
-
24
- ## Operating Posture
25
-
26
- You are a senior mobile engineer building the animation yourself. Make the call, state the reasoning in one line, write the code. Never present motion options as a menu.
27
-
28
- Two failure modes, and the first is worse:
29
-
30
- 1. **Animating something that shouldn't animate.** The gate below exists to produce zero lines of code sometimes.
31
- 2. **Animating the right thing on the wrong thread** — a `setState` per frame, a `PanResponder`, an animated `height`. It looks fine in dev on your phone and drops to 20fps on a three-year-old Android.
32
-
33
- ## Hard Rules
34
-
35
- 1. **Run the sequence in order.** Steps 1 and 2 gate everything.
36
- 2. **Reanimated, not core `Animated`.** Core `Animated` can't be driven by a gesture without crossing the bridge, and `useNativeDriver` refuses anything but transform and opacity anyway. Reanimated worklets run on the UI thread and keep running while JS is busy.
37
- 3. **No approximated values.** Curves and spring configs come from the tables below.
38
- 4. **Reduced motion ships with the animation**, not as a follow-up.
39
- 5. **Feel is judged on a release build on the slowest device you support.** Nothing else counts as verified.
40
-
41
- ## The Build Sequence
42
-
43
- ### 1. Should this animate at all?
44
-
45
- | Frequency | Decision |
46
- | --- | --- |
47
- | 100+ times/day — tab switches, keyboard open/close, scrolling, toggles in settings | **No animation.** Platform default or nothing. Stop here. |
48
- | Tens of times/day — press feedback, list navigation, row selection | Near-imperceptible only: under 150ms, or nothing |
49
- | Occasional — sheets, modals, toasts, onboarding steps | Standard animation |
50
- | Rare / first-time — success states, empty-state illustrations, celebration | The delight budget lives here |
51
-
52
- **Tab switches never slide.** Tabs are peers, not a hierarchy — sliding implies depth that isn't there, and the user pays for it dozens of times a session. `animation: 'none'`.
53
-
54
- If the request fails this gate, say so and don't write it.
55
-
56
- ### 2. What is the purpose?
57
-
58
- Name it in one word before continuing: **feedback**, **spatial consistency**, **state indication**, **preventing a jarring change**, **explanation**, or **delight** (rare tier only).
59
-
60
- Can't name it? Don't build it.
61
-
62
- ### 3. Pick the tool — cheapest that works
63
-
64
- Walk down; stop at the first that fits.
65
-
66
- | Need | Tool |
67
- | --- | --- |
68
- | A state-driven change with no gesture — press, toggle, color, a value flipping | **Reanimated CSS transition** (`transitionProperty` in the style) |
69
- | Loop, multi-stage, or plays on mount with no state change | **Reanimated CSS animation** (`animationName` keyframes) |
70
- | An element mounting or unmounting, or a list reflowing | **Layout animations** (`entering` / `exiting` / `itemLayoutAnimation`) |
71
- | Anything a finger touches, or anything derived from scroll | **`useSharedValue` + `Gesture` + `useAnimatedStyle`** |
72
- | Screen to screen | **Native stack options in Expo Router.** Never hand-roll this |
73
- | A bottom sheet that is its own screen | **`presentation: 'formSheet'`** — it's a real UISheetPresentationController, free and correct |
74
- | Tab bar | **`NativeTabs`** (from `expo-router/unstable-native-tabs`) — the platform's real tab bar, its behaviors and transitions included |
75
- | Context menu, press-and-hold preview | **`Link.Menu` / `Link.Preview`** (Expo Router, iOS-only) — native menus and peek, never rebuilt in JS |
76
- | Header that collapses into a large title | **`headerLargeTitleEnabled`** on the native stack (iOS-only; `headerLargeTitle` is deprecated) — not a scroll worklet |
77
- | Pull to refresh | **`RefreshControl`** — hand-roll only when it's a signature interaction (see the threshold recipe) |
78
- | UI that tracks the keyboard | **`react-native-keyboard-controller`** — the keyboard's real position, frame by frame, on the UI thread |
79
- | Vector illustration, celebration, empty state | **Lottie** — for illustration only, never for UI state |
80
- | A huge animated scene, freeform drawing | **`@shopify/react-native-skia`** — a canvas, for when the view hierarchy itself is the bottleneck |
81
-
82
- Reach for a shared value only when the value is continuous or interruptible. A press scale is a CSS transition; a drag is a shared value. Using a worklet for a two-state toggle is the mobile equivalent of installing a motion library for a fade.
83
-
84
- **Dependencies.** Install with `npx expo install <package>` — it resolves the version that matches the project's SDK, which plain `npm install` won't:
85
-
86
- | Need | Package |
87
- | --- | --- |
88
- | Animation | `react-native-reanimated` + `react-native-worklets` |
89
- | Gestures | `react-native-gesture-handler` |
90
- | Navigation, sheets, native tabs, menus | `expo-router` |
91
- | Haptics | `expo-haptics` |
92
- | Keyboard-following UI | `react-native-keyboard-controller` (needs `KeyboardProvider` at the root — see the keyboard recipe) |
93
- | Illustration, celebration | `lottie-react-native` |
94
- | Very large animated scenes, custom drawing | `@shopify/react-native-skia` |
95
-
96
- ### 4. Pick the properties
97
-
98
- - **`transform` and `opacity` are free.** Everything else is a layout pass. `width`, `height`, `margin`, `padding`, `flex`, `top`, `left`, `gap` re-run Yoga on every frame for that node *and its siblings*.
99
- - **The one exception: an absolutely positioned element with no children** — a tab pill, a progress bar fill. It's out of flow, so nothing else re-lays-out, and animating `width` keeps the corner radius that `scaleX` would smear.
100
- - **Never `scale(0)`.** Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.
101
- - **`transform` is an array and order matters** — `[{ translateY }, { scale }]` scales after moving; reversed, the translate gets scaled too. Keep translate first unless you want the multiplication.
102
- - **Android shadows are `elevation`, and animating elevation re-renders the shadow every frame.** Animate opacity of a pre-shadowed layer instead.
103
- - **Never animate `BlurView` intensity.** On Android it re-renders the blur each frame. Crossfade the opacity of a static `BlurView` instead.
104
- - **Percentages work in `translate`** and are relative to the element's own size — `translateY('100%')` moves a sheet by its own height whatever its content.
105
-
106
- ### 5. Timing or spring
107
-
108
- **If a finger was involved, use a spring.** Springs carry velocity through an interruption; timing curves restart. Everything else uses timing.
109
-
110
- Reanimated's spring takes Apple's two designer parameters directly — use this form, not mass/stiffness/damping:
111
-
112
- | Interaction | Config |
113
- | --- | --- |
114
- | Default settle, no overshoot | `{ duration: 400, dampingRatio: 1 }` |
115
- | Reposition / snap back after a drag | `{ duration: 400, dampingRatio: 0.8, velocity }` |
116
- | Sheet, drawer | `{ duration: 300, dampingRatio: 0.8, velocity }` |
117
- | Must not pass a hard edge | add `overshootClamping: true` |
118
-
119
- **Bounce only when the gesture carried momentum.** Overshoot on a menu that faded in feels wrong; overshoot on a card you flicked feels right.
120
-
121
- **Easing**, for everything without a finger on it:
122
-
123
- | Situation | Easing |
124
- | --- | --- |
125
- | Entering or exiting | `ease-out` |
126
- | Moving / morphing on screen | `ease-in-out` |
127
- | Constant motion (progress, marquee) | `linear` |
128
- | Default | `ease-out` |
129
-
130
- **Never `ease-in` on UI.** It starts slow, delaying the exact moment the user is watching. Reanimated's built-ins are as weak as CSS's — use these:
131
-
132
- ```js
133
- import { Easing } from 'react-native-reanimated';
134
-
135
- const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1); // strong ease-out for UI
136
- const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1); // on-screen movement
137
- const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1); // iOS sheet curve
138
- ```
139
-
140
- **Duration:**
141
-
142
- | Element | Duration |
143
- | --- | --- |
144
- | Press feedback | 100–150ms |
145
- | Toggle, chip, small state change | 150–200ms |
146
- | Sheet, modal, drawer | spring, ~300ms perceived |
147
- | Screen transition | the platform default — don't override it |
148
-
149
- Mobile UI animations stay under 300ms, same as web. The platform's own transitions are longer (iOS push is 350ms); match the platform for navigation, beat it everywhere else.
150
-
151
- ### 6. Keep it off the JS thread
152
-
153
- This is the mobile-specific craft, and it's where most React Native motion dies.
154
-
155
- - **Never `setState` from a gesture or scroll handler.** One React render per frame is the single biggest cause of jank in RN apps. Shared value → `useAnimatedStyle`, and React never re-renders at all.
156
- - **Never schedule back to the RN runtime inside `onUpdate` or a scroll handler.** `scheduleOnRN(fn, ...args)` from `react-native-worklets` — the Reanimated 4 replacement for the deprecated `runOnJS(fn)(...args)` — queues an RN-runtime call, and in `onUpdate` that's 60–120× per second. It belongs in `onEnd`, or in a `useAnimatedReaction` that fires when a value crosses a threshold.
157
- - **Never read a shared value during render** (`translateY.get()` in JSX). It's a snapshot that never updates and it silently desyncs. **Never write one during render either** — it fires mid-reconciliation, and a re-render you didn't cause replays the write. Touch shared values only in worklets, handlers, and effects.
158
- - **Use `.get()` / `.set()`, not `.value`.** Same API, but direct `.value` access is the form the React Compiler can't see through — the Reanimated docs call `get`/`set` the compiler-safe way. `set` also takes a functional update: `sv.set((v) => v + 1)`.
159
- - **Functions called from a worklet need `'worklet'`** as their first line, or they throw at runtime on device while working fine in the debugger.
160
-
161
- ### 7. Press, not hover
162
-
163
- Every hover affordance from the web has to be redesigned, not ported.
164
-
165
- - **Feedback on press-in, commit on press-out.** Waiting for the tap to complete before showing anything feels dead — this is the latency the user actually perceives.
166
- - **`scale: 0.97` in 100–150ms** on any pressable, `Pressable` + a CSS transition. `scale` takes the label and icons with it, which is what makes it read as physical.
167
- - **44×44pt minimum touch target** (48dp Android). If the visual is smaller, add `hitSlop` — don't grow the visual.
168
- - **`pressRetentionOffset`** so a finger drifting a few pixels doesn't cancel a press the user meant.
169
- - **Android ripple only in a Material-styled app.** In a custom-designed app, the same scale on both platforms is more coherent than a ripple on one.
170
-
171
- ### 8. Haptics
172
-
173
- Mobile has a sense the web doesn't. Use it sparingly and it becomes the thing that makes the app feel expensive; use it everywhere and users turn it off.
174
-
175
- | Moment | Call |
176
- | --- | --- |
177
- | A value ticks past a step — picker, slider detent, segmented control | `Haptics.selectionAsync()` |
178
- | Something snaps home, a sheet detent catches, a drag commits | `Haptics.impactAsync(ImpactFeedbackStyle.Light)` |
179
- | A heavy object lands, a destructive action fires | `Haptics.impactAsync(ImpactFeedbackStyle.Medium)` |
180
- | Operation succeeded or failed | `Haptics.notificationAsync(NotificationFeedbackType.Success / Error)` |
181
-
182
- Three rules, and they're absolute:
183
-
184
- - **Same frame as the visual.** A haptic that lags its animation reads as a glitch, not as feedback. Fire it at the causal moment — the detent catching — not when the animation finishes.
185
- - **One per user action.** Never on scroll, never per frame, never on an entrance animation the user didn't cause.
186
- - **Never the only feedback.** Haptics are off system-wide for many users, and silent on most Android hardware. The visual has to stand alone.
187
-
188
- From a worklet, haptics must be scheduled back to the RN runtime: `scheduleOnRN(Haptics.selectionAsync)`.
189
-
190
- ### 9. Reduced motion and accessibility
191
-
192
- ```jsx
193
- import { useReducedMotion, ReduceMotion, withSpring } from 'react-native-reanimated';
194
-
195
- const reduced = useReducedMotion();
196
- const y = useSharedValue(reduced ? 0 : SHEET_HEIGHT);
197
-
198
- // or let each animation decide
199
- withSpring(0, { duration: 300, dampingRatio: 0.8, reduceMotion: ReduceMotion.System });
200
- ```
201
-
202
- Reduced motion means **fewer and gentler**, not zero: keep opacity and color changes that explain a state change, drop translation, scale, parallax and overshoot. Screen transitions become `animation: 'fade'`.
203
-
204
- **Text scales.** `allowFontScaling` is on by default, so any height you measured at default type size is wrong at 200%. Never animate to a hardcoded height — measure with `onLayout`, or animate a transform instead.
205
-
206
- ## Setup that silently breaks motion
207
-
208
- Check these first when "the animation just doesn't run":
209
-
210
- - Install through Expo so versions match the SDK: `npx expo install react-native-reanimated react-native-worklets`. In an Expo project, `babel-preset-expo` configures the worklets Babel plugin automatically — no `babel.config.js` step. Only a bare RN project without that preset adds the plugin manually, and there it must be last in the list. A missing or misplaced plugin doesn't silently fall back anymore — it throws `Failed to create a worklet` at runtime.
211
- - `GestureHandlerRootView` must wrap the app, or gestures do nothing with no error.
212
- - Reanimated 4 requires the New Architecture.
213
- - **Expo Go is not a performance environment.** Judge feel in a release build; a dev build's JS thread is slow enough to hide exactly the problems you're looking for.
214
-
215
- ## 120fps
216
-
217
- On ProMotion iPhones, third-party animations are capped at 60fps unless `CADisableMinimumFrameDurationOnPhone` is set. Recent Expo SDKs set it by default — confirm it's there, and add it if not:
218
-
219
- ```json
220
- { "expo": { "ios": { "infoPlist": { "CADisableMinimumFrameDurationOnPhone": true } } } }
221
- ```
222
-
223
- Then the frame budget is 8ms, not 16. This is also why a UI-thread animation matters more on mobile than it does on web.
224
-
225
- ## Recipes
226
-
227
- For ready-to-build implementations — press feedback, drag-to-dismiss sheet, swipe-to-delete, collapsing header, list entrances, keyboard-synced UI, tab indicator, screen transitions — see [RECIPES.md](RECIPES.md). Load it whenever the request matches one; start from the recipe rather than from a blank file.
228
-
229
- ## Never Ship
230
-
231
- | Never | Instead |
232
- | --- | --- |
233
- | `PanResponder` | `Gesture.Pan()` from gesture-handler |
234
- | `setState` in a gesture or scroll handler | shared value + `useAnimatedStyle` |
235
- | `runOnJS` (deprecated in Reanimated 4) | `scheduleOnRN` from `react-native-worklets` |
236
- | `scheduleOnRN` per frame | `onEnd`, or `useAnimatedReaction` at a threshold |
237
- | Reading or writing a shared value during render | `.get()` / `.set()` in worklets, handlers, effects |
238
- | Core `Animated` for anything a finger touches | Reanimated |
239
- | Animating `height` / `width` / `margin` / `flex` / `top` | `transform` + `opacity` (absolute, childless elements exempt) |
240
- | Animating `BlurView` intensity or Android `elevation` | crossfade a static layer |
241
- | `entering` on a virtualized list row | animate the container, or `itemLayoutAnimation` |
242
- | A screen transition rebuilt in JS | native stack `animation` |
243
- | Sliding between tabs | `animation: 'none'` |
244
- | `Easing.in(...)` on a UI element | `Easing.bezier(0.23, 1, 0.32, 1)` |
245
- | `scale(0)` entrance | `scale(0.95)` + `opacity: 0` |
246
- | Distance-only dismissal threshold | velocity **or** distance — a flick is enough |
247
- | Hard stop at a boundary | rubber-band resistance |
248
- | A haptic per frame, or as the only feedback | one per commit, always paired with a visual |
249
- | Judging feel in Expo Go or the simulator | release build, slowest supported device |
250
-
251
- ## Output
252
-
253
- Write the code. Then, in at most a few lines:
254
-
255
- - **The gate result** — frequency tier and named purpose. Say what you rejected and why.
256
- - **The ingredients** — tool, properties, spring or curve + duration, thread.
257
- - **What to feel-check on device** — gestures, velocity handoff and haptic timing cannot be judged from code. Name what to try: flick it, interrupt it mid-flight, reverse it, run it on the slowest Android you have.
258
-
259
- The code is the deliverable. Don't pad it into a report.
260
-
261
- ## Tone
262
-
263
- Opinionated and brief. When the honest answer is "this shouldn't animate," or "this needs a real device before I can tell you if it's right," give it.
@@ -1,181 +0,0 @@
1
- ---
2
- name: animation-vocabulary
3
- description: Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.
4
- ---
5
-
6
- # Animation Vocabulary
7
-
8
- ## Initial Response
9
-
10
- When this skill is first invoked without a specific question, respond only with:
11
-
12
- > I'm ready to put a name to any motion effect you describe, my knowledge comes from Emil Kowalski's animation philosophy.
13
-
14
- Do not provide any other information until the user asks a question.
15
-
16
- Turn a vague description of a motion or effect into the precise term, so the user knows what to ask for.
17
-
18
- ## Quick Start
19
-
20
- The user describes an effect loosely. You return the matching term(s) in this format:
21
-
22
- ```
23
- **Stagger** — Animate several items one after another with a small delay between each, creating a cascade.
24
- ```
25
-
26
- If several terms could fit, list the best match first, then 1–2 alternates with a one-line note on how they differ.
27
-
28
- ## Instructions
29
-
30
- 1. **Read for intent, not keywords.** Users describe what they *see* or *feel* ("springy", "slides off", "draws itself in"), not the technical name. Map the sensation to the glossary below.
31
- 2. **Quote the glossary verbatim.** Its descriptions are authoritative — use them as-is, don't paraphrase.
32
- 3. **Disambiguate close terms.** When two compete (*Clip-path* vs *Mask*, *Pop in* vs *Bounce*, *Shared element transition* vs *Layout animation*), contrast them so the user can pick.
33
- 4. **When nothing matches exactly,** name the closest term and say plainly it's an approximation, or describe the effect in the glossary's vocabulary (e.g. "that's a *stagger* of *scale-in* entrances").
34
- 5. **Stay within this glossary.** If a term genuinely isn't here, say so rather than inventing one — though you may explain the concept using these words.
35
- 6. **Keep it tight.** A naming question wants a name, not an essay. Lead with the term; expand only if asked.
36
-
37
- ## Examples
38
-
39
- **Example 1 — feel-based**
40
- User: "What's it called when a popover seems to grow out of the button you clicked instead of from its middle?"
41
- Output:
42
- ```
43
- **Origin-aware animation** — An element animates out of its trigger, like a popover growing from the button that opened it instead of from its own center which is the default in CSS.
44
- ```
45
-
46
- **Example 2 — disambiguation**
47
- User: "The thing where one image turns into another image."
48
- Output:
49
- ```
50
- **Morph** — One shape smoothly turns into another shape, e.g. Dynamic Island.
51
-
52
- Close alternates:
53
- - **Crossfade** — if they simply fade over each other in the same spot.
54
- - **Shared element transition** — if an element travels and transforms from one position into another.
55
- ```
56
-
57
- **Example 3 — physics feel**
58
- User: "That iOS scroll where it resists and snaps back when you pull too far."
59
- Output:
60
- ```
61
- **Rubber-banding** — Resistance and snap-back when you drag past a boundary (the iOS overscroll feel).
62
- ```
63
-
64
- ## Glossary
65
-
66
- _A curated snapshot mirroring the project's `/vocabulary` page; keep the two in sync when either changes._
67
-
68
- ### Entrances & Exits — how elements appear and disappear
69
- - **Fade in / Fade out** — Element appears or disappears by changing opacity.
70
- - **Slide in** — Element enters by sliding in from off-screen (left, right, top, or bottom).
71
- - **Scale in** — Element grows from smaller to full size as it appears, often paired with a fade.
72
- - **Pop in** — Element appears with a slight overshoot, like it bounces into place.
73
- - **Reveal** — Content is uncovered gradually, often by animating a clip-path or mask.
74
- - **Enter / Exit** — The animation an element plays when it's added to or removed from the screen.
75
-
76
- ### Sequencing & Timing — coordinating multiple elements or moments
77
- - **Keyframes** — Defined points in an animation (0%, 50%, 100%) that the browser fills the gaps between.
78
- - **Interpolation / Tween** — Generating all the in-between frames between a start and end value, so motion is continuous.
79
- - **Stagger** — Animate several items one after another with a small delay between each, creating a cascade.
80
- - **Orchestration** — Deliberately timing multiple animations so they feel like one coordinated motion.
81
- - **Delay** — Time before an animation starts.
82
- - **Duration** — How long an animation takes.
83
- - **Fill mode** — Whether an element keeps its first or last frame's styles before the animation starts or after it ends (e.g. forwards).
84
- - **Stepped animation** — An animation that is divided into discrete steps, like a countdown timer.
85
-
86
- ### Movement & Transforms — changing an element's position, size, or angle
87
- - **Translate** — Move an element along the X or Y axis.
88
- - **Scale** — Make an element bigger or smaller.
89
- - **Rotate** — Spin an element around a point.
90
- - **Skew** — Slant an element along the X or Y axis, shearing it out of its rectangular shape.
91
- - **3D tilt / Flip** — Rotate in 3D space (rotateX / rotateY) to add depth.
92
- - **Perspective** — How strong the 3D effect looks — a lower value exaggerates depth, like the viewer is closer.
93
- - **Transform origin** — The anchor point a scale or rotation grows or spins from.
94
- - **Origin-aware animation** — An element animates out of its trigger, like a popover growing from the button that opened it instead of from its own center which is the default in CSS.
95
-
96
- ### Transitions Between States — connecting one state, view, or element to another
97
- - **Crossfade** — One element fades out as another fades in, in the same spot.
98
- - **Continuity transition** — A change that keeps the user oriented by visually connecting before and after. For example, making the same rectangle bigger and smaller.
99
- - **Morph** — One shape smoothly turns into another shape, e.g. Dynamic Island.
100
- - **Shared element transition** — An element travels and transforms from one position into another, like a thumbnail expanding into a card.
101
- - **Layout animation** — When an element's size or position changes, it animates to the new spot instead of snapping.
102
- - **Accordion / Collapse** — A section smoothly expands and collapses its height to show or hide content.
103
- - **Direction-aware transition** — Content slides one way going forward and the opposite way going back, so navigation has a sense of direction.
104
-
105
- ### Scroll — motion tied to scrolling or navigating between views
106
- - **Scroll reveal** — Elements fade or slide into place as they enter the viewport.
107
- - **Scroll-driven animation** — An animation whose progress is tied directly to scroll position.
108
- - **Parallax** — Background and foreground move at different speeds while scrolling, creating depth.
109
- - **Page transition** — An animation that plays when navigating from one page or route to another.
110
- - **View transition** — The browser morphs between two states or pages, connecting shared elements.
111
-
112
- ### Feedback & Interaction — responding to the user's actions
113
- - **Hover effect** — Visual change when the cursor moves over an element.
114
- - **Press / Tap feedback** — A subtle scale-down when an element is clicked, so it feels physical.
115
- - **Hold to confirm** — A progress effect that fills up while the user holds a button.
116
- - **Drag** — Moving an element by grabbing it, often with momentum when released.
117
- - **Drag to reorder** — Dragging items in a list to rearrange them, while the others shift to make room.
118
- - **Swipe to dismiss** — Dragging an element off-screen to close it, like a drawer or toast.
119
- - **Rubber-banding** — Resistance and snap-back when you drag past a boundary (the iOS overscroll feel).
120
- - **Shake / Wiggle** — A quick side-to-side jitter signaling an error or rejected input.
121
- - **Ripple** — A circle expanding from the point of a tap, confirming the press.
122
-
123
- ### Easing — how speed changes over an animation
124
- - **Easing** — The rate at which an animation speeds up or slows down.
125
- - **Ease-out** — Starts fast, ends slow. The default for most UI and anything responding to the user.
126
- - **Ease-in** — Starts slow, ends fast. Usually avoided; can feel sluggish.
127
- - **Ease-in-out** — Slow, fast, slow. Good for elements already on screen moving from A to B.
128
- - **Linear** — Constant speed. Avoid for UI; reserve for spinners or marquees.
129
- - **Cubic-bezier** — A custom easing curve you define for precise control.
130
- - **Asymmetric easing** — A curve that accelerates and decelerates at different rates. Feels more alive than a symmetric one.
131
-
132
- ### Spring Animations — physics-based motion as an alternative to fixed-duration easing
133
- - **Spring** — Motion driven by physics (tension, mass, damping) rather than a set duration.
134
- - **Stiffness / Tension** — How strongly the spring pulls toward its target. Higher feels snappier.
135
- - **Damping** — How quickly a spring settles. Lower damping means more bounce and oscillation.
136
- - **Mass** — How heavy the animated element feels. More mass makes it slower and more sluggish.
137
- - **Bounce** — A spring that overshoots and settles, adding playfulness.
138
- - **Perceptual duration** — How long a spring feels finished, even though it keeps micro-settling underneath.
139
- - **Momentum** — Motion that carries velocity, especially after a drag or interruption.
140
- - **Velocity** — How fast and in which direction an element is moving. A spring carries it into the next animation when interrupted, so a flicked element keeps its speed.
141
- - **Interruptible animation** — An animation that can be smoothly redirected mid-flight instead of finishing first.
142
-
143
- ### Looping & Ambient Motion — animations that run on their own
144
- - **Marquee** — Text or content that scrolls continuously in a loop.
145
- - **Loop** — An animation that repeats, a set number of times or infinitely.
146
- - **Alternate (yoyo)** — A loop that plays forward then reverses each iteration, instead of jumping back to the start.
147
- - **Orbit** — An element circling around another in a continuous path.
148
- - **Pulse** — A gentle repeating scale or opacity change to draw attention.
149
- - **Float** — A gentle, continuous up-and-down drift that makes a static element feel alive and weightless.
150
- - **Idle animation** — Subtle motion that plays while an element is just sitting there, waiting to be interacted with.
151
-
152
- ### Polish & Effects — the small touches that separate good from great
153
- - **Blur** — A blur filter used to soften an element or mask tiny imperfections.
154
- - **Clip-path** — Clipping an element to a shape, used for reveals, masks, and before/after sliders.
155
- - **Mask** — Hiding or revealing parts of an element using a shape or gradient — like clip-path, but with soft, fadeable edges.
156
- - **Before / after slider** — A draggable divider that wipes between two overlaid images to compare them.
157
- - **Line drawing** — An SVG path that draws itself in, like an invisible pen tracing it.
158
- - **Text morph** — Text that animates character by character when it changes, drawing attention to the new value.
159
- - **Skeleton / Shimmer** — A placeholder with a moving sheen shown while content loads.
160
- - **Number ticker** — Digits rolling or counting up to a value.
161
- - **Tabular numbers** — Fixed-width digits so numbers don't shift around as they change. Essential for tickers, timers, and counters.
162
- - **Typewriter** — Text appearing one character at a time, as if being typed.
163
-
164
- ### Performance — what keeps motion smooth instead of stuttering
165
- - **Frame rate (FPS)** — Frames drawn per second. 60fps is the baseline for smooth motion; 120fps on newer displays.
166
- - **Jank** — Visible stutter when the browser drops frames because it can't keep up with the animation.
167
- - **Dropped frame** — A frame the browser missed its deadline to draw, causing a tiny hitch in motion.
168
- - **Compositing** — Letting the GPU move or fade an element on its own layer without redoing layout or paint.
169
- - **will-change** — A CSS hint that an element is about to animate, so the browser can promote it to its own layer ahead of time.
170
- - **Layout thrashing** — Animating properties like width, height, top, or left that force the browser to recalculate layout every frame, causing jank.
171
-
172
- ### Principles to Know — concepts that guide when and how to animate
173
- - **Purposeful animation** — Motion should serve a function — orient, give feedback, show relationships — not just decorate.
174
- - **Anticipation** — A small wind-up in the opposite direction before a move, hinting at what's about to happen.
175
- - **Follow-through** — Parts of an element keep moving and settle slightly after the main motion stops, adding weight.
176
- - **Squash & stretch** — Deforming an element as it moves to convey weight, speed, and flexibility.
177
- - **Perceived performance** — The right animation makes an interface feel faster, even when it isn't.
178
- - **Frequency of use** — The more often a user sees an animation, the shorter and subtler it should be.
179
- - **Spatial consistency** — Animating so an element keeps its identity and position across states, so users never lose track of where things went.
180
- - **Hardware acceleration** — Animating transform and opacity lets the GPU keep motion smooth.
181
- - **Reduced motion** — Respecting the user's prefers-reduced-motion setting by toning down or removing motion.