product-tour-onboarding-ui Stinger
Start with README.md for the workflow map and detailed references.
Procedural arsenal for product-tour-onboarding-ui-wasp-drone, the Drone that owns the in-app guided-experience layer.
This stinger is organized around the seven action verbs from the Command Brief: qualify the tour stack, select a platform, implement components, wire segment triggers, build the checklist UI, establish a maintenance protocol, and produce a tour health report.
The stinger's three non-negotiables (from guides/00-principles.md):
- Stable anchors first. Never target an element by CSS class or text if you can add a
data-tour attribute. Classes change; data-tour attributes are a contract.
- Qualify before recommending. Run the four-axis decision framework (cost, code-depth, team size, DOM stability) before naming a platform.
- Tour maintenance is code maintenance. A tour without a selector registry and CI smoke test is technical debt from day one.
When this stinger applies
Load this stinger when product-tour-onboarding-ui-wasp-drone is invoked. Trigger scenarios:
- User wants to add a product tour to a React/Next.js app.
- User is deciding between Userpilot, Appcues, Userflow, Pendo, Driver.js, or Shepherd.js.
- Tours are breaking after UI changes (selector drift problem).
- User wants to show different tours to different user segments.
- User wants to add an onboarding checklist with progress gamification.
- User wants to audit existing tours for health and effectiveness.
Do NOT load for:
- Onboarding email sequences (out of scope: no Drone owns this yet).
- User authentication flows (auth-wasp-drone).
- Design token system for tour tooltip styling (ux-ui-svelte-wasp-drone).
- Analytics funnel instrumentation for tour events (posthog/mixpanel Drones).
- Database schema for user-progress storage (db-wasp-drone).
First action when this stinger is loaded
Read these files in order before producing any output:
guides/00-principles.md: the three non-negotiables and the foreman's boundary; read on every invocation.
guides/01-platform-selection.md: the four-axis decision framework for tool selection; required before any platform recommendation.
- The guide(s) that match the user's specific task (see the guide index below).
Guide index
| Guide |
When to read |
guides/00-principles.md |
Every invocation |
guides/01-platform-selection.md |
Any platform recommendation or comparison |
guides/02-tooltip-modal-hotspot.md |
Implementing tour component UI (tooltips, modals, hotspots, spotlights) |
guides/03-driver-js-shepherd-js.md |
Code-first open-source implementation (Driver.js or Shepherd.js) |
guides/04-segment-triggers.md |
Wiring tour trigger logic or segment conditions |
guides/05-checklist-activation.md |
Onboarding checklist UI, progress gamification, activation milestones |
guides/06-maintenance-and-drift.md |
Tour breakage diagnosis, selector hygiene, CI integration |
Worked examples
examples/happy-path-driver-js.md: end-to-end implementation of a three-step product tour with Driver.js 9.x + React + data-tour anchors + localStorage persistence.
examples/saas-platform-audit.md: walkthrough of the qualification checklist applied to a 2,000-MAU SaaS startup choosing between Userpilot, Userflow, and Driver.js.
Output templates
templates/tour-audit-report.md: the tour health report template; produced for every standalone audit.
templates/data-tour-registry.json: the selector registry template; populate one entry per interactive element targeted by any tour.
Critical directives (lifted from the Command Brief)
- Select stable element anchors (
data-tour attributes) over class or text selectors. CSS class names change with every CSS-in-JS rebuild; data-tour is a durable engineering contract. See guides/06-maintenance-and-drift.md.
- Never recommend a tour platform without running the qualification checklist first. Wrong-tool selection costs months of migration. The checklist lives in
guides/01-platform-selection.md.
- Treat tour maintenance as code maintenance. A tour without a CI smoke test and selector registry will break silently. The maintenance protocol is
guides/06-maintenance-and-drift.md.
- Route visual polish to
ux-ui-svelte-wasp-drone. Tour tooltip/modal CSS must consume the product's design tokens; a parallel custom-CSS system in the tour layer is a maintenance trap.
- Do not instrument analytics yourself. Flag what needs tracking; route to the appropriate analytics Drone.
Research foundation
All factual claims in this stinger's guides trace to files in the source research archive (not shipped; the shipped distillation summarizes it). The research index is at research/index.md (source-repository research, not shipped with the plugin). The summary of the five most influential sources is at research/research-summary.md. Refresh annually or on a major platform version bump.
Key sources (source-repository research, not shipped with the plugin):
- Platform pricing + features:
research/external/2026-05-20-saas-platform-comparison.md (source-repository research, not shipped with the plugin)
- OSS library comparison:
research/external/2026-05-20-oss-tour-libraries.md (source-repository research, not shipped with the plugin)
- Maintenance + drift prevention:
research/external/2026-05-20-tour-maintenance-unbreakable.md (source-repository research, not shipped with the plugin)
- Segment triggers:
research/external/2026-05-20-segment-triggers-feature-flags.md (source-repository research, not shipped with the plugin)
- Checklist activation:
research/external/2026-05-20-checklist-activation-gamification.md (source-repository research, not shipped with the plugin)
- Shepherd.js integration:
research/external/2026-05-20-shepherdjs-react-integration.md (source-repository research, not shipped with the plugin)
- Driver.js integration:
research/external/2026-05-20-driverjs-react-integration.md (source-repository research, not shipped with the plugin)
- Tour analytics ROI:
research/external/2026-05-20-tour-analytics-effectiveness.md (source-repository research, not shipped with the plugin)
Forged by stinger-forge from product-tour-onboarding-ui-wasp-drone-command-brief.md and research/. Part of the Wasp Nest.
1---2name: product-tour-onboarding-ui-stinger-33description: "Build in-app tours and onboarding UI. Use for tour tools, tooltips, checklists, segment triggers, or maintenance after UI changes. Read README.md for the guide map."4license: AGPL-3.0-or-later5metadata:6 source: https://skillmd.com/skills/legioncodeinc/product-tour-onboarding-ui-stinger-37---89# product-tour-onboarding-ui Stinger1011Start with [README.md](README.md) for the workflow map and detailed references.1213Procedural arsenal for `product-tour-onboarding-ui-wasp-drone`, the Drone that owns the in-app guided-experience layer.1415This stinger is organized around the seven action verbs from the Command Brief: qualify the tour stack, select a platform, implement components, wire segment triggers, build the checklist UI, establish a maintenance protocol, and produce a tour health report.1617**The stinger's three non-negotiables (from `guides/00-principles.md`):**18191. **Stable anchors first.** Never target an element by CSS class or text if you can add a `data-tour` attribute. Classes change; `data-tour` attributes are a contract.202. **Qualify before recommending.** Run the four-axis decision framework (cost, code-depth, team size, DOM stability) before naming a platform.213. **Tour maintenance is code maintenance.** A tour without a selector registry and CI smoke test is technical debt from day one.2223---2425## When this stinger applies2627Load this stinger when `product-tour-onboarding-ui-wasp-drone` is invoked. Trigger scenarios:2829- User wants to add a product tour to a React/Next.js app.30- User is deciding between Userpilot, Appcues, Userflow, Pendo, Driver.js, or Shepherd.js.31- Tours are breaking after UI changes (selector drift problem).32- User wants to show different tours to different user segments.33- User wants to add an onboarding checklist with progress gamification.34- User wants to audit existing tours for health and effectiveness.3536Do NOT load for:37- Onboarding email sequences (out of scope: no Drone owns this yet).38- User authentication flows (auth-wasp-drone).39- Design token system for tour tooltip styling (ux-ui-svelte-wasp-drone).40- Analytics funnel instrumentation for tour events (posthog/mixpanel Drones).41- Database schema for user-progress storage (db-wasp-drone).4243---4445## First action when this stinger is loaded4647Read these files in order before producing any output:48491. **`guides/00-principles.md`**: the three non-negotiables and the foreman's boundary; read on every invocation.502. **`guides/01-platform-selection.md`**: the four-axis decision framework for tool selection; required before any platform recommendation.513. The guide(s) that match the user's specific task (see the guide index below).5253---5455## Guide index5657| Guide | When to read |58|---|---|59| `guides/00-principles.md` | Every invocation |60| `guides/01-platform-selection.md` | Any platform recommendation or comparison |61| `guides/02-tooltip-modal-hotspot.md` | Implementing tour component UI (tooltips, modals, hotspots, spotlights) |62| `guides/03-driver-js-shepherd-js.md` | Code-first open-source implementation (Driver.js or Shepherd.js) |63| `guides/04-segment-triggers.md` | Wiring tour trigger logic or segment conditions |64| `guides/05-checklist-activation.md` | Onboarding checklist UI, progress gamification, activation milestones |65| `guides/06-maintenance-and-drift.md` | Tour breakage diagnosis, selector hygiene, CI integration |6667---6869## Worked examples7071- `examples/happy-path-driver-js.md`: end-to-end implementation of a three-step product tour with Driver.js 9.x + React + `data-tour` anchors + localStorage persistence.72- `examples/saas-platform-audit.md`: walkthrough of the qualification checklist applied to a 2,000-MAU SaaS startup choosing between Userpilot, Userflow, and Driver.js.7374---7576## Output templates7778- `templates/tour-audit-report.md`: the tour health report template; produced for every standalone audit.79- `templates/data-tour-registry.json`: the selector registry template; populate one entry per interactive element targeted by any tour.8081---8283## Critical directives (lifted from the Command Brief)8485- **Select stable element anchors (`data-tour` attributes) over class or text selectors.** CSS class names change with every CSS-in-JS rebuild; `data-tour` is a durable engineering contract. See `guides/06-maintenance-and-drift.md`.86- **Never recommend a tour platform without running the qualification checklist first.** Wrong-tool selection costs months of migration. The checklist lives in `guides/01-platform-selection.md`.87- **Treat tour maintenance as code maintenance.** A tour without a CI smoke test and selector registry will break silently. The maintenance protocol is `guides/06-maintenance-and-drift.md`.88- **Route visual polish to `ux-ui-svelte-wasp-drone`.** Tour tooltip/modal CSS must consume the product's design tokens; a parallel custom-CSS system in the tour layer is a maintenance trap.89- **Do not instrument analytics yourself.** Flag what needs tracking; route to the appropriate analytics Drone.9091---9293## Research foundation9495All factual claims in this stinger's guides trace to files in the source research archive (not shipped; the shipped distillation summarizes it). The research index is at `research/index.md` (source-repository research, not shipped with the plugin). The summary of the five most influential sources is at `research/research-summary.md`. Refresh annually or on a major platform version bump.9697Key sources (source-repository research, not shipped with the plugin):98- Platform pricing + features: `research/external/2026-05-20-saas-platform-comparison.md` (source-repository research, not shipped with the plugin)99- OSS library comparison: `research/external/2026-05-20-oss-tour-libraries.md` (source-repository research, not shipped with the plugin)100- Maintenance + drift prevention: `research/external/2026-05-20-tour-maintenance-unbreakable.md` (source-repository research, not shipped with the plugin)101- Segment triggers: `research/external/2026-05-20-segment-triggers-feature-flags.md` (source-repository research, not shipped with the plugin)102- Checklist activation: `research/external/2026-05-20-checklist-activation-gamification.md` (source-repository research, not shipped with the plugin)103- Shepherd.js integration: `research/external/2026-05-20-shepherdjs-react-integration.md` (source-repository research, not shipped with the plugin)104- Driver.js integration: `research/external/2026-05-20-driverjs-react-integration.md` (source-repository research, not shipped with the plugin)105- Tour analytics ROI: `research/external/2026-05-20-tour-analytics-effectiveness.md` (source-repository research, not shipped with the plugin)106107---108109*Forged by stinger-forge from `product-tour-onboarding-ui-wasp-drone-command-brief.md` and `research/`. Part of the Wasp Nest.*