saglitzdesign-mcp 0.3.1

package/knowledge/patterns/mobile/android-patterns.md

@@ -0,0 +1,181 @@
+---
+id: android-patterns
+title: "Android Conventions & Top-App Patterns"
+category: pattern
+platform: mobile
+tags: [android, material, conventions, top-apps]
+sources: ["https://9to5google.com/2025/11/17/google-material-3-expressive-redesign/", "https://9to5google.com/2025/05/14/material-3-expressive-navigation/", "https://9to5google.com/2025/05/18/material-3-expressive-toolbars/", "https://www.androidpolice.com/whatsapp-revamped-material-design-3-ui-reaching-few-beta-testers/", "https://www.androidauthority.com/google-material-3-expressive-features-changes-availability-supported-devices-3556392/", "https://m3.material.io/components/navigation-bar", "https://developer.android.com/design/ui/mobile/guides/patterns/predictive-back", "https://developer.android.com/about/versions/16/behavior-changes-16", "https://developer.android.com/docs/quality-guidelines/core-app-quality"]
+updated: 2026-07-08
+---
+
+# Android Conventions & Top-App Patterns (2026)
+
+How real top Android apps structure themselves, where they follow Material 3 (Expressive) vs go brand-custom, and the Android-specific conventions iOS-first designers miss. Companion to `android-app-design` (system rules, dp specs) and the general M3 doc (visual language).
+
+## 1. How top apps actually structure navigation
+
+**The consensus: 3–5 bottom destinations + a FAB for the single primary action + drawer only for overflow hierarchies.**
+
+- **Gmail** — 2-tab bottom bar (Mail, Meet) + modal drawer for labels + "Compose" extended FAB that collapses on scroll. M3 Expressive wave: search app bar with the avatar outside the pill, conversation list wrapped in rounded surface containers.
+- **Phone by Google** — the M3 Expressive flagship redesign: bottom tabs *reduced* from four to three (Home = Favorites + Recents merged, Keypad promoted to its own tab, Voicemail), contacts relocated to a drawer. Lesson: Google merges destinations rather than adding a fifth tab.
+- **Files by Google** — navigation rail on large screens, animated M3 carousel + category grid on phones. Rail-on-tablet is now the expected large-screen answer, not a stretched bottom bar.
+- **Google Calendar** — **FAB menu**: the FAB expands into stacked, labeled pill actions (Event, Task, Out of office, Birthday). This is the sanctioned replacement for speed-dial mini-FAB stacks.
+- **Google Drive / Wallet** — oversized M3E "large FAB" for the hero action; **Clock / Pixel Screenshots** — rounded-square FAB variant. FAB shape/size is now an expression axis, position is not.
+- **Google Meet / Messages / Chat** — content in rounded "container" groupings (cards-as-list-sections), M3E's most visible signature.
+- **WhatsApp** — spent a decade on top swipe-tabs, then moved to a 4-tab bottom bar (Chats, Updates, Communities, Calls) + per-tab FAB (new chat, camera). Follows M3 structurally (bottom nav, FAB, rounded menus, M3 switches, Material ripple) but keeps brand green and **skips dynamic color**. Its Android and iOS builds now deliberately converge on structure while keeping components platform-native.
+- **Telegram** — the classic Android-divergent app: hamburger **drawer** navigation on Android vs bottom tabs on iOS. Almost entirely custom-drawn UI, yet deeply Android-native in behavior: system back everywhere (with predictive back support), themed monochrome icon, long-press context menus, in-chat haptic ticks, Android sharesheet. Proof that "custom skin, native skeleton" works.
+- **Spotify** — fully brand-custom (own dark surfaces, Circular type, zero M3 components, no dynamic color) with a 3-tab bottom bar (Home, Search, Your Library; a Create/Premium tab appears in some markets) + persistent now-playing bar docked above the nav bar. Still honors the skeleton: system back, edge-to-edge, adaptive icon, MediaStyle notifications, 48dp targets.
+- **Airbnb** — near pixel-identical cross-platform brand system, 5-tab bottom bar (Explore, Wishlists, Trips, Messages, Profile). Behaviors are swapped per platform: Android build uses system back, Android sharesheet, native date pickers in places, snackbar-style feedback.
+- **Revolut** — custom fintech design system, 5 bottom tabs, and *bottom sheets for nearly every action* (transfers, details, confirmations) — a house style that happens to be the most Android-idiomatic pattern available.
+
+**Takeaway:** nobody credible ships top-tab primary navigation anymore; everyone ships bottom bar + FAB; the drawer survives only as a secondary surface (labels, accounts, contact overflow). Brand-custom *visuals* are fine — brand-custom *behavior* (back, share, insets, targets) is not.
+
+## 2. FAB patterns
+
+- One FAB per screen, bottom-right, **16dp** from edges and above nav-bar insets. Standard **56dp**; M3E medium **80dp** / large **96dp** for hero actions; rounded-square variant acceptable.
+- The FAB is the screen's single most important **creative** action: compose, add, record, scan. It is never search, never filter, never navigation, never "more".
+- 2–6 related actions → **FAB menu** (FAB morphs into labeled pills, scrim behind, back dismisses). Never stack bare mini-FABs; never use a bottom sheet as a fake FAB menu.
+- Extended FAB (icon + label) at rest, collapsing to circular while scrolling (Gmail Compose). On expanded widths the FAB relocates into the navigation rail's top slot.
+- FAB may hide on scroll-down and return on scroll-up, but must never permanently cover content: lists under a FAB need ~**88–96dp** bottom content padding.
+- If a screen has no natural primary creation action, it gets no FAB. Symmetry is not a reason.
+
+## 3. Bottom sheets
+
+- Android's workhorse surface. Where iOS splits into action sheets, popovers, and half-modals, Android apps (Maps, Google Pay, Revolut, the sharesheet itself) use one component.
+- **Modal sheet** — one task or choice set:
+  - Drag handle **32×4dp** centered in a 48dp hit area; top corner radius **28dp**; scrim behind.
+  - Dismiss three ways, all mandatory: drag down, scrim tap, **system back** (predictive back animates the sheet down with the drag).
+  - First actionable element within thumb reach; primary CTA pinned above `ime`/nav insets.
+- **Standard (persistent) sheet** — the Maps pattern: collapsed peek (~72–120dp showing a title/summary) → half-expanded → full; content behind stays interactive. At full expansion it may morph into a full-screen surface with its own top app bar.
+- Rules: never stack sheets on sheets; a flow that outgrows one step becomes a full screen; sheet content scrolls internally only after the sheet is fully expanded.
+
+## 4. Search patterns
+
+- The M3 pattern: a **search bar** (pill in the app-bar slot) that expands into a **search view** — full-screen on compact — with recent queries and suggestions; predictive back collapses it back into the pill. Gmail, Keep, Chat, and Password Manager all adopted this in the 2025 M3E wave.
+- Search as a **destination** (Spotify, YouTube, Play Store): a bottom-nav tab whose screen leads with the search field plus browse/category content — use when discovery is a core loop.
+- Search as a **tool** (Contacts, Settings, Files): a magnifier icon action expanding in place — use when search is occasional.
+- Conventions: recent queries with per-row delete, live results where cheap, voice input affordance in Google-adjacent contexts, keyboard action = Search. One back press closes the keyboard; the next collapses the search view.
+
+## 5. Settings
+
+- Android settings are a **full-screen preference list**, not iOS inset-grouped tables: section headers (~14sp, primary color), rows 56–72dp with optional 24dp leading icon, title + supporting text, trailing M3 switch for toggles.
+- Row grammar (mirror system Settings): tap-through rows open sub-screens (← Up returns); toggle rows flip in place; **split rows** (tap to configure + independent switch) for enable-and-configure items.
+- Entry point: avatar menu or ⋮ overflow in the top app bar → Settings. Settings is never a bottom-nav destination.
+- Include the Android-expected set:
+  - **Notifications** — deep-link to system channel settings (`ACTION_APP_NOTIFICATION_SETTINGS`) rather than rebuilding toggles.
+  - **Theme** — System default / Light / Dark, defaulting to System.
+  - **Language** — per-app language (Android 13+ `LocaleManager`), surfaced both in-app and in system settings.
+  - Storage/data-saver controls where relevant.
+- Destructive account actions last, visually separated; About with version + open-source licenses at the bottom. Add settings search once the tree exceeds ~2 levels (Google-app standard).
+
+## 6. Android-specific patterns iOS designers miss
+
+1. **System back everywhere** — an OS-level gesture closes sheets, menus, dialogs, search, selection modes, and the keyboard. Every surface needs a defined back behavior; iOS only has explicit dismiss affordances, so ports routinely ship broken back.
+2. **Long-press is a first-class verb** — app icon → shortcuts (≈4, pinnable to home screen); list items → multi-select mode (checkboxes + contextual action bar with batch actions) rather than iOS swipe-to-delete; text → selection handles + context menu. Wherever iOS uses swipe rows or haptic-touch menus, Android expects long-press.
+3. **The sharesheet is bidirectional** — send via `Intent.createChooser` (direct-share contact targets, copy, nearby, your custom action row) and *receive* by registering intent filters so your app appears in other apps' sheets. iOS-first teams design only the outbound half, often as custom UI. Don't.
+4. **Overflow menu (⋮)** — the top app bar carries 2–3 icon actions; everything else lives in the trailing three-dot menu (M3E menus: bigger radius, grouped sections with gaps). Don't invent a "•••"-triggered bottom sheet for four text items.
+5. **Snackbar + UNDO** — the Android idiom for reversible actions: delete immediately, offer UNDO for ~4s. No confirmation dialogs for undoable operations.
+6. **Ripple feedback** — every touchable shows a ripple. Even fully custom apps (Spotify, Telegram) keep it; suppressing it makes an Android UI feel dead.
+7. **Home-screen presence** — widgets, themed icon, pinned shortcuts: Android users compose your app onto their launcher. This surface has no iOS design source; budget for it.
+8. **Per-tab state restoration** — leaving and re-entering a bottom tab restores its scroll position and stack (YouTube, Play Store). Resetting to root reads as data loss.
+9. **Intent interop** — "Open with", default-app roles, App Links from notifications/widgets/search: every content screen needs a stable deep-link route with a sane synthesized Up stack.
+10. **Predictive-back choreography** — surfaces shrink/slide *with the drag* (peek-and-cancel), not vanish on release. Cross-screen shared elements tracking the gesture are the current polish bar.
+11. **System pickers over custom ones** — photo picker (no storage permission), Credential Manager for sign-in (passkeys + Google sign-in in one sheet), system autofill. Custom equivalents now read as both lazy and invasive.
+12. **Custom Tabs, not embedded WebView chrome** — external links open in Chrome Custom Tabs themed to your app; a hand-rolled in-app browser with custom toolbar is an anti-pattern.
+
+## 7. Lists, content, and feedback conventions
+
+- **Pull-to-refresh** — M3 loading indicator (the M3E shape-morphing spinner) descending under the drag; only on feeds where new-at-top content actually arrives. Not a substitute for live updates.
+- **Swipe actions exist on Android too, but differently**: one action per direction, full-row swipe with a colored background + icon revealed (Gmail archive/delete pattern), always with an UNDO snackbar. Not iOS-style multi-button reveal stacks — multi-action belongs in long-press selection or the ⋮ row menu.
+- **Section grouping (M3 Expressive)** — list items grouped into rounded surface containers with small gaps between groups (Gmail, Messages, system Settings). This replaced full-bleed divider-separated lists as the modern Android look.
+- **Empty states** — illustration or large glyph + one-line explanation + the same action the FAB offers. Never a blank screen; never a spinner as a permanent resident.
+- **Loading** — prefer content-shaped placeholders (skeletons) for feeds, the M3 loading indicator for discrete waits, and determinate progress whenever length is knowable. Show cached content immediately and refresh behind it (offline-first is a core-quality expectation).
+- **Errors** — inline at the point of failure with a Retry affordance; snackbar for transient global failures; full-screen error state only when the whole destination is unusable.
+- **Selection** — long-press starts multi-select, tap extends it, count + batch actions in the contextual top bar, back exits. Checkbox avatars (tap avatar to select, Gmail-style) are the discoverability booster.
+
+## 8. Onboarding, permissions, and auth patterns
+
+- Top Android apps front-load value, not forms: WhatsApp = phone verify then straight into Chats; Spotify/Revolut ≤ 3 screens before content. Skippable everything, progress via dots or a progress bar — never a back-trap (system back must exit onboarding backwards).
+- **Permissions in context, one at a time**: camera permission when the user taps the camera, notifications after the first thing worth notifying about exists. Precede sensitive asks (location, contacts) with a one-screen rationale *only* when the benefit isn't obvious; handle "don't ask again" with a settings deep link, never a nag loop.
+- Use the **system photo picker** (no permission dialog at all) instead of requesting media/storage access — requesting broad storage now looks hostile and triggers Play review friction.
+- **Sign-in**: Credential Manager sheet (passkeys + saved passwords + Google sign-in unified) as the primary path; email forms as fallback with autofill hints set. Biometric re-auth (`BiometricPrompt`) for sensitive in-app actions — Revolut-style fintech UX expects it.
+- Account switching: avatar in the top app bar → account sheet (Google apps pattern), including on-avatar swipe-to-switch where multi-account is core.
+
+## 9. Follow-Material vs brand-custom: the decision grid
+
+| Layer | Follow M3 strictly | Brand-custom acceptable |
+|---|---|---|
+| Navigation structure (bar/rail, back, stacks) | Always | Never |
+| System surfaces (sharesheet, notifications, splash, IME, pickers) | Always | Never |
+| Insets, targets, ripple, state restore | Always | Never |
+| Components (buttons, sheets, dialogs, switches) | Default choice | OK with equal affordances (WhatsApp, Telegram) |
+| Color | Dynamic color for utilities/tools | Brand palette for brand-led apps (Spotify) — still via M3 roles, still dark-theme |
+| Typography | Roboto + M3 scale default | Brand font fine; keep sp units and 200% scaling |
+| Motion | M3 springs, shared axis, container transform | Brand motion OK if predictive back still tracks the finger |
+| Iconography | Material Symbols default | Custom set fine on the 24dp grid |
+
+Rule of thumb: the further a layer sits from *system interaction*, the more brand freedom you have. Visual skin: free. Component behavior: constrained. System behavior: zero freedom.
+
+## 10. Do / Don't
+
+**Do**
+- 3–5 bottom destinations; merge before adding a fifth (Phone by Google precedent)
+- FAB for the one primary creative action; FAB menu for a related cluster
+- Bottom sheets for choices and single-step tasks; promote to full screens beyond that
+- UNDO snackbars instead of confirm dialogs for anything reversible
+- Long-press → selection mode with a contextual action bar for batch operations
+- Dynamic color for tools and utilities; deliberate role-mapped brand palette otherwise
+- Test with 3-button navigation enabled — a large minority still uses it and it eats bottom space differently
+- Per-app language, 200% font scale, TalkBack pass on the top 5 flows
+- Real tablet layouts (rail + two-pane) — Play's large-screen tiers gate store placement
+
+**Don't**
+- Ship iOS "‹ Back" labels, centered-only titles, segmented controls, iOS switches, or SF Symbols on Android
+- Intercept back for "Are you sure you want to exit?" — predictive back breaks it, and on SDK 36 your legacy interception isn't even called
+- Use toasts for anything actionable or important; use dialogs for anything undoable
+- Put navigation in a FAB, or add FABs for symmetry
+- Build custom share UI or custom in-app browser chrome (sharesheet + Custom Tabs exist)
+- Lock portrait — Android 16 overrides restrictions on ≥ 600dp displays anyway
+- Half-adopt dynamic color (brand primary on wallpaper-tinted surfaces clashes randomly)
+- Rebuild system surfaces "for brand consistency" — users chose their launcher, keyboard, and wallpaper; respect it
+
+## 11. Anti-patterns (instant "iOS port" tells)
+
+1. **iOS back chevron top-left as the only exit** + broken system back — the #1 tell. Fix: ← Up in the app bar, predictive back on every surface.
+2. **Non-adaptive icon** — legacy square art shrunk into a white circle by the launcher; no monochrome layer, so themed home screens show it as the broken odd-one-out.
+3. **No dark theme / no dynamic-color decision** — a permanently white-branded screen inside a dark-themed OS.
+4. **Opaque status-bar strip or hardcoded 24dp inset** — a visible seam up top, content trapped above the gesture area below. Edge-to-edge is enforced at SDK 36; unhandled insets = overlapping UI, not a stylistic choice.
+5. **iOS action sheets and centered alerts with stacked full-width buttons** where Android expects bottom sheets and M3 dialogs (text buttons, bottom-right, confirm rightmost).
+6. **Custom splash activity with a 2–3s brand hold** — produces a double splash on Android 12+; ads or tips on launch are worse.
+7. **Toast-driven UX** — errors and confirmations that TalkBack users and anyone glancing away simply miss.
+8. **Tabs reset on return** — bottom destinations that lose scroll/stack when revisited read as data loss.
+9. **Stretched phone UI on tablets/foldables** — letterboxed portrait lock or 900dp-wide single-column forms; fails adaptive quality tiers and tanks tablet store placement.
+10. **`vibrate(100)` buzzes on taps** — semantic `HapticFeedbackConstants` or nothing.
+11. **Play screenshots with iOS chrome** (Dynamic Island, iOS status bar/keyboard) — credibility killer and policy risk.
+12. **One default notification channel for everything** — the first promo push gets your transactional messages blocked too.
+13. **Login walls before value + custom sign-in forms** — Android expects Credential Manager (passkeys/Google sign-in) and autofill-friendly fields.
+
+## 12. Motion & transition conventions (as top apps use them)
+
+- **Forward navigation** — shared-axis X (siblings/steps) or fade-through (bottom-tab switches). Container transform for card → detail (Play Store, Photos): the tapped surface *becomes* the next screen. No iOS push-from-right slides.
+- **Back navigation** — mirrors forward, but must track the predictive-back drag: scale-down + reveal for cross-screen, sheet-follows-finger for sheets, search view collapsing into its bar. Release-to-cancel must restore state losslessly.
+- **Bottom-tab switches** — fade-through (~200ms), never horizontal slides (tabs are peers, not a sequence); content swipe-between-tabs is reserved for secondary tabs within a destination.
+- **M3 Expressive motion** — spring-based (expressive/standard motion schemes) rather than duration curves: FAB → FAB menu morph, shape-morphing loading indicator, container grouping expand/collapse. Use springs for user-initiated spatial changes, plain fades for content refresh.
+- **List changes animate** — item add/remove/reorder with `animateItem`-style placement animation and the UNDO snackbar timed to match; instant list jumps read as glitches.
+- **Duration discipline** — small component changes ~100–200ms, screen transitions ~300–400ms, nothing user-blocking above ~500ms; honor "Remove animations" (reduced motion) by collapsing to fades.
+- **Brand motion** (Spotify's crossfades, Telegram's message pops, Revolut's card flips) layers *on top* of these skeleton transitions — it never replaces back-gesture tracking or state restoration.
+
+## 13. Quick reference numbers
+
+- Nav bar **64dp** (M3E flexible; classic 80dp) · indicator pill ≥ 56×32dp · icon 24dp · label 12sp
+- Nav rail **96dp** collapsed / ~220dp expanded · modal drawer ≤ 360dp · drawer/list row 56dp
+- Top app bar 64 / 112 / 152dp (small/medium/large) · FAB 56 / 80 / 96dp with 16dp margins
+- Touch targets ≥ **48×48dp** · sheet drag handle 32×4dp · sheet top radius 28dp
+- Breakpoints: **600dp** (bar→rail, phones end) · **840dp** (expanded, two-pane) · **1200dp** (large)
+- List bottom padding with FAB ≈ 88–96dp · readable text measure ≤ ~640dp
+- Settings rows 56–72dp · section headers ~14sp · overflow menu ⋮ after 2–3 app-bar actions
+- Snackbar duration ~4s (matches UNDO window) · tab-switch fade ~200ms · screen transition 300–400ms
+- Standard sheet peek ~72–120dp · notification small icon 24dp white-on-transparent
+- Minimum text 12sp, body 16sp, all type in sp · icons on the 24dp Material Symbols grid
+
+Cross-reference: dp specs and system rules in `android-app-design`; M3 color/shape/motion tokens in the Material 3 doc; iOS equivalents in `ios-app-design` for porting comparisons.

package/knowledge/patterns/mobile/auth-patterns.md

@@ -0,0 +1,69 @@
+---
+id: mobile-auth-patterns
+title: "Mobile Login & Social Sign-In Patterns"
+category: pattern
+platform: mobile
+tags: [auth, login, social-sign-in, sso, forms]
+sources:
+  - "https://mobbin.com/screens/3a993e71-e6d1-49bc-9451-495fca570e36"
+  - "https://mobbin.com/screens/faef2f5a-0953-470e-b56b-38a4c3ccd789"
+  - "https://mobbin.com/screens/08780534-efa2-4feb-a429-6bbb525e59aa"
+  - "https://mobbin.com/screens/7336baf0-22a8-4e07-be82-59bd383432a4"
+  - "https://mobbin.com/screens/62f02032-d47e-49ff-9bef-1424e97d00ac"
+  - "https://mobbin.com/screens/71bd698f-b9a5-4943-8f1f-1753ea918739"
+  - "https://mobbin.com/screens/f12af768-77c6-45cd-b71a-bce949365de4"
+updated: 2026-07-08
+---
+
+# Mobile Login with Social Sign-In (iOS)
+
+Based on real screens from Reddit, Balance, Strava, MyFitnessPal, Vocabulary, IMDb, and Airalo on Mobbin.
+
+## Observed patterns
+
+### Social-first layout (most common)
+- [Reddit](https://mobbin.com/screens/3a993e71-e6d1-49bc-9451-495fca570e36): close X top-left, "Sign up" link top-right, large "Log in" title, legal microcopy ("By continuing, you agree to our User Agreement and Privacy Policy") directly under the title, then three **identical outlined pill buttons** — brand icon left-aligned, label centered: "Continue with Google", "Continue with Apple", "Continue with Login Link". Below: an "OR" divider with hairlines, filled gray Username/Password fields (password has an eye toggle), a "Forgot password?" link, and a full-width "Continue" button at the bottom that sits **disabled (washed-out gradient)** until fields are valid.
+- [Strava](https://mobbin.com/screens/08780534-efa2-4feb-a429-6bbb525e59aa): nav bar with "< Back" and centered "Log In" title; Facebook button filled in brand blue on top, Google and Apple as white outlined buttons beneath — all full-width, same height, stacked with tight equal gaps; then a grouped Email/Password field pair and "Forgot Password".
+- [Airalo](https://mobbin.com/screens/f12af768-77c6-45cd-b71a-bce949365de4): presented as a **bottom sheet** with a Log in / Sign up segmented tab underline at the top. Social options are three compact **icon-only pills in a row** (Apple, Google, Facebook), followed by Email + Password outlined fields, "Forgot password", a disabled "Log in" pill, and a secondary "Log in with SSO" text link.
+
+### Email-first layout
+- [MyFitnessPal](https://mobbin.com/screens/7336baf0-22a8-4e07-be82-59bd383432a4): labeled Email/Password fields on top, a filled blue "Log In" button, "Forgot password?" link, then an "OR" divider and three white card-style social buttons (Google, Apple, Facebook) with icon + centered label. Reassurance microcopy at the very bottom: "We will never post anything without your permission."
+
+### Minimal / value-framed layout
+- [Vocabulary](https://mobbin.com/screens/62f02032-d47e-49ff-9bef-1424e97d00ac) frames sign-in as a benefit, not a gate: mascot illustration, headline "Keep your data safe", subcopy explaining that an account preserves favorites and settings across devices. Only two options: black "Sign in with Apple" pill first, white outlined "Sign in with Google" second. Legal microcopy in small centered gray text at the bottom.
+- [Balance](https://mobbin.com/screens/faef2f5a-0953-470e-b56b-38a4c3ccd789): three stacked full-width rectangles each filled with the provider's brand color (Apple black, Facebook blue, Email teal) — bold but visually noisy; the three competing brand colors give no clear primary.
+- [IMDb](https://mobbin.com/screens/71bd698f-b9a5-4943-8f1f-1753ea918739): "Returning customer?" heading over a uniform list of white rounded rows, each with a brand icon and left-aligned label (IMDb, Amazon, Google, Apple) — treating providers as a neutral choice list.
+
+### Cross-app constants
+- Social buttons are always **full-width (or equal-width), ~48–56pt tall, pill or 8–12pt rounded**, stacked vertically with equal spacing, and use the provider's official icon.
+- "Continue with X" / "Sign in with X" wording — never bare brand names.
+- Apple is always present and usually first or second (App Store requirement when third-party login is offered).
+- Email/password is positioned as the fallback below an "OR" divider (Reddit, MyFitnessPal, Strava, Airalo).
+- Legal agreement copy appears on the login screen itself, in small gray text near the title (Reddit) or the bottom (Vocabulary).
+
+## Design rules derived
+
+**Do**
+1. Offer 2–4 social providers max; include Sign in with Apple whenever any social login exists (App Store Review 4.8).
+2. Make every social button the same shape, width, and height; differentiate providers by icon + label, not by size.
+3. Use "Continue with [Provider]" labels — "Continue" works for both new and returning users.
+4. Give the recommended provider the only filled/high-contrast treatment (black Apple pill in Vocabulary); render the rest outlined.
+5. Separate social options from email/password with a hairline "OR" divider.
+6. Include: "Forgot password?" link near the password field, a show/hide eye toggle on password, and a route to the opposite mode (Sign up link in the nav or a tab pair like Airalo).
+7. Keep the email/password submit button disabled until inputs are plausibly valid, like Reddit and Airalo.
+8. Put agreement microcopy ("By continuing you agree to…") on the auth screen with linked Terms/Privacy.
+9. Add one line of trust reassurance when a provider raises privacy fears (MyFitnessPal's "We will never post anything without your permission").
+10. If auth is optional, frame it around the user's benefit ("Keep your data safe" — Vocabulary) and keep it skippable.
+
+**Don't**
+1. Don't fill every button with its provider's brand color (Balance) — the screen loses a visual hierarchy and a primary action.
+2. Don't hide email login entirely if your audience includes users without the offered social accounts.
+3. Don't use icon-only social pills (Airalo) unless space is critical; labels remove ambiguity and help accessibility.
+4. Don't place legal text where it interrupts the field → CTA flow; above the title or below the CTA are the observed safe zones.
+
+## Anti-patterns seen
+
+- **Brand-color soup** (Balance): three saturated brand-filled buttons of equal weight; no primary action, poor scalability when providers are added.
+- **Duplicate affordances** (Strava): "Log In" appears both as a disabled nav-bar button and as the implicit form action — two competing submit locations.
+- **Ultra-low-contrast disabled CTA** (Reddit): the disabled gradient "Continue" is so faint it can read as decorative; disabled states should stay legible.
+- **No sign-up escape hatch on screen** (IMDb, Balance): returning-user screens without a visible "create account" path strand new users behind the back button.

package/knowledge/patterns/mobile/checkout-payments.md

@@ -0,0 +1,77 @@
+---
+id: mobile-checkout-payments
+title: "Mobile Checkout & Payment Method Selection Patterns"
+category: pattern
+platform: mobile
+tags: [checkout, payments, ecommerce, forms, trust]
+sources:
+  - "https://mobbin.com/screens/b01088bd-226f-45fa-9f9e-1c990e3b1b76"
+  - "https://mobbin.com/screens/a4f7b96f-ff18-49ef-914a-9a9cff8c8a42"
+  - "https://mobbin.com/screens/5712cce4-8d52-4d29-bee9-ece6ca849b5c"
+  - "https://mobbin.com/screens/2a0f9220-30a0-4b1d-b122-88b3e49500d2"
+  - "https://mobbin.com/screens/b595b518-e339-44c9-86ca-83fd80a0184c"
+  - "https://mobbin.com/screens/b488d6f6-ce3d-4853-a0c1-15a4a4be3944"
+  - "https://mobbin.com/screens/229ed6f0-0414-4be4-b4d0-54395b56037c"
+updated: 2026-07-08
+---
+
+# Checkout with Payment Method Selection (iOS)
+
+Based on real screens from Zalando, Etsy, Woolworths, Warby Parker, UNIQLO, and Houzz on Mobbin.
+
+## Observed patterns
+
+### Step indication
+- [Zalando](https://mobbin.com/screens/b01088bd-226f-45fa-9f9e-1c990e3b1b76) shows a 5-node horizontal stepper under the nav bar: "Sign in ✓ — Address ✓ — Payment (3) — Confirm — Done!" with completed steps as checkmarks, the current step as a filled numbered circle, and future steps grayed.
+- [Etsy](https://mobbin.com/screens/5712cce4-8d52-4d29-bee9-ece6ca849b5c) uses a lighter 3-dot stepper (Shipping ✓ — Payment ● — Review ○) beneath a "Cancel | Checkout" nav bar.
+- [Woolworths](https://mobbin.com/screens/2a0f9220-30a0-4b1d-b122-88b3e49500d2) shows pill steps with green checks (Details ✓ Products ✓ Summary ✓ | 4 Pay), and [Houzz](https://mobbin.com/screens/229ed6f0-0414-4be4-b4d0-54395b56037c) simply titles the screen "2 of 3: Billing & Payment". Every app tells the user where they are and what remains.
+
+### Payment method selection = radio list with brand logos
+- Etsy: "Choose a payment method" section header, then radio rows — "Card" with Visa/Mastercard/Amex/Discover logos right-aligned, "Pay with PayPal" + PayPal wordmark, "Pay with Apple Pay" + Apple Pay mark. One radio row per method; logos always trail on the right.
+- [Zalando (payment step)](https://mobbin.com/screens/b01088bd-226f-45fa-9f9e-1c990e3b1b76): filled black radio for the selected "PayPal" with an inline explanation underneath ("You'll be forwarded to PayPal to complete your payment"); the "Credit/Debit Card" row shows the four network badges. Zalando's [saved-card variant](https://mobbin.com/screens/a4f7b96f-ff18-49ef-914a-9a9cff8c8a42) nests a masked saved Visa card (blurred number, trash icon to delete) plus a "New Credit or Debit Card" radio under the card method — method first, instrument second.
+- [Warby Parker](https://mobbin.com/screens/b595b518-e339-44c9-86ca-83fd80a0184c) strips it to a single white card: question-style headline ("How do you want to pay?") with "Order total: $120" directly under it, two radio rows (card / PayPal) with trailing glyphs, a separate "(+) Check and apply benefits" row, and a full-width blue "Review your order" pill.
+- [UNIQLO](https://mobbin.com/screens/b488d6f6-ce3d-4853-a0c1-15a4a4be3944) uses numbered sections ("2. Payment option") with big outlined selectable rows (Credit card / PayPal / Apple Pay) — same list idea, checkbox-free tap-to-select rows.
+
+### Unavailable options stay visible, with the reason
+- Etsy grays out Klarna and prints the rule inline: "$50.00 product minimum applies" + Klarna badge. The option is discoverable but clearly not tappable.
+
+### Order summary + CTA
+- Zalando places a gray summary block (Subtotal £7.97 / Delivery £3.99 / **Total VAT included £11.96**) directly above a full-width black "Next" button, with the note "You can review and confirm your order in the next step."
+- Woolworths uses a **sticky bottom bar**: expandable "Total (Incl. GST) $34.00" on the left, "Place Order" button right — the button rendered disabled until the payment step is valid.
+- The total is always visible on the same screen where a payment decision is made (Warby Parker puts it right in the header).
+
+### Trust and support signals
+- Etsy: "You will not be charged until you review this order on the next page" under the section title.
+- UNIQLO: a security footnote ("We protect all your sensitive information with TLS encryption technology") and an embedded help entry ("Having issues with checkout? IQ chat can help").
+- Zalando/Etsy: voucher & gift card entry lives in its own labeled section with chevron rows, kept out of the payment radio list.
+- Every screen keeps an exit: X (Zalando), "Cancel" (Etsy, Woolworths), or back chevron (Houzz, UNIQLO).
+
+### Card entry (when chosen)
+- Houzz shows inline card fields: labeled inputs with red asterisks for required (Name on Card, Card Number with network icons that light up as detected, MM/YY dropdowns, Security Code with a CVV hint illustration) — labels above fields, one column.
+
+## Design rules derived
+
+**Do**
+1. Show a stepper (checkmark for done, highlighted current, gray future) or an "N of M" title on every checkout screen.
+2. Present payment methods as a single-select radio/tap list — one row per method, method name left, brand logos right-aligned.
+3. Nest saved instruments (masked card + delete) under their method; default-select the user's last-used or saved option.
+4. Keep unavailable methods visible but disabled with the reason inline (Etsy/Klarna pattern).
+5. Show the order total on the payment screen — either a summary block above the CTA (Zalando) or a sticky bottom bar with total-left, CTA-right (Woolworths).
+6. Label the CTA by what happens next: "Next" / "Review your order" when a review step follows; "Place Order" only on the final commit, and disable it until valid.
+7. Add a no-surprise line ("You won't be charged until you review…") whenever the CTA does not immediately charge.
+8. Offer Apple Pay as a first-class listed method on iOS.
+9. Separate promo/gift-card entry into its own section — never as a competing field inside the payment list.
+10. For card forms: labels above fields, required markers, network auto-detection, and a CVV location hint.
+
+**Don't**
+1. Don't hide the total behind a later step; price uncertainty is the top abandonment driver and every strong screen surfaces it.
+2. Don't use brand logos as the tap target by themselves — the row label carries the meaning, logos are recognition support.
+3. Don't remove the escape hatch; Cancel/X was present in all seven screens.
+4. Don't mix selection paradigms on one screen (radios + tappable cards + toggles).
+
+## Anti-patterns seen
+
+- **Redirect surprise**: sending users to PayPal without warning; Zalando neutralizes it with the inline "You'll be forwarded…" note — omit that note and trust drops.
+- **Long single-scroll payment + address + billing forms** (Houzz): stacking card entry and full billing address on one screen makes the CTA fall far below the fold; the stepper-split apps read as lighter.
+- **CTA below the fold** (Zalando's second variant): when the summary grows (vouchers, saved cards), "Next" slips off-screen — the sticky bottom bar (Woolworths) is the safer construction.
+- **Dropdowns for expiry date** (Houzz MM/YY selects): slower than a masked text input with auto-advance on mobile.

package/knowledge/patterns/mobile/empty-states-buttons.md

@@ -0,0 +1,80 @@
+---
+id: mobile-empty-states-buttons
+title: "Mobile Empty States & Bottom Primary Button Patterns"
+category: pattern
+platform: mobile
+tags: [empty-state, illustration, cta, buttons, primary-action]
+sources:
+  - "https://mobbin.com/screens/763e2666-87c9-41d6-a155-c13d050a18db"
+  - "https://mobbin.com/screens/9a3f8ab3-581b-4995-9fd0-65fa1f091fb7"
+  - "https://mobbin.com/screens/c041a22d-8521-4351-8a41-18892e7e795c"
+  - "https://mobbin.com/screens/15181740-6713-4946-b348-777d27483d2f"
+  - "https://mobbin.com/screens/7e5f69c8-bf8b-4a66-99dc-c811a1aeded7"
+  - "https://mobbin.com/screens/1ecb8058-f083-42c9-980a-ae3eb46e3eab"
+  - "https://mobbin.com/screens/66f2bada-95e8-483f-a261-8f3cb8a9c135"
+  - "https://mobbin.com/screens/ae92be67-4594-414c-886d-9cf56f0cf30e"
+  - "https://mobbin.com/screens/860f329c-21e8-476d-8e4d-d232aa8e1c7a"
+  - "https://mobbin.com/screens/bd5ce18a-a93a-44ea-a69e-f2b41207605c"
+  - "https://mobbin.com/screens/3066c4ce-b6c8-4ee5-ac94-6d81a4d1cc2e"
+  - "https://mobbin.com/screens/706d47e1-6f7c-4318-bb98-927e66bb744d"
+  - "https://mobbin.com/screens/f230bb20-7010-4c79-9a3f-4cef18995b31"
+  - "https://mobbin.com/screens/dcf90bfd-070e-42cf-967a-1853377516f4"
+updated: 2026-07-08
+---
+
+# Empty States & Bottom Primary Actions (iOS)
+
+Based on real screens from Collect, Shake Shack, Lex, Coursera, Grab, Demo, Shop, Greg, Google Gemini, Apple Wallet, Weverse, Deepstash, and Snapchat on Mobbin.
+
+## Observed patterns — empty states
+
+### The universal 4-part stack (vertically centered)
+Illustration → bold headline → 1–2 line gray explanation → single CTA.
+- [Grab](https://mobbin.com/screens/1ecb8058-f083-42c9-980a-ae3eb46e3eab): character illustration, bold "No restaurant bookings yet", gray subcopy ("Explore top dining spots in your city and make a booking instantly!"), full-width green pill "Explore dining spots".
+- [Coursera](https://mobbin.com/screens/7e5f69c8-bf8b-4a66-99dc-c811a1aeded7): simple line-art book icon over a soft blue blob, "You haven't enrolled in any courses (yet)", explanation, compact blue "Explore courses" button — centered, hugging its label.
+- [Shake Shack](https://mobbin.com/screens/c041a22d-8521-4351-8a41-18892e7e795c): brand-voice headline "Say what?! Your bag is empty." with a stick-figure illustration in brand green on black, and a full-width green "Find a Location" CTA.
+- [Lex](https://mobbin.com/screens/15181740-6713-4946-b348-777d27483d2f) frames the whole empty state inside a rounded card: mascot, "No saved posts", "You haven't saved any posts yet! Your saved posts will show up here.", small green "Go to feed" button.
+
+### CTA routes to the filling action
+Every observed CTA sends the user to the place where the empty collection gets filled — "Find a Location" (bag), "Explore courses" (enrollments), "Go to feed" (saved posts), "Explore dining spots" (bookings). None say generic "Get started".
+
+### FAB + coach-mark variant
+- [Collect's board view](https://mobbin.com/screens/763e2666-87c9-41d6-a155-c13d050a18db): "Looks a little empty in here / Tap the + to get started" with an orange tooltip bubble ("Tap to add content to this board") pointing directly at the orange "+" FAB. Its [My items screen](https://mobbin.com/screens/9a3f8ab3-581b-4995-9fd0-65fa1f091fb7) repeats the pattern with a blue tooltip and FAB.
+- [Demo](https://mobbin.com/screens/66f2bada-95e8-483f-a261-8f3cb8a9c135): serif "Next up" headline, "To create your first project, just tap the '+' button below", coral "+" FAB centered at the bottom. When the creation control already exists on screen, the empty state teaches it rather than duplicating it.
+
+### Tone and craft
+- Headlines are short, human, and often optimistic ("(yet)" — Coursera; "Say what?!" — Shake Shack). Illustrations are brand-styled (mascots for Lex/Collect, brand-line-art for Shake Shack, human characters for Grab) — never generic stock clip-art. Explanations always say what *will* appear here.
+
+## Observed patterns — primary action at bottom of screen
+
+- **Full-width anchored pill**: [Weverse](https://mobbin.com/screens/706d47e1-6f7c-4318-bb98-927e66bb744d) pins a teal "Start Subscription" pill at the bottom, and it activates only after the "I have reviewed…" checkbox above it is ticked. [Deepstash](https://mobbin.com/screens/f230bb20-7010-4c79-9a3f-4cef18995b31) anchors a dark full-width "Continue" pill inside a bottom sheet. [Snapchat](https://mobbin.com/screens/dcf90bfd-070e-42cf-967a-1853377516f4) uses a slightly inset blue pill "📎 Attach to Snap" centered above the home indicator.
+- **Compact corner pill for contextual actions**: [Google Gemini](https://mobbin.com/screens/bd5ce18a-a93a-44ea-a69e-f2b41207605c) puts a small blue "✓ Attach" pill bottom-right over dark content; [Greg](https://mobbin.com/screens/860f329c-21e8-476d-8e4d-d232aa8e1c7a) puts "Post ↑" bottom-right of a camera view; [Shop](https://mobbin.com/screens/ae92be67-4594-414c-886d-9cf56f0cf30e) ends a media toolbar with a purple "Next" pill on the right. Corner placement = "proceed with this content", full-width = "commit to this screen's single purpose".
+- **Paired decision**: [Apple Wallet](https://mobbin.com/screens/3066c4ce-b6c8-4ee5-ac94-6d81a4d1cc2e) closes a terms sheet with "Disagree" as a gray/secondary pill on the left and "Agree" as the filled blue pill on the right — primary right, equal heights, both above the home indicator.
+- Buttons keep high contrast against any content behind them (blue-on-black Gemini, white-on-dark Shop) and add an icon when the verb alone is ambiguous (📎 Attach, ✓, ↑).
+
+## Design rules derived
+
+**Do**
+1. Build empty states as: brand illustration → ≤6-word bold headline → 1–2 line gray explanation of what will live here → exactly one CTA.
+2. Name the CTA after the filling action and route straight there ("Explore courses", not "OK" or "Get started").
+3. If the screen already has a create control (FAB, "+"), point at it with a one-time coach-mark tooltip instead of adding a second button.
+4. Vertically center the stack; keep the illustration under ~40% of screen height so headline + CTA never fall below the fold.
+5. Write in the product's voice and allow warmth ("(yet)") — the empty state is a first impression, not an error.
+6. Anchor a screen's single commit action as a full-width pill (~50–56pt tall, 16–20pt side margins) above the home-indicator safe area.
+7. Use compact corner pills only for contextual "proceed" actions layered over content (camera, preview, media).
+8. Gate irreversible CTAs on explicit acknowledgment (Weverse's checkbox → enabled button), and show the disabled state clearly.
+9. In two-button decisions, put the primary filled button on the right and the secondary as gray/ghost on the left, equal height (Apple Wallet).
+10. Guarantee button contrast over any backdrop — solid fills or a scrim, never text-only floating on imagery.
+
+**Don't**
+1. Don't stack multiple CTAs in an empty state — one action, one destination.
+2. Don't use generic stock illustrations that ignore the brand's palette and style.
+3. Don't phrase emptiness as failure ("Nothing found", "No data") when the state is expected for new users.
+4. Don't float a full-width primary button over scrollable legal/reading content without a scrim or edge — it will obscure the last lines (see Apple Wallet's terms text running beneath its buttons).
+
+## Anti-patterns seen
+
+- **Buttons overlapping content** ([Apple Wallet terms sheet](https://mobbin.com/screens/3066c4ce-b6c8-4ee5-ac94-6d81a4d1cc2e)): Disagree/Agree float over the final lines of the terms text with no gradient scrim — the content is partially unreadable at the decision point.
+- **Explaining instead of doing** (Demo): the empty state says "tap the '+' button below" in prose; the Collect tooltip-pointing-at-FAB version is faster to parse.
+- **Dead-feeling blank canvases** (Shop's editor): a nearly blank screen whose only guidance is a toolbar; pairing it with a first-run hint would remove the "now what?" moment.
+- **Icon-only floating actions on busy imagery** (Greg's camera overlay): small labels over a live photo need heavier scrims to stay legible.

package/knowledge/patterns/mobile/navigation-home.md

@@ -0,0 +1,78 @@
+---
+id: mobile-navigation-home
+title: "Mobile Home Feed & Bottom Tab Navigation Patterns"
+category: pattern
+platform: mobile
+tags: [navigation, tab-bar, home-feed, cards, skeleton-loading]
+sources:
+  - "https://mobbin.com/screens/27c8555f-f63a-40f5-b83f-ab2c62472421"
+  - "https://mobbin.com/screens/857360ff-cae6-4b2c-a198-9929531590ec"
+  - "https://mobbin.com/screens/5da431f9-f050-424c-92b9-40522bb7cccb"
+  - "https://mobbin.com/screens/cae51397-2fa9-4e28-9426-ee99b8cfe395"
+  - "https://mobbin.com/screens/07a2eeb8-1f5f-46d9-bbba-f8c56a989025"
+  - "https://mobbin.com/screens/53fd138d-3c0b-4832-824b-657e6563e36b"
+  - "https://mobbin.com/screens/ecf0ad43-2bdc-4950-af5d-774b414a4a48"
+updated: 2026-07-08
+---
+
+# Home Feed with Bottom Tab Navigation (iOS)
+
+Based on real screens from Reddit, Medium, BuzzFeed, and Neverthink on Mobbin.
+
+## Observed patterns
+
+### Tab bar anatomy
+- [BuzzFeed](https://mobbin.com/screens/07a2eeb8-1f5f-46d9-bbba-f8c56a989025) runs the classic 5-tab bar: Home, News, Shopping, Quizzes, Search — outline icons **with text labels**, active tab tinted in the brand gradient/purple, inactive tabs gray, on a white bar above the home indicator.
+- [Medium](https://mobbin.com/screens/cae51397-2fa9-4e28-9426-ee99b8cfe395) uses 4 icon-only tabs (home, search, bookmarks, profile avatar); the active tab is the filled icon variant, inactive are outlines. Its [dark-mode home](https://mobbin.com/screens/857360ff-cae6-4b2c-a198-9929531590ec) keeps the identical structure — tab bar sits on the dark surface with the same filled/outline logic.
+- [Reddit](https://mobbin.com/screens/27c8555f-f63a-40f5-b83f-ab2c62472421) uses 5 icon-only tabs with a **center "+" create tab**; active = filled black glyph.
+- [Neverthink](https://mobbin.com/screens/ecf0ad43-2bdc-4950-af5d-774b414a4a48) reduces to 3 tabs (profile, grid/browse, favorites) with the middle browse tab active in cyan — viable only because the app has very few top-level areas.
+- Home/primary feed is always the **first (leftmost) tab and the launch tab**.
+
+### Header zone above the feed
+- Medium: large-title "Home" top-left with a notification bell top-right (bell carries a green unread dot in dark mode).
+- Reddit: compact header with avatar (status-dotted) left, full-width search field center, coin/reward icon right.
+- BuzzFeed: centered brand logo, settings gear left, "Sign In" text button right.
+- The header scrolls away or condenses; the tab bar never moves.
+
+### Second-level navigation: horizontal chips/tabs under the header
+- Medium's [light feed](https://mobbin.com/screens/cae51397-2fa9-4e28-9426-ee99b8cfe395): a horizontally scrollable chip row — leading "+" chip to add topics, "For you" as a filled dark pill (selected), "Following" and topic chips ("Immigration") as light gray pills.
+- Reddit: text tabs "News · Home · Popular" with an underline indicator on the active one.
+- BuzzFeed: scrollable underline tabs ("Recently Viewed, Latest, Trending, …") including a yellow "NEW" badge chip; its [quiz feed](https://mobbin.com/screens/53fd138d-3c0b-4832-824b-657e6563e36b) shows the same strip scrolled mid-list (Health, LGBTQ, Music…), with the active item underlined in purple.
+- This chip/underline strip is the standard way to fork one feed into personalized/temporal variants without new tabs.
+
+### Feed content layout
+- Medium's list cell: author byline row (tiny avatar + name + publication) → bold 2–3 line headline → gray metadata row (date, read time) → small square thumbnail right-aligned; bookmark and overflow "…" actions per cell. Text leads, image supports.
+- BuzzFeed uses a 2-column card grid: large image on top, headline below, category badge ("QUIZ") overlaid on the image corner.
+- Medium (dark) shows a green circular **compose FAB** floating above the tab bar, bottom-right — creation kept out of the cell layout.
+- Neverthink uses a full-bleed media player pinned top with a channel grid beneath — feed-as-player variant.
+
+### Loading states
+- Medium's [skeleton screen](https://mobbin.com/screens/5da431f9-f050-424c-92b9-40522bb7cccb) mirrors the real cell geometry exactly: gray avatar circle, headline bars, thumbnail block — header, chip row, and tab bar all render immediately.
+- BuzzFeed's skeleton does the same with gray card blocks in the grid; Reddit shows a centered branded spinner with chrome (search, tabs, tab bar) already interactive. Skeletons that preserve layout read as faster than spinners.
+
+## Design rules derived
+
+**Do**
+1. Use 3–5 bottom tabs; put the primary feed first and land there on launch.
+2. Pair icons with labels unless the icons are unambiguous (home, search, profile); when going icon-only, use filled-vs-outline plus tint to mark the active tab.
+3. Keep the tab bar persistent and stationary; scroll or collapse the header instead.
+4. Reserve the tab bar for top-level destinations; feed variants (For you / Following / topics) belong in a horizontal chip or underline-tab row directly under the header.
+5. Make the selected chip visually inverted (filled dark pill vs light gray pills, per Medium) — underline alone is weak at chip size.
+6. In feed cells, lead with the headline; keep thumbnails small and right-aligned for text-first content, or use image-top card grids for visual content.
+7. Give every cell a metadata line (source, time, engagement) in ~12–13pt gray, and an overflow "…" for per-item actions.
+8. Put creation behind a FAB (Medium) or a dedicated center tab (Reddit) — never buried in a menu if it's the core action.
+9. Ship skeleton screens matching the final layout; render header, chips, and tab bar instantly while content loads.
+10. Badge sparingly: a small dot on the bell (Medium) or one "NEW" chip (BuzzFeed) — single-point notifications, not counts everywhere.
+
+**Don't**
+1. Don't exceed 5 tabs or hide tabs behind a "More" item at this nav level.
+2. Don't move top-level destinations into the chip row or vice versa — the two rows have distinct jobs.
+3. Don't block the whole screen with a spinner when chrome could already be interactive (Reddit's spinner is the weakest loading pattern seen here).
+4. Don't mix underline tabs and pill chips in the same strip; pick one selected-state language.
+
+## Anti-patterns seen
+
+- **Unlabeled ambiguous tabs** (Neverthink): a grid icon and heart with no labels force guessing; fine at 3 tabs, hostile at 5.
+- **Auth action stranded in the header** (BuzzFeed's "Sign In" top-right): easy to miss; sign-in prompts convert better contextually (on save/comment attempts).
+- **Chip row overflow with no affordance** (BuzzFeed): the category strip cuts off mid-word ("Coronavi…") — acceptable, but only because truncation itself signals scrollability; avoid ending strips exactly at a chip boundary.
+- **Spinner-only first paint** (Reddit): perceived load time is worse than skeleton equivalents in the same corpus.

package/knowledge/patterns/mobile/onboarding-paywall.md

@@ -0,0 +1,85 @@
+---
+id: mobile-onboarding-paywall
+title: "Mobile Onboarding & Paywall Patterns"
+category: pattern
+platform: mobile
+tags: [onboarding, paywall, conversion, personalization, free-trial, subscription]
+sources:
+  - "https://mobbin.com/flows/7ffbd4f0-78d1-49be-bf0d-9c90cac00e8c"
+  - "https://mobbin.com/flows/2959b3ec-3a19-475e-82b4-47762857b3a4"
+  - "https://mobbin.com/flows/5df9112e-cba3-41a0-bad1-cf6ea08161e6"
+  - "https://mobbin.com/flows/744ab3a0-fb8c-4d6c-83c3-e4389eeb9916"
+  - "https://mobbin.com/flows/43df4d6b-29ef-484e-98bc-2164e5c193b7"
+  - "https://mobbin.com/flows/f04eeefd-deae-48eb-b2af-cb249490247a"
+  - "https://mobbin.com/flows/afe2cc2a-7672-43f7-b75c-15c1ff369a52"
+  - "https://mobbin.com/flows/97217110-f239-4169-a82b-e92df6c3b23b"
+  - "https://mobbin.com/flows/671e3f4d-bd4d-4d0e-b229-fec56d4e215f"
+  - "https://mobbin.com/flows/d55019e6-7b8a-4bbd-bc64-7682bb183689"
+  - "https://mobbin.com/flows/e6e28fb7-a294-4b88-b03e-1617e967e47b"
+  - "https://mobbin.com/flows/aa956b58-fb2c-40b5-a9af-ca313fb252ba"
+updated: 2026-07-08
+---
+
+# Mobile Onboarding & Paywall Patterns (iOS)
+
+Based on real flows from Brilliant, Nibble, UNIQLO, Wanderlog, Vocabulary, Alma, Apple News, CapWords, Jobber, and bless. on Mobbin.
+
+## Observed patterns — personalization onboarding
+
+### Structure: one question per screen, thin progress bar on top
+- [Brilliant's onboarding](https://mobbin.com/flows/7ffbd4f0-78d1-49be-bf0d-9c90cac00e8c) uses a back chevron + slim green progress bar pinned to the top of every question screen. Each screen asks exactly one question ("How will learning fit into your day?") with 3–5 full-width rounded option cards, each prefixed by a small emoji/icon and a **bolded key phrase** followed by lighter descriptive text.
+- [Nibble](https://mobbin.com/flows/5df9112e-cba3-41a0-bad1-cf6ea08161e6) does the same: thin green progress line, a "← Back" pill, an emoji + bold question headline top-left, and stacked white rounded option cards ("Male / Female / Other" with emoji). Multi-select questions show trailing checkboxes and instruction copy ("Choose up to 3 topics max").
+- [UNIQLO](https://mobbin.com/flows/744ab3a0-fb8c-4d6c-83c3-e4389eeb9916) shows an explicit step counter ("1 / 3") centered in the nav bar with a "Skip" link at top-right. Category selection is a wrap-grid of outlined chips; selected chips get a heavier border.
+- [Wanderlog](https://mobbin.com/flows/43df4d6b-29ef-484e-98bc-2164e5c193b7) uses a centered large question headline over stacked emoji-prefixed option cards on a soft gradient background, with "Skip" at top-right.
+
+### CTA behavior
+- The primary CTA is a full-width pill button pinned at the bottom (purple for Nibble, near-black for Brilliant and UNIQLO). It renders **disabled (gray)** until a valid selection is made — seen identically in Brilliant, Nibble, and UNIQLO.
+- Vocabulary enforces "Select at least one option to continue" as helper text under the headline in its [goal-selection step](https://mobbin.com/flows/f04eeefd-deae-48eb-b2af-cb249490247a).
+
+### Motivation interstitials between questions
+- Wanderlog inserts an affirmation screen: "We like the way you travel! We'll use your answers to personalize your trips" — telling users *why* they answered questions.
+- Brilliant shows "You'll fit right in" with playful illustration and social-proof copy before asking for account creation.
+- [Nibble's setup flow](https://mobbin.com/flows/2959b3ec-3a19-475e-82b4-47762857b3a4) inserts a testimonial screen ("People love Nibble") with 5-star review speech bubbles before the paywall.
+
+### Permission priming
+- Both Nibble and UNIQLO show a **pre-permission screen** before the iOS notification prompt: a benefit-led headline ("Remember 3x more new information with visual learning" — Nibble; "Turn on push notifications to receive the latest news" — UNIQLO) plus a mock notification card or illustration. UNIQLO pairs a filled "CONTINUE" with an outlined "SKIP" of equal size.
+
+### Account creation placed late
+- Brilliant asks for the account only *after* the questionnaire: "Create a free account to discover your personalized learning path" — three icon-only pill buttons (Apple, Google, Facebook), a black "Continue with email" pill, and "Existing user? Log in" at the bottom.
+- Vocabulary defers sign-in even further, letting users pick app icon, goals, and see a word before any account step.
+
+## Observed patterns — paywalls
+
+- [Alma's paywall](https://mobbin.com/flows/afe2cc2a-7672-43f7-b75c-15c1ff369a52) is the canonical layout, top to bottom: close X (top-right), app icon, serif headline ("Get the full Alma experience"), reassurance line ("Try free for 7 days. Cancel anytime."), star rating + review count, a checklist card of 5 concrete benefits, two plan cards (Yearly with "17% OFF" badge and check preselected vs Monthly), a full-width dark-green CTA ("Get started for free"), then a footer row of small links: Restore Purchases · Terms · Privacy · Redeem.
+- [Brilliant](https://mobbin.com/flows/7ffbd4f0-78d1-49be-bf0d-9c90cac00e8c) uses the **trial-timeline pattern**: a vertical stepper ("Today: Get Premium access → Day 5: Trial reminder → Day 7: Trial ends") that defuses trial anxiety, plus anchored pricing with strikethrough ("~~$197.98~~ S$164.98 per year ($13.74 per month)") and a "Special discount applied" badge above a green "Start your 7-day free trial" pill.
+- [CapWords](https://mobbin.com/flows/d55019e6-7b8a-4bbd-bc64-7682bb183689) puts two plan cards side by side with a "✱ Best Value ✱" badge on the free-trial option (preselected), an award credential ("Apple Design Award 2025 Winner"), a benefit checklist, a gradient CTA, and the exact renewal terms as fine print directly under the button ("Try 3 days free, then S$19.98/year"). Confetti plays on success.
+- [Apple News+](https://mobbin.com/flows/97217110-f239-4169-a82b-e92df6c3b23b) presents the paywall as a modal sheet with a wall of recognizable publication logos as social proof and the auto-renew price ("Plan auto-renews for $12.99/month until canceled") in small gray text *above* the red "Get Started" CTA.
+- [Jobber](https://mobbin.com/flows/e6e28fb7-a294-4b88-b03e-1617e967e47b) uses horizontally swipeable plan cards with per-plan feature checklists; [bless.](https://mobbin.com/flows/aa956b58-fb2c-40b5-a9af-ca313fb252ba) shows a benefit checklist over branded artwork and swaps the CTA to "You're already subscribed!" for active subscribers.
+
+## Design rules derived
+
+**Do**
+1. Ask one question per screen; show progress (thin bar or "1/3" counter) and a back affordance on every step.
+2. Render answers as full-width rounded cards (~56pt tall, 16pt side margins) with an emoji/icon prefix and the key phrase bolded; use chip grids only for many short multi-select options.
+3. Keep the primary CTA a full-width pill pinned to the bottom safe area; disable it until the step is valid.
+4. Offer "Skip" (top-right, low-emphasis text) on any question that isn't strictly required.
+5. Insert a "here's what your answers unlock" interstitial before asking for account or payment — connect effort to value.
+6. Prime notification permission with a benefit-led custom screen before the system dialog, and give Skip equal visual weight to Continue.
+7. On paywalls: close X top-right, benefit checklist (concrete outcomes, not features), 2 plan options max with the preferred one preselected and badged ("Best Value" / "% OFF"), one CTA, and Restore Purchases + Terms + Privacy links.
+8. State the full renewal price and trial length in plain text adjacent to the CTA (Brilliant, CapWords, Apple News all do this).
+9. Use a trial timeline (Day 0 / reminder / charge date) for free trials — it is the strongest anxiety-reducing pattern observed.
+10. Add social proof near the purchase decision: star rating + review count (Alma), testimonials (Nibble), logo wall (Apple News), or award badges (CapWords).
+
+**Don't**
+1. Don't ask for account creation before the personalization questionnaire — every strong flow defers it.
+2. Don't enable the CTA before a selection exists; silent no-op taps erode trust.
+3. Don't present more than ~2 pricing options on mobile; Jobber's horizontally scrolled multi-plan cards force pogo-sticking.
+4. Don't hide the paywall dismiss affordance or delay its appearance.
+5. Don't fire the iOS notification permission dialog cold, without a priming screen.
+
+## Anti-patterns seen
+
+- **Wall-of-legalese above the CTA** (CapWords second screen): a long gray paragraph of subscription terms pushes the CTA down and gets skipped; keep a one-line disclosure and link the rest.
+- **Questionnaire length creep**: Vocabulary's 21-screen onboarding works only because each step is trivially fast; anything slower at that length would bleed users.
+- **Low-contrast "Cancel"** (CapWords): the dismiss label is faint gray on a light gradient — technically present, practically hidden. Borderline dark pattern.
+- **Truncated legal text mid-scroll** (Jobber): terms cut off behind the tab bar with no scroll affordance.