The first screen of our first mini-program had four bullet points, a two-step tutorial overlay, and a sign-up card before the actual menu. We thought we were being generous. The numbers argued back: a large share of people who landed there never reached the menu at all.

In a native app, that kind of front door is survivable. Someone just downloaded you, so they came in expecting a setup ritual — account, permissions, a tour of the tabs. A mini-program sits inside a host the user already trusts and already uses. They didn't come for you; they came for a ride, a bill, a coupon. The moment you start explaining yourself, you're spending attention they didn't agree to give.

Why the door is narrower here

A web or native app earns a few seconds of patience by virtue of the install. A mini-program gets none. The host hands you a cold start, a loading spinner, and a user whose thumb is already moving. If the first thing they meet is a wall of intent, the back gesture is one swipe away and it costs them nothing.

So the instinct to over-explain is doubly dangerous here. We've watched teams pour a value proposition, a feature carousel, and three permission prompts into the first view, convinced that clarity requires coverage. It doesn't. Clarity requires one thing to do.

First-run mistakeWhat the user actually doesWhat we ship instead
Tutorial overlay before contentSwipes it away, or leavesContent first, tutorial on a long-press
Sign-up card on entryCloses the programOne tap to the core action, account later
Three permission prompts at onceDenies all, permanentlyAsk the one we need, ask the rest in context
Four bullet points of valueReads none of themOne sentence, if the screen has room
Hidden primary actionTaps the wrong thingOne obvious button, everything else recedes

The table isn't a style guide; it's what our analytics kept shouting. Every extra element on that first screen was a small tax, and taxes compound.

The temptation to over-explain

Here's the thing we had to admit: over-explaining feels like diligence. A product manager can point at a tutorial and say we told them how it works. But telling isn't activation. Activation is the user doing the one thing that makes the program worth keeping — placing the order, sending the message, finishing the level — within the first session.

We measure that now, and we measure it narrowly. Not installs, not opens, but first-action-completed within, say, ninety seconds of first run. When we stripped the welcome screen down to a single primary action and moved every explanation behind a help affordance, that number moved more than any redesign we'd shipped before. We didn't add clarity. We removed friction.

And yes, there's a real risk in being too thin. If the program's value really does need a word of context — a novel interaction, a confusing category — then hiding everything can leave people stranded. The test we use is simple: can a returning user who forgot us complete the core action cold? If yes, the first run can stay nearly empty. If no, one sentence earns its place.

Deferring the asks

Permission prompts are the easiest trap. Location, contacts, notifications — each one is a small chance the user says no forever, and a denied permission in a mini-program is harder to win back than on a phone where settings are one tap deeper. We ask for the one permission the immediate action needs, and we ask it inside the moment it's needed, not on arrival. The rest wait until the user has a reason to grant them.

This isn't just politeness. It changes the activation curve. People who complete the core action before seeing a single prompt are far more willing to grant the next one, because by then the program has kept a promise.

One primitive, not a hundred reinventions

There's a platform angle that rarely gets said out loud. Today, every merchant who builds a mini-program reinvents this same first-run dance — their own tutorial, their own deferred-permission logic, their own idea of a primary action. Multiply that across hosts and you get a hundred slightly broken onboarding flows, each maintained by someone who isn't thinking about onboarding full time.

A runtime that targets several hosts can carry one well-tested onboarding primitive — progressive disclosure, a single primary action, context-scoped permission asks — and let every mini-program inherit it. The merchant stops solving a problem they didn't hire for, and users stop relearning the front door every time they enter a new program. We'd rather see that primitive get a thousand hours of attention once than a thousand programs each spend an afternoon on it.

Sources