vibecodeagent 0.0.0-stage → 0.1.64

package/dist/resources/skills/builtin/frontend-design/references/craft.md

@@ -0,0 +1,128 @@
+# Interface Craft
+
+The habits that separate an interface that feels considered from one that merely works. Each is here because its absence has a specific, recognisable symptom — named so you can catch it before a person has to. The compressed version of the first six lives in the skill hub; this file is the full text, plus component-building principles and where to look for reference.
+
+## 1. Space is the design; everything else is content
+
+Most interfaces that "look off" are spaced off, not coloured off.
+
+- **Pick one scale and never leave it.** 4 / 8 / 12 / 16 / 24 / 32. A single `13px` gap among 12s and 16s is invisible alone and reads as sloppiness in aggregate.
+- **Space belongs to the group, not the element.** Set gaps on the container (`gap`, `space-y`), never as a margin on each child. Margins on children make the first and last item wrong, and every conditional item wrong twice.
+- **Proximity IS grouping.** Things 8px apart read as one thing; 24px apart read as two. If a label and its input are as far apart as two unrelated fields, no amount of styling repairs it.
+- **The symptom of getting this wrong:** everything is aligned, nothing is ugly, and the screen still feels like a list of parts.
+- **Components respond to their container, not the viewport.** A card that lives in both a sidebar and a main column needs `@container`, not `@media` — viewport breakpoints describe the page, container queries describe the component. Reach for media queries only for page-level layout shifts.
+
+## 2. Three type sizes, two weights, one family
+
+An interface needs far less typographic variety than it seems.
+
+- Body, secondary, and one heading size covers almost every screen. Reach for a fourth only when a real hierarchy demands it.
+- **Weight carries hierarchy better than size.** Going 500 → 600 separates a heading from body more cleanly than adding 4px, and it does not disturb the vertical rhythm.
+- **Line height tracks size inversely.** Body text wants 1.5–1.6; a 32px heading wants 1.1–1.2. Uniform line height makes headings look loose and body text look cramped, and it is the single most common giveaway of an unstyled app.
+- **Long lines are unreadable.** Cap prose at 60–75 characters. Full-width text in a wide window is the most common accessibility failure that no checker flags.
+- Use `text-wrap: balance` on headings and `text-wrap: pretty` on prose to kill orphans; `font-variant-numeric: tabular-nums` wherever numbers change in place (timers, counters, prices) so digits don't shift the layout.
+
+For display-scale typography — dramatic pairings, fluid `clamp()` scales, tracking ladders — see [typography.md](typography.md).
+
+## 3. Colour carries meaning, not decoration
+
+- **Neutrals do the work; one accent does the pointing.** If two colours compete for attention, neither has it.
+- **Never use colour as the only signal.** Red text alone excludes colour-blind users and anyone glancing. Pair it with an icon, a label, or a shape.
+- **Contrast is a number, not an impression.** 4.5:1 for body text, 3:1 for large text and UI boundaries. "Looks fine on my screen" is measured on one screen, at one brightness, by someone who already knows what it says.
+- **Semantic tokens, never raw hex.** `--danger`, not `#e5484d`. Raw values are how a theme drifts: the tenth red is never quite the first nine.
+- **Design light and dark together, not dark as an afterthought.** Dark mode is not inverted light mode: shadows stop working (use borders and lighter surfaces to signal elevation), pure white text on pure black vibrates (use `#e5e5e5`-ish on `#0a0a0a`-ish), and saturated accents need desaturating a step. Define both palettes as the same semantic tokens and switch at the token layer — never per-component. Full implementation doctrine (token architecture, no-flash, the three-state toggle) in [theming.md](theming.md).
+
+## 4. Design every state, not just the happy one
+
+The screen you sketch is one of five, and the other four are where people live.
+
+| State | The question it answers |
+|---|---|
+| Empty | What is this, and what do I do first? |
+| Loading | Is it working, and roughly how long? |
+| Partial | Some data arrived — is the rest coming or gone? |
+| Error | What happened, and what can I do now? |
+| Full | The one everyone designs |
+
+- **An empty state is the best onboarding you will ever ship.** It is the only screen where the user is looking directly at the thing they do not understand yet. "No sessions yet" wastes it; "Start by typing below" does not.
+- **Skeletons beat spinners** when you know the shape of what is coming: the layout stops jumping when data lands. Reserve space for anything async (`aspect-ratio`, fixed skeleton heights) — layout shift is a design failure before it is a metric failure.
+- **Errors must name the next action.** "Something went wrong" is the interface admitting it will not help. Say what failed and what to press.
+
+## 5. Interactive things must look and behave interactive
+
+- **Hit targets are 44×44 minimum,** regardless of how small the icon looks. Padding counts toward it; the icon alone does not.
+- **Every interactive element needs hover, focus-visible, active, and disabled.** Missing focus-visible is a keyboard user hitting Tab into nothing — the most common way an interface silently excludes people.
+- **Buttons must feel responsive to press**: `transform: scale(0.97)` on `:active` with `transition: transform 160ms var(--ease-out)`. Subtle (0.95–0.98). `scale()` takes the label and icons with it, which is what makes it read as a physical press.
+- **Disabled must say why.** A greyed-out button with no explanation is a dead end; a tooltip or an inline line turns it into an instruction.
+- **Never remove an outline without replacing it.** `outline: none` with nothing after it is the single most damaging line in web CSS.
+- **Use the platform's real elements before rebuilding them.** `<dialog>` gives you focus trapping, `Esc`, and a top-layer z-index for free; the `popover` attribute does the same for popovers/menus, and `@starting-style` animates both without JS. A `<div>` dropdown with hand-rolled focus management is how accessibility dies. When a real component library is warranted, consult [libraries.md](libraries.md).
+
+## 6. Forms are where trust is won or lost
+
+- **Visible labels, always.** A placeholder is not a label — it vanishes the moment the user starts typing, exactly when they need it.
+- **Validate at the right moment**: on blur for format errors, on submit for completeness, *never* on every keystroke of an incomplete entry. Yelling "invalid email" after the first character is the interface interrupting mid-sentence. Once a field has erred, re-validate eagerly so the error clears the moment it is fixed.
+- **The error lives next to the field**, in text, with an icon — plus a summary at the top only for long forms. Colour alone is not an error message.
+- **Don't fight the browser.** Correct `type=` and `autocomplete=` attributes give users their saved addresses and passwords; `inputmode` gives them the right keyboard. Blocking paste in a password or code field breaks password managers and fails WCAG.
+- **Preserve what the user typed** through every failure — a submit error that clears the form is data loss, and the user experiences it exactly that way.
+- **The primary action is one button.** One screen, one primary CTA; everything else is visually subordinate.
+
+## 7. Motion clarifies; it does not perform
+
+The compressed rule set — full doctrine with all values in [motion.md](motion.md):
+
+- **Fast.** 150–250ms for most transitions. Anything past 300ms reads as lag.
+- **Ease-out for entrances, ease-in for exits only in the sense of leaving faster** — never `ease-in` to arrive. Linear reads as mechanical.
+- **Animate transforms and opacity only.**
+- **Motion should explain where something came from.** A menu growing out of the button that opened it teaches the relationship; the same menu fading in from nowhere teaches nothing and costs the same.
+- **Honour `prefers-reduced-motion`.** For some people this is not a preference; it is nausea.
+
+## Component-building principles
+
+From building components people love (Sonner, 13M+ weekly downloads) — they apply to any component:
+
+1. **Developer experience is adoption.** No hooks, no context, no setup ceremony. The less friction to adopt, the more it gets used.
+2. **Good defaults matter more than options.** Ship beautiful out of the box; most users never customize. The default easing, timing, and visual design should be excellent.
+3. **Handle edge cases invisibly.** Pause timers when the tab is hidden. Fill gaps between stacked items with pseudo-elements so hover state survives. Capture pointer events during drag. Users never notice — that is exactly right.
+4. **Cohesion beats correctness-in-isolation.** The easing, duration, visual design, and even the name should be in harmony. Match the motion to the component's personality.
+5. **Unseen details compound.** Most details users never consciously notice — when a feature works exactly as someone assumes it should, they proceed without a second thought. That is the goal. The aggregate of invisible correctness is why an interface feels loved.
+
+## Where to look, and how to steal
+
+The fastest way to raise the quality of an interface is to look at one that is already excellent — and the fastest way to waste that is to copy its surface.
+
+**Study the decisions, not the screenshots.** When you look at an interface you admire, the useful questions are structural: What is the spacing unit? (Measure two gaps — you will almost always find 4 or 8, everywhere.) How many type sizes are actually used? (Usually three.) Where does the single accent colour appear — and where does it deliberately not? What happens on hover, focus, and press? What does the empty state say? Copying a screenshot gives you someone else's answer to a question you never asked. Copying the *scale* gives you a system.
+
+**Interfaces worth reading closely** — chosen because their decisions are legible: **Linear** (density, keyboard-first, colour restraint), **Vercel/Geist** (typography and spacing discipline, documented publicly), **Stripe** (forms, error states, docs — their form validation is the reference implementation), **Raycast** (command palettes, keyboard models), **Arc/Notion** (motion explaining hierarchy). For motion: `animations.dev` and the source of `sonner` and `vaul` — small enough to read end to end.
+
+**Galleries, with one caution**: Godly (curated, marketing-heavy), Mobbin (real product screens by flow — the best source for "how do others solve onboarding/settings/empty states"), Land-book (landing pages), and the book *Refactoring UI* (the densest actionable rules for developers who design). The caution: galleries reward the photogenic. Award-winning sites are often slow, inaccessible, and unusable on a phone, because a screenshot cannot show any of that. Never take a gallery entry as the target for an application UI — marketing pages and products have opposite goals. (When the brief genuinely *is* an award-level marketing page, that's [art-direction.md](art-direction.md).)
+
+**Systems worth adopting instead of inventing**: Radix Primitives / Base UI (unstyled, accessible, correct) and shadcn/ui (copy-in, not dependency); ONE icon set — Lucide, Phosphor, or Heroicons — never mixed, because stroke weights differ by fractions and the eye catches every one; Radix Colors or Tailwind's palette for a colour system that already solved dark mode and contrast pairs; Inter, Geist, or the system stack for dense UI (a distinctive display face is for landing pages — see [typography.md](typography.md)).
+
+**Judge a reference by what a screenshot hides.** Before adopting anything: Tab through it (if focus disappears, the design is incomplete), resize to 375px (most award layouts collapse), and throttle CPU/network (motion that felt elegant at 8× CPU often reads as broken at 1×). An interface that survives all three is worth learning from. One that does not is a picture, not a design.
+
+## Text is data too — i18n and RTL
+
+Interfaces built for one language break in the second one. The habits that cost nothing now and everything later:
+
+- **Logical properties, not physical.** `margin-inline-start`, `padding-inline`, `inset-inline-end`, `text-align: start` — then `dir="rtl"` works without a second stylesheet. `margin-left` is a bug waiting for its first RTL user.
+- **Design for +30% text.** German and Indonesian run longer than English; a button sized to fit "Save" exactly will truncate "Simpan perubahan". Let containers grow (`min-width`, not `width`) and test one verbose locale.
+- **Never concatenate sentence fragments** around variables or controls — word order differs per language. One string with placeholders (`"Menghapus {n} berkas"`), never `"Menghapus " + n + " berkas"`.
+- **`Intl` formats numbers, dates, and lists** — hand-formatted `1,234.56` is wrong in most of the world. `tabular-nums` still applies to whatever `Intl` produces.
+- **Icons flip selectively in RTL**: directional ones (back arrows, "next") mirror; universal ones (clock, search, media play) do not.
+
+## Pre-delivery checklist — web
+
+The last pass before calling UI done. Each line is checkable without taste:
+
+1. **Keyboard**: Tab through everything — visible focus on every stop, order matches visual order, `Esc` closes what it should, focus returns to the trigger after overlays close.
+2. **States**: empty, loading, error, and partial each render something designed — no blank panes, no raw error strings.
+3. **375px width**: no horizontal scroll, no truncated critical text, targets still 44×44.
+4. **Dark mode** (if shipped): flip it — no raw-hex survivors, no glowing shadows, imagery not blinding; check at low screen brightness.
+5. **Reduced motion**: toggle it in DevTools Rendering panel — movement gone, feedback still present.
+6. **Contrast**: spot-check body text and muted text against their real backgrounds — 4.5:1, measured, both themes.
+7. **Slow it down**: CPU 4×, network Slow 3G — skeletons appear, nothing jumps when data lands (CLS ≈ 0), interactions still respond < 200ms.
+8. **Zoom 200%**: text scales, nothing overlaps, nothing is clipped.
+9. **Real content**: longest plausible names, 0 items, 10,000 items, a 2-line title — the layout survives all four.
+10. **Console clean** and no 404s for fonts/images.
+
+The native-app version of this checklist (safe areas, haptics, platform idioms) is in [app-polish.md](app-polish.md).

package/dist/resources/skills/builtin/frontend-design/references/expo.md

@@ -0,0 +1,251 @@
+
+# Building Animations in Expo
+
+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.
+
+Mobile changes three things about animation, and everything in this skill follows from them:
+
+1. **There is no hover.** Every affordance the web puts in hover has to live in press, position, or nothing.
+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.
+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.
+
+## Operating Posture
+
+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.
+
+Two failure modes, and the first is worse:
+
+1. **Animating something that shouldn't animate.** The gate below exists to produce zero lines of code sometimes.
+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.
+
+## Hard Rules
+
+1. **Run the sequence in order.** Steps 1 and 2 gate everything.
+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.
+3. **No approximated values.** Curves and spring configs come from the tables below.
+4. **Reduced motion ships with the animation**, not as a follow-up.
+5. **Feel is judged on a release build on the slowest device you support.** Nothing else counts as verified.
+
+## The Build Sequence
+
+### 1. Should this animate at all?
+
+| Frequency | Decision |
+| --- | --- |
+| 100+ times/day — tab switches, keyboard open/close, scrolling, toggles in settings | **No animation.** Platform default or nothing. Stop here. |
+| Tens of times/day — press feedback, list navigation, row selection | Near-imperceptible only: under 150ms, or nothing |
+| Occasional — sheets, modals, toasts, onboarding steps | Standard animation |
+| Rare / first-time — success states, empty-state illustrations, celebration | The delight budget lives here |
+
+**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'`.
+
+If the request fails this gate, say so and don't write it.
+
+### 2. What is the purpose?
+
+Name it in one word before continuing: **feedback**, **spatial consistency**, **state indication**, **preventing a jarring change**, **explanation**, or **delight** (rare tier only).
+
+Can't name it? Don't build it.
+
+### 3. Pick the tool — cheapest that works
+
+Walk down; stop at the first that fits.
+
+| Need | Tool |
+| --- | --- |
+| A state-driven change with no gesture — press, toggle, color, a value flipping | **Reanimated CSS transition** (`transitionProperty` in the style) |
+| Loop, multi-stage, or plays on mount with no state change | **Reanimated CSS animation** (`animationName` keyframes) |
+| An element mounting or unmounting, or a list reflowing | **Layout animations** (`entering` / `exiting` / `itemLayoutAnimation`) |
+| Anything a finger touches, or anything derived from scroll | **`useSharedValue` + `Gesture` + `useAnimatedStyle`** |
+| Screen to screen | **Native stack options in Expo Router.** Never hand-roll this |
+| A bottom sheet that is its own screen | **`presentation: 'formSheet'`** — it's a real UISheetPresentationController, free and correct |
+| Tab bar | **`NativeTabs`** (from `expo-router/unstable-native-tabs`) — the platform's real tab bar, its behaviors and transitions included |
+| Context menu, press-and-hold preview | **`Link.Menu` / `Link.Preview`** (Expo Router, iOS-only) — native menus and peek, never rebuilt in JS |
+| Header that collapses into a large title | **`headerLargeTitleEnabled`** on the native stack (iOS-only; `headerLargeTitle` is deprecated) — not a scroll worklet |
+| Pull to refresh | **`RefreshControl`** — hand-roll only when it's a signature interaction (see the threshold recipe) |
+| UI that tracks the keyboard | **`react-native-keyboard-controller`** — the keyboard's real position, frame by frame, on the UI thread |
+| Vector illustration, celebration, empty state | **Lottie** — for illustration only, never for UI state |
+| A huge animated scene, freeform drawing | **`@shopify/react-native-skia`** — a canvas, for when the view hierarchy itself is the bottleneck |
+
+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.
+
+**Dependencies.** Install with `npx expo install <package>` — it resolves the version that matches the project's SDK, which plain `npm install` won't:
+
+| Need | Package |
+| --- | --- |
+| Animation | `react-native-reanimated` + `react-native-worklets` |
+| Gestures | `react-native-gesture-handler` |
+| Navigation, sheets, native tabs, menus | `expo-router` |
+| Haptics | `expo-haptics` |
+| Keyboard-following UI | `react-native-keyboard-controller` (needs `KeyboardProvider` at the root — see the keyboard recipe) |
+| Illustration, celebration | `lottie-react-native` |
+| Very large animated scenes, custom drawing | `@shopify/react-native-skia` |
+
+### 4. Pick the properties
+
+- **`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*.
+- **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.
+- **Never `scale(0)`.** Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.
+- **`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.
+- **Android shadows are `elevation`, and animating elevation re-renders the shadow every frame.** Animate opacity of a pre-shadowed layer instead.
+- **Never animate `BlurView` intensity.** On Android it re-renders the blur each frame. Crossfade the opacity of a static `BlurView` instead.
+- **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.
+
+### 5. Timing or spring
+
+**If a finger was involved, use a spring.** Springs carry velocity through an interruption; timing curves restart. Everything else uses timing.
+
+Reanimated's spring takes Apple's two designer parameters directly — use this form, not mass/stiffness/damping:
+
+| Interaction | Config |
+| --- | --- |
+| Default settle, no overshoot | `{ duration: 400, dampingRatio: 1 }` |
+| Reposition / snap back after a drag | `{ duration: 400, dampingRatio: 0.8, velocity }` |
+| Sheet, drawer | `{ duration: 300, dampingRatio: 0.8, velocity }` |
+| Must not pass a hard edge | add `overshootClamping: true` |
+
+**Bounce only when the gesture carried momentum.** Overshoot on a menu that faded in feels wrong; overshoot on a card you flicked feels right.
+
+**Easing**, for everything without a finger on it:
+
+| Situation | Easing |
+| --- | --- |
+| Entering or exiting | `ease-out` |
+| Moving / morphing on screen | `ease-in-out` |
+| Constant motion (progress, marquee) | `linear` |
+| Default | `ease-out` |
+
+**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:
+
+```js
+import { Easing } from 'react-native-reanimated';
+
+const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1);      // strong ease-out for UI
+const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1);  // on-screen movement
+const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1);    // iOS sheet curve
+```
+
+**Duration:**
+
+| Element | Duration |
+| --- | --- |
+| Press feedback | 100–150ms |
+| Toggle, chip, small state change | 150–200ms |
+| Sheet, modal, drawer | spring, ~300ms perceived |
+| Screen transition | the platform default — don't override it |
+
+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.
+
+### 6. Keep it off the JS thread
+
+This is the mobile-specific craft, and it's where most React Native motion dies.
+
+- **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.
+- **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.
+- **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.
+- **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)`.
+- **Functions called from a worklet need `'worklet'`** as their first line, or they throw at runtime on device while working fine in the debugger.
+
+### 7. Press, not hover
+
+Every hover affordance from the web has to be redesigned, not ported.
+
+- **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.
+- **`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.
+- **44×44pt minimum touch target** (48dp Android). If the visual is smaller, add `hitSlop` — don't grow the visual.
+- **`pressRetentionOffset`** so a finger drifting a few pixels doesn't cancel a press the user meant.
+- **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.
+
+### 8. Haptics
+
+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.
+
+| Moment | Call |
+| --- | --- |
+| A value ticks past a step — picker, slider detent, segmented control | `Haptics.selectionAsync()` |
+| Something snaps home, a sheet detent catches, a drag commits | `Haptics.impactAsync(ImpactFeedbackStyle.Light)` |
+| A heavy object lands, a destructive action fires | `Haptics.impactAsync(ImpactFeedbackStyle.Medium)` |
+| Operation succeeded or failed | `Haptics.notificationAsync(NotificationFeedbackType.Success / Error)` |
+
+Three rules, and they're absolute:
+
+- **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.
+- **One per user action.** Never on scroll, never per frame, never on an entrance animation the user didn't cause.
+- **Never the only feedback.** Haptics are off system-wide for many users, and silent on most Android hardware. The visual has to stand alone.
+
+From a worklet, haptics must be scheduled back to the RN runtime: `scheduleOnRN(Haptics.selectionAsync)`.
+
+### 9. Reduced motion and accessibility
+
+```jsx
+import { useReducedMotion, ReduceMotion, withSpring } from 'react-native-reanimated';
+
+const reduced = useReducedMotion();
+const y = useSharedValue(reduced ? 0 : SHEET_HEIGHT);
+
+// or let each animation decide
+withSpring(0, { duration: 300, dampingRatio: 0.8, reduceMotion: ReduceMotion.System });
+```
+
+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'`.
+
+**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.
+
+## Setup that silently breaks motion
+
+Check these first when "the animation just doesn't run":
+
+- 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.
+- `GestureHandlerRootView` must wrap the app, or gestures do nothing with no error.
+- Reanimated 4 requires the New Architecture.
+- **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.
+
+## 120fps
+
+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:
+
+```json
+{ "expo": { "ios": { "infoPlist": { "CADisableMinimumFrameDurationOnPhone": true } } } }
+```
+
+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.
+
+## Recipes
+
+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-expo.md](recipes-expo.md). Load it whenever the request matches one; start from the recipe rather than from a blank file.
+
+## Never Ship
+
+| Never | Instead |
+| --- | --- |
+| `PanResponder` | `Gesture.Pan()` from gesture-handler |
+| `setState` in a gesture or scroll handler | shared value + `useAnimatedStyle` |
+| `runOnJS` (deprecated in Reanimated 4) | `scheduleOnRN` from `react-native-worklets` |
+| `scheduleOnRN` per frame | `onEnd`, or `useAnimatedReaction` at a threshold |
+| Reading or writing a shared value during render | `.get()` / `.set()` in worklets, handlers, effects |
+| Core `Animated` for anything a finger touches | Reanimated |
+| Animating `height` / `width` / `margin` / `flex` / `top` | `transform` + `opacity` (absolute, childless elements exempt) |
+| Animating `BlurView` intensity or Android `elevation` | crossfade a static layer |
+| `entering` on a virtualized list row | animate the container, or `itemLayoutAnimation` |
+| A screen transition rebuilt in JS | native stack `animation` |
+| Sliding between tabs | `animation: 'none'` |
+| `Easing.in(...)` on a UI element | `Easing.bezier(0.23, 1, 0.32, 1)` |
+| `scale(0)` entrance | `scale(0.95)` + `opacity: 0` |
+| Distance-only dismissal threshold | velocity **or** distance — a flick is enough |
+| Hard stop at a boundary | rubber-band resistance |
+| A haptic per frame, or as the only feedback | one per commit, always paired with a visual |
+| Judging feel in Expo Go or the simulator | release build, slowest supported device |
+
+## Output
+
+Write the code. Then, in at most a few lines:
+
+- **The gate result** — frequency tier and named purpose. Say what you rejected and why.
+- **The ingredients** — tool, properties, spring or curve + duration, thread.
+- **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.
+
+The code is the deliverable. Don't pad it into a report.
+
+## Tone
+
+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.