Rendering and accessibility

One host

An application renders one <TourHost />. The host renders the overlay, card, arrow, and Vue content. A second host produces a development error instead of a second control plane.

The default card must be good enough to ship. A single #card slot replaces the complete card for applications with another design system. Stable data-tour-part attributes and a small set of CSS custom properties support visual theming without freezing internal DOM structure.

The package does not accept raw HTML strings. Rich content uses Vue components. The package does not accept configured button arrays. The default card owns the normal actions, and the full-card slot owns custom actions.

Interaction modes

An interactive tour card is a dialog, not an ARIA tooltip.

• modal prevents background interaction, traps focus, and uses aria-modal="true".
• target keeps the card and the current target interactive. The dialog is not modal.
• page keeps the page generally interactive. The dialog is not modal.

The package must not use aria-modal="true" only because an overlay is visible.

Keyboard and focus

The default keyboard contract is Tab, Shift+Tab, Escape, and visible buttons. Safari follows the operating system's full-keyboard-access preference, so its Tab order can omit buttons when that preference is disabled. Nuxt Tour respects the browser's order and still keeps any focusable tour target inside the active focus scope. Left and right arrows are not global shortcuts because they conflict with editors, sliders, menus, grids, and text controls.

When a modal step opens, focus moves to a useful heading or card control. A maintained focus engine keeps focus inside the card. Target mode treats the card and highlighted target as one focus scope and makes unrelated subtrees inert. Nested widgets receive Escape before the tour. When the tour ends, focus returns to the invoking element when that element still exists.

Positioning and motion

Floating UI is the intended positioning dependency. Nuxt Tour exposes common placement and spacing concepts, not the full middleware configuration. The dependency is added only with the positioning implementation.

Overlay geometry and card positioning are separate internal systems. Version 1 supports one spotlight hole: the current target. Multiple highlighted targets wait until a real journey proves the extra SVG geometry and browser test cost.

Motion uses CSS and never restarts the backdrop while moving between steps. On start, the spotlight is born closed and the card hidden while the immediate full-page cover is active. The reveal then opens both from that painted state, so neither element can flash at its final appearance. Scrolling starts immediately, while the previous spotlight opening closes before the runtime swaps to the next target geometry. This prevents a translucent rectangle from jumping between targets. Route changes and late targets cannot expose an unshaded frame. The geometry handoff waits for the real cover animation before replacing the spotlight target. The command can complete as soon as the destination is positioned and usable; it does not wait for the decorative reveal to finish. The backdrop starts as soon as the tour starts. A destination spotlight opens when its target is close and slow enough. Native smooth scrolling keeps the travel distance adaptive without a second scrolling engine. prefers-reduced-motion removes movement while preserving state and focus behavior. The default theme follows the operating-system color scheme and also recognizes .light, .dark, and matching data-theme application themes.

The visual spotlight includes --tour-spotlight-padding so the target's focus ring is not dimmed. Pointer isolation still uses the target's real rectangle.

Accessibility evidence

Automated release tests cover dialog naming, focus containment, nested Escape, focus restoration, inert, target interaction, reduced motion, dark mode, and Chromium, Firefox, WebKit, mobile Chromium, and mobile WebKit projects. These checks do not replace assistive-technology testing. A release must not claim a manual NVDA, VoiceOver, or mobile screen-reader pass until that dated check is recorded by a human.

Reference standard

Implementation follows the WAI-ARIA dialog pattern. Tooltip semantics are not valid for a card that contains buttons or other focusable content.