{% tour %}

Attributes

Parameter	Type	Required	Description
kind	enum	—	walkthrough | demo | checklist — default: walkthrough
transition	enum	—	Default animation between stops: none | fade | slide | slide-back
scale	number	—	Default zoom percentage for all stops (e.g., 75 = 75%)
feature	string	—	Cross-doc ref to the owning feature (e.g., 'feature/onboarding')
scope	string	—	Visibility scope — defaults to 'public agent'

Valid Children

Tag	Multiplicity
{% tldr %}	[1]
{% explanation %}	[*]
{% stop %}	[+]

Rules

Rule	Force	Realm	Reference	Description
tour-stop-surface-resolves	must	global	—	must resolve in the global surface index (). validationreferential-integrity
tour-spotlight-target-exists	must	global	—	must appear as in the referenced surface's Pug DSL. validationreferential-integrity
tour-feature-resolves	must	global	—	, if set, must resolve in the bundle cache. validationreferential-integrity

Root tag of a .tour.mdoc document. Tours are author-scripted sequences — the complement to \{% interactions %\} which is a free-form prototype sandbox. Tours live in content/tours/ as .tour.mdoc files.

Tour kinds:

• walkthrough — manual prev/next navigation
• demo — auto-advances through stops
• checklist — user marks each stop done

Transition values: none, fade, slide, slide-back

Child tag reference

Tag	Attributes	Description
stop	surface (required), title (required), transition, duration, scale	A single step in the tour. Body prose is the annotation shown in the player’s annotation panel. \{% spotlight %\} and \{% overlay %\} tags may appear anywhere in the body.
spotlight	target (required), type (`ring	pulse
overlay	target (required), anchor (`top	right

\{% stop %\} attributes

Attribute	Type	Required	Default	Description
surface	string	yes	—	Cross-file surface ref: \{uiDocId\}/\{surfaceId\}. Resolved against all .ui.mdoc files globally.
title	string	yes	—	Step label shown in the chrome header and progress dots
transition	enum	no	(tour default)	Overrides the tour-level transition for this stop’s entrance animation
duration	number	no	3000	Auto-advance delay in ms (kind="demo" only)
scale	number	no	(tour default)	Overrides the tour-level zoom percentage for this stop (e.g. 60 = 60%)

Transition inheritance

The compiler resolves effectiveTransition = stop.transition ?? tour.transition ?? 'none'. A stop with an explicit transition attribute overrides the tour-level default; stops without one inherit it.

\{% spotlight %\} attributes

Attribute	Type	Required	Default	Description
target	string	yes	—	Element data-wf-id within the stop’s surface
type	enum	no	ring	ring — crisp outline; pulse — animated ping; dim — focus lens (dims everything else); highlight — accent background fill
duration	number	no	1200	Animation cycle ms for pulse type

Combining types: a dim spotlight focuses attention on one element; adding a ring on a second element labels a secondary target while the rest is dimmed.

\{% overlay %\} attributes

Attribute	Type	Required	Default	Description
target	string	yes	—	Element data-wf-id within the stop’s surface
anchor	enum	no	top	Which side of the element the tooltip appears on: top, right, bottom, left

Aggregate: Tours Gallery

The public pass generates a tours-gallery.mdx page after the per-file loop. All tours are grouped by their feature reference. The gallery is linked in the sidebar under Reference → Tours.

Guided onboarding tour with stops, spotlights, and overlays

tagtourstopspotlightoverlay tour-tag-full

{% tour kind="walkthrough" transition="slide" feature="feature/onboarding" %}

{% tldr %}A guided walkthrough of the onboarding experience for new users.{% /tldr %}

{% stop surface="onboarding/welcome-screen" title="Welcome" %}
First screen after sign-up. The single CTA is intentional — no distractions at this stage.
{% /stop %}

{% stop surface="onboarding/profile-setup" title="Set Up Your Profile" transition="fade" %}
{% spotlight target="avatar-btn" type="pulse" /%}
{% spotlight target="name-field" type="ring" /%}
Fill in your name to personalise your experience.
{% /stop %}

{% stop surface="main/dashboard" title="Your Dashboard" %}
{% spotlight target="primary-nav" type="dim" /%}
{% overlay target="primary-nav" anchor="bottom" %}
Core actions are in the top nav.
{% /overlay %}
After onboarding, users land here.
{% /stop %}

{% /tour %}

Tag Tree

{% tldr %}[1]One-sentence summary rendered as a lead paragraph and used as the document's short description throughout the site.{% explanation %}[*]Provides targeted advice or collapsible detail for a specific audience. Renders as a callout () or a disclosure element (). Supports full Markdown in the body.{% stop %}[+]A single step in a tour sequence, displaying a surface with an annotation and optional spotlights and overlays.{% spotlight %}[*]Highlights a UI element on a tour stop's surface with a ring, pulse, dim, or highlight effect.{% overlay %}[*]Renders a tooltip anchored to a UI element on a tour stop's surface.