@superwall/cli 1.7.0 → 2.0.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.
- package/README.md +192 -52
- package/dist/{setup-Bxj22rYi.js → apple-CkKlHBZ9.js} +82 -76
- package/dist/auth.d.ts +4 -19
- package/dist/auth.js +4 -2
- package/dist/{actions-B7ym3oVS.js → billing-XCZU_T46.js} +98 -28
- package/dist/{bind-YrJvuRF9.js → bind-drne__Ys.js} +38 -33
- package/dist/{build-DLoCW5Ri.js → build-Gpdq5QXP.js} +20 -26
- package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
- package/dist/client-DP6Rc0t_.js +176 -0
- package/dist/config-BO1Y87kV.js +105 -0
- package/dist/{notification-url-DuKF2659.js → create-BBrtgUgS.js} +235 -539
- package/dist/{create-pkANt1Gs.js → create-Cwc3SRWJ.js} +194 -168
- package/dist/create-Yvf2gStM.js +19 -0
- package/dist/doctor-C9ldpPFC.js +83 -0
- package/dist/{drivers-Qx9LxmRN.js → drivers-DNrx4LWA.js} +185 -172
- package/dist/entry.d.ts +0 -5
- package/dist/entry.js +28073 -1134
- package/dist/environment-DF1qKlny.js +58 -0
- package/dist/{existing-AVEfZu2A.js → existing-78LWSsqS.js} +12 -6
- package/dist/held-Cy8Wl4D1.js +1112 -0
- package/dist/held-Ddw1XSsr.js +16 -0
- package/dist/input-vi0bou04.js +42 -0
- package/dist/{integrate-brmhPG-S.js → integrate-DcJhpXy8.js} +277 -254
- package/dist/kinds-GFXB3sYu.js +11 -0
- package/dist/log-NVhVe_oe.js +62 -0
- package/dist/login-B2TsCE2H.js +53 -0
- package/dist/login-BoBe8Psl.js +16 -0
- package/dist/{login-Do4wFuLv.js → login-D0lh3_JI.js} +118 -55
- package/dist/lookup-D-nmmAbw.js +71 -0
- package/dist/migrate-Cfec564E.js +274 -0
- package/dist/notification-url-YDbq6FMA.js +100 -0
- package/dist/{open-studio-DOw-6ydc.js → open-Ba2vBl1_.js} +34 -43
- package/dist/org-D0g_q3mv.js +35 -0
- package/dist/output-Ggzq5_-t.js +122 -0
- package/dist/paths-DxSLdpOI.js +29 -0
- package/dist/playbook-DIeb7hne.js +53 -0
- package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
- package/dist/promote-COD4fYdz.js +91 -0
- package/dist/push-CncywhkQ.js +482 -0
- package/dist/push-CtD4FZQV.js +22 -0
- package/dist/registry-DSrosOYs.js +10228 -0
- package/dist/{reports-CfJqoava.js → reports-DdPq4blM.js} +7 -6
- package/dist/{resources-Bf9O1JNM.js → resources-Dqr01Dep.js} +150 -55
- package/dist/{run-DsVZ5snL.js → run-C9qg_QlC.js} +16 -22
- package/dist/scan-Cv5uOwVY.js +4 -0
- package/dist/{scan-zKsddO72.js → scan-DLrsrFS9.js} +48 -37
- package/dist/scope-V336uz8j.js +198 -0
- package/dist/screenshot-file-0UETadF8.js +16 -0
- package/dist/{selection-CxZoX4NT.js → selection-Rdw-ZUoG.js} +94 -51
- package/dist/send-BxD9yf6F.js +150 -0
- package/dist/{dev-DmB3XqaJ.js → server-D0tGG8C4.js} +82 -92
- package/dist/server-z1LH94R_.js +22 -0
- package/dist/session-1AV_Bs_d.js +6 -0
- package/dist/session-CFAmMhem.js +40 -0
- package/dist/session-D_nEWKXT.js +768 -0
- package/dist/skills/animate-onboarding/SKILL.md +467 -0
- package/dist/skills/animate-onboarding/references/engine.md +494 -0
- package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
- package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
- package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
- package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
- package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
- package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
- package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
- package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
- package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
- package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
- package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
- package/dist/skills/animate-onboarding/references/performance.md +41 -0
- package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
- package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
- package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
- package/dist/skills/index.json +37 -0
- package/dist/skills/mobile-design/SKILL.md +447 -0
- package/dist/skills/mobile-design/references/responsive.md +162 -0
- package/dist/skills/onboarding-questions/SKILL.md +231 -0
- package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
- package/dist/skills/onboarding-questions/references/craft.md +142 -0
- package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
- package/dist/skills/superwall/SKILL.md +82 -9
- package/dist/skills/superwall/references/api.md +153 -37
- package/dist/skills/superwall/references/apple-setup.md +316 -0
- package/dist/skills/superwall/references/asc.md +74 -38
- package/dist/skills/superwall/references/data-analytics.md +55 -21
- package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
- package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
- package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
- package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
- package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
- package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
- package/dist/skills/superwall/workflows/placements/android.md +2 -2
- package/dist/skills/superwall/workflows/placements/expo.md +2 -2
- package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
- package/dist/skills/superwall/workflows/placements/ios.md +2 -2
- package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
- package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
- package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
- package/dist/skills/superwall/workflows/review/playbook.md +1 -1
- package/dist/skills/superwall-editor/SKILL.md +61 -0
- package/dist/skills/superwall-editor/references/cli.md +135 -0
- package/dist/skills/superwall-editor/references/design.md +51 -0
- package/dist/skills/superwall-editor/references/native-elements.md +171 -0
- package/dist/skills/superwall-editor/references/workflow.md +65 -0
- package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
- package/dist/skills/superwall-framework/SKILL.md +78 -28
- package/dist/skills/superwall-framework/references/cli.md +58 -28
- package/dist/skills/superwall-framework/references/examples.md +4 -3
- package/dist/skills/superwall-framework/references/layout.md +30 -8
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
- package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
- package/dist/skills/wwdc/SKILL.md +22 -0
- package/dist/skills/wwdc/references/docs.md +52 -0
- package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
- package/dist/{skills-DPzlnfCK.js → skills-BvFOa4y6.js} +99 -122
- package/dist/skills-DMG4bpKk.js +14 -0
- package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
- package/dist/spinner-CneRK5rk.js +294 -0
- package/dist/storage-DYvmIOHa.d.ts +16 -0
- package/dist/storage-s2Dnz-yl.js +31 -0
- package/dist/storekit-DafAnGkM.js +16 -0
- package/dist/storekit-yY_kS2iR.js +47 -0
- package/dist/telemetry-DtG92m5O.js +56 -0
- package/dist/theme-DUsCh-Vd.js +25 -0
- package/dist/timing-BVxPrYq3.js +5 -0
- package/dist/{token-C0it-Xh7.js → token-DzRh7dI1.js} +6 -38
- package/dist/tools.d.ts +96 -0
- package/dist/tools.js +11178 -0
- package/dist/ui-D_qf3Gvw.js +53 -0
- package/dist/upgrade-Bt4Ouw1y.js +117 -0
- package/dist/upgrade-Cqy5orjb.js +7 -0
- package/package.json +10 -5
- package/dist/api-CZzirVMj.js +0 -151
- package/dist/api-output-aJNw7Syy.js +0 -20
- package/dist/app-DH6U8yuI.js +0 -190
- package/dist/asa-C-sQzPPn.js +0 -1194
- package/dist/asc-1ZBJ6DwS.js +0 -778
- package/dist/auth-YRhlV3DE.js +0 -140
- package/dist/billing-CCYHdApx.js +0 -80
- package/dist/bundle-id-CKxl_026.js +0 -121
- package/dist/command-CMIz81Da.js +0 -301
- package/dist/dev-DZy6pOnB.js +0 -22
- package/dist/doctor-H-hf-Yww.js +0 -88
- package/dist/feedback-CKf-rpBW.js +0 -152
- package/dist/hosted-CXe9TrWx.js +0 -32
- package/dist/migrate-C9ERDR6y.js +0 -284
- package/dist/org-sj7uyvp-.js +0 -40
- package/dist/output-C4o2gJ1K.js +0 -146
- package/dist/params-l3CrvRtR.js +0 -51
- package/dist/pipeline-BqzqZhX1.js +0 -977
- package/dist/print-skill-ZojRSybs.js +0 -74
- package/dist/promote-BG8X4Nv_.js +0 -88
- package/dist/publish-sxLh-G4G.js +0 -35
- package/dist/push-bQ6Vxtg8.js +0 -35
- package/dist/query-_FbybaH-.js +0 -53
- package/dist/resource-CGIwSd29.js +0 -323
- package/dist/revenue-provider-ebsRINY8.js +0 -100
- package/dist/scope-BvzD-kO4.js +0 -223
- package/dist/skills-D_R-lEsK.js +0 -64
- package/dist/spinner-TWa0hia6.js +0 -18
- package/dist/storekit-Cj9Cpjcz.js +0 -29
- package/dist/telemetry-DeA1mvnT.js +0 -169
- package/dist/ui-Dy0b-9L8.js +0 -27738
- package/dist/update-B2fWIc4q.js +0 -59
- package/dist/upgrade-BmzkTKrh.js +0 -72
- /package/dist/{devtools-8EgLo86w.js → devtools-ByZ6XYnn.js} +0 -0
|
@@ -0,0 +1,467 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: animate-onboarding
|
|
3
|
+
description: Animate a tap-through onboarding or web funnel (quiz, survey, web2app flow) so the motion tells the flow's story — each page-to-page hand-off gets its own choreography tied to what the two pages say, the chosen answer physically becomes the progress it earns or the next page's hero, and everything stays fluid, physical and smooth on real phones. Built for flows shipped as Superwall surfaces (the superwall framework: pages, router transitions, layout chrome), with the engine mapped onto the router; the same direction applies to any tap-through web flow. Motion only; no new screens. Use when the user asks to "animate the onboarding", "make the funnel feel premium", "add transitions between onboarding pages", or when a flow's page transitions feel flat, generic, choppy, or cheap.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Animate Onboarding
|
|
8
|
+
|
|
9
|
+
Make an onboarding flow move like it means something. The pages, answer
|
|
10
|
+
capsules, progress bar and buttons already exist; this skill changes only how
|
|
11
|
+
they move — so the reader feels the story the questions tell, and the tap on an
|
|
12
|
+
answer is visibly what moves them forward.
|
|
13
|
+
|
|
14
|
+
## Where the flow lives: a Superwall surface
|
|
15
|
+
|
|
16
|
+
An onboarding is a screen the team will want to change after shipping —
|
|
17
|
+
reorder a question, cut a step, try a new statement — without an app release.
|
|
18
|
+
That is what the **superwall framework** is for: the flow is one surface in
|
|
19
|
+
`superwall/` (`config.ts` plus one page per screen in `app/`, shared chrome in
|
|
20
|
+
`layout.tsx`), previewed on every device in `superwall dev`, pushed as an
|
|
21
|
+
immutable version and switched live from the dashboard. Everything in this
|
|
22
|
+
skill assumes that shape, and the engine below is mapped onto its router:
|
|
23
|
+
|
|
24
|
+
- **A page is a route and the router owns every page change**
|
|
25
|
+
(`router.push`, `router.back`, `useRouter()` from `superwall/navigation`).
|
|
26
|
+
Never build a page swapper, a custom router or a cloned outgoing page:
|
|
27
|
+
the leaving page stays mounted while it animates away, so there is
|
|
28
|
+
nothing to clone. The only script in a hand-off is the shared-element
|
|
29
|
+
flight that rides on top of the router's transition (a thin wrapper
|
|
30
|
+
around `useRouter`, `references/framework/useStoryRouter.ts`, that
|
|
31
|
+
measures, calls `router.push`, and measures again).
|
|
32
|
+
- **A hand-off is a custom transition name** on the page being entered
|
|
33
|
+
(`export const transition = "story-picture"`), styled through the router's
|
|
34
|
+
four phases (`enter`, `recede`, `leave`, `return`) on `[data-sw-route]`.
|
|
35
|
+
- **The progress bar, back button and primary button live in `layout.tsx`**,
|
|
36
|
+
so the chosen answer has something persistent to fly into.
|
|
37
|
+
- **The first page's entrance gates on presentation** (`useSuperwallSnapshot
|
|
38
|
+
().paywall !== undefined`), never mount: the SDK preloads surfaces hidden.
|
|
39
|
+
|
|
40
|
+
Read the `superwall-framework` skill before touching the flow (install it if
|
|
41
|
+
it isn't there: `npx skills add https://github.com/superwall/skills/tree/next
|
|
42
|
+
--skill superwall-framework --global --yes --agent claude-code universal
|
|
43
|
+
--full-depth`); its `references/mobile-design.md` carries the touch, motion
|
|
44
|
+
and type rules this skill builds on. A flow that is not a surface yet (a
|
|
45
|
+
native onboarding, a hand-rolled web funnel) is worth proposing as one first
|
|
46
|
+
(`superwall create`, or `superwall migrate --screen <path>` for a native
|
|
47
|
+
screen); the user decides. Only if they keep their own web runtime does
|
|
48
|
+
`references/web-runtime/` apply, and never on a surface.
|
|
49
|
+
|
|
50
|
+
The direction comes from Emil Kowalski's design engineering and Apple's
|
|
51
|
+
fluid interfaces (both folded into `mobile-design.md`), the idea that every
|
|
52
|
+
hand-off is tied to the copy of the two pages it joins, and a long round of
|
|
53
|
+
direct feedback on a shipped funnel (Reflective's discovery flow). **The
|
|
54
|
+
direction below is that feedback. It outranks general taste.**
|
|
55
|
+
|
|
56
|
+
## The one rule: Frame A → Frame B share one geometry, at every moment
|
|
57
|
+
|
|
58
|
+
> **When element A transforms into element B, A and B must have exactly the
|
|
59
|
+
> same geometry — size, position, corner radius, blur — on every frame of the
|
|
60
|
+
> transition. Not "close". Not "driven by the same numbers". The same.**
|
|
61
|
+
|
|
62
|
+
Two separate animated copies (A's and B's), each with its own clip, transform
|
|
63
|
+
and blur, *will* drift apart: A's own rounded ends, a border, a margin, a
|
|
64
|
+
different blur, a rounding difference. The eye catches a 1px mismatch
|
|
65
|
+
instantly, and the whole morph reads as broken.
|
|
66
|
+
|
|
67
|
+
So build every A → B as **one frame with two faces** (`references/morphFrame.ts`):
|
|
68
|
+
a single element owns all of the geometry (the clip is the only outline, one
|
|
69
|
+
transform, one blur), and A and B are *faces* that fill it and only crossfade.
|
|
70
|
+
They cannot differ in geometry, because there is only one.
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
const answer = fillFace(answerEl, answerRect); // capture A before the page swaps
|
|
74
|
+
// …swap the page…
|
|
75
|
+
morph({
|
|
76
|
+
from: { rect: answerRect, radius: answerRect.height / 2 },
|
|
77
|
+
to: { rect: photoRect, radius: 20 },
|
|
78
|
+
faces: { from: answer, to: photoFace(photoEl) },
|
|
79
|
+
duration: 504,
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Faces: `photoFace(img)`, `fillFace(el, rect)` (answers, buttons: its colour
|
|
84
|
+
fills the frame, its content sits where it rests), `colorFace(color)`
|
|
85
|
+
(backgrounds). Recipes for every case are in `references/handoffs.md`. Never
|
|
86
|
+
hand-roll an A → B morph as two layers.
|
|
87
|
+
|
|
88
|
+
Check it: the frame must start exactly on A's rect and radius and end exactly
|
|
89
|
+
on B's, so the handover to the live elements is pixel-exact.
|
|
90
|
+
|
|
91
|
+
References — read when you reach that part:
|
|
92
|
+
|
|
93
|
+
- `references/framework/` — **the engine on the superwall framework, as
|
|
94
|
+
shipped** in the `animated-onboarding` example (`superwall create --example
|
|
95
|
+
animated-onboarding` gives the whole project): `handoffs.ts` (every
|
|
96
|
+
hand-off, both directions, cleanup), `useStoryRouter.ts` (`router.push` /
|
|
97
|
+
`back` inside the hand-off), `motion.css` (exits and entrances on the
|
|
98
|
+
router's phases), `layout.tsx` (chrome and the motion layer),
|
|
99
|
+
`Question.tsx`, `flow.ts`. Start from these on a surface.
|
|
100
|
+
- `references/engine.md` — the hand-off engine on the framework's router:
|
|
101
|
+
the hold on the layer, `flushSync` around `router.push`, the motion
|
|
102
|
+
layer, chrome in the layout, the focus trap, the flag, roles declared up
|
|
103
|
+
front, loaded destinations, interruption, traps.
|
|
104
|
+
- `references/handoffs.md` — how the transforms are built (answer → progress
|
|
105
|
+
bar, answer ↔ photo, bar → answer), the clock, and the hand-off catalog.
|
|
106
|
+
- `references/performance.md` — what to animate, what never to, and how to
|
|
107
|
+
diagnose "it's choppy".
|
|
108
|
+
- `references/morphFrame.ts` — **the A → B morph**: one frame, two faces, the
|
|
109
|
+
glide clock, the shape. Use it for every element-into-element transform.
|
|
110
|
+
- `references/imageReady.ts` — image readiness incl. Safari.
|
|
111
|
+
- `references/web-runtime/` — the same engine for a flow the user keeps in
|
|
112
|
+
a hand-rolled web runtime (it clones the outgoing page because that
|
|
113
|
+
runtime has no router). Never the starting point on a surface.
|
|
114
|
+
|
|
115
|
+
## Direction (from the feedback)
|
|
116
|
+
|
|
117
|
+
### 1. Map every element before choreographing
|
|
118
|
+
|
|
119
|
+
Before writing any motion, build a **map of every element on every page, for
|
|
120
|
+
each hand-off in both directions**, and give each exactly one role. Elements
|
|
121
|
+
are the same when they're **optically equivalent** — they look like the same
|
|
122
|
+
thing in the same place — not when they're literally the same component.
|
|
123
|
+
Always read between the lines.
|
|
124
|
+
|
|
125
|
+
| From → to | Motion |
|
|
126
|
+
|---|---|
|
|
127
|
+
| **A → A**, same position, same size | **No animation.** No transition out or in for either. Animating it only draws attention to something that didn't change (e.g. a pinned "Continue" on consecutive pages). |
|
|
128
|
+
| **A → A**, different position, size or text | Transition gracefully out and in. |
|
|
129
|
+
| **A → B** (a different element) | **The transform *is* the transition.** No exit on A, no entrance on B; nothing else may compete with it. |
|
|
130
|
+
| **A → nothing** | Scale, fade and blur out. Cascade it so the elements feel like they move *because the others did* — subtle, like dominoes. Sneak in physics wherever possible: falling back with a skew or perspective. |
|
|
131
|
+
| **nothing → B** | Usually the reverse idea of the above. |
|
|
132
|
+
|
|
133
|
+
**Choosing A (the source)** — the element the user interacted with last has
|
|
134
|
+
top priority: the option they picked in a single select. A continue button has
|
|
135
|
+
the lowest. For multiple choice, animate **all** the chosen options into the
|
|
136
|
+
progress bar.
|
|
137
|
+
|
|
138
|
+
**Choosing B (the destination)** — in order:
|
|
139
|
+
|
|
140
|
+
1. **The most visually demanding element on the next screen that ties to the
|
|
141
|
+
story.** If option A in a selection is purple and the next screen has a
|
|
142
|
+
purple background, the background is a great destination.
|
|
143
|
+
2. **A hero image.** It's always nice to morph a chosen option, or the
|
|
144
|
+
continue button, into the next screen's hero.
|
|
145
|
+
3. When in doubt, **the progress bar**: it gamifies selection and increases
|
|
146
|
+
completion.
|
|
147
|
+
4. Or **the next continue button**: it makes them want to press it again.
|
|
148
|
+
|
|
149
|
+
**Back reverses roles.** If three answers collapsed into a photo going
|
|
150
|
+
forward, all three come *out of* it going back — not just the chosen one while
|
|
151
|
+
the others do a standard rise.
|
|
152
|
+
|
|
153
|
+
**Verify the map in code.** Every element gets the standard entrance by
|
|
154
|
+
default, so an element marked "transformed from" whose exemption is missing
|
|
155
|
+
runs its entrance *and* the transform — two animations fighting. For every
|
|
156
|
+
hand-off in both directions, confirm each destination's standard entrance is
|
|
157
|
+
off (declare it up front: `engine.md`, "Roles, declared up front").
|
|
158
|
+
|
|
159
|
+
### 2. How an A → B transform moves
|
|
160
|
+
|
|
161
|
+
It should feel fluid and physical, as one continuous thing.
|
|
162
|
+
|
|
163
|
+
- **One clock for every stacked phase.** A transform is several phases
|
|
164
|
+
stacked (lift, travel, open, land). Drive every channel — position, size,
|
|
165
|
+
corners, crossfade, blur — from **one** clock, so phase 1 eases in, each next
|
|
166
|
+
phase starts with the velocity and acceleration the last one left, and the
|
|
167
|
+
final phase eases out. Giving each phase its own eased span makes it stall
|
|
168
|
+
at every boundary. The move leads and the opening follows on the same curve
|
|
169
|
+
(e.g. size on `p^1.5`), never restarting from rest.
|
|
170
|
+
- **The clock is a critically damped spring** (damping 1.0, Apple's default
|
|
171
|
+
for UI), in every dimension it drives (position *and* size): a barely-there
|
|
172
|
+
pull-back (~1%), a quick rise to top speed early (~27% of the duration),
|
|
173
|
+
then a **long, continuously slowing tail** into the target — **no constant-
|
|
174
|
+
speed middle and no overshoot or bounce at the end**. At rest at both ends
|
|
175
|
+
(a final taper lands it exactly on the last frame). Check it numerically:
|
|
176
|
+
near top speed ≤ ~15% of the time, overshoot 0, soft braking in the last
|
|
177
|
+
quarter.
|
|
178
|
+
- **Keep the path gentle.** Arrive at a normal slope and grow size linearly
|
|
179
|
+
near the destination; a steep final curve or a multiplicative grow rushes
|
|
180
|
+
the end and magnifies any change in speed.
|
|
181
|
+
- **Size floor: never more than 20% smaller than the smaller end.** 80 → 100
|
|
182
|
+
may dip to 64 on the way, never to 20. No pinching an answer down to a
|
|
183
|
+
thumbnail. (Exception: an answer becoming a stretch of a 4px progress bar
|
|
184
|
+
has to shrink to be it.)
|
|
185
|
+
- **Bubbly:** a dimension that's about the same at both ends (e.g. both
|
|
186
|
+
348px wide) **dips up to 20%** mid-flight (sin-shaped) and swells back —
|
|
187
|
+
squeezing through like a bubble. None once the ends differ by half or more.
|
|
188
|
+
- **One geometry** (the rule above): the frame's clip is the only outline.
|
|
189
|
+
Never scale a rounded shape non-uniformly (it squashes round ends into
|
|
190
|
+
ovals); the frame clips (`inset(... round r)`) and only ever scales *up*.
|
|
191
|
+
- **Corners are proportional.** Interpolate the corner radius as a *fraction
|
|
192
|
+
of the shape's shorter side* (its roundness: 0.5 = fully round ends), not in
|
|
193
|
+
pixels, starting from the source's own roundness and ending at the
|
|
194
|
+
destination's. A fully round answer opening into a square full-screen
|
|
195
|
+
background stays visibly rounded while it's big and only goes square at the
|
|
196
|
+
very end; interpolated in pixels, a big frame has tiny, sharp-looking
|
|
197
|
+
corners almost at once.
|
|
198
|
+
- **Blur is motion blur.** It **starts and ends crisp**, and is blurred only
|
|
199
|
+
while the frame is moving fastest: **from 25% to 75% of the duration**
|
|
200
|
+
(easing in over 25–35%, a full 5px on screen over 35–65%, easing out over
|
|
201
|
+
65–75%). One blur for both faces, on the frame's outer wrapper (no
|
|
202
|
+
transform), so it softens the silhouette in screen pixels. **The swap
|
|
203
|
+
(handover) happens inside that window**, so A becomes B under the blur.
|
|
204
|
+
A single colour going into the bar (or back out) has nothing to smear:
|
|
205
|
+
`blur: 0`. Keep one switch for all motion blur (`MOTION_BLUR_ENABLED` in
|
|
206
|
+
`morphFrame.ts`) so it can be turned off in one place to isolate a problem.
|
|
207
|
+
- **Back is never a rewind.** Going back is its own move on the same clock,
|
|
208
|
+
landing on the same long gentle tail, with no direction flip mid-motion. E.g. back from
|
|
209
|
+
the progress bar: the pill takes its stretch of bar with it (the bar gives
|
|
210
|
+
it up at once, under the pill), slides out, and drops and grows into the
|
|
211
|
+
answer.
|
|
212
|
+
- **One duration for every A → B transform** — 504ms in the reference. They
|
|
213
|
+
drifted to 720–820ms and felt slow; keep them equal and brisk.
|
|
214
|
+
|
|
215
|
+
### 3. Handovers: no doubles, no flashes, no missing targets
|
|
216
|
+
|
|
217
|
+
- **A destination never fades in while something transforms into it.** Keep
|
|
218
|
+
the live element hidden; the transforming copy carries it the whole way.
|
|
219
|
+
- **Hand over on the last frame, already painted.** Keep the live element at
|
|
220
|
+
`opacity: 0.001` for the whole transform (painted, but invisible), let it
|
|
221
|
+
return to 1 as the transform ends, and remove the copy in that same frame.
|
|
222
|
+
A browser doesn't paint a fully transparent element, so one kept at 0 and
|
|
223
|
+
revealed only on the last frame shows a frame of nothing: a flash.
|
|
224
|
+
- **The destination must be loaded.** An unloaded `<img>` has no height, so
|
|
225
|
+
the morph measures a zero target and animates a blank. Decode every image
|
|
226
|
+
up front and keep it; before a hand-off into a page with an image, wait for
|
|
227
|
+
it (up to ~400ms, a newer tap cancels the wait); if it still isn't there,
|
|
228
|
+
skip the morph and fade the image in on load.
|
|
229
|
+
- **Safari (every iPhone) loads even a cached image asynchronously** when a
|
|
230
|
+
new `<img>` is created: right after the page swaps, the new image reports
|
|
231
|
+
"not loaded" with zero height. So:
|
|
232
|
+
- never require the *new* `<img>` to be loaded to run the morph — require
|
|
233
|
+
the flow's own decoded copy to be ready (a morph gated on the live element
|
|
234
|
+
simply never runs on an iPhone);
|
|
235
|
+
- render images with `width`/`height` from their known natural size, so the
|
|
236
|
+
box is right before it paints;
|
|
237
|
+
- build copies from the already-decoded `Image` object, not `cloneNode()`
|
|
238
|
+
of an `<img>` (a clone reloads and paints blank);
|
|
239
|
+
- keep the copy on top until the live image has actually loaded;
|
|
240
|
+
- mark an image ready on its `load` event; older Safari rejects `decode()`
|
|
241
|
+
for images outside the document.
|
|
242
|
+
Test on a real iPhone: none of this reproduces in desktop Chrome.
|
|
243
|
+
|
|
244
|
+
- **Remove each copy when its own transform ends.** The copies' removal waits
|
|
245
|
+
only on the copies' animations and the destinations' 0.001 holds (which end
|
|
246
|
+
on the same frame), plus a live photo's load. Never on the new page's
|
|
247
|
+
entrances: a copy that waits for them sits over them for their whole
|
|
248
|
+
duration. Under a full-screen colour that hid the statement's words for
|
|
249
|
+
~1s, then they just appeared. Keep two lists (`engine.md`): everything, for
|
|
250
|
+
a fast second tap to finish, and the handovers, for cleanup.
|
|
251
|
+
- **Nothing enters under a covering copy.** A morph frame is above the live
|
|
252
|
+
page until it hands over. Anything whose entrance starts before then (words
|
|
253
|
+
on a full-screen colour, a header switching onto it) fades in unseen and pops
|
|
254
|
+
in mid-fade when the frame goes. Start those after `TRANSFORM_MS`.
|
|
255
|
+
|
|
256
|
+
### 3b. Full-screen colour moments (statement screens)
|
|
257
|
+
|
|
258
|
+
A "Did you know…" statement on a full-screen field of the answer colour is a
|
|
259
|
+
strong beat between questions. Its background is by far the most visually
|
|
260
|
+
demanding element on the screen, and it's the answer's own colour, so by the
|
|
261
|
+
destination rules:
|
|
262
|
+
|
|
263
|
+
- **Question → statement: the chosen answer opens into the background.** One
|
|
264
|
+
frame, answer face → colour face, the corners going from the pill's full
|
|
265
|
+
roundness to square only at the end. The answer doesn't fly into the
|
|
266
|
+
progress bar here: the background is the better destination (the bar steps
|
|
267
|
+
normally).
|
|
268
|
+
- **The colour is its own full-screen layer**, rendered by the runtime behind
|
|
269
|
+
the page (not the page's or body's background), so it can be a morph
|
|
270
|
+
destination and source as one element, and stays out of sight (0.001) until
|
|
271
|
+
the morph hands over.
|
|
272
|
+
- **The words arrive after the colour** (entrance delayed ~540ms: just after
|
|
273
|
+
the 504ms frame hands over, never under it), and the header and button
|
|
274
|
+
invert onto it, switching only once the colour has arrived.
|
|
275
|
+
- **Statement → next question: the colour goes into the progress bar exactly
|
|
276
|
+
like an answer pill** (see 4): its right edge flies to where the bar ends as
|
|
277
|
+
it shrinks to a bar-height pill, joins, grows together with the bar to the
|
|
278
|
+
new length, and bounces. The statement becomes progress. Its words leave
|
|
279
|
+
first, one after another, above the colour.
|
|
280
|
+
- **Back** is the pill's return: the stretch of bar slides out along it, then
|
|
281
|
+
drops and grows into the full-screen colour; and the colour closes back into
|
|
282
|
+
the answer that opened it.
|
|
283
|
+
|
|
284
|
+
### 3c. The browser's own chrome (iOS 26 toolbar tint) — web funnels only
|
|
285
|
+
|
|
286
|
+
A surface in the SDK's webview has no browser chrome; skip this section
|
|
287
|
+
there, and never add a `position: fixed` element to a native surface (the
|
|
288
|
+
framework's insets rule). On a web funnel in Safari it matters: iOS 26
|
|
289
|
+
Safari ignores `<meta name="theme-color">`. It tints its toolbars from
|
|
290
|
+
a `position: fixed` element touching the top edge (within ~4px, 80%+ of the
|
|
291
|
+
width, 3px+ tall, with its own background colour), otherwise from the page
|
|
292
|
+
background. A full-screen colour sweeping in makes it retint mid-transition,
|
|
293
|
+
which looks janky. So:
|
|
294
|
+
|
|
295
|
+
- **Pin the tint with a sentinel**: one permanent fixed element at the very
|
|
296
|
+
top, 4px tall, full width, in the page colour, topmost. Safari always tints
|
|
297
|
+
from it. Keep `theme-color` for Chrome and older Safari.
|
|
298
|
+
- **Never animate with `position: fixed`.** Every copy, frame and flying pill
|
|
299
|
+
is `position: absolute` at the same screen coordinates (the page itself
|
|
300
|
+
doesn't scroll). A full-screen fixed morph frame is exactly what Safari tints
|
|
301
|
+
from: it flashed the statement colour into the toolbar. The sentinel must be
|
|
302
|
+
the only fixed element.
|
|
303
|
+
- To verify on a phone, turn the sentinel red for a test: the toolbar should
|
|
304
|
+
go red and hold through every transition.
|
|
305
|
+
|
|
306
|
+
### 4. The signature move: the answer becomes the progress
|
|
307
|
+
|
|
308
|
+
- **Every chosen answer flies into the progress bar** — on every question
|
|
309
|
+
page, unless it's morphing into something better (the next page's hero).
|
|
310
|
+
- **The selection is what grows the bar, not a timer.** The bar holds still
|
|
311
|
+
until the answer arrives, then they move as one, driven by **one sampled
|
|
312
|
+
timeline**. A CSS transition with a guessed delay is not good enough.
|
|
313
|
+
- **Right edge to right edge.** The answer shrinks around its *right* edge,
|
|
314
|
+
and that edge flies to where the bar *currently ends*; they join, then
|
|
315
|
+
**grow together** to the new length. Not "dropping into the gap like a
|
|
316
|
+
brick".
|
|
317
|
+
- **Path: rise and drift together, rise leading**; it reaches the bar's height
|
|
318
|
+
~87% of the way across and slides the last short stretch level.
|
|
319
|
+
- **A bounce after growing** (~13%, ease-out-back).
|
|
320
|
+
- **Nothing about the bar changes except its length** — no colour or opacity
|
|
321
|
+
animation (the pill reaches the bar's colour *before* it joins and is
|
|
322
|
+
removed without a fade), and **no height change** (a swell reads as a flash,
|
|
323
|
+
since the pill on top doesn't swell with it).
|
|
324
|
+
- The fill slides with `translateX` inside the clipping track, never `scaleX`,
|
|
325
|
+
so its round end stays round.
|
|
326
|
+
- **Anything that goes into the bar goes the same way** — a full-screen
|
|
327
|
+
statement colour included: right edge to the bar's end, shrinking to a
|
|
328
|
+
bar-height pill, join, grow together, bounce. Build it through the
|
|
329
|
+
one-geometry frame with a custom path (`morph({ path })`), never by
|
|
330
|
+
stretching the shape (a full-screen rectangle scaled to 4px squashes its
|
|
331
|
+
corners). The progress bar is the one exception to the size floor.
|
|
332
|
+
- **Back:** see "Back is never a rewind" above.
|
|
333
|
+
|
|
334
|
+
### 5. What landed well
|
|
335
|
+
|
|
336
|
+
- "Gone within a day": the old page fades to nothing, a beat of emptiness
|
|
337
|
+
(~120ms), then the photo settles in from `scale(1.03)`; its exit lifts the
|
|
338
|
+
photo first, then the words.
|
|
339
|
+
- The welcome page's exit — **the example of physics in an A → nothing**: it
|
|
340
|
+
leans back in perspective as it floats up
|
|
341
|
+
(`perspective(900px) translateY(-20px) rotateX(22deg) scale(.97)` about its
|
|
342
|
+
bottom edge, fading), like a card tipping away.
|
|
343
|
+
- Hand-offs chosen per pair from the copy (forgetting pages drift away,
|
|
344
|
+
"re-explaining" arrives from above, agitation gets faster cuts, the last
|
|
345
|
+
answer completes the bar and hands over to "You're all set").
|
|
346
|
+
|
|
347
|
+
### 6. What was tried and rejected — don't reach for these
|
|
348
|
+
|
|
349
|
+
| Tried | Why it failed |
|
|
350
|
+
|---|---|
|
|
351
|
+
| View Transitions API snapshots for exits and morphs | Snapshot artefacts (smeared edges, stretched morphs), a full-page snapshot re-composited every frame |
|
|
352
|
+
| `filter: blur()` on every entering line, answer and image | ~15fps on software raster; blurred text halos |
|
|
353
|
+
| `backdrop-filter` on answer capsules while they move | Re-computed every frame they move |
|
|
354
|
+
| Genie / mesh "sucked into the bar" (sliced strips) | Didn't read as premium; too clever |
|
|
355
|
+
| Rotating the pill to face its velocity | Didn't feel right; a straight path with the right timing did |
|
|
356
|
+
| A decorative background pattern reacting to transitions | Decoration competing with the story |
|
|
357
|
+
| Answer filling the bar's gap like a brick (left edge to bar end) | Reads as placement, not propulsion |
|
|
358
|
+
| A height swell on the bar when the answer joins | Flash: the pill on top doesn't swell with it |
|
|
359
|
+
| Fading the flying pill out over the bar | Visible as a colour change in the bar |
|
|
360
|
+
| A photo fading in from a large source rect | Ghosting |
|
|
361
|
+
| Squeezing the answer to a thumbnail to swap with the photo | Too small; squashed corners; not fluid |
|
|
362
|
+
| Stock `easeInOutBack` | 10% pull-back and overshoot, rushed middle: abrupt |
|
|
363
|
+
| A stiff simulated spring | ~6% overshoot that swells and snaps back in ~75ms |
|
|
364
|
+
| A smooth-step ease to a 1.5% overshoot at 82%, settling back in ~90ms | Too linear in the middle, too bouncy/snappy at the end |
|
|
365
|
+
| A separately eased span per phase | Stalls at every phase boundary |
|
|
366
|
+
| The destination fading in as the transform arrives | The element appears twice |
|
|
367
|
+
| Playing the forward move in reverse for back | Direction flips mid-motion; no physical landing |
|
|
368
|
+
| Revealing the destination on the last frame | A one-frame flash before it's painted |
|
|
369
|
+
| A and B as two separate animated layers, each with its own clip, transform and blur, "driven by the same numbers" | Geometry drift: A's own rounded ends, different blur, rounding; visibly different sizes mid-morph |
|
|
370
|
+
| Gating the morph on the new `<img>` being loaded | Never ran on iOS Safari (it loads cached images asynchronously) |
|
|
371
|
+
| Corner radius interpolated in pixels | A big frame gets tiny, sharp-looking corners almost at once |
|
|
372
|
+
| A statement colour shrinking into the bar as a plain morph to the new segment | Should move like a pill: right edge to the bar's end, join, grow together |
|
|
373
|
+
| `position: fixed` animated copies and morph frames | iOS 26 Safari tints its toolbar from a fixed element at the top: the statement colour flashed into the browser chrome |
|
|
374
|
+
| Blur tied to the swap, rising into it and fading out to the last frame | Blurred only for the first half. Blur is motion blur: crisp at both ends, blurred from 25% to 75% |
|
|
375
|
+
| Removing the copies once *every* animation had finished, the new page's entrances included | The full-screen colour frame sat over the statement's words for their whole entrance: a long red pause, then the words just appeared |
|
|
376
|
+
| Words entering on a statement at ~420ms, under a 504ms frame | Their first ~84ms happened unseen, so they popped in mid-fade when the frame went |
|
|
377
|
+
|
|
378
|
+
When the user rejects an approach, **revert it completely** to the last
|
|
379
|
+
approved state (confirm with the build output), then try the next idea. Don't
|
|
380
|
+
stack a fix on top of a rejected idea.
|
|
381
|
+
|
|
382
|
+
## Principles
|
|
383
|
+
|
|
384
|
+
**Restraint first.** Onboarding is a
|
|
385
|
+
first-time, rare surface — it has the delight budget — but every motion still
|
|
386
|
+
needs a named purpose: explanation, spatial consistency, state indication,
|
|
387
|
+
feedback. Keyboard navigation (Enter/Esc) and browser back/forward get a
|
|
388
|
+
**plain** 200ms fade: repeated or system-animated, they must not be
|
|
389
|
+
choreographed.
|
|
390
|
+
|
|
391
|
+
**The router owns navigation.** Every hand-off is a custom transition the
|
|
392
|
+
router runs (`export const transition = "story-…"`, CSS on
|
|
393
|
+
`data-sw-transition` and `data-sw-phase`); the script only adds the
|
|
394
|
+
shared-element flights, inside a wrapper around `useRouter`. A custom
|
|
395
|
+
router, a page swapper, a cloned page or a `position: fixed` copy is a
|
|
396
|
+
rejected approach on a surface, whatever it would make easier.
|
|
397
|
+
|
|
398
|
+
**Each hand-off is tied to the pair.** Read the copy of page A
|
|
399
|
+
and page B, and pick motion that says what B says. Name the idea for each pair
|
|
400
|
+
in a code comment. In a long quiz, a family of related question → question
|
|
401
|
+
hand-offs is fine; make the act boundaries the distinct moments. Change pacing
|
|
402
|
+
by act: calm, soft, faster under tension, settled at the resolution.
|
|
403
|
+
|
|
404
|
+
**Fluid, not scripted.** Respond on pointer-down. Every
|
|
405
|
+
navigation first settles the previous hand-off instantly, so a fast second tap
|
|
406
|
+
never waits. Motion hints at its destination (it starts moving before it
|
|
407
|
+
opens).
|
|
408
|
+
|
|
409
|
+
**Craft (`mobile-design.md`, Motion).**
|
|
410
|
+
- Curves: `--ease-out: cubic-bezier(0.23, 1, 0.32, 1)`,
|
|
411
|
+
`--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1)`. Never `ease-in` on UI.
|
|
412
|
+
- Exits quicker than entries: exits 120–380ms, entries 240–720ms; A → B
|
|
413
|
+
transforms one shared, brisk duration.
|
|
414
|
+
- Entrances: title, then subtitle, then answers 40ms apart (30–80ms); answers
|
|
415
|
+
are tappable from the first frame.
|
|
416
|
+
- Never from `scale(0)`; from 0.9+ with opacity.
|
|
417
|
+
- Only `transform` and `opacity` move, with two sanctioned exceptions on a
|
|
418
|
+
single element at a time: the morph's `clip-path` and its 5px blur.
|
|
419
|
+
- Reduced motion: opacity only, nothing moves.
|
|
420
|
+
- Self-check against the never-ship list in `mobile-design.md` (`transition:
|
|
421
|
+
all`, `scale(0)`, `ease-in`, width/height animation, ungated hover, no
|
|
422
|
+
reduced motion, everything entering at once).
|
|
423
|
+
|
|
424
|
+
## Workflow
|
|
425
|
+
|
|
426
|
+
1. **Recon.** Find the surface (`config.ts`, one route per page in `app/`,
|
|
427
|
+
`layout.tsx` with the progress bar and back button), the answer
|
|
428
|
+
component, the page-title component, every image, and existing
|
|
429
|
+
easing/duration tokens. Read every page's copy and name the story arc
|
|
430
|
+
(acts). If a page change happens anywhere but `router.push` /
|
|
431
|
+
`router.back`, fix that first.
|
|
432
|
+
2. **Plan as a table, then stop.** One row per hand-off: from → to, what
|
|
433
|
+
moves, why it fits that pair — choosing A and B by the priorities above.
|
|
434
|
+
Under it, the **element map** for each hand-off in both directions (every
|
|
435
|
+
element's role). Plus the whole-flow rules. Ask at most one decision
|
|
436
|
+
question with a recommendation. Build only after approval.
|
|
437
|
+
3. **Build the engine** (`engine.md`, starting from `references/framework/`):
|
|
438
|
+
an opt-in flag, a `story-…` transition name per page, the hold on the
|
|
439
|
+
route layer, `router.push` / `router.back` wrapped so the swap happens
|
|
440
|
+
inside the hand-off (and waits for the destination's image), the motion
|
|
441
|
+
layer in the layout, destinations declared up front.
|
|
442
|
+
4. **Build the transforms and hand-offs** (`handoffs.md`): the answer → bar
|
|
443
|
+
flight first, then the A → B morphs, then each pair's exit, then entrances
|
|
444
|
+
as CSS variable overrides.
|
|
445
|
+
5. **Map check, geometry check, timeline check and performance pass** before
|
|
446
|
+
showing anyone: every "transformed from" element has its entrance off;
|
|
447
|
+
every A → B goes through `morph()` (one frame) and starts and ends exactly
|
|
448
|
+
on the real rects; no destination is visible before the last frame or faded
|
|
449
|
+
in over its copy; nothing animated is `position: fixed`. **Timeline:** for
|
|
450
|
+
each hand-off, list every copy's lifetime on screen next to every entrance
|
|
451
|
+
beneath it. No entrance may run under a copy that covers it (a full-screen
|
|
452
|
+
colour frame covers the whole page), and each copy is removed when its own
|
|
453
|
+
transform ends, not when the entrances do. Then `performance.md`. Then test
|
|
454
|
+
on a real iPhone.
|
|
455
|
+
6. **Run it for the user.** `superwall dev`, then the studio's **Preview**
|
|
456
|
+
button for a QR code that opens the flow on their phone; a production
|
|
457
|
+
build (`superwall push`, then the studio's pushed version) is what to judge
|
|
458
|
+
smoothness on. Don't claim it feels right without the user's eyes on it.
|
|
459
|
+
7. **Iterate on feel, one change per round, with numbers.** Compute a table
|
|
460
|
+
from the actual keyframes (t, ms, size, corners, position, opacity, blur)
|
|
461
|
+
and verify the invariants (size floor, no overshoot, speed continuity, at rest
|
|
462
|
+
at both ends) before reporting. For your own checks, play it at 2–5× or step
|
|
463
|
+
it frame by frame.
|
|
464
|
+
8. **Ship behind the flag** so the old motion stays reachable (a `motion`
|
|
465
|
+
query key on a web funnel; a constant or a placement param natively) for
|
|
466
|
+
comparing funnel drop-off. `superwall push` only when asked; the user
|
|
467
|
+
promotes.
|