In-app tutorial design: a practical screen by screen method

Good in-app tutorial design teaches one task by having the user do it, in the real interface, in as few steps as possible, and it always lets them skip. Plan it screen by screen: for each step, write what the user sees, the one action they take, and what happens if they skip, wander off or get it wrong. Then draw every one of those situations before you build any of them.

Pick the pattern that fits the task

“Tutorial” covers several patterns, and they are not interchangeable.

Pattern	Good for	Watch out for
Welcome carousel	One or two sentences of value before the app	Users swipe through without reading; it teaches nothing about controls
Coach marks	Pointing at one or two controls that are not obvious	Too many in a row; covering the thing they point at
Guided task	The core task, done for real, with guidance	Blocking the whole interface; no way out
Empty state guidance	The first visit to a screen with no data	Generic “Nothing here” copy
Setup checklist	Setup that spans several sessions	Items that stay unchecked forever
Hint on first use	Secondary features, when the user reaches them	Showing every hint on day one

For most products, the strongest combination is a short guided task for the core action and empty state guidance everywhere else. A carousel before the app is the weakest way to teach: the user has not yet seen the interface the slides describe.

Write steps that teach by doing

Each step should ask for one action, in the words of the interface. Start with the verb, name the control exactly as it is labelled, and say what will happen.

A three-step script for a task app might read:

1. “Tap New task to add your first task.” (The pointer targets the button.)
2. “Type what you need to do, then tap Add.” (The sheet is open and the field has focus.)
3. “Swipe the task right to mark it done.” (The new task is highlighted.)

Then the tutorial ends, with one sentence (“You’re set. Find this tour again in Help.”) and no fourth tip. If you find yourself writing a step that asks the user to read rather than act, that content probably belongs in an empty state or in the help pages.

Keep each step short enough to read at a glance, since the user’s attention is on the control, not on the bubble. Write the copy with the real labels of your interface, and plan for translation: a label that fits in English may wrap in another language and push the pointer off its target.

Draw every state of every step

Each step is a state of the underlying screen, and each step has states of its own. For the script above:

• Step shown: the overlay, the pointer, the text and Skip.
• Step done: the user did the action; the next step appears, or the tutorial ends.
• Off script: the user tapped something else. Do you pause, wait, or end the tutorial?
• Error inside a step: the user tapped Add with an empty field.
• Skipped: the user tapped Skip. What do they see now, and how do they get back to the tutorial?
• Finished: the screen after the last step, showing the real content the user just created.
• Replayed: the tutorial started again from Help, on a screen that now has data.

The replayed state is the one most often forgotten: a tutorial written for an empty screen can point at nothing once the user has twenty tasks. The UI states checklist helps with the screen states underneath the overlay.

Let users skip, pause and come back

• Put Skip on every step, in the same place, as a visible text button.
• Do not ask “Are you sure?” on Skip. Say where to find the tutorial again.
• Remember progress and the decision to skip. A tutorial that returns at every launch teaches users to dismiss overlays without reading them.
• Let the user leave the tutorial by simply using the app. If they create a task without it, the tutorial has done its job.
• Offer replay from the help menu or the settings.

Make overlays accessible

A tutorial that sits on top of the interface has to work with a keyboard and a screen reader, not only with a finger or a mouse.

• When a step opens as a modal overlay, move focus into it, keep Tab inside it, close it with Escape, and return focus to where it was. The W3C dialog (modal) pattern describes these rules.
• For a coach mark that does not block the page, do not trap focus: the user must be able to reach the control it points at.
• Keep the step text as real text, not baked into an image, with enough contrast against the dimmed background.
• Do not rely on the pointer or the highlight alone to show which control is meant: name the control in the text.

Prototype the tutorial before coding it

A tutorial is a sequence of states laid over real screens, which makes it easy to prototype as static screens, one per step and situation. A coding agent can draw them to match your real components and copy, without touching the app code. A prompt:

Prototype an in-app tutorial for the Tasks screen. Do not change the app code.
Three steps: tap New task, type and tap Add, swipe to mark done.
Draw one screen per state: each step shown, the empty-field error in step 2,
the screen after Skip, the finished screen with the new task, and the
tutorial replayed from Help on a screen with 12 tasks.
Put a Skip text button on every step. Match our real components and copy.

In agentappbuilder, each of those states becomes a frame, and the steps are linked by their triggers (“Tap Next”, “Tap Skip”), so you can follow the path on the canvas; its docs use an onboarding tutorial as their example of a new flow. If your app already runs, your agent can first capture the real screen, with your agreement. Once you import that capture into the prototype and ask for the tutorial on it, your agent recreates the screen as HTML and applies your change, so the overlay points at the controls users actually see. You can also duplicate a step to try a variation yourself, adjust its padding or text styles in the Design panel of the canvas, then ask your agent to implement your edits. Working with your agent lists the prompts, and the canvas covers duplication and editing. For the flow that leads into the tutorial, see how to prototype an onboarding flow with an AI agent.

Measure it after launch

Once it ships, track a few numbers: the share of new users who start the tutorial, completion per step (the step where most people drop out is the one to fix first), the skip rate, and whether users who finish reach the core action more often than those who skip. If users who skip do as well as those who finish, the tutorial may not be needed at all, and your empty states may already be doing the teaching.