Skip to content

feat: add first-time onboarding tour for Stellar flow#45

Closed
Dami24-hub wants to merge 1 commit into
wraith-protocol:mainfrom
Dami24-hub:feature/stellar-onboarding-tour
Closed

feat: add first-time onboarding tour for Stellar flow#45
Dami24-hub wants to merge 1 commit into
wraith-protocol:mainfrom
Dami24-hub:feature/stellar-onboarding-tour

Conversation

@Dami24-hub
Copy link
Copy Markdown

This PR implements Issue #17: First-time user onboarding tour for Stellar flow. It introduces a lightweight, interactive, and fully accessible onboarding wizard to guide new users through the Stellar stealth payment flow, reducing immediate bounce rates and clarifying the platform's core UX mechanics.

A new Git branch feature/stellar-onboarding-tour was created and pushed to remote upstream prior to development.

Problem Context

First-time visitors landing on the demo are often overwhelmed by the specialized stealth-address terminology, the wallet connection mechanics, and the overall UI. Without a clear step-by-step introduction, users struggle to build a proper mental model of how private Stellar payments function, leading to drop-offs.

Proposed Changes

Tour Implementation & Architecture

  • Library Selection: Integrated driver.js due to its ultra-lightweight footprint (<10 KB gzipped) and stellar accessibility compliance.
  • State Persistence: Implemented a check on localStorage.wraith.tourCompleted. The tour automatically triggers for new users on the home/send page and sets this flag to true upon completion or manual dismissal, preventing annoying auto-relaunches.
  • Manual Reset: Added a "Take the tour" interactive link within the site footer to let users manually restart the flow at any time.

The 5-Step Guided Flow

All copy has been externalized to src/i18n/en.json to preserve future localization capabilities:

  1. Step 1 (Header/Wallet): Introduces Wraith as a private payment layer on Stellar testnet and prompts a wallet connection.
  2. Step 2 (Post-Connect): Explains the cryptographic safety of the local stealth-key derivation message.
  3. Step 3 (Recipient Input): Guides users on entering a Stellar stealth meta-address or a .wraith domain name.
  4. Step 4 (Amount Input): Explains how fresh stealth addresses are generated dynamically on-chain.
  5. Step 5 (Submit/Send): Explains the privacy mechanism (unlinkable target addresses) seen by network observers.

Accessibility & UX Guardrails

  • Keyboard Navigation: Enabled full keyboard traversal (Arrow keys to navigate, Esc to instantly dismiss).
  • Reduced Motion: Hooked into the prefers-reduced-motion media query to disable animations gracefully for users with motion sensitivities.
  • Non-Blocking Overlay: Configured the overlay to ensure it does not trap user clicks, allowing seamless abandonment or manual UI exploration.

Technical Checklist

  • Lightweight onboarding library added (<10KB gzipped impact).
  • All 5 steps mapped to correct UI anchor elements.
  • State tracking via localStorage fully functional.
  • Hardcoded strings avoided; copy centralized in src/i18n/en.json.
  • Manual trigger added to the application footer.

Types of Changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)

Testing & Verification

Automated Tests

  • Added a comprehensive Playwright E2E test suite in tests/onboarding.spec.ts covering:
    • The happy-path workflow completion (Steps 1 through 5).
    • Dismissal via the Skip button and the Esc key.
    • Verification that localStorage correctly persists and blocks auto-firing upon page reload.

Manual Verification Checklist

  • Persistence: Verified that refreshing the page after closing the tour does not re-trigger it.
  • Footer Link: Confirmed clicking "Take the tour" in the footer forces a manual restart regardless of storage flags.
  • A11y: Focus management manually tested using Chrome DevTools and keyboard-only tracking.

Closes #17

- Install driver.js (6.4 KB gzipped, < 10 KB constraint)
- Add i18n keys in src/i18n/en.json under onboardingTour.*
- Implement useStellarTour hook with 5-step driver.js tour
- Add data-tour attributes to wallet button, recipient input,
  amount input, and send button
- Auto-start tour on /send when wraith.tourCompleted is unset
- Add footer 'Take the tour' button to force-restart tour
- Respect prefers-reduced-motion (disables animations)
- No spotlight overlay (overlayOpacity: 0) — users can click freely
- Add Playwright E2E tests covering happy path, dismissal
  persistence, no auto-fire on reload, and footer restart

Closes wraith-protocol#17
@vercel
Copy link
Copy Markdown

vercel Bot commented Jun 1, 2026

@Dami24-hub is attempting to deploy a commit to the truthixify's projects Team on Vercel.

A member of the Team first needs to authorize it.

@drips-wave
Copy link
Copy Markdown

drips-wave Bot commented Jun 1, 2026

@Dami24-hub Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@truthixify
Copy link
Copy Markdown
Contributor

Closing as duplicate. Issue #17 is being handled in #39 which was opened first (waiting on a rebase).

If #39's content doesn't end up covering everything you have here (i18n strings, specific tour steps, custom mock approach), feel free to open a small follow-up PR after #39 lands. Otherwise, open Stellar Wave issues: https://github.com/wraith-protocol/demo/issues?q=is%3Aopen+label%3A%22Stellar+Wave%22

Thanks @Dami24-hub.

@truthixify truthixify closed this Jun 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

First-time user onboarding tour for Stellar flows

2 participants