@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.
Files changed (165) hide show
  1. package/README.md +192 -52
  2. package/dist/{setup-Bxj22rYi.js → apple-CkKlHBZ9.js} +82 -76
  3. package/dist/auth.d.ts +4 -19
  4. package/dist/auth.js +4 -2
  5. package/dist/{actions-B7ym3oVS.js → billing-XCZU_T46.js} +98 -28
  6. package/dist/{bind-YrJvuRF9.js → bind-drne__Ys.js} +38 -33
  7. package/dist/{build-DLoCW5Ri.js → build-Gpdq5QXP.js} +20 -26
  8. package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
  9. package/dist/client-DP6Rc0t_.js +176 -0
  10. package/dist/config-BO1Y87kV.js +105 -0
  11. package/dist/{notification-url-DuKF2659.js → create-BBrtgUgS.js} +235 -539
  12. package/dist/{create-pkANt1Gs.js → create-Cwc3SRWJ.js} +194 -168
  13. package/dist/create-Yvf2gStM.js +19 -0
  14. package/dist/doctor-C9ldpPFC.js +83 -0
  15. package/dist/{drivers-Qx9LxmRN.js → drivers-DNrx4LWA.js} +185 -172
  16. package/dist/entry.d.ts +0 -5
  17. package/dist/entry.js +28073 -1134
  18. package/dist/environment-DF1qKlny.js +58 -0
  19. package/dist/{existing-AVEfZu2A.js → existing-78LWSsqS.js} +12 -6
  20. package/dist/held-Cy8Wl4D1.js +1112 -0
  21. package/dist/held-Ddw1XSsr.js +16 -0
  22. package/dist/input-vi0bou04.js +42 -0
  23. package/dist/{integrate-brmhPG-S.js → integrate-DcJhpXy8.js} +277 -254
  24. package/dist/kinds-GFXB3sYu.js +11 -0
  25. package/dist/log-NVhVe_oe.js +62 -0
  26. package/dist/login-B2TsCE2H.js +53 -0
  27. package/dist/login-BoBe8Psl.js +16 -0
  28. package/dist/{login-Do4wFuLv.js → login-D0lh3_JI.js} +118 -55
  29. package/dist/lookup-D-nmmAbw.js +71 -0
  30. package/dist/migrate-Cfec564E.js +274 -0
  31. package/dist/notification-url-YDbq6FMA.js +100 -0
  32. package/dist/{open-studio-DOw-6ydc.js → open-Ba2vBl1_.js} +34 -43
  33. package/dist/org-D0g_q3mv.js +35 -0
  34. package/dist/output-Ggzq5_-t.js +122 -0
  35. package/dist/paths-DxSLdpOI.js +29 -0
  36. package/dist/playbook-DIeb7hne.js +53 -0
  37. package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
  38. package/dist/promote-COD4fYdz.js +91 -0
  39. package/dist/push-CncywhkQ.js +482 -0
  40. package/dist/push-CtD4FZQV.js +22 -0
  41. package/dist/registry-DSrosOYs.js +10228 -0
  42. package/dist/{reports-CfJqoava.js → reports-DdPq4blM.js} +7 -6
  43. package/dist/{resources-Bf9O1JNM.js → resources-Dqr01Dep.js} +150 -55
  44. package/dist/{run-DsVZ5snL.js → run-C9qg_QlC.js} +16 -22
  45. package/dist/scan-Cv5uOwVY.js +4 -0
  46. package/dist/{scan-zKsddO72.js → scan-DLrsrFS9.js} +48 -37
  47. package/dist/scope-V336uz8j.js +198 -0
  48. package/dist/screenshot-file-0UETadF8.js +16 -0
  49. package/dist/{selection-CxZoX4NT.js → selection-Rdw-ZUoG.js} +94 -51
  50. package/dist/send-BxD9yf6F.js +150 -0
  51. package/dist/{dev-DmB3XqaJ.js → server-D0tGG8C4.js} +82 -92
  52. package/dist/server-z1LH94R_.js +22 -0
  53. package/dist/session-1AV_Bs_d.js +6 -0
  54. package/dist/session-CFAmMhem.js +40 -0
  55. package/dist/session-D_nEWKXT.js +768 -0
  56. package/dist/skills/animate-onboarding/SKILL.md +467 -0
  57. package/dist/skills/animate-onboarding/references/engine.md +494 -0
  58. package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
  59. package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
  60. package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
  61. package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
  62. package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  63. package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
  64. package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
  65. package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  66. package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
  67. package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
  68. package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
  69. package/dist/skills/animate-onboarding/references/performance.md +41 -0
  70. package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
  71. package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  72. package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  73. package/dist/skills/index.json +37 -0
  74. package/dist/skills/mobile-design/SKILL.md +447 -0
  75. package/dist/skills/mobile-design/references/responsive.md +162 -0
  76. package/dist/skills/onboarding-questions/SKILL.md +231 -0
  77. package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
  78. package/dist/skills/onboarding-questions/references/craft.md +142 -0
  79. package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
  80. package/dist/skills/superwall/SKILL.md +82 -9
  81. package/dist/skills/superwall/references/api.md +153 -37
  82. package/dist/skills/superwall/references/apple-setup.md +316 -0
  83. package/dist/skills/superwall/references/asc.md +74 -38
  84. package/dist/skills/superwall/references/data-analytics.md +55 -21
  85. package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
  86. package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
  87. package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
  88. package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
  89. package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
  90. package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
  91. package/dist/skills/superwall/workflows/placements/android.md +2 -2
  92. package/dist/skills/superwall/workflows/placements/expo.md +2 -2
  93. package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
  94. package/dist/skills/superwall/workflows/placements/ios.md +2 -2
  95. package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
  96. package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
  97. package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
  98. package/dist/skills/superwall/workflows/review/playbook.md +1 -1
  99. package/dist/skills/superwall-editor/SKILL.md +61 -0
  100. package/dist/skills/superwall-editor/references/cli.md +135 -0
  101. package/dist/skills/superwall-editor/references/design.md +51 -0
  102. package/dist/skills/superwall-editor/references/native-elements.md +171 -0
  103. package/dist/skills/superwall-editor/references/workflow.md +65 -0
  104. package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
  105. package/dist/skills/superwall-framework/SKILL.md +78 -28
  106. package/dist/skills/superwall-framework/references/cli.md +58 -28
  107. package/dist/skills/superwall-framework/references/examples.md +4 -3
  108. package/dist/skills/superwall-framework/references/layout.md +30 -8
  109. package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
  110. package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
  111. package/dist/skills/wwdc/SKILL.md +22 -0
  112. package/dist/skills/wwdc/references/docs.md +52 -0
  113. package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
  114. package/dist/{skills-DPzlnfCK.js → skills-BvFOa4y6.js} +99 -122
  115. package/dist/skills-DMG4bpKk.js +14 -0
  116. package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
  117. package/dist/spinner-CneRK5rk.js +294 -0
  118. package/dist/storage-DYvmIOHa.d.ts +16 -0
  119. package/dist/storage-s2Dnz-yl.js +31 -0
  120. package/dist/storekit-DafAnGkM.js +16 -0
  121. package/dist/storekit-yY_kS2iR.js +47 -0
  122. package/dist/telemetry-DtG92m5O.js +56 -0
  123. package/dist/theme-DUsCh-Vd.js +25 -0
  124. package/dist/timing-BVxPrYq3.js +5 -0
  125. package/dist/{token-C0it-Xh7.js → token-DzRh7dI1.js} +6 -38
  126. package/dist/tools.d.ts +96 -0
  127. package/dist/tools.js +11178 -0
  128. package/dist/ui-D_qf3Gvw.js +53 -0
  129. package/dist/upgrade-Bt4Ouw1y.js +117 -0
  130. package/dist/upgrade-Cqy5orjb.js +7 -0
  131. package/package.json +10 -5
  132. package/dist/api-CZzirVMj.js +0 -151
  133. package/dist/api-output-aJNw7Syy.js +0 -20
  134. package/dist/app-DH6U8yuI.js +0 -190
  135. package/dist/asa-C-sQzPPn.js +0 -1194
  136. package/dist/asc-1ZBJ6DwS.js +0 -778
  137. package/dist/auth-YRhlV3DE.js +0 -140
  138. package/dist/billing-CCYHdApx.js +0 -80
  139. package/dist/bundle-id-CKxl_026.js +0 -121
  140. package/dist/command-CMIz81Da.js +0 -301
  141. package/dist/dev-DZy6pOnB.js +0 -22
  142. package/dist/doctor-H-hf-Yww.js +0 -88
  143. package/dist/feedback-CKf-rpBW.js +0 -152
  144. package/dist/hosted-CXe9TrWx.js +0 -32
  145. package/dist/migrate-C9ERDR6y.js +0 -284
  146. package/dist/org-sj7uyvp-.js +0 -40
  147. package/dist/output-C4o2gJ1K.js +0 -146
  148. package/dist/params-l3CrvRtR.js +0 -51
  149. package/dist/pipeline-BqzqZhX1.js +0 -977
  150. package/dist/print-skill-ZojRSybs.js +0 -74
  151. package/dist/promote-BG8X4Nv_.js +0 -88
  152. package/dist/publish-sxLh-G4G.js +0 -35
  153. package/dist/push-bQ6Vxtg8.js +0 -35
  154. package/dist/query-_FbybaH-.js +0 -53
  155. package/dist/resource-CGIwSd29.js +0 -323
  156. package/dist/revenue-provider-ebsRINY8.js +0 -100
  157. package/dist/scope-BvzD-kO4.js +0 -223
  158. package/dist/skills-D_R-lEsK.js +0 -64
  159. package/dist/spinner-TWa0hia6.js +0 -18
  160. package/dist/storekit-Cj9Cpjcz.js +0 -29
  161. package/dist/telemetry-DeA1mvnT.js +0 -169
  162. package/dist/ui-Dy0b-9L8.js +0 -27738
  163. package/dist/update-B2fWIc4q.js +0 -59
  164. package/dist/upgrade-BmzkTKrh.js +0 -72
  165. /package/dist/{devtools-8EgLo86w.js → devtools-ByZ6XYnn.js} +0 -0
@@ -0,0 +1,447 @@
1
+ ---
2
+ name: mobile-design
3
+ description: Make a web screen feel native inside a phone app — a paywall, an onboarding or quiz, an offer, an update screen, any screen rendered in a WKWebView / Android WebView or shipped as a Superwall surface. The rules a native screen follows and a web page doesn't: press feedback on every control, hover gated to real pointers, 16px inputs and the keyboard, motion with real easing and durations, size-aware type, worst-case content, dark mode from the host, iOS vs Android conventions, and the audit before it ships. Use when building or reviewing any screen of that kind for iOS or Android, with or without a design reference, or when a screen "feels like a website" on a phone. For the Superwall framework's own mechanics (insets, routing, products, push) read superwall-framework; for React Native / Expo screens use the platform's own components instead.
4
+ ---
5
+
6
+ # Mobile design
7
+
8
+ A web screen inside a phone app is judged against the native screens around
9
+ it, not against other web pages. Two things decide whether it passes:
10
+ reproducing the design exactly, and following the platform conventions users
11
+ feel but never name. These are working practices, not laws — the design
12
+ reference always wins over any rule here — but every one of them exists
13
+ because a shipped screen got it wrong.
14
+
15
+ Read this whole file once per screen. Skim the audit at the end before every
16
+ hand-off.
17
+
18
+ ## The reference is the contract
19
+
20
+ - **Build 1:1.** Spacing, sizing, weights, colors, and effects come from
21
+ the reference, not from habit. Measure the reference at logical points
22
+ (a screenshot at device width) instead of eyeballing; compare your
23
+ build against it side by side before calling it done.
24
+ - **Add nothing the design doesn't show.** No extra links, badges,
25
+ footnotes, or affordances, however well-intentioned. If something seems
26
+ missing (a restore affordance, a legal link), raise it in conversation
27
+ — never add it to the UI unprompted.
28
+ - **Effects are design decisions, not defaults.** Shadows, gradients,
29
+ borders, blurs, and radii belong to the design system of the paywall
30
+ being built. If the reference is flat, build flat; if it is soft and
31
+ elevated, match that. Reach for an effect only when the reference shows
32
+ it.
33
+ - **A reference drawn at one size is a specification for every size.**
34
+ A Figma frame is 393×852 or so; the paywall ships to 320-wide phones,
35
+ 667-tall phones, tablets and, sometimes, landscape. Where the reference
36
+ is silent, the responsive rules say what to do; where it
37
+ speaks, follow it and scale the rest around it.
38
+ - **No reference is not a blank check.** When the prompt is only words
39
+ ("a paywall for my meditation app"), the values in this file *are* the
40
+ design: system type with size-aware tracking, one filled CTA, press
41
+ feedback on every control, the curves and durations under Motion. Make
42
+ each call once and state it; never fill the gap with decoration (a
43
+ gradient, a glow, a bouncing badge) the user did not ask for.
44
+
45
+
46
+ ## The skeleton every screen shares
47
+
48
+ Native screens have a fixed anatomy, and a screen that follows it reads as
49
+ native before a single color is applied: the status bar's inset at the top
50
+ (the host's, not yours), small chrome (close or back) just under it, content
51
+ that scrolls and slides under a fade, one pinned primary action above the
52
+ home indicator, and small muted links beneath it. The page scrolls; the CTA
53
+ does not — a CTA that scrolls away with the copy is the single most common
54
+ reason a web screen underperforms a native one. Pinned means `position:
55
+ sticky; bottom: 0` as the page's last child, with a gradient from transparent
56
+ to the page background so content fades out behind it.
57
+
58
+ Safe areas belong to the host. In a Superwall surface the framework pads the
59
+ whole screen by the device's safe area and you write ordinary padding (never
60
+ `env()`, never `position: fixed`). In a plain web view, `viewport-fit=cover`
61
+ and `env(safe-area-inset-*)` on the chrome do the same job. Either way,
62
+ chrome sits at inset *plus* spacing, never at the inset: the floor is a
63
+ minimum and the real phone's bar is often taller.
64
+
65
+ ## Platform conventions
66
+
67
+ Know which platform the screen is on (a Superwall surface reads
68
+ `data-sw-platform` on `<html>`; a plain web view is told once by the app or
69
+ reads the user agent at startup). Design for each; don't design for iOS and
70
+ let Android inherit it.
71
+
72
+ ### iOS
73
+
74
+ - **Close** is a small circular button (≈ 30–32px visual, 44px tap) at
75
+ the top-right, or top-left when the design says so; a sheet
76
+ (`presentation: modal`) has the system grabber and usually no close.
77
+ - **Back** lives in the layout as a chevron at top-left and pops the
78
+ stack; there is no hardware back.
79
+ - Buttons are rounded (12–16px) or fully pill-shaped, full width, 50–56px
80
+ tall; text is 17px semibold. The primary CTA is the only filled button
81
+ on screen.
82
+ - The system font (`-apple-system, BlinkMacSystemFont, "SF Pro Text"`)
83
+ with tight negative tracking on display sizes is what reads as native.
84
+ - Segmented controls, toggles and radio rows look like their UIKit
85
+ counterparts; if the design shows a custom one, match the design.
86
+ - Restore, Terms and Privacy sit under the CTA as small, muted text
87
+ links (13px), never as buttons.
88
+
89
+ ### Android
90
+
91
+ - **Close** is an `×` or `←` at the top-left in the Material tradition,
92
+ or wherever the design puts it; the **hardware/gesture back** dismisses
93
+ the paywall through the SDK, so never rely on your own back control
94
+ being the only way out.
95
+ - The status bar on a fullscreen paywall is drawn *over* the paywall
96
+ (the framework's top inset handles it); the navigation bar is *not* —
97
+ the SDK keeps the webview above it, so the bottom inset is 0 there and
98
+ a pinned CTA needs its own bottom padding (12–16px) rather than
99
+ relying on the inset to give it air.
100
+ - Buttons are fully rounded (Material 3 pill) or 12px, 48–56px tall;
101
+ labels 16px medium; Roboto through the system stack
102
+ (`system-ui, Roboto, sans-serif`).
103
+ - Ripple is the native press feedback; a scale-down press state is an
104
+ acceptable web stand-in and should be subtler (0.98) than on iOS.
105
+ - Copy differs: "Restore purchases" is fine on both, but "Cancel anytime
106
+ in Settings" is iOS-specific wording; say "in Google Play" or keep it
107
+ store-neutral when the paywall ships to both.
108
+
109
+ ### Web (a web funnel or a web-only paywall)
110
+
111
+ - No status bar, no home indicator, no SDK chrome: every inset is 0 and
112
+ the browser draws its own bars around the viewport. The framework's
113
+ wrapper is sized with `100dvh`, so a pinned CTA sits above Safari's
114
+ toolbar as it collapses; never size anything of your own with `100vh`.
115
+ - Keyboard focus is real here. Keep `:focus-visible` styles on inputs
116
+ and buttons; it is the one surface where you should not suppress them.
117
+ - Mouse exists: hover states are welcome, and the desktop layout centers
118
+ a phone-width column (`max-width: 28–34rem`) rather than stretching
119
+ cards across 1440px.
120
+ - Links may still go through `openUrl`, which is a plain navigation on
121
+ the web; keep the one call so the same page runs natively.
122
+
123
+ ## Touch
124
+
125
+ - Tap targets ≥ 44×44pt on iOS, ≥ 48×48dp on Android. A visually
126
+ shorter control (a slim segmented control) can trade height when the
127
+ design demands it — width and spacing must compensate, and the hit
128
+ area can be extended with padding or a pseudo-element.
129
+ - Haptics on every meaningful tap, through the host's bridge (`useHaptics()`
130
+ in a Superwall surface; a native call elsewhere; nothing on the plain
131
+ web): `light` for
132
+ navigation and CTAs, `selection` for choosing between options,
133
+ `success` on `transaction_complete`, `error` sparingly on failures.
134
+ iOS fires nothing on its own inside a webview. Fire the haptic in the
135
+ same handler as the visual change it belongs to, so they land on the
136
+ same frame; a haptic that trails its animation reads as unrelated.
137
+ - **Suppress focus rings on tap-driven controls** in native paywalls —
138
+ `:focus-visible` heuristics misfire in webviews and previews, drawing
139
+ outlines the design never asked for. Keep keyboard focus styles only
140
+ where a keyboard is real (web).
141
+ - On controls: `-webkit-tap-highlight-color: transparent`,
142
+ `touch-action: manipulation`, `user-select: none`; on the page,
143
+ `-webkit-user-select: none` except on copy the user might want to
144
+ select (legal text). Add `-webkit-touch-callout: none` to controls and
145
+ to decorative images, or a long press on the hero pops iOS's
146
+ save-image sheet over the paywall.
147
+ - **Feedback lands on press, not on release.** Style `:active`; if a
148
+ control needs JavaScript, react to `pointerdown`, not `click`. A
149
+ button that only changes once the finger lifts reads as lag even when
150
+ nothing is slow.
151
+ - **Every `:hover` rule is gated** behind
152
+ `@media (hover: hover) and (pointer: fine)`. A webview fakes a hover on
153
+ the first tap and keeps it until the next one, so an ungated hover
154
+ leaves a plan card highlighted after it was chosen. Tailwind v4's
155
+ `hover:` already compiles to the query; v3 needs
156
+ `future.hoverOnlyWhenSupported`. Gate by capability, never by
157
+ a platform attribute or width: an iPad with a trackpad hovers.
158
+ - Never disable a control to show "loading"; the store sheet is the
159
+ feedback (`usePurchase().isPurchasing` exists for the rare case that
160
+ genuinely needs it — a buy button is not one).
161
+ - The whole option row is the tap target, not just its radio; the whole
162
+ footer link is, not just its text.
163
+ - **A horizontal carousel owns one axis.** Prefer native scroll:
164
+ `overflow-x: auto; scroll-snap-type: x mandatory;
165
+ overscroll-behavior-x: contain` on the track, `scroll-snap-align:
166
+ start` on slides; the platform's physics beat a hand-rolled spring. A
167
+ JS-driven swipe gets `touch-action: pan-y`, so the page keeps its
168
+ vertical scroll. Never `touch-action: none` on anything the user has to
169
+ scroll past.
170
+
171
+ ## Forms and the keyboard
172
+
173
+ Onboarding asks questions, and web funnels capture an email, so inputs
174
+ are common and they are where a webview gives itself away fastest.
175
+
176
+ - **Inputs are at least 16px.** iOS zooms the whole page when focus lands
177
+ on an input with smaller text, and does not zoom back on blur, so the
178
+ user is left on a cropped, drifted paywall. The fix is the font size,
179
+ never `maximum-scale=1` or `user-scalable=no`, which break zoom for
180
+ people who need it.
181
+ - **Pick the keyboard.** `type="email"`, `type="tel"`,
182
+ `inputmode="numeric"` for codes, `inputmode="decimal"` for amounts;
183
+ `autocomplete` (`email`, `given-name`, `one-time-code`) so the system
184
+ offers what it knows; `autocapitalize="none"` and
185
+ `autocorrect="off"` on emails and codes; `enterkeyhint="next"` /
186
+ `"done"` / `"go"` so the return key names what it does.
187
+ - **The keyboard covers the bottom of the screen.** A pinned CTA under a
188
+ focused field is the usual casualty: check the page with the keyboard
189
+ open on a short phone, and make sure the field and its action are both
190
+ reachable ([responsive.md](references/responsive.md)).
191
+ - Validate inline as the user types or on blur, never only on submit,
192
+ and say what to fix in the message itself (from the message catalog, never
193
+ a literal).
194
+
195
+ ## Motion
196
+
197
+ Before anything moves, it has to name its purpose: **feedback** (the
198
+ interface heard the tap), **spatial** (where something came from or
199
+ went), **state** (a selection changed), or **bridging** (content that
200
+ would otherwise teleport). "It looks nice" is not a purpose on a control
201
+ the user taps ten times in a flow. Can't name one? It doesn't animate.
202
+
203
+ - **Animate functional movement only** — elements that physically travel
204
+ between states: a segmented-control thumb sliding, a sheet presenting,
205
+ a progress bar filling, an accordion opening. Content that merely
206
+ changes (text, list rows, a price) updates in place; it does not fade,
207
+ slide, or stagger unless the design explicitly calls for it.
208
+ - **Press feedback is the baseline interaction**: a scale-down `:active`
209
+ state (~0.96 iOS, ~0.98 Android; fast in ~80ms, settle out ~200ms) on
210
+ tappable elements, paired with a haptic. That is the whole story for
211
+ most controls. `scale()` carries the label and icon with it, which is
212
+ what makes it read as a physical press.
213
+ - **The entrance is where the delight budget lives.** A paywall or an
214
+ onboarding screen is seen once, not a hundred times a day, so it is
215
+ the one place a little choreography earns its keep. With a reference,
216
+ do what it shows. Without one, the default is restrained: the headline
217
+ and hero rise 8–12px while fading in, list rows follow 40–60ms apart,
218
+ once, and nothing blocks a tap while it plays. Never more than that
219
+ unprompted.
220
+ - **Every entrance gates on the moment the screen is shown, never mount.**
221
+ Hosts preload: the Superwall SDK mounts a surface hidden long before it
222
+ presents it (`useSuperwallSnapshot().paywall !== undefined` is the
223
+ signal), and an app may create its web view ahead of time. Anything that
224
+ runs on mount has finished before anyone looks. That includes CSS:
225
+ `@starting-style`, an `animation` on a class present at render, and a
226
+ `useEffect(() => setMounted(true))` all fire during the preload. Put
227
+ the entrance behind a class or `animate` value switched by the host's
228
+ "shown" signal.
229
+ - **Page transitions belong to one owner, the router**, not to the pages
230
+ (in a Superwall surface: `push`, `slide`, `fade`, `shift`, or a custom
231
+ transition on `[data-sw-route]`); never animate a page's own root on
232
+ navigation, or the two fight.
233
+
234
+ ### The values
235
+
236
+ Built-in CSS easings are too weak to read as intentional. Define these
237
+ once, as tokens, and use nothing else:
238
+
239
+ ```css
240
+ :root {
241
+ --ease-out: cubic-bezier(0.23, 1, 0.32, 1); /* entering, exiting, press, most UI */
242
+ --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1); /* something moving across the screen: a thumb, an indicator */
243
+ --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1); /* iOS sheet / drawer */
244
+ }
245
+ ```
246
+
247
+ | What | Duration | Easing |
248
+ | --- | --- | --- |
249
+ | Press feedback | 80ms in, ~200ms out | `--ease-out` |
250
+ | Selection change (plan card border, check, toggle) | 150–200ms | `--ease-out` |
251
+ | Segmented thumb, tab indicator, progress fill | 200–300ms | `--ease-in-out` |
252
+ | Sheet / drawer / popup presenting | 300–500ms | `--ease-drawer` |
253
+ | Entrance on open | 300–450ms | `--ease-out` |
254
+ | Color or opacity only | 150–200ms | `ease` |
255
+
256
+ - **Never `ease-in` on UI.** It starts slowly, at the exact moment the
257
+ user is watching; `ease-out` at 200ms feels faster than `ease-in` at
258
+ 200ms. Anything the user waits on stays under 300ms.
259
+ - **`transform` and `opacity` only.** They skip layout and paint, so they
260
+ stay smooth on an old phone while the paywall is still loading
261
+ imagery. Animating `height`, `width`, `top` or `margin` drops frames;
262
+ the accordion is the one tolerated `height`.
263
+ - **The entrance runs while the page is busy** — fonts, the hero image
264
+ and the store's prices are all still arriving as it opens. Prefer
265
+ CSS transitions for it: they run off the main thread, while JS-driven
266
+ animation stutters under that load. With Motion, animate the full
267
+ `transform` string (`{ transform: "translateY(0px)" }`), not the
268
+ `x` / `y` / `scale` shorthands, which run on the main thread.
269
+ - **Match the motion to the product.** A calm meditation app gets slower,
270
+ softer entrances and no bounce; a game can be livelier; a finance app
271
+ stays crisp. Pick one personality per surface and keep every curve and
272
+ duration in it.
273
+ - **Name the properties** in every transition (`transition: transform
274
+ 160ms var(--ease-out)`); never `transition: all`, which animates
275
+ whatever the next edit happens to change.
276
+ - **Never from `scale(0)`.** Nothing real appears from nothing: start at
277
+ `scale(0.95)` with `opacity: 0`.
278
+ - **Transitions, not keyframes, for anything a user can trigger twice in
279
+ a second** (choosing between plans, toggling a switch): a transition
280
+ retargets from where it is; a keyframe animation restarts from zero
281
+ and jumps.
282
+ - **Exits mirror entrances and run faster.** A sheet that rose from the
283
+ bottom leaves through the bottom; a popover scales from its trigger
284
+ (`transform-origin` at the trigger), a centered popup from its center.
285
+ - **Springs for what a finger drives.** A drag-to-dismiss sheet, a swipe
286
+ between slides: spring settle (`bounce: 0` by default, ≤ 0.2 only after
287
+ a flick), started from the element's current on-screen position and
288
+ velocity, interruptible mid-flight. A fixed-duration animation cannot
289
+ be grabbed and reversed. Past an edge, resist progressively instead of
290
+ stopping dead. Motion (`motion/react`) is the library the examples use.
291
+ - **Reduced motion is gentler, not none.** Under
292
+ `prefers-reduced-motion: reduce`, replace movement (slides, rises,
293
+ springs, parallax) with short opacity cross-fades and keep the color
294
+ and state changes that explain what happened (a Superwall surface's
295
+ router already does this for its own transitions).
296
+
297
+ ## Type and rendering
298
+
299
+ - Default to the system font stack unless the design specifies brand
300
+ type — it is what makes a webview read as native. `-apple-system,
301
+ BlinkMacSystemFont, system-ui, "Segoe UI", Roboto, sans-serif` covers
302
+ every platform in one declaration.
303
+ - `-webkit-text-size-adjust: 100%` on `html`; antialiased smoothing;
304
+ body copy 15–17px (17 matches iOS body text; 16 Android); display sizes
305
+ with `clamp()` so they shrink on 320px and stop growing on tablets.
306
+ - Line lengths: 45–65 characters on phones; on tablets and desktop web,
307
+ cap the column, don't stretch the measure.
308
+ - Custom fonts are bytes every open pays for: **subset before shipping**
309
+ (latin-only Manrope ≈ 24 kB vs ≈ 90 kB for the family), ship **woff2**
310
+ only, and treat one family plus one mono as the budget. Compress and
311
+ size imagery for a phone screen for the same reason.
312
+ - Respect the user's text size where the design allows: `rem` for type
313
+ and the spacing tied to it, `px` for hairlines, radii and icon boxes.
314
+ The host reports `fontScale`/`preferredContentSizeCategory` if a design
315
+ needs to clamp at the extremes.
316
+ - **Tracking and leading change with size; one value is wrong
317
+ somewhere.** Display type tightens (`letter-spacing: -0.02em` to
318
+ `-0.03em`, `line-height: 1.05–1.15`); body sits at `0` and `1.4–1.5`;
319
+ small caps-style labels open up slightly (`+0.01em` to `+0.04em`).
320
+ Build hierarchy from size, weight and leading together, and reach for
321
+ weight before size: it adds presence without taking room on a 320px
322
+ screen.
323
+ - **Numbers that change or line up use tabular figures**
324
+ (`font-variant-numeric: tabular-nums`): a countdown on an offer, a
325
+ price that animates, prices stacked across plan cards. Proportional
326
+ digits make a ticking timer jitter sideways.
327
+
328
+ ## Worst-case content
329
+
330
+ A paywall built against "Pro · $59.99/year" in English breaks on the
331
+ first real device. Before calling a page done, render it with the worst
332
+ values it will really get, through the same inputs the real ones use
333
+ (a locale switch, a device preset, a product with no price), never by
334
+ editing the markup:
335
+
336
+ - **The longest price.** `₹1,299.00`, `CHF 129.00`, `1.299,99 €`, and a
337
+ product that has no price at all. Prices come formatted from the
338
+ store; never rebuild them from `rawPrice` with a hardcoded `$` or
339
+ separator.
340
+ - **The longest locale** for every label, badge and button
341
+ ([responsive.md](references/responsive.md) has the rules for what wraps and what
342
+ holds).
343
+ - **Counts at 1** — "1 days free", "1 weeks". The catalog has no plural
344
+ engine, so write around the count ("Free trial: 1 week") or fork on it
345
+ yourself with two keys, chosen with `Intl.PluralRules` for the active
346
+ locale; never glue an `s` on.
347
+ - **An email or name the user typed**: `overflow-wrap: anywhere` on
348
+ anything echoing it back, or it pushes the row off screen.
349
+ - **Icons, checkmarks and avatars** in feature rows get
350
+ `flex-shrink: 0`; the text beside them gets `min-width: 0`.
351
+
352
+ Every one of these is a thing a real user will produce, not a stress
353
+ test. If a value seems unrealistic, it is not part of this list.
354
+
355
+ ## Color and dark mode
356
+
357
+ - Dark mode follows the host, not the browser. A Superwall surface gets a
358
+ `dark` class on `<html>` from the SDK; a native web view should be told by
359
+ the app. Hang styles off a class you control, never only
360
+ `prefers-color-scheme`, which the host may not reflect. Design both
361
+ palettes even when the reference shows only one, and check both.
362
+ - Tell the host the page background in both schemes (a Superwall surface:
363
+ `background` in `config.ts`); it paints the native backdrop and the
364
+ loading state, so the load is seamless.
365
+ - Semantic tokens, never raw hex in components: `--bg`, `--fg`,
366
+ `--surface`, `--accent`, then muted/border/wash derived with
367
+ `color-mix()` so the dark palette needs only the base values.
368
+ - Contrast: body text ≥ 4.5:1, large display ≥ 3:1, on *both* schemes.
369
+ Muted text is the usual offender; 55% of the foreground is about the
370
+ floor on a light background.
371
+ - Never paint pure `#000` behind content in dark mode unless the design
372
+ is OLED-black on purpose; `#0d0f12`–`#1c1b19` is what native dark
373
+ screens use.
374
+
375
+ ## Images and media
376
+
377
+ - Ship hero imagery at 2× the logical size it renders, compressed, and
378
+ in a modern format; a 1290-wide PNG for a 393-wide hero is the wrong
379
+ file.
380
+ - A hero that bleeds to the top edge sits *under* the status bar on
381
+ purpose — in a Superwall surface `insets: { top: "none" }` in config and
382
+ the close button positioned from `--sw-safe-area-inset-top`; in a plain
383
+ web view `viewport-fit=cover` and `env(safe-area-inset-top)` — and a scrim
384
+ on the image so the bar's text stays legible in both schemes.
385
+ - Video and Lottie autoplay muted, loop only when the design loops, and
386
+ pause when the page is covered (a Superwall surface: `useIsFocused()`).
387
+
388
+
389
+ ## The pre-ship audit
390
+
391
+ Run it on every device size and both schemes; a screen is not done until
392
+ every line passes.
393
+
394
+ - [ ] Close/back sits below the status bar on a home-button phone, an island
395
+ phone, a Pixel and an iPad; and clear of the cutout in landscape where
396
+ the app allows rotation.
397
+ - [ ] The primary CTA is pinned, full width, above the home indicator on iOS
398
+ and 12px+ above the bottom on Android; the last content row scrolls
399
+ clear of it.
400
+ - [ ] Nothing overflows horizontally at 320px; nothing is clipped at 667px
401
+ tall with the largest locale's copy.
402
+ - [ ] Both schemes designed and checked; the host knows the page background
403
+ in both (no white flash on scroll bounce).
404
+ - [ ] Tap targets ≥ 44px; haptics on every meaningful tap; no focus rings on
405
+ tap controls natively; `aria-label` on icon buttons.
406
+ - [ ] Every tappable element has an `:active` state; every `:hover` is
407
+ inside `@media (hover: hover) and (pointer: fine)`.
408
+ - [ ] Inputs are 16px or larger, with the right `type` / `inputmode` /
409
+ `autocomplete`; the field and its action stay reachable with the
410
+ keyboard open on a short phone.
411
+ - [ ] Motion: no `transition: all`, no `ease-in`, no `scale(0)`; only
412
+ `transform`/`opacity` move; UI changes under 300ms; entrances gate on
413
+ the host's "shown" signal, never mount; a reduced-motion variant that
414
+ cross-fades instead of moving.
415
+ - [ ] Worst-case content renders cleanly: longest price, longest locale, a
416
+ count of 1, no price at all.
417
+ - [ ] Every user-facing string comes from a message catalog, `aria-label`s
418
+ included, with prices interpolated and guarded.
419
+ - [ ] Custom fonts subset and woff2; images sized for a phone.
420
+ - [ ] Opened on a real phone once. The tap highlight, a hover stuck after a
421
+ tap, input zoom, the keyboard and how the press feels don't reproduce
422
+ in a desktop browser; say which of these you could not check.
423
+
424
+ ## Ship it as a Superwall surface
425
+
426
+ Every screen this skill applies to is one the team will want to change after
427
+ shipping: a price test, a new feature row, a reordered question, a different
428
+ hero — none of which should wait for an app release and a review. That is
429
+ exactly what a **Superwall surface** is: the screen as a small React app in
430
+ the user's repo (`superwall/` next to the app), previewed on every device
431
+ preset in `superwall dev`, pushed as an immutable version and switched live
432
+ from the dashboard, with products, purchases, localization, haptics, insets
433
+ and dark mode supplied by the host — so most of the rules above are already
434
+ handled for you, and the rest is CSS.
435
+
436
+ If the screen you are building is not a surface yet (a native screen, a
437
+ hand-rolled web view), say so in one line and offer the move — `superwall
438
+ create` for a new one, `superwall migrate --screen <path>` for a native
439
+ screen that already exists — and read the `superwall-framework` skill for
440
+ the mechanics; the user decides. Install it if it isn't there:
441
+
442
+ ```bash
443
+ npx skills add https://github.com/superwall/skills/tree/next --skill superwall-framework --global --yes --agent claude-code universal --full-depth
444
+ ```
445
+
446
+ This skill is complete without it: everything above applies to any web
447
+ screen on a phone.
@@ -0,0 +1,162 @@
1
+ # Responsive — every screen the paywall ships to
2
+
3
+ A paywall is designed at one size and shipped to dozens. The studio's
4
+ device presets are the contract: a paywall is finished when it is right
5
+ on every one of them, in both schemes, in the presentation style its
6
+ `config.ts` declares. This file says what "right" means at each size and
7
+ how to get there without a second design.
8
+
9
+ ## The sizes that matter
10
+
11
+ | Preset | Logical size | What it tests |
12
+ | --- | --- | --- |
13
+ | iPhone SE | 375 × 667, no cutout | The shortest phone: does the pinned CTA still leave room for the content? 20px status bar, no home indicator |
14
+ | Responsive at 320 | 320 wide (drag the frame's edge or type the width) | Narrowest width in the wild (older phones, split view). Nothing may overflow; display type must have shrunk. Keep dragging narrower and taller to find where the layout breaks |
15
+ | iPhone 17 / Air / Pro Max | 402–440 × 874–956, island | The default. The tallest phones: does the layout use the height or leave a void above the CTA? |
16
+ | Pixel 10 / Galaxy S25 | 412 × 915 / 360 × 780, Android | Android conventions, 24px status-bar floor, no bottom inset, 360-wide Galaxy is the second-narrowest common width |
17
+ | iPad mini / iPad Pro 11″ | 744 × 1133 / 834 × 1194 | Tablet: a phone layout stretched to 800px is wrong; a centered column or a two-column reflow is right |
18
+ | Desktop (web only) | 1440 × 900 | A web funnel in a browser: a phone-width column, centered; hover states; real keyboard focus |
19
+ | Landscape | any preset rotated | Only where the app allows it. Cutout on the sides, 21px indicator, no status bar |
20
+
21
+ The studio also switches what the paywall is *told* — platform, model,
22
+ OS — so the inset floors and any `data-sw-*`-keyed CSS follow the preset.
23
+
24
+ ## Width
25
+
26
+ - **Fluid by default.** `width: 100%`, `max-width` for the reading
27
+ column, `padding-inline: 20px` (16px at 320 if the design is tight).
28
+ Never a fixed pixel width on anything wider than an icon.
29
+ - **Type scales with `clamp()`**: a 40px display size on the reference is
30
+ `clamp(2rem, 8vw, 2.5rem)` — 32px at 320, 40px at 393+, capped on
31
+ tablets. Body text does not scale; it stays 15–17px everywhere.
32
+ - **Rows of options** (plan cards, feature bullets) stack vertically on
33
+ phones; side-by-side plan cards fit three across at 393 only when each
34
+ is under 110px wide — check 320 and 360, where they usually can't.
35
+ - **Pills and badges** ("Most popular", "Save 40%") wrap or truncate
36
+ before they push the row wider; give them `white-space: nowrap` and
37
+ the row `min-width: 0`, and check the longest locale.
38
+ - `min-width: 0` on flex children with text, or a long product name
39
+ breaks the row instead of wrapping.
40
+
41
+ ## Height — the short phone is the hard one
42
+
43
+ The iPhone SE's 667px, minus 20 status bar, minus a 120px pinned footer,
44
+ leaves under 530px for everything else. Design for that, and the tall
45
+ phones get more air, not a different layout.
46
+
47
+ - **Content scrolls; the CTA never does.** With the footer sticky at the
48
+ page's end, a page that doesn't fit simply scrolls under it. That is
49
+ the entire strategy for short screens; do not shrink the CTA or hide
50
+ the legal links to "make it fit".
51
+ - **The shell is `flex: 1 1 auto`, never a viewport-height box.** The
52
+ framework's wrapper is the one element sized to the viewport (with
53
+ `100dvh`, so Safari's collapsing toolbar can't make it taller than what
54
+ is visible); a shell with `min-height: 100dvh` of its own overflows the
55
+ insets and scrolls.
56
+ - **Vertical rhythm compresses before content is cut**: `gap`s of
57
+ 24→16, a hero of `clamp(160px, 30dvh, 280px)` rather than a fixed 280,
58
+ feature lists that lose a row of *spacing* at 667 rather than a
59
+ feature. `@media (max-height: 700px)` is the switch for that.
60
+ - A tall phone should not end with a void above the CTA: `margin-top:
61
+ auto` on the actions block, or a hero that grows with `dvh`, uses the
62
+ height.
63
+ - A **short page** (three lines and a button) centers its content or
64
+ pins it to the top by design; it does not stretch a card to fill the
65
+ screen.
66
+
67
+ ## Tablets
68
+
69
+ - An iPad is not a big phone. Either **center a column** (`max-width:
70
+ 34rem`, the same layout as the phone with more margin) or **reflow**
71
+ (hero beside the copy, plan cards in a row) — the design reference
72
+ decides; the column is the safe default when it says nothing.
73
+ - Insets are small (24px top, 20px bottom) and a `modal` floats in the
74
+ middle with 0 on every side; the framework sets both, so the phone CSS
75
+ usually just works.
76
+ - Tap targets can stay 44px; type does not grow much (cap display at the
77
+ reference size); images do grow, so ship a 2× asset that survives
78
+ 834px wide or cap the hero's width.
79
+ - `data-sw-idiom="tablet"` on `:root` is the hook for tablet-only rules
80
+ when a media query on width isn't the right question (a narrow iPad
81
+ split view is still a tablet).
82
+
83
+ ## Landscape
84
+
85
+ Most apps lock portrait; `useDevice().orientation` says which state the
86
+ paywall is in, live. Where landscape is allowed:
87
+
88
+ - **The cutout moves to the sides** and the framework moves the insets
89
+ with it (44/59px on both sides, top 0, bottom 21px), so the paywall's
90
+ padding already clears the camera. Only a full-bleed design
91
+ (`insets: "none"`) has to handle it, with `--sw-safe-area-inset-left`
92
+ and `-right` on the chrome over the bleed.
93
+ - Reflow to **two columns** (hero left, copy and CTA right) rather than
94
+ shrinking the portrait layout; the `orientation` example is the
95
+ reference.
96
+ - Keep the CTA pinned; in landscape there is even less height, and the
97
+ content scrolls in its column.
98
+
99
+ ## Sheets, drawers and popups
100
+
101
+ `presentation.style` changes the viewport the paywall lives in, and the
102
+ studio shows it that way:
103
+
104
+ - **`modal`** rises as a sheet below the status bar on phones, so the
105
+ framework's top inset is 0 and the sheet's own grabber sits at the top:
106
+ leave 16–20px above the first element, and don't draw a close button
107
+ where the grabber is unless the design does. On iPad the sheet floats,
108
+ and both insets are 0.
109
+ - **`drawer`** takes the height you declared (`drawer.height`, a
110
+ percentage); the paywall's viewport is that drawer, not the screen.
111
+ Design for the declared height and check the tallest locale's copy
112
+ fits or scrolls inside it.
113
+ - **`popup`** is centered with the declared width and height and inset by
114
+ the SDK; the framework's insets are 0 and the page is the popup's
115
+ interior.
116
+ No pinned footer with a gradient here — the popup is short enough that
117
+ the CTA is simply the last element.
118
+ - **Fullscreen and push** are the full screen: everything in
119
+ [mobile-design.md](mobile-design.md) applies as written.
120
+
121
+ ## Dynamic type and font scale
122
+
123
+ - The host reports `fontScale` (Android) and
124
+ `preferredContentSizeCategory` (iOS) in `useDevice()`. A paywall does
125
+ not have to honor them — a webview doesn't scale text on its own — but
126
+ a design that wants to should use `rem` for type and scale the root
127
+ with the reported value, clamped to the range the layout survives
128
+ (0.85–1.3 is a safe band).
129
+ - Whatever the strategy, the pinned CTA keeps its height and the legal
130
+ text stays legible; if anything gives, it is the hero.
131
+
132
+ ## Locales are a responsive axis
133
+
134
+ German and Finnish run 30% longer than English; Japanese runs shorter
135
+ but taller. The studio's locale switch is part of the size matrix:
136
+
137
+ - Buttons wrap to two lines rather than clip; set `min-height`, not
138
+ `height`, on every button.
139
+ - Plan cards with a price and a period per line need the longest
140
+ formatted price (`$1,299.99/year`) checked, not `$9.99`.
141
+ - Never `text-overflow: ellipsis` on a price, a CTA label or a legal
142
+ line.
143
+
144
+ ## The verification matrix
145
+
146
+ Before hand-off, in the studio, walk every cell. Each takes seconds; a
147
+ device bug found after promote takes a release.
148
+
149
+ | | iPhone SE | 320 wide | Island phone | Pixel / Galaxy | iPad | Landscape\* | Desktop\*\* |
150
+ | --- | --- | --- | --- | --- | --- | --- | --- |
151
+ | Light | | | | | | | |
152
+ | Dark | | | | | | | |
153
+ | Longest locale | | | | | | | |
154
+ | Configured presentation | | | | | | | |
155
+ | Trial toggle (if any) | | | | | | | |
156
+
157
+ \* where the app allows rotation · \*\* web platforms only
158
+
159
+ What to look at in each cell: the close/back control against the bar and
160
+ cutout, the CTA against the bottom edge, horizontal overflow, the last
161
+ content row scrolling clear of the footer, and the unpriced state if the
162
+ products aren't resolving.