How to create an interactive product tour in your repo

Open your current product tour in one tab and your live product in another. The mismatch usually shows up in under ten seconds: a button label changed, a nav item moved, a feature shipped two sprints ago and still isn't in the tour. That happens because the tour lives somewhere else. If you want an interactive product tour that stays accurate, build it where the product lives: in your repo.

Why an interactive product tour belongs in your repo

Open the tour next to the product and count the mismatch

That little exercise is the point. Every UI change that does not trigger a tour update is another moment where a new user sees something that no longer exists. The tour is wrong not because someone was careless, but because the tour and the product are separate artifacts with no shared source of truth.

Why separate builders turn small changes into rework

When the tour lives in a SaaS builder, a UI change creates two jobs: ship the product change, then open the builder and sync the tour by hand. Those jobs drift apart fast because they live in different tools, different contexts, and often different people's queues.

The repo-native version is simpler. The tour step, the component it points to, and the copy that describes it all live in the same codebase. When your agent edits the component, you prompt it to update the step config in the same pass. One `git diff`, one PR, one deploy. Vercel's write-up on their own virtual product tour shows what that looks like in practice: the tour is part of the codebase, not an afterthought in a third-party editor.

Choose the right interactive product tour pattern

When a tooltip is enough and a tour is too much

A tooltip answers one question at one moment. A tour moves a user through a sequence of steps toward a specific outcome. If the user's confusion is local, like "what does this button do?", a tooltip is the right tool. A tour makes sense when the user has to complete a short sequence to get value and probably will not figure it out alone.

If you're reaching for a tour because the product is hard to understand, the tour is probably doing the wrong job. Fix the product first. If you're reaching for a tour because there is a non-obvious path to the first win, then it belongs there.

Hotspots, modals, slideouts, and branching flows

• Tooltips and hotspots — low interruption, anchored to a specific UI element. Good for pointing at a feature the user is already near.
• Modals — high interruption, demand full attention. Good for a one-time setup step the user must finish before anything else works.
• Slideouts — medium interruption, stay in context. Good for guidance that should not block the UI.
• Branching flows — multiple paths based on role or behavior. Good when different users need different next steps. A project management tool where admins configure workspaces and members join them needs two different next steps after sign-up; a single linear walkthrough will send one group somewhere irrelevant.

Pick the pattern that matches how much the user needs to stop what they're doing. More interruption means more attention, which means more justification.

Map the tour to one job and one activation milestone

Do not make the tour explain the whole app

The instinct is to show everything. Resist it. A product walkthrough that covers every feature teaches the user that the product is complicated. A tour that gets the user to one specific win teaches them that the product works.

If you cannot finish the sentence "this tour ends when the user has ___", the scope is too wide. Cut it until you can name one concrete action.

Pick the first win the user needs to reach

The activation milestone is the moment a user has done something real with the product, not just clicked through a tour. For a project tool, it's creating the first project. For a collaboration tool, it's inviting the first teammate. For a publishing tool, it's publishing the first item.

PostHog's training approach is a good example: they ask users to build something during training, not just watch. The milestone is not "finished the tour" — it's "built the filter." Track the activation event, not tour completion. Completion tells you the tour ran. The activation event tells you it worked.

Build the interactive product tour step by step

Start with the smallest believable flow

The onboarding tour scope that ships is better than the comprehensive tour scope that never does. For a first version: one entry point, three to five steps, one activation event at the end. That is enough.

Build sequence:

• Define the activation milestone. One sentence: "User has created their first X."
• Map the steps backward from the milestone. What's the last action before the milestone? The second-to-last? Stop when you reach the entry point.
• Write the copy for each step. One line of instruction, one line of context if needed. No feature explanations, just the next action.
• Wire each step to a UI target. The selector that anchors the tooltip or highlights the element.
• Set the completion condition. What event fires when the user finishes the step? A click, a form submit, a route change.

Wire the copy, state, and UI targets into code

A step config in your repo looks something like this:

The target, the copy, and the completion event live together. When the button ID changes, the agent updates the selector in the same edit. When the copy needs refreshing, it's a string in a file, not a login to a third-party dashboard.

Keep personalization in the same flow

Role-based branching does not need to be a separate tour variant managed in a separate tool. A condition on the step config handles it:

Both paths live in the same repo, same PR, same deploy. The agent can update both in one prompt.

Trigger the interactive product tour from real behavior

Use product events, not page load, as the trigger

Firing the tour on page load means firing it on every page load, including users who already know the product, users who refreshed the tab, and users in the middle of something else. The tour turns into noise.

A better trigger: `onboarding_tour_eligible` — a condition that is true only when the user has signed up, has not completed the activation milestone, and has not dismissed the tour. Fire it once, on the first meaningful interaction after sign-up, not on the URL change.

Delay the tour when the user is already moving

If a user signs up and immediately starts creating a project, the tour is interrupting someone who does not need it. Watch for the first moment of hesitation: a pause on the dashboard, a hover on a help icon, a second visit to the same screen. Product analytics research on behavior-triggered guidance shows that timed or event-based triggers usually outperform page-load triggers for completion and activation.

A practical event map: `signup_completed` → start eligibility window → `first_session_idle` (user hasn't acted in 8 seconds) → fire tour.

Test the tour in staging before users see it

Walk the happy path and the broken path

QA checklist for every tour version:

• Happy path: complete every step in order. Confirm the activation event fires at the end.
• Missing element: remove or hide the target element. Confirm the tour fails gracefully, with no broken tooltip anchored to empty space.
• Wrong state: start the tour from a state where the user has already completed step 2. Confirm the tour skips correctly or resumes.
• Skipped step: dismiss the tour mid-flow. Confirm it doesn't re-fire on the next page load.

Check the edge cases that break onboarding

• Different roles: run the tour as an admin and as a member. Confirm branching fires correctly.
• Stale data: run the tour in an account with existing data. Confirm steps that depend on empty states do not break.
• Delayed events: slow down the network. Confirm completion events fire correctly when the API response is slow.
• UI elements that fail to mount: if the target element renders asynchronously, the tooltip needs a mount check, not a fixed timeout.

Staging checklist item to copy: `[selector: #create-project-btn] → [event: project.created] → [fallback: dismiss + log] → [rollback: feature flag off]`.

Track completion, drop-off, and activation impact

Completion rate is the weak signal

A tour that gets finished but does not move users to the activation milestone is a tour that entertains without helping. Completion rate tells you the tour ran. It does not tell you the tour worked.

Watch where people bail and what they do next

The useful analytics view:

• Step completion funnel — where do users exit the tour? A drop at step 2 means step 2 is either confusing or interrupting something the user cares about more.
• Exit step → next action — what do users who exit at step 2 do next? If they go straight to the activation milestone anyway, the tour may be unnecessary for that segment.
• Tour completers vs. non-completers on activation rate — did users who finished the tour reach the activation milestone faster? If the gap is small, the tour is not moving the needle. If the gap is large, it is.

Set up these three views before launch. If you cannot point to activation lift after two weeks, the tour needs a redesign, not more steps.

Where Inkly comes in

The problem this article describes — a tour that drifts from the product because it lives in a separate builder — is structural, not a tooling gap. The tour and the product are two artifacts with no shared source of truth. Every UI change creates a manual sync job.

Inkly is built on the opposite premise: the demo is code you own, living next to your product, authored and maintained by your own agent (Cursor, Claude, Codex). The three-prompt loop — create, update, produce a variant — means a UI change does not open a ticket in a third-party dashboard. It opens a prompt. The agent updates the demo code in the same pass as the product code. No re-record, no manual sync, no drift.

The honest tradeoff: Inkly's MVP path is bring-your-own-agent. If you're not already working with Cursor or Claude Code, there is setup before the loop pays off. But if you are, the demo and the product stay in sync by default because they live in the same place. Build the first version from a prompt and the maintenance loop starts there.

FAQ

Q: How do I decide whether I need an interactive product tour at all, or just a tooltip, checklist, or walkthrough?

Use a tooltip for a single moment of confusion anchored to one UI element. Use a checklist when the user needs to complete several independent tasks in any order. Use a tour when there is a specific sequence the user must walk through to reach value, and they will not find it on their own. If you cannot name the activation milestone the tour is supposed to move, you do not need a tour yet.

Q: What is the simplest step-by-step process to create a product tour that helps users reach value faster?

Pick one activation milestone. Map the steps backward from it, usually three to five. Write one line of copy per step. Wire each step to a UI selector and a completion event. Trigger the tour from a behavior event after sign-up, not from page load. Ship it, then track activation rate for users who completed the tour versus those who did not.

Q: Which UI pattern should I use for my tour: tooltip, hotspot, modal, slideout, or branching interactive flow?

Match the pattern to how much you need the user to stop. Tooltips and hotspots are low interruption and good for pointing at something nearby. Modals are high interruption and good for a required setup step. Slideouts sit in the middle. Branching flows are right when different roles need different next steps after the same entry point.

Q: How do I trigger the tour at the right moment based on user behavior or product events?

Do not fire on page load. Fire on a behavioral condition: the user has signed up, has not reached the activation milestone, and has not dismissed the tour. Add a hesitation signal, like a pause on the dashboard or a second visit to the same screen, so you are not interrupting someone who is already moving. A practical trigger: `signup_completed` → wait for first idle moment → fire.

Q: How many steps should an effective product tour have, and what should each step accomplish?

Three to five steps for a first version. Each step should move the user one action closer to the activation milestone, not explain a feature or show what is possible. It should just name the next action. If a step does not map to a specific user action that moves toward the milestone, cut it. A tour that finishes in under two minutes and gets the user to the activation milestone beats a comprehensive tour that loses them at step four.

Conclusion

The tour that stays accurate is the one that lives where the product lives. A separate builder creates a second artifact to maintain, and that artifact falls behind every time the product ships. Put the step config, the selectors, and the copy in the repo. Wire the trigger to a real behavior event. Track activation, not completion.

Pick one activation milestone this week, the first project created, the first teammate invited, the first item published, and wire the first three steps of the tour to it. That's the version worth shipping.