Onboarding — آشنایی با محصول و «قطرهٔ روغن» از داکت لوگو

داکت شیشه‌ای لوگو، نمایندهٔ برند در بالای هر صفحهٔ توکاپس، در لحظهٔ شروع آشنایی خودش مایع می‌شود: کارت محو می‌شود و در همان جا قطره‌ای شفاف و روغنی شکل می‌گیرد. قطره روی عنصر واقعی هر مرحله می‌نشیند — عنصر از پشت قطره دیده می‌شود، فقط پررنگ‌تر و براق‌تر؛ هیچ‌چیز تار یا کپی نمی‌شود — معلق و سیال می‌ماند و حباب زیر آن با نوار پیشرفت هفت‌رنگ توضیح می‌دهد. در پایان، قطره به جای داکت برمی‌گردد و با نمایش کوتاهی (فنر، درخشش شیشه، بیرون‌آمدن لوگو، یک دور حلقهٔ هفت‌رنگ) دوباره داکت لوگو می‌شود. این رفتار ثابت بنیان است و در همهٔ تم‌ها یکی است؛ هر تم فقط حس حرکت را امضا می‌کند.

وضعیت: beta · لایه: ۴ (@tokapps/patternsکپی کد) · فراداده: packages/patterns/src/onboarding/Onboarding.metadata.jsonکپی کد · Storybook: TUK/Patterns/Onboardingکپی کد

import { Onboarding, OnboardingTour, OnboardingTourHost, openOnboardingTour, tourStepProps } from '@tokapps/patterns';

راهنمایی از دل کد

هر صفحه راهنمای خودش را کنار عناصر خودش نگه می‌دارد: عنصر را با tourStepProps()کپی کد (یا صفت‌های data-tour-idکپی کد / data-tour-titleکپی کد / data-tour-bodyکپی کد / data-tour-orderکپی کد / data-tour-paddingکپی کد) نشانه‌گذاری کنید. OnboardingTourHostکپی کد یک‌بار در قاب برنامه می‌نشیند و openOnboardingTour()کپی کد از هر جایی (دکمه، اولین ورود، مرکز راهنما) آن را باز می‌کند. مرحله‌ها خودکار از صفحه جمع می‌شوند (ترتیب orderکپی کد سپس ترتیب سند) و متن‌ها هم‌زبان و ترجمه‌پذیر با خود صفحه می‌مانند.

همین سایت میزبان را در قاب خود دارد؛ دکمهٔ زیر داکت لوگوی واقعی بالای صفحه را قطره می‌کند. با onceکپی کد فقط بار اول باز می‌شود («فراموش کن» آن را پاک می‌کند).

// app/layout.tsx — یک‌بار در قاب برنامهimport { OnboardingTourHost } from '@tokapps/patterns';export default function Layout({ children }) {  return (<>{children}<OnboardingTourHost /></>);}// app/page.tsx — عناصر واقعی را نشانه‌گذاری کنید و هر جا خواستید باز کنیدimport { Button } from '@tokapps/tuk/controls';import { openOnboardingTour, tourStepProps } from '@tokapps/patterns';<input {...tourStepProps({ id: 'search', title: 'جستجو همه‌جا در دسترس است', body: 'میان‌بر ⌘K هم کار می‌کند.' })} /><IdeaCard {...tourStepProps({ id: 'idea', title: 'ایده‌تان را ثبت کنید', body: 'دیگران رأی می‌دهند.', order: 2 })} /><Button onClick={() => openOnboardingTour({ once: 'home-v1' })}>شروع آشنایی</Button>

• openOnboardingTour({ stepsRoot: '#main' })کپی کد فقط داخل یک ریشه می‌گردد؛ steps: [...]کپی کد مرحله‌های صریح می‌دهد؛ optionsکپی کد حالت‌های همین اجرا را عوض می‌کند.
• onboardingTourSeen(key)کپی کد و resetOnboardingTour(key)کپی کد برای «راهنما را دوباره نشان بده» در تنظیمات.
• بدون هیچ عنصر نشانه‌گذاری‌شده، چیزی باز نمی‌شود.

نمونهٔ زنده (کنترل‌شده)

وقتی میزبان سراسری نمی‌خواهید، خود OnboardingTourکپی کد را با openکپی کد کنترل کنید. در نمونه‌های زیر مرحله‌ها از صفت‌های همان صحنه جمع می‌شوند (stepsRootکپی کد).

import { useState } from 'react';import { Button } from '@tokapps/tuk/controls';import { OnboardingTour, tourStepProps } from '@tokapps/patterns';function Page() {  const [open, setOpen] = useState(false);  return (    <section id="home">      <input {...tourStepProps({ id: 'search', title: 'جستجو همه‌جا در دسترس است', body: 'میان‌بر ⌘K هم کار می‌کند.' })} />      <Button onClick={() => setOpen(true)}>شروع آشنایی</Button>      <OnboardingTour open={open} onOpenChange={setOpen} stepsRoot="#home" onSkip={() => track('tour:skip')} onComplete={() => track('tour:done')} />    </section>  );}

حالت‌ها — دست توسعه‌دهنده باز است

مسیر (داکت → قطره → عناصر → داکت) ثابت است؛ حالت‌ها با چند prop انتخاب و با هم ترکیب می‌شوند.

تک‌رنگ تم

نوار پیشرفت و رِیم قطره با رنگ اکسنت تم؛ برای صفحه‌های آرام‌تر یا وقتی هفت‌رنگ جای دیگری در نما هست.

<OnboardingTour open={open} onOpenChange={setOpen} rim="accent" />

ته‌رنگ روی صفحه

پرده ته‌رنگ کمی می‌گیرد تا تمرکز بیشتر شود؛ همچنان بدون تاری و صفحه خوانا می‌ماند.

<OnboardingTour open={open} onOpenChange={setOpen} scrim="tint" />

حباب بالای عنصر

وقتی زیر عنصر جای مهمی است (مثلاً فرم). اگر بالا جا نباشد، خودکار پایین می‌رود.

<OnboardingTour open={open} onOpenChange={setOpen} bubblePlacement="above" />

آرام

بدون شناوری و بدون رِیم؛ قطره فقط می‌نشیند. مناسب محیط‌های پرتراکم یا داشبورد.

<OnboardingTour open={open} onOpenChange={setOpen} float={false} rim="none" />

بستن با کلیک بیرون

پیش‌فرض خاموش است تا کاربر ناخواسته آشنایی را از دست ندهد.

<OnboardingTour open={open} onOpenChange={setOpen} dismissOnOutsideClick />

مرحله‌های صریح

بدون صفت روی عناصر: هدف هر مرحله انتخابگر CSS، refکپی کد یا تابعی است که عنصر را برمی‌گرداند. paddingکپی کد حاشیهٔ قطره دور عنصر است.

<OnboardingTour  open={open}  onOpenChange={setOpen}  steps={[    { id: 'search', title: 'جستجو', body: 'میان‌بر ⌘K.', target: '#site-search' },    { id: 'profile', title: 'پروفایل', target: profileRef, padding: 8 },    { id: 'dock', title: 'منوی اصلی', target: () => document.querySelector('[data-tds="dock"]') },  ]}/>

کارت آشنایی

کارت کلاسیک برای صفحهٔ خوش‌آمد یا مودال؛ نوار پیشرفت accentکپی کد (پیش‌فرض) یا rainbowکپی کد. پیشرفت همیشه با متن «۲ از ۳» هم بیان می‌شود.

import { Onboarding } from '@tokapps/patterns';const steps = [  { id: 'welcome', title: 'به توکاپس خوش آمدید', body: 'این راهنما در چند قدم کوتاه نشان می‌دهد هر بخش کجاست.' },  { id: 'ideas', title: 'ایده‌های خود را ثبت کنید', body: 'هر ایده عنوان، توضیح کوتاه و یک نویسنده دارد.' },  { id: 'notify', title: 'از پیشرفت ایده‌ها باخبر شوید', body: 'اعلان‌ها را در مرکز اعلان‌ها ببینید.' },];<Onboarding steps={steps} onSkip={() => undefined} onComplete={() => undefined} /><Onboarding steps={steps} step={index} onStepChange={setIndex} onComplete={done} />   // کنترل‌شده<Onboarding steps={[steps[0]]} labels={{ finish: 'ورود به محصول' }} onComplete={done} /> // تک‌مرحله

حرکت ثابت

• زایش: داکت لوگو (data-tour-morph="away"کپی کد) محو و کمی کوچک می‌شود و در همان جا قطره پدیدار می‌شود؛ مکث کوتاه --tds-onboarding-tour-settleکپی کد تا تبدیل دیده شود.
• سفر: قطره با --tds-onboarding-tour-flowکپی کد به عنصر می‌رود؛ دنباله با --tds-onboarding-tour-tailکپی کد کندتر زیر فیلتر چسبنده کشیده می‌شود (کشیدگی روغنی). سیلوئت مایع کم‌رنگ است (--tds-onboarding-tour-liquid-opacityکپی کد) تا صفحه دیده شود.
• نشستن: فشردگی ژله‌ای کوتاه، سپس شناوری --tds-onboarding-tour-floatکپی کد و چرخش رِیم --tds-onboarding-tour-rim-speedکپی کد؛ عنصر از پشت قطره با saturate/contrast/brightnessکپی کد پررنگ‌تر دیده می‌شود (هرگز blurکپی کد).
• بازگشت برند: قطره به جای داکت برمی‌گردد و محو می‌شود؛ کارت با فنر پدیدار می‌شود، شیشه‌اش یک لحظه می‌درخشد، لوگو از دل آن بیرون می‌آید و حلقهٔ هفت‌رنگ دور کارت یک دور می‌چرخد و محو می‌شود (data-tour-morph="reborn"کپی کد).
• اگر TopBar نباشد، Dock پایین مبدأ است (تلّ روی لبه‌اش)؛ بدون هیچ‌کدام، جای فرضی لوگو در گوشهٔ آغازین بالا.
• کاهش حرکت: بدون سفر، فیلتر، شناوری و چرخش؛ قطره در جای هدف پدیدار می‌شود و داکت بی‌درنگ پنهان/پیدا می‌شود.

هویت هر تم

بنیان ثابت است؛ هر تم در packages/theme-<id>/src/onboarding-tour.cssکپی کد فقط توکن‌های زمان/منحنی و انیمیشن اسلات‌های مجاز (dropکپی کد, tailکپی کد, lensکپی کد, rimکپی کد, glintکپی کد, bubbleکپی کد) را امضا می‌کند (Onboarding.motion.tsکپی کد):

/* packages/theme-<id>/src/onboarding-tour.css — نمونه */[data-theme="funding"] { --tds-onboarding-tour-float: 6s; --tds-onboarding-tour-rim-speed: 12s; }[data-theme="funding"] [data-tds="onboarding-tour"][data-phase="settled"] [data-part="lens"] {  animation-name: tds-onboarding-tour-land, tds-onboarding-tour-funding-tide;}@keyframes tds-onboarding-tour-funding-tide { 0%, 100% { translate: 0 0; } 25% { translate: 0 -3px; } 75% { translate: 0 3px; } }

Storybook → TUK/Patterns/Onboardingکپی کد → Identitiesکپی کد هر شش تم را کنار هم نشان می‌دهد.

رفتار کیبورد، صفحه‌خوان و RTL

• Tabکپی کد/Shift+Tabکپی کد داخل حباب می‌چرخد؛ Escapeکپی کد رد کردن؛ ←کپی کد/→کپی کد قبل/بعد (RTL-aware)؛ Homeکپی کد/Endکپی کد. فوکوس پس از نشستن به عنوان مرحله می‌رود و با بستن به عنصر قبلی برمی‌گردد.
• حباب role="dialog" aria-modal="true"کپی کد؛ نوار پیشرفت role="progressbar"کپی کد با aria-valuetext="۲ از ۵"کپی کد. قطره و مایع تزئینی‌اند؛ عنصر واقعی دست نمی‌خورد.
• هندسهٔ قطره فیزیکی است و به جهت وابسته نیست؛ حباب با dirکپی کد سند؛ نوار در RTL از راست پر می‌شود.
• هفت‌رنگ (نوار و رِیم) در کنتراست بالا تک‌رنگ می‌شود؛ با prefers-reduced-transparencyکپی کد قطره کمی مات‌تر است، همچنان بدون تاری.

چه وقت استفاده کنیم

• اولین ورود کاربر به محصول با ۳ تا ۶ مرحلهٔ کوتاه
• نشان‌دادن جای واقعی عناصر روی صفحهٔ موجود (جستجو، داک، کارت) با قطرهٔ روغن
• هر صفحه‌ای که بخواهد راهنمایش را کنار کد خودش نگه دارد

چه وقت نه

• راهنمای مرجع با جستجو (مستندات)
• نکتهٔ تکی روی یک عنصر (Tooltip/Popover)
• فرم چندمرحله‌ای با داده‌های ورودی (Stepper + فرم)

API

میزبان: OnboardingTourHost(defaults)کپی کد, openOnboardingTour({ steps?, stepsRoot?, once?, options? })کپی کد, closeOnboardingTour()کپی کد, onboardingTourSeen(key)کپی کد, resetOnboardingTour(key)کپی کد, useOnboardingTourRequest()کپی کد. نشانه‌گذاری: tourStepProps({ id, title, body?, order?, padding? })کپی کد, collectTourSteps(root?)کپی کد.

آزمون و پیش‌نمایش

• Storybook: TUK/Patterns/Onboardingکپی کد (Tourکپی کد, TourAccentکپی کد, TourTintکپی کد, TourAboveکپی کد, TourCalmکپی کد, TourDismissableکپی کد, TourExplicitStepsکپی کد, TourGlobalHostکپی کد, Rainbowکپی کد, Identitiesکپی کد).
• تست واحد: packages/patterns/src/onboarding/Onboarding.test.tsxکپی کد (SSR، هندسه، data-tour-*کپی کد، قرارداد هویت شش تم).