Issue — Post-Signup Coach-Mark Tours (Tutors & Parents/Students)

Summary

When a new Tutor finishes onboarding, or a Parent/Student creates an account, they currently land on a dashboard with no clear next steps. We need a "game-tutorial" style spotlight tour that dims the background, highlights key UI elements, and guides them through the platform's core features.

1. Technical & UI Requirements (DO NOT build from scratch)

Do not write a custom CSS overlay engine for this. It will cause z-index stacking bugs.

• Library Recommendation: Use a standard lightweight library like driver.js (highly recommended, vanilla JS/React compatible) or react-joyride.
• Visual Style:
  • Overlay: Dark semi-transparent background (rgba(0,0,0,0.6) or tailwind bg-black/60).
  • Spotlight: A clean cutout over the target element with a 2px-4px padding so the button breathes.
  • Popover/Tooltip: White card, clean rounded corners, pointing arrow to the highlighted element.
  • Controls: "Next", "Skip Tour" (dismisses forever), and "Done" at the end. Progress dots are optional.
• Mobile Behavior: The library MUST automatically scroll the page to bring the next highlighted element into the viewport.
• Graceful Failure (Ghost Elements): If a target DOM element is not currently visible on the screen (e.g., hidden under a mobile menu), the tour should gracefully skip that step rather than throwing a JS error and freezing the screen.

2. Trigger Logic & State

• Do not fire a blind tour immediately on signup (users dismiss pop-ups).
• Tutor Trigger: Fires exactly once after the tutor profile is approved and published (not merely submitted), when they next land on Dashboard / Profile editor.
• Parent/Student Trigger: Fires exactly once on the first interaction with the main search bar or the first view of a tutor card — not on account-create alone.
• Persistence: Store a boolean flag in the database (e.g., has_seen_tutor_tour: true / has_seen_parent_tour: true) or localStorage so it never triggers again once completed or skipped.
• Library: Keep driver.js as recommended.

3. Tutor Tour Flow (DOM Targets & Copy)

Developer Note: Attach id or data-tour attributes to these elements.

1. Target: Public Profile Preview Button/Card
   • Copy: "This is how parents see you. Your phone number and email are always hidden."
2. Target: Edit Profile / Rates Section
   • Copy: "Update your subjects, bio, and set your 1-on-1 or Small Group rates here."
3. Target: Verification / Blue Tick (verification badge)
   • Copy: "Submit your transcripts to earn the Blue Tick verification badge. Unverified tutors must show proof before the first lesson."
4. Target: Shop / Sell Notes Entry Point
   • Copy: "Upload study notes, video courses, or services here. Parents buy them directly and you keep 80%."
5. Target: Open Cases / Jobs Board
   • Copy: "Browse open student requests and claim cases that fit your schedule."
6. Target: (No target, center screen modal)
   • Copy: "You're all set! Check your WhatsApp for new case introductions from our concierge team."

4. Parent / Student Tour Flow (DOM Targets & Copy)

1. Target: Main Search Bar / Filters
   • Copy: "Filter tutors by curriculum (IB/DSE), subject, or MTR district."
2. Target: Any Tutor Card (first in list)
   • Copy: "Click any card to see full academic scores, group class rates, and verified experience."
3. Target: 'Save/Heart' Button on a card
   • Copy: "Save your favorite tutors to compare them later."
4. Target: Shop / Study Materials Row
   • Copy: "Browse the Shop to instantly buy study notes, video courses, and past paper reviews."
5. Target: 'Request Tutor' / Concierge Button
   • Copy: "Found a match or need help deciding? Send a request and our team will coordinate the introduction."

Acceptance Criteria

• Implement driver.js (or similar) to handle spotlight, overlay, and popovers.
• Tour triggers only per contextual rules above (tutor: after approved/published; parent: first search bar or first tutor card) — not blind post-signup.
• Dismissing ("Skip Tour") or finishing the tour sets a flag so it does not reappear on reload.
• Tour auto-scrolls correctly on mobile devices to find the highlighted element.
• If a UI element is missing from the DOM, the tour skips that step without breaking.
• Z-index of the highlighted element and popover sits cleanly above the overlay, even for sticky headers.

CEO / Gemini notes (2026-10-21 SAFE)

Product locks

• Badge language: Blue Tick / verification badge only — never “Gold Verified”.
• Library: driver.js (preferred) or react-joyride — do not hand-roll overlay z-index.
• Contextual triggers (not blind post-signup):
  • Tutor: fire once after profile is approved/published, when they next land on account / profile surfaces (prefer live routes /account and related editor entry points — not a fake post-submit splash).
  • Parent/Student: fire once on first visit to /tutors (or first meaningful search/card interaction on that surface) — not on account-create alone.
• Persist dismiss/complete (has_seen_tutor_tour / has_seen_parent_tour or equivalent) so it never loops.

Live route targets

• Tutor tour DOM targets should exist on live /account (and public profile preview entry) after publish.
• Parent tour DOM targets on live /tutors explore (search bar, first card, save, shop row, request CTA).
• Do not invent deprecated dashboard URLs; attach data-tour / id hooks on current components.

Copy

• Keep EN step copy in §§3–4 above.
• Ship EN first; add zh-HK / zh-CN tour strings in the same PR when Feature: Traditional & Simplified Chinese UI + Dynamic SEO Meta Titles #401 locale files are touched (parity preferred). Do not block the tour on perfect literary translation — but do not leave raw i18n keys visible.

Sequencing

• Ship after Feature: Dual-Language Custom Headline + Core Academic Breakdown Restructure #411 / [Compliance / B2B] Extend centre partnership (#251/#256–258): 3-step EA-safe triage, BR org fields, COMPLIANCE_HOLD, How-it-works Partners tab #412 / [Feature · V1] Extracurriculars — hybrid tags, portfolio, ecosystem #415 profile sections exist so tour targets are stable.