Why product tours break every time you ship

Every product team that has shipped an onboarding tour knows the moment. A designer moves the “Export” button into a menu, the release goes out, and the tour’s third tooltip now points at an empty patch of screen. Nobody notices for two weeks, until a support ticket arrives with a screenshot.

This isn’t bad luck or a careless team. It is how tours are built.

A tour is a recording of a UI that no longer exists

Almost every tour tool works the same way. Someone opens the app with an editor, clicks through a journey and attaches a step to each element. Under the hood each step stores a way to find that element again: a CSS selector, a text match, sometimes a position. The tour is a recording of the UI on the day it was made.

Your UI keeps moving. In a typical SaaS release you might:

rename a button (“Export” becomes “Download”),
move an action into an overflow menu,
split one settings page into tabs,
change a component library, which regenerates class names,
run an A/B test, so half your users see a different layout.

Each of these can break a selector, and each tour step is another selector. A ten-step tour across three pages has ten chances to break on every release, and the journeys that matter most (setup, billing, permissions) are the ones that change most.

The real cost is upkeep, not the license

The license is the visible cost. The bigger ones are quieter:

Authoring time. Someone has to decide which journeys get a tour, write the copy and click through the editor. That is usually a product manager or a customer success lead, doing it between other jobs.
Regression checks. After each release, someone should replay every tour. In practice nobody does, which is how broken tours stay live for weeks.
Coverage gaps. Because each tour costs effort, only a handful of journeys get one. Users who need anything else get nothing.
Trust. A tour that points at the wrong place once teaches users to dismiss tours.

What teams do about it

1. Stable hooks in the code

Add data-tour="export-button" attributes and point the tour at those instead of generated classes. This is the single most effective fix for selector breakage, and it is cheap. It doesn’t help when the journey itself changes, for example when the button moves to another page.

2. Fewer, shorter tours

Three steps that get someone to a first result beat a twelve-step feature parade. Shorter tours break less and get finished more. The trade-off is less coverage.

3. Tours as code

Developer-first tools let engineers define onboarding in the codebase, so a refactor that breaks a step fails a test. Great if engineering time is available; it moves the upkeep, it doesn’t remove it.

4. Guidance that reads the page each time

The newer approach is to stop recording. Instead of storing “step 3 is the element matching .toolbar > .btn-export”, the guide looks at the live page when the user asks, and chooses the next step from what is there now. If “Export” became “Download” inside a menu, the guide sees a menu and a “Download” item.

This is what we built Wayhint to do. A user types their goal, the widget sends a masked list of the visible controls, and the guide picks one step: walk to this button, point, explain. After the click it looks again. An app map learned from real use and from a crawler gives it the bigger picture (what is behind each menu) without anyone authoring flows.

It has trade-offs too. A model choosing steps can pick the wrong element, so you want measurement: on our own demo app, Pepper pointed at the right control on 97.3% of steps with a learned app map (measured with a local Qwen3 model). You also give up word-for-word control of a scripted tour. For a polished first-run announcement, a scripted tour is still a fine tool.

A quick audit you can run this week

List every live tour and the pages it touches.
Replay each one on production today. Note every broken or misleading step.
Check your release log: how many releases in the last quarter touched those pages?
Estimate hours per quarter spent fixing tours, plus hours you should have spent.

If the answer is “several broken steps and nobody owns the fixes”, the problem is not the tool you picked. It is the model of recording a UI that keeps changing. Here is how the alternative works.