Toutour — ship guided tours that actually pass. A two-tier generator for welcome card, main tour and mini-tours; a Playwright verification harness; recipes for Next.js, Vue, Svelte and React. Free and MIT, one command.

License: MIT skill v1.2.0 Toutour Pro

Turn any website into a guided experience.

Toutour is an agent skill (universal SKILL.md format — works in Claude Code, Cursor, Gemini CLI, Codex CLI...) that analyzes a website's layout, tabs and UI components, interviews the developer about their preferences, then generates, wires up and verifies a spotlight onboarding tour — the dark-mask, step-by-step walkthrough pattern that most vibe-coded sites are missing.

中文:Toutour 是一個 agent skill——讓 AI 編程助手替你的網站自動分析版面、訪談偏好、產生並「實測驗證」遮罩步驟式新手導覽。誕生自 telaaurealab.com 上線實戰的導覽引擎。

Toutour demo

v1.2.0 — deep links and mid-tour resume, in the MIT engine. A tour is no longer all-or-nothing. Toutour.start(steps, { startAt: 3 }) drops a user straight onto step 3 — so a docs link, a support reply or an empty-state button can point at the exact step that explains the thing. Toutour.resume(steps) picks a tour back up where the user abandoned it, within a time window you set. Both clamp to the filtered step list, so they stay correct when steps are conditionally skipped. Resuming emits tour_resumed.

v1.1.0 — three additions:

• engine/scroll-hint.js — the false-bottom repair. A 100vh hero with no visible continuation reads as the end of the page, and exploration stops there. This mounts a peeking next-section cue, skips itself when the page is already scrolled, dismisses on the first scroll or keypress, never intercepts a click, and keeps the cue (minus the motion) under prefers-reduced-motion. MIT, ~6 KB, zero dependencies.
• references/anti-patterns.md — ten onboarding anti-patterns, each carrying its published number (Google's own install-interstitial case study, Baymard's checkout-abandonment waves, the NN/g tutorial study, the NHANES vestibular-dysfunction figure). Phase 1 of the skill now audits the site against all ten and reports every hit as a friction finding. Fixing these routinely matters more than adding the tour.
• patterns.html / patterns.en.html — the interactive gallery, in Traditional Chinese and English.

Guided tours are one of the highest-leverage UX features a tool-style website can add, yet almost no AI-generated site ships one. Existing libraries (Driver.js, Intro.js, Shepherd.js) solve the rendering — nobody solves the authoring: deciding what to introduce, in what order, on which breakpoint, in which language, without covering the thing you're pointing at. That authoring knowledge is exactly what an agent is good at — if you give it the right playbook. Toutour is that playbook, plus a zero-dependency MIT reference engine, plus a verification recipe that catches the bugs we hit shipping this for real.

npx skills add matt-ye/Toutour # universal SKILL.md installer
# or copy SKILL.md into your agent's skills directory

Then ask your agent: "use toutour to add an onboarding tour to my site".

The skill asks (never assumes):

• Step granularity — condensed main tour / exhaustive per-control / two-tier (main + per-panel "?" mini-tours)
• Mask — dark overlay on/off, spotlight ring emphasis (accent border) on/off
• Languages — which locales the tour copy ships in
• Theming — follow the site's day/night mode or single look
• Trigger — auto-show on first visit (with localStorage opt-out) and/or a persistent "?" button

// Point a docs link, a support reply or an empty-state button at one exact step.
Toutour.start(steps, { startAt: 3 });
// Or pick the tour back up where the user left off, if they were here recently.
Toutour.resume(steps, { resumeMaxMin: 30 }); // default 30 min; falls back to a normal start

startAt is clamped to the filtered step list, so it stays correct on a site where steps are conditionally skipped (a locked panel, a mobile-only control). resume() emits tour_resumed {step} when it actually resumes, so an abandoned-then-resumed tour shows up in your funnel as exactly that, rather than as a second cold start.

The engine emits tour_start, tour_step {step, total}, tour_done, tour_skip {step} and tour_resumed {step} through a single onEvent hook — no analytics vendor is bundled. Wire it to whatever the site already uses (GA4, Plausible, Umami, PostHog...) and you get a per-step funnel: exactly which step users abandon on.

Toutour.start(steps, {
 onEvent: (name, data) => gtag('event', name, data), // GA4
 // onEvent: (name, data) => plausible(name, { props: data }), // Plausible
});

No onEvent → no data collected. The skill asks about analytics during the developer interview and never adds a tracking vendor uninvited.

Everything in this repo is MIT and free forever. Pro is the optional paid layer for teams who want the depth as working, tested code instead of a playbook to implement.

Every row above is playable in the pattern gallery — each card is tagged, so you can see the line before you buy.

Toutour Pro (v0.2.0) is sixteen guidance modules plus the assembler that wires them together. assemble() takes a single config and resolves the module graph for you — the checklist↔tours cycle, the event-chain order, per-module storage keys — because hand-wiring is where generated integrations break.

• Tour layer — the two-tier generator (welcome card with optional audience segmentation, condensed main tour, persistent "?" replay, per-panel mini-tours, action-gated steps), a getting-started checklist that survives sessions, competency tracking that proves completion from real app events rather than scripted clicks, and once-ever milestone celebration.
• Ambient layer — the guidance moments that are not a sequence: one-target nudges, persistent beacons for shipped-but-unnoticed features, just-in-time first-visit offers, stall detection that fires on hesitation rather than page-load, and a polite queued slideout.
• Commerce layer — a personalization quiz whose walk() fails your build if any answer path lands on zero results, a chart-based size finder with a unit-tested resolver, zero-results and empty-cart recovery with merchant-side query logging, an honest welcome offer whose guardrails are not configurable, and permission priming that cannot reach the real browser API before an affirmative click.
• Analytics & verification — a GA4 adapter that turns the event stream into a funnel in one line (including the exact step users abandon on, and time-to-value), and a parameterized Playwright harness: describe your tour in one config, get the full verification pass across both viewports, both themes, reduced-motion, and network/console errors. 106 end-to-end checks ship with the package itself.

One purchase covers unlimited sites you build or maintain. Get Toutour Pro →

Shipped: the skill (v1.2.0), the zero-dependency engine with deep links and resume, the scroll-hint module, the anti-pattern audit list, a bilingual pattern gallery, live demos + video, CI (lint + Playwright e2e on every push), and a verified npx skills add path. Toutour Pro v0.2.0 is available. See docs/feasibility.md for the roadmap.

MIT. The reference engine and skill are free forever; Toutour Pro is a separately-licensed commercial add-on that does not restrict anything in this repo.

Privacy : Toutour has no server, no account and no telemetry, and neither the engine nor any Pro module makes a network request of any kind. The engine writes a few keys to the visitor's own localStorage (tour seen, resume position, scroll cue dismissed) and nothing leaves the browser. The onEvent hook and the GA4 adapter call the analytics library your site already loads — that data is yours, under your policy.