Pattern — Onboarding / product-tour

Status: v0.1.0 — Draft. Promoted from the KDS × gov.br Design System gap analysis (tools/design-gen/docs/govbr-ds-gap-analysis.md, GVB-15). Source: gov.br Padrão Digital onboarding pattern. KDS had single contextual hints (guide-cue / info-sprinkle) but no chained tour.

R1 — When to use (vs a single hint / empty state)

• Onboarding tour (this): a first-time, multi-step walkthrough of a surface with several parts the user must discover in sequence.
• Single contextual hint (a lone callout / specs/patterns/callout-card.kmd): one tip about one element — do not escalate to a tour for one hint.
• Empty state (specs/patterns/empty-state.kmd): teaches by showing a first-action affordance when there is no data yet — often a better first-run teacher than a tour. Prefer it when the lesson is "do this one thing first".

R2 — Progressive, anchored coach-marks

• A tour is an ordered list of steps; each step is a coach-mark anchored to a real UI element (spotlight/highlight on the target + a small callout describing it). One step is visible at a time.
• Steps advance Next / Back; the target of the current step is visually emphasized and scrolled into view. The tour never points at an element that is off-screen or absent.
• Keep tours short (a handful of steps). If the surface needs more, it is probably too complex — fix the surface, don't lengthen the tour.

R3 — Skip, dismiss, never-again

• Every step offers Skip / Dismiss — the user can leave the tour at any point, and leaving is remembered (R4), not re-prompted next step.
• The tour is never modal-trapping: the user can interact with the app or close the tour with Esc (pairs with specs/navigation/back-behavior.kmd). A tour that blocks work is a defect.
• Offer a way to replay the tour later (a "Show tips" affordance) for users who skipped or want a refresher.

R4 — Seen-state persistence

• The tour's completed/skipped state is persisted per user (and per tour version) so it shows once and does not repeat on every visit.
• Persistence is keyed to a stable tour id + version — bumping the version (materially new steps) may re-show; cosmetic edits must not.
• First-run detection is per surface/feature, not global: reaching a new surface for the first time may start its own tour.

R5 — Timing & non-interruption

• Start a tour when the user arrives at the surface and is idle, not mid-task and not before the surface has painted. Never launch a tour over a loading state or an error.
• At most one tour runs at a time. Never stack a tour on a modal, a toast, or another tour.

R6 — Accessibility & i18n

• Each step's callout is a labeled region; focus moves to the step callout when it appears and returns to a sensible place on dismiss (no focus loss). Esc closes; Tab order is preserved.
• The current-step target is announced (name + the step's description); progress ("step 2 of 4") is available to assistive tech.
• Motion (spotlight, scroll) respects reduced-motion preferences.
• All step copy, Next/Back/Skip labels, and the replay affordance are translatable per specs/i18n/contract.kmd.

Não-escopo

• One-off contextual hints / tooltips on a single element (a single callout, not a tour).
• Marketing modals / changelog announcements (a different surface).
• The first-action teaching of an empty data view (specs/patterns/empty-state.kmd).
• Full setup wizards that gate usage (specs/patterns/wizard-multistep.kmd).