Shopify Embedded App: First-Run Onboarding UX

Onboarding is the single highest-leverage screen in your app. A merchant who never reaches "aha" within their first session uninstalls inside 7 days at rates of 40-60% across the App Store. The goal of this skill is to get every merchant to one observable, on-store value moment in under 5 minutes, with zero theme code edits and zero credit-card friction.

This skill is opinionated. It is built on (1) the Shopify Built for Shopify requirements, (2) the Polaris onboarding guidance, (3) a teardown of 6 top-grossing apps (Klaviyo, Gorgias, Judge.me, Loox, Vitals, PageFly).

1. When to use

Pull this skill in when you are:

• Designing the welcome screen / first-run flow of a brand new Shopify embedded app
• Reworking an existing app's activation funnel because installs are not converting to paid
• Adding a "setup guide" or "getting started checklist" to an existing dashboard
• Deciding whether to gate the app behind a wizard or drop merchants into a tile-grid
• Pursuing the Built for Shopify badge (which has explicit onboarding requirements)
• Writing the empty state for the merchant's first visit before any data exists
• Auditing your own app and asking "why is our 7-day retention so bad"