From a7808a471b707e1fd223dba4c1197cc03cc91e02 Mon Sep 17 00:00:00 2001
From: dc <eopoxf@gmail.com>
Date: Thu, 23 Oct 2025 15:07:11 +0530
Subject: [PATCH] Add basic touring feature

---
 app/[locale]/(user)/components/Content.tsx    |  13 +-
 .../(user)/components/ListingComponent.tsx    |  12 +-
 .../DatasetDetailsPage.tsx                    |  12 +-
 .../[entitySlug]/dataset/page.tsx             |   6 +
 app/[locale]/dashboard/page.tsx               |   7 +-
 components/Tour/TourButton.tsx                |  75 +++
 components/Tour/TourGuide.tsx                 | 171 ++++++
 components/Tour/index.ts                      |   2 +
 components/provider.tsx                       |  17 +-
 config/tours.ts                               | 230 ++++++++
 contexts/TourContext.tsx                      | 157 ++++++
 docs/TOUR_GUIDE.md                            | 489 ++++++++++++++++++
 hooks/use-tour-trigger.ts                     |  58 +++
 lib/tour-utils.ts                             | 271 ++++++++++
 package-lock.json                             | 145 ++++++
 package.json                                  |   1 +
 types/tour.ts                                 | 180 +++++++
 17 files changed, 1829 insertions(+), 17 deletions(-)
 create mode 100644 components/Tour/TourButton.tsx
 create mode 100644 components/Tour/TourGuide.tsx
 create mode 100644 components/Tour/index.ts
 create mode 100644 config/tours.ts
 create mode 100644 contexts/TourContext.tsx
 create mode 100644 docs/TOUR_GUIDE.md
 create mode 100644 hooks/use-tour-trigger.ts
 create mode 100644 lib/tour-utils.ts
 create mode 100644 types/tour.ts

diff --git a/app/[locale]/(user)/components/Content.tsx b/app/[locale]/(user)/components/Content.tsx
index 8c96b20f..9fea2c38 100644
--- a/app/[locale]/(user)/components/Content.tsx
+++ b/app/[locale]/(user)/components/Content.tsx
@@ -10,6 +10,7 @@ import { SearchInput, Spinner, Tag, Text } from 'opub-ui';
 import { GraphQL } from '@/lib/api';
 import { cn } from '@/lib/utils';
 import Styles from '../page.module.scss';
+import { useTourTrigger } from '@/hooks/use-tour-trigger';
 
 const statsInfo: any = graphql(`
   query StatsList {
@@ -34,6 +35,10 @@ const statsInfo: any = graphql(`
 
 export const Content = () => {
   const router = useRouter();
+  
+  // Enable tour for first-time users
+  useTourTrigger(true, 1500);
+  
   const Stats: { data: any; isLoading: any } = useQuery([`statsDetails`], () =>
     GraphQL(statsInfo, {}, [])
   );
@@ -104,7 +109,11 @@ export const Content = () => {
           ) : (
             <div className="flex flex-wrap items-center gap-4 md:gap-0 lg:gap-0 ">
               {Metrics.map((item, index) => (
-                <Link key={`${item.label}_${index}`} href={item.link}>
+                <Link 
+                  key={`${item.label}_${index}`} 
+                  href={item.link}
+                  data-tour={index === 0 ? 'datasets-link' : index === 1 ? 'usecases-link' : index === 2 ? 'publishers-link' : undefined}
+                >
                   <div
                     key={index}
                     className="flex flex-col border-x-[1px] border-solid border-tertiaryAccent px-4"
@@ -123,7 +132,7 @@ export const Content = () => {
               ))}
             </div>
           )}
-          <div className="w-full">
+          <div className="w-full" data-tour="search-bar">
             <SearchInput
               className={cn(Styles.Search)}
               onSubmit={handleSearch}
diff --git a/app/[locale]/(user)/components/ListingComponent.tsx b/app/[locale]/(user)/components/ListingComponent.tsx
index 5a349f76..96c3a297 100644
--- a/app/[locale]/(user)/components/ListingComponent.tsx
+++ b/app/[locale]/(user)/components/ListingComponent.tsx
@@ -23,6 +23,7 @@ import { fetchData } from '@/fetch';
 import { cn, formatDate } from '@/lib/utils';
 import Filter from '../datasets/components/FIlter/Filter';
 import Styles from '../datasets/dataset.module.scss';
+import { useTourTrigger } from '@/hooks/use-tour-trigger';
 
 // Helper function to strip markdown and HTML tags for card preview
 const stripMarkdown = (markdown: string): string => {
@@ -256,6 +257,8 @@ const ListingComponent: React.FC<ListingProps> = ({
   redirectionURL,
   lockedFilters = {},
 }) => {
+  useTourTrigger(true, 1500);
+  
   const [facets, setFacets] = useState<{
     results: any[];
     total: number;
@@ -397,7 +400,7 @@ const ListingComponent: React.FC<ListingProps> = ({
 
         <div className="mt-5 lg:mt-10">
           <div className="row mb-16 flex gap-5 ">
-            <div className="hidden min-w-64 max-w-64 lg:block">
+            <div className="hidden min-w-64 max-w-64 lg:block" data-tour="filters">
               <Filter
                 options={filterOptions}
                 setSelectedOptions={handleFilterChange}
@@ -408,7 +411,7 @@ const ListingComponent: React.FC<ListingProps> = ({
 
             <div className="flex w-full flex-col gap-4 px-2">
               <div className="flex flex-wrap items-center justify-between gap-5 rounded-2 py-2 lg:flex-nowrap">
-                <div className="w-full md:block">
+                <div className="w-full md:block" data-tour="search">
                   <SearchInput
                     key={queryParams.query}
                     label="Search"
@@ -468,7 +471,7 @@ const ListingComponent: React.FC<ListingProps> = ({
                       />
                     </Button>
                   </div>
-                  <div className="flex items-center gap-2">
+                  <div className="flex items-center gap-2" data-tour="sort">
                     <Select
                       label=""
                       labelInline
@@ -541,7 +544,7 @@ const ListingComponent: React.FC<ListingProps> = ({
                   onPageSizeChange={handlePageSizeChange}
                   view={view}
                 >
-                  {datasetDetails.map((item: any) => {
+                  {datasetDetails.map((item: any, index: number) => {
                     const image = item.is_individual_dataset
                       ? item?.user?.profile_picture
                         ? `${process.env.NEXT_PUBLIC_BACKEND_URL}/${item.user.profile_picture}`
@@ -654,6 +657,7 @@ const ListingComponent: React.FC<ListingProps> = ({
                         }
                         iconColor="warning"
                         href={`${redirectionURL}/${item.id}`}
+                        data-tour={index === 0 && type === 'dataset' ? 'dataset-card' : index === 0 && type === 'usecase' ? 'usecase-card' : undefined}
                       />
                     );
                   })}
diff --git a/app/[locale]/(user)/datasets/[datasetIdentifier]/DatasetDetailsPage.tsx b/app/[locale]/(user)/datasets/[datasetIdentifier]/DatasetDetailsPage.tsx
index f89c5ef6..cc7340be 100644
--- a/app/[locale]/(user)/datasets/[datasetIdentifier]/DatasetDetailsPage.tsx
+++ b/app/[locale]/(user)/datasets/[datasetIdentifier]/DatasetDetailsPage.tsx
@@ -13,6 +13,7 @@ import Metadata from './components/Metadata';
 import PrimaryData from './components/PrimaryData';
 import Resources from './components/Resources';
 import SimilarDatasets from './components/SimilarDatasets';
+import { useTourTrigger } from '@/hooks/use-tour-trigger';
 
 const datasetQuery: any = graphql(`
   query getDataset($datasetId: UUID!) {
@@ -84,6 +85,9 @@ export default function DatasetDetailsPage({
 }: {
   datasetId: string;
 }) {
+  // Enable tour for first-time users
+  useTourTrigger(true, 1500);
+  
   const Datasetdetails: { data: any; isLoading: any } = useQuery(
     [`details_${datasetId}`],
     () => GraphQL(datasetQuery, {}, { datasetId: datasetId })
@@ -114,7 +118,7 @@ export default function DatasetDetailsPage({
           ]}
         />
         <div className="flex">
-          <div className="w-full gap-10 border-r-2 border-solid border-greyExtralight p-6 lg:w-3/4 lg:p-10">
+          <div className="w-full gap-10 border-r-2 border-solid border-greyExtralight p-6 lg:w-3/4 lg:p-10" data-tour="dataset-info">
             {Datasetdetails.isLoading ? (
               <div className=" mt-8 flex justify-center">
                 <Spinner />
@@ -125,9 +129,9 @@ export default function DatasetDetailsPage({
                 isLoading={Datasetdetails.isLoading}
               />
             )}
-            <Details />
-            <Resources />
-            <SimilarDatasets />
+            <Details data-tour="preview" />
+            <Resources data-tour="download-button" />
+            <SimilarDatasets data-tour="related-datasets" />
           </div>
           <div className=" hidden  w-1/4 gap-10 px-7 py-10 lg:block">
             {Datasetdetails.isLoading ? (
diff --git a/app/[locale]/dashboard/[entityType]/[entitySlug]/dataset/page.tsx b/app/[locale]/dashboard/[entityType]/[entitySlug]/dataset/page.tsx
index e410d50d..c6f99c91 100644
--- a/app/[locale]/dashboard/[entityType]/[entitySlug]/dataset/page.tsx
+++ b/app/[locale]/dashboard/[entityType]/[entitySlug]/dataset/page.tsx
@@ -15,6 +15,7 @@ import { ActionBar } from './components/action-bar';
 import { Content } from './components/content';
 import { Navigation } from './components/navigate-org-datasets';
 import { formatDate } from '@/lib/utils';
+import { useTourTrigger } from '@/hooks/use-tour-trigger';
 
 const allDatasetsQueryDoc: any = graphql(`
   query allDatasetsQuery($filters: DatasetFilter, $order: DatasetOrder) {
@@ -69,6 +70,8 @@ export default function DatasetPage({
 }: {
   params: { entityType: string; entitySlug: string };
 }) {
+  useTourTrigger(true, 1500);
+  
   const router = useRouter();
 
   const [navigationTab, setNavigationTab] = useQueryState('tab', parseAsString);
@@ -252,6 +255,7 @@ export default function DatasetPage({
         <Navigation
           setNavigationTab={setNavigationTab}
           options={navigationOptions}
+          data-tour="sidebar"
         />
 
         {AllDatasetsQuery.data?.datasets.length > 0 ? (
@@ -264,6 +268,7 @@ export default function DatasetPage({
                 content: 'Add New Dataset',
                 onAction: () => CreateDatasetMutation.mutate(),
               }}
+              data-tour="create-dataset"
             />
 
             <DataTable
@@ -271,6 +276,7 @@ export default function DatasetPage({
               rows={generateTableData(AllDatasetsQuery.data.datasets)}
               hideSelection
               hideViewSelector
+              data-tour="my-datasets"
             />
           </div>
         ) : AllDatasetsQuery.isLoading ? (
diff --git a/app/[locale]/dashboard/page.tsx b/app/[locale]/dashboard/page.tsx
index 89db6085..98cb31ae 100644
--- a/app/[locale]/dashboard/page.tsx
+++ b/app/[locale]/dashboard/page.tsx
@@ -7,8 +7,12 @@ import BreadCrumbs from '@/components/BreadCrumbs';
 import { Icons } from '@/components/icons';
 import { Loading } from '@/components/loading';
 import { useDashboardStore } from '@/config/store';
+import { useTourTrigger } from '@/hooks/use-tour-trigger';
 
 const UserDashboard = () => {
+  // Enable tour for first-time users
+  useTourTrigger(true, 1500);
+  
   const { userDetails } = useDashboardStore();
   const list = [
     {
@@ -43,12 +47,13 @@ const UserDashboard = () => {
             <Text variant="headingXl"> User Dashboard</Text>
           </div>
           <div className="flex-1 ">
-            <div className="flex flex-wrap items-center gap-6 md:flex-nowrap lg:flex-nowrap">
+            <div className="flex flex-wrap items-center gap-6 md:flex-nowrap lg:flex-nowrap" data-tour="sidebar">
               {list.map((item, index) => (
                 <Link
                   key={index}
                   href={item.path}
                   className=" flex max-h-56 min-h-56 w-full flex-col  items-center justify-center gap-3 rounded-4 bg-greyExtralight p-4 "
+                  data-tour={index === 0 ? 'my-datasets' : undefined}
                 >
                   <Icon source={item.icon} size={60} color="highlight" />
                   <Text variant="headingLg">{item.label}</Text>
diff --git a/components/Tour/TourButton.tsx b/components/Tour/TourButton.tsx
new file mode 100644
index 00000000..6533bdcb
--- /dev/null
+++ b/components/Tour/TourButton.tsx
@@ -0,0 +1,75 @@
+'use client';
+
+import React from 'react';
+import { useManualTour } from '@/hooks/use-tour-trigger';
+import { HelpCircle } from 'lucide-react';
+
+interface TourButtonProps {
+  variant?: 'icon' | 'text' | 'both';
+  className?: string;
+  label?: string;
+}
+
+/**
+ * Button component to manually trigger the tour for current page
+ * Can be placed in header, footer, or anywhere on the page
+ */
+export function TourButton({ 
+  variant = 'both', 
+  className = '',
+  label = 'Take a tour'
+}: TourButtonProps) {
+  const { startTour, hasTour, isTourRunning } = useManualTour();
+
+  // Don't render if no tour available for current page
+  if (!hasTour) {
+    return null;
+  }
+
+  // Don't render if tour is already running
+  if (isTourRunning) {
+    return null;
+  }
+
+  const baseClasses = 'inline-flex items-center gap-2 rounded-md transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-actionPrimaryBasicDefault';
+  
+  const variantClasses = {
+    icon: 'p-2 hover:bg-actionSecondaryBasicHovered',
+    text: 'px-4 py-2 text-sm font-medium text-textMedium hover:text-textDefault hover:bg-actionSecondaryBasicHovered',
+    both: 'px-4 py-2 text-sm font-medium bg-actionSecondaryBasicDefault hover:bg-actionSecondaryBasicHovered text-textDefault',
+  };
+
+  return (
+    <button
+      onClick={startTour}
+      className={`${baseClasses} ${variantClasses[variant]} ${className}`}
+      aria-label={label}
+      title={label}
+    >
+      <HelpCircle className="w-4 h-4" />
+      {(variant === 'text' || variant === 'both') && <span>{label}</span>}
+    </button>
+  );
+}
+
+/**
+ * Floating action button for tour - positioned fixed on screen
+ */
+export function FloatingTourButton() {
+  const { startTour, hasTour, isTourRunning } = useManualTour();
+
+  if (!hasTour || isTourRunning) {
+    return null;
+  }
+
+  return (
+    <button
+      onClick={startTour}
+      className="fixed bottom-6 right-6 z-50 flex items-center justify-center w-14 h-14 rounded-full bg-actionPrimaryBasicDefault text-textOnBGDefault shadow-lg hover:bg-actionPrimaryBasicHovered transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-actionPrimaryBasicDefault"
+      aria-label="Take a tour"
+      title="Take a tour"
+    >
+      <HelpCircle className="w-6 h-6" />
+    </button>
+  );
+}
diff --git a/components/Tour/TourGuide.tsx b/components/Tour/TourGuide.tsx
new file mode 100644
index 00000000..6728f7f4
--- /dev/null
+++ b/components/Tour/TourGuide.tsx
@@ -0,0 +1,171 @@
+'use client';
+
+import React, { useEffect } from 'react';
+import Joyride, { CallBackProps, STATUS, EVENTS, ACTIONS } from 'react-joyride';
+import { useTour } from '@/contexts/TourContext';
+
+/**
+ * Custom styled TourGuide component using React Joyride
+ * Styled according to platform design language
+ */
+export function TourGuide() {
+  const { activeTour, isTourRunning, stepIndex, nextStep, prevStep, stopTour, isMobile } = useTour();
+
+  // Handle Joyride callbacks
+  const handleJoyrideCallback = (data: CallBackProps) => {
+    const { status, type, action } = data;
+
+    // Tour finished or skipped
+    if ([STATUS.FINISHED, STATUS.SKIPPED].includes(status as any)) {
+      stopTour();
+      return;
+    }
+
+    // Handle step changes
+    if (type === EVENTS.STEP_AFTER) {
+      if (action === ACTIONS.NEXT) {
+        nextStep();
+      } else if (action === ACTIONS.PREV) {
+        prevStep();
+      } else if (action === ACTIONS.CLOSE) {
+        stopTour();
+      }
+    }
+
+    // Handle target not found
+    if (type === EVENTS.TARGET_NOT_FOUND) {
+      console.warn('Tour target not found, skipping step');
+      nextStep();
+    }
+  };
+
+  // Disable body scroll when tour is running (optional)
+  useEffect(() => {
+    if (isTourRunning && activeTour?.disableScrolling) {
+      document.body.style.overflow = 'hidden';
+      return () => {
+        document.body.style.overflow = '';
+      };
+    }
+  }, [isTourRunning, activeTour]);
+
+  if (!activeTour || !isTourRunning) {
+    return null;
+  }
+
+  return (
+    <Joyride
+      steps={activeTour.steps}
+      run={isTourRunning}
+      stepIndex={stepIndex}
+      continuous={activeTour.continuous ?? true}
+      showProgress={activeTour.showProgress ?? true}
+      showSkipButton={activeTour.showSkipButton ?? true}
+      callback={handleJoyrideCallback}
+      disableScrolling={activeTour.disableScrolling ?? false}
+      disableOverlayClose={false}
+      hideCloseButton={false}
+      scrollToFirstStep={true}
+      scrollOffset={100}
+      spotlightClicks={false}
+      // Custom styles matching platform design
+      styles={{
+        options: {
+          arrowColor: 'var(--base-pure-white)',
+          backgroundColor: 'var(--base-pure-white)',
+          overlayColor: 'rgba(0, 0, 0, 0.5)',
+          primaryColor: 'var(--base-violet-solid-9)',
+          textColor: 'var(--text-default)',
+          width: isMobile ? 300 : 400,
+          zIndex: 10000,
+        },
+        tooltip: {
+          borderRadius: 'var(--border-radius-md, 8px)',
+          padding: isMobile ? 16 : 20,
+          boxShadow: '0 8px 24px rgba(0, 0, 0, 0.15)',
+        },
+        tooltipContainer: {
+          textAlign: 'left',
+        },
+        tooltipTitle: {
+          fontSize: isMobile ? '16px' : '18px',
+          fontWeight: 600,
+          color: 'var(--text-default)',
+          marginBottom: 8,
+        },
+        tooltipContent: {
+          fontSize: isMobile ? '14px' : '15px',
+          lineHeight: 1.6,
+          color: 'var(--text-medium)',
+          padding: '8px 0',
+        },
+        buttonNext: {
+          backgroundColor: 'var(--action-primary-basic-default)',
+          borderRadius: 'var(--border-radius-sm, 6px)',
+          color: 'var(--text-on-bg-default)',
+          fontSize: isMobile ? '13px' : '14px',
+          fontWeight: 500,
+          padding: isMobile ? '8px 16px' : '10px 20px',
+          outline: 'none',
+          border: 'none',
+          cursor: 'pointer',
+          transition: 'background-color 0.2s ease',
+        },
+        buttonBack: {
+          backgroundColor: 'transparent',
+          borderRadius: 'var(--border-radius-sm, 6px)',
+          color: 'var(--text-medium)',
+          fontSize: isMobile ? '13px' : '14px',
+          fontWeight: 500,
+          padding: isMobile ? '8px 16px' : '10px 20px',
+          outline: 'none',
+          border: '1px solid var(--border-default)',
+          cursor: 'pointer',
+          marginRight: 8,
+          transition: 'all 0.2s ease',
+        },
+        buttonSkip: {
+          backgroundColor: 'transparent',
+          color: 'var(--text-subdued)',
+          fontSize: isMobile ? '12px' : '13px',
+          fontWeight: 500,
+          padding: isMobile ? '6px 12px' : '8px 16px',
+          outline: 'none',
+          border: 'none',
+          cursor: 'pointer',
+          transition: 'color 0.2s ease',
+        },
+        buttonClose: {
+          color: 'var(--text-subdued)',
+          fontSize: '20px',
+          padding: 8,
+          outline: 'none',
+          border: 'none',
+          cursor: 'pointer',
+          transition: 'color 0.2s ease',
+        },
+        spotlight: {
+          borderRadius: 'var(--border-radius-md, 8px)',
+        },
+        beacon: {
+          backgroundColor: 'var(--action-primary-basic-default)',
+          borderRadius: '50%',
+        },
+        beaconInner: {
+          backgroundColor: 'var(--action-primary-basic-default)',
+        },
+        beaconOuter: {
+          backgroundColor: 'var(--action-primary-basic-default)',
+          border: '2px solid var(--action-primary-basic-default)',
+        },
+      }}
+      locale={{
+        back: 'Back',
+        close: 'Close',
+        last: 'Finish',
+        next: 'Next',
+        skip: 'Skip tour',
+      }}
+    />
+  );
+}
diff --git a/components/Tour/index.ts b/components/Tour/index.ts
new file mode 100644
index 00000000..c423ae83
--- /dev/null
+++ b/components/Tour/index.ts
@@ -0,0 +1,2 @@
+export { TourGuide } from './TourGuide';
+export { TourButton, FloatingTourButton } from './TourButton';
diff --git a/components/provider.tsx b/components/provider.tsx
index 317706a6..e107a994 100644
--- a/components/provider.tsx
+++ b/components/provider.tsx
@@ -9,6 +9,8 @@ import { Toaster, Tooltip } from 'opub-ui';
 
 import { RouterEvents } from '@/lib/navigation';
 import SessionGuard from './SessionGuard';
+import { TourProvider } from '@/contexts/TourContext';
+import { TourGuide } from './Tour';
 
 export default function Provider({ children }: { children: React.ReactNode }) {
   const [client] = React.useState(
@@ -40,12 +42,15 @@ export default function Provider({ children }: { children: React.ReactNode }) {
       <SessionProvider>
         <SessionGuard>
           <QueryClientProvider client={client}>
-            <RouterEvents />
-            <HolyLoader color="var(--action-primary-success-default)" />
-            <Tooltip.Provider>
-              {children}
-              <Toaster />
-            </Tooltip.Provider>
+            <TourProvider>
+              <RouterEvents />
+              <HolyLoader color="var(--action-primary-success-default)" />
+              <Tooltip.Provider>
+                {children}
+                <Toaster />
+              </Tooltip.Provider>
+              <TourGuide />
+            </TourProvider>
           </QueryClientProvider>
         </SessionGuard>
       </SessionProvider>
diff --git a/config/tours.ts b/config/tours.ts
new file mode 100644
index 00000000..85c438f2
--- /dev/null
+++ b/config/tours.ts
@@ -0,0 +1,230 @@
+import { Step } from 'react-joyride';
+
+/**
+ * Tour configuration type
+ */
+export interface TourConfig {
+  id: string;
+  name: string;
+  steps: Step[];
+  continuous?: boolean;
+  showProgress?: boolean;
+  showSkipButton?: boolean;
+  disableScrolling?: boolean;
+}
+
+/**
+ * Home page tour configuration
+ */
+export const homeTour: TourConfig = {
+  id: 'home-tour',
+  name: 'Home Page Tour',
+  continuous: true,
+  showProgress: true,
+  showSkipButton: true,
+  steps: [
+    {
+      target: 'body',
+      content: 'Welcome to CivicDataSpace! Let\'s take a quick tour to help you get started.',
+      placement: 'center',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="search-bar"]',
+      content: 'Use the search bar to quickly find datasets, use cases, and other resources.',
+      placement: 'bottom',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="datasets-link"]',
+      content: 'Browse all available datasets organized by categories and sectors.',
+      placement: 'bottom',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="usecases-link"]',
+      content: 'Explore real-world use cases and applications of our data.',
+      placement: 'bottom',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="publishers-link"]',
+      content: 'View all data publishers and organizations contributing to the platform.',
+      placement: 'bottom',
+      disableBeacon: true,
+    },
+  ],
+};
+
+/**
+ * Datasets listing page tour
+ */
+export const datasetsListingTour: TourConfig = {
+  id: 'datasets-listing-tour',
+  name: 'Datasets Listing Tour',
+  continuous: true,
+  showProgress: true,
+  showSkipButton: true,
+  steps: [
+    {
+      target: '[data-tour="filters"]',
+      content: 'Use filters to narrow down datasets by sector, organization, tags, and more.',
+      placement: 'right',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="search"]',
+      content: 'Search for specific datasets using keywords.',
+      placement: 'bottom',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="sort"]',
+      content: 'Sort datasets by relevance, date, or alphabetically.',
+      placement: 'bottom',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="dataset-card"]',
+      content: 'Click on any dataset card to view detailed information and download options.',
+      placement: 'top',
+      disableBeacon: true,
+    },
+  ],
+};
+
+/**
+ * Dataset detail page tour
+ */
+export const datasetDetailTour: TourConfig = {
+  id: 'dataset-detail-tour',
+  name: 'Dataset Detail Tour',
+  continuous: true,
+  showProgress: true,
+  showSkipButton: true,
+  steps: [
+    {
+      target: '[data-tour="dataset-info"]',
+      content: 'View comprehensive information about the dataset including description, metadata, and publisher details.',
+      placement: 'bottom',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="download-button"]',
+      content: 'Download the dataset in various formats.',
+      placement: 'left',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="preview"]',
+      content: 'Preview the dataset structure and sample data.',
+      placement: 'top',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="related-datasets"]',
+      content: 'Discover related datasets that might be useful for your work.',
+      placement: 'top',
+      disableBeacon: true,
+    },
+  ],
+};
+
+/**
+ * Dashboard tour
+ */
+export const dashboardTour: TourConfig = {
+  id: 'dashboard-tour',
+  name: 'Dashboard Tour',
+  continuous: true,
+  showProgress: true,
+  showSkipButton: true,
+  steps: [
+    {
+      target: '[data-tour="sidebar"]',
+      content: 'Navigate between different sections of your dashboard using the sidebar.',
+      placement: 'right',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="create-dataset"]',
+      content: 'Create and publish new datasets to share with the community.',
+      placement: 'bottom',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="my-datasets"]',
+      content: 'Manage all your published datasets here.',
+      placement: 'bottom',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="analytics"]',
+      content: 'View analytics and insights about your datasets\' usage and impact.',
+      placement: 'left',
+      disableBeacon: true,
+    },
+  ],
+};
+
+/**
+ * Use cases listing tour
+ */
+export const useCasesListingTour: TourConfig = {
+  id: 'usecases-listing-tour',
+  name: 'Use Cases Listing Tour',
+  continuous: true,
+  showProgress: true,
+  showSkipButton: true,
+  steps: [
+    {
+      target: '[data-tour="filters"]',
+      content: 'Filter use cases by sector, status, and related datasets.',
+      placement: 'right',
+      disableBeacon: true,
+    },
+    {
+      target: '[data-tour="usecase-card"]',
+      content: 'Click on any use case to learn more about real-world applications.',
+      placement: 'top',
+      disableBeacon: true,
+    },
+  ],
+};
+
+/**
+ * All available tours mapped by route pattern
+ */
+export const toursByRoute: Record<string, TourConfig> = {
+  '/': homeTour,
+  '/datasets': datasetsListingTour,
+  '/datasets/[slug]': datasetDetailTour,
+  '/usecases': useCasesListingTour,
+  '/dashboard': dashboardTour,
+};
+
+/**
+ * Get tour configuration by route
+ */
+export function getTourByRoute(route: string): TourConfig | null {
+  // Exact match
+  if (toursByRoute[route]) {
+    return toursByRoute[route];
+  }
+
+  // Pattern match for dynamic routes
+  for (const [pattern, tour] of Object.entries(toursByRoute)) {
+    if (pattern.includes('[') && route.match(new RegExp(pattern.replace(/\[.*?\]/g, '[^/]+')))) {
+      return tour;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get all available tours
+ */
+export function getAllTours(): TourConfig[] {
+  return Object.values(toursByRoute);
+}
diff --git a/contexts/TourContext.tsx b/contexts/TourContext.tsx
new file mode 100644
index 00000000..8ba02491
--- /dev/null
+++ b/contexts/TourContext.tsx
@@ -0,0 +1,157 @@
+'use client';
+
+import React, { createContext, useContext, useState, useCallback, useEffect } from 'react';
+import { TourConfig } from '@/config/tours';
+
+interface TourContextType {
+  // Current active tour
+  activeTour: TourConfig | null;
+  
+  // Tour state
+  isTourRunning: boolean;
+  stepIndex: number;
+  
+  // Tour controls
+  startTour: (tour: TourConfig) => void;
+  stopTour: () => void;
+  nextStep: () => void;
+  prevStep: () => void;
+  goToStep: (index: number) => void;
+  
+  // First-time user tracking
+  hasSeenTour: (tourId: string) => boolean;
+  markTourAsSeen: (tourId: string) => void;
+  resetAllTours: () => void;
+  
+  // Mobile detection
+  isMobile: boolean;
+}
+
+const TourContext = createContext<TourContextType | undefined>(undefined);
+
+const STORAGE_KEY = 'civicdata-tours-seen';
+
+interface TourProviderProps {
+  children: React.ReactNode;
+}
+
+export function TourProvider({ children }: TourProviderProps) {
+  const [activeTour, setActiveTour] = useState<TourConfig | null>(null);
+  const [isTourRunning, setIsTourRunning] = useState(false);
+  const [stepIndex, setStepIndex] = useState(0);
+  const [seenTours, setSeenTours] = useState<Set<string>>(new Set());
+  const [isMobile, setIsMobile] = useState(false);
+
+  // Load seen tours from localStorage on mount
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      if (stored) {
+        setSeenTours(new Set(JSON.parse(stored)));
+      }
+    } catch (error) {
+      console.error('Failed to load tour history:', error);
+    }
+  }, []);
+
+  // Detect mobile devices
+  useEffect(() => {
+    const checkMobile = () => {
+      setIsMobile(window.innerWidth < 768);
+    };
+    
+    checkMobile();
+    window.addEventListener('resize', checkMobile);
+    
+    return () => window.removeEventListener('resize', checkMobile);
+  }, []);
+
+  // Save seen tours to localStorage
+  const saveSeenTours = useCallback((tours: Set<string>) => {
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(Array.from(tours)));
+    } catch (error) {
+      console.error('Failed to save tour history:', error);
+    }
+  }, []);
+
+  const startTour = useCallback((tour: TourConfig) => {
+    setActiveTour(tour);
+    setIsTourRunning(true);
+    setStepIndex(0);
+  }, []);
+
+  const stopTour = useCallback(() => {
+    if (activeTour) {
+      const newSeenTours = new Set(seenTours);
+      newSeenTours.add(activeTour.id);
+      setSeenTours(newSeenTours);
+      saveSeenTours(newSeenTours);
+    }
+    
+    setIsTourRunning(false);
+    setActiveTour(null);
+    setStepIndex(0);
+  }, [activeTour, seenTours, saveSeenTours]);
+
+  const nextStep = useCallback(() => {
+    if (activeTour && stepIndex < activeTour.steps.length - 1) {
+      setStepIndex(stepIndex + 1);
+    } else {
+      stopTour();
+    }
+  }, [activeTour, stepIndex, stopTour]);
+
+  const prevStep = useCallback(() => {
+    if (stepIndex > 0) {
+      setStepIndex(stepIndex - 1);
+    }
+  }, [stepIndex]);
+
+  const goToStep = useCallback((index: number) => {
+    if (activeTour && index >= 0 && index < activeTour.steps.length) {
+      setStepIndex(index);
+    }
+  }, [activeTour]);
+
+  const hasSeenTour = useCallback((tourId: string) => {
+    return seenTours.has(tourId);
+  }, [seenTours]);
+
+  const markTourAsSeen = useCallback((tourId: string) => {
+    const newSeenTours = new Set(seenTours);
+    newSeenTours.add(tourId);
+    setSeenTours(newSeenTours);
+    saveSeenTours(newSeenTours);
+  }, [seenTours, saveSeenTours]);
+
+  const resetAllTours = useCallback(() => {
+    setSeenTours(new Set());
+    localStorage.removeItem(STORAGE_KEY);
+  }, []);
+
+  const value: TourContextType = {
+    activeTour,
+    isTourRunning,
+    stepIndex,
+    startTour,
+    stopTour,
+    nextStep,
+    prevStep,
+    goToStep,
+    hasSeenTour,
+    markTourAsSeen,
+    resetAllTours,
+    isMobile,
+  };
+
+  return <TourContext.Provider value={value}>{children}</TourContext.Provider>;
+}
+
+export function useTour() {
+  const context = useContext(TourContext);
+  if (context === undefined) {
+    throw new Error('useTour must be used within a TourProvider');
+  }
+  return context;
+}
diff --git a/docs/TOUR_GUIDE.md b/docs/TOUR_GUIDE.md
new file mode 100644
index 00000000..85f43391
--- /dev/null
+++ b/docs/TOUR_GUIDE.md
@@ -0,0 +1,489 @@
+# Platform Tour Guide - React Joyride Integration
+
+This document explains how to use and configure the platform walkthrough feature built with React Joyride.
+
+## Overview
+
+The tour system provides an interactive walkthrough for users to learn about the platform's features. It includes:
+
+- ✅ **First-time user detection** - Automatically shows tours to new users
+- ✅ **Manual triggering** - Users can restart tours anytime
+- ✅ **Skip functionality** - Users can skip tours at any point
+- ✅ **Custom styling** - Matches platform design language
+- ✅ **Config-driven** - Easy to add/modify tours via configuration
+- ✅ **Mobile responsive** - Optimized for mobile devices
+- ✅ **LocalStorage persistence** - Remembers which tours users have seen
+
+## Architecture
+
+### Core Components
+
+1. **TourProvider** (`contexts/TourContext.tsx`)
+   - Manages tour state globally
+   - Tracks which tours have been seen
+   - Provides tour control methods
+
+2. **TourGuide** (`components/Tour/TourGuide.tsx`)
+   - Renders the Joyride component
+   - Applies custom styling
+   - Handles tour callbacks
+
+3. **Tour Configuration** (`config/tours.ts`)
+   - Defines all available tours
+   - Maps tours to routes
+   - Configures tour steps
+
+4. **Hooks**
+   - `useTour()` - Access tour state and controls
+   - `useTourTrigger()` - Auto-trigger tours for first-time users
+   - `useManualTour()` - Manual tour control for current page
+
+5. **UI Components**
+   - `TourButton` - Button to manually start tours
+   - `FloatingTourButton` - Floating action button for tours
+
+## Quick Start
+
+### 1. Add Tour Data Attributes to Your Components
+
+Add `data-tour` attributes to elements you want to highlight:
+
+```tsx
+// Example: Home page
+<div data-tour="search-bar">
+  <SearchBar />
+</div>
+
+<nav>
+  <Link href="/datasets" data-tour="datasets-link">
+    Datasets
+  </Link>
+  <Link href="/usecases" data-tour="usecases-link">
+    Use Cases
+  </Link>
+</nav>
+```
+
+### 2. Enable Auto-Tour for First-Time Users
+
+In your page component:
+
+```tsx
+'use client';
+
+import { useTourTrigger } from '@/hooks/use-tour-trigger';
+
+export default function HomePage() {
+  // Automatically show tour to first-time users
+  useTourTrigger(true, 1000); // enabled, delay in ms
+
+  return (
+    <div>
+      {/* Your page content */}
+    </div>
+  );
+}
+```
+
+### 3. Add Manual Tour Button
+
+```tsx
+import { TourButton } from '@/components/Tour';
+
+export default function Header() {
+  return (
+    <header>
+      {/* Other header content */}
+      <TourButton variant="both" label="Take a tour" />
+    </header>
+  );
+}
+```
+
+Or use a floating button:
+
+```tsx
+import { FloatingTourButton } from '@/components/Tour';
+
+export default function Layout({ children }) {
+  return (
+    <>
+      {children}
+      <FloatingTourButton />
+    </>
+  );
+}
+```
+
+## Creating New Tours
+
+### Step 1: Define Tour Configuration
+
+Edit `config/tours.ts`:
+
+```typescript
+export const myNewTour: TourConfig = {
+  id: 'my-new-tour',
+  name: 'My New Feature Tour',
+  continuous: true,
+  showProgress: true,
+  showSkipButton: true,
+  steps: [
+    {
+      target: 'body', // Use 'body' for centered modals
+      content: 'Welcome to the new feature!',
+      placement: 'center',
+      disableBeacon: true, // Skip beacon for first step
+    },
+    {
+      target: '[data-tour="feature-button"]',
+      content: 'Click here to access the feature.',
+      placement: 'bottom',
+    },
+    {
+      target: '[data-tour="settings"]',
+      content: 'Configure your preferences here.',
+      placement: 'left',
+    },
+  ],
+};
+```
+
+### Step 2: Register Tour with Route
+
+Add to `toursByRoute` in `config/tours.ts`:
+
+```typescript
+export const toursByRoute: Record<string, TourConfig> = {
+  '/': homeTour,
+  '/datasets': datasetsListingTour,
+  '/my-new-page': myNewTour, // Add your tour here
+  // ... other tours
+};
+```
+
+### Step 3: Add Data Attributes to Your Page
+
+```tsx
+export default function MyNewPage() {
+  useTourTrigger(); // Enable auto-tour
+
+  return (
+    <div>
+      <button data-tour="feature-button">
+        Feature Button
+      </button>
+      <div data-tour="settings">
+        Settings Panel
+      </div>
+    </div>
+  );
+}
+```
+
+## Tour Step Configuration
+
+Each step supports these properties:
+
+```typescript
+{
+  target: string | HTMLElement;        // CSS selector or element
+  content: React.ReactNode;            // Step content
+  placement?: 'top' | 'bottom' | 'left' | 'right' | 'center';
+  title?: React.ReactNode;             // Optional step title
+  disableBeacon?: boolean;             // Skip beacon animation
+  disableOverlay?: boolean;            // Disable spotlight overlay
+  disableScrolling?: boolean;          // Prevent scrolling to target
+  offset?: number;                     // Offset from target
+  placementBeacon?: Placement;         // Beacon placement
+  styles?: Styles;                     // Custom styles for this step
+}
+```
+
+## Programmatic Control
+
+### Using the useTour Hook
+
+```tsx
+import { useTour } from '@/contexts/TourContext';
+
+function MyComponent() {
+  const {
+    activeTour,
+    isTourRunning,
+    stepIndex,
+    startTour,
+    stopTour,
+    nextStep,
+    prevStep,
+    hasSeenTour,
+    markTourAsSeen,
+    resetAllTours,
+  } = useTour();
+
+  const handleStartTour = () => {
+    const tour = getTourByRoute('/datasets');
+    if (tour) {
+      startTour(tour);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleStartTour}>Start Tour</button>
+      <button onClick={stopTour}>Stop Tour</button>
+      <button onClick={resetAllTours}>Reset All Tours</button>
+    </div>
+  );
+}
+```
+
+### Using the useManualTour Hook
+
+```tsx
+import { useManualTour } from '@/hooks/use-tour-trigger';
+
+function MyComponent() {
+  const { startTour, stopTour, hasTour, tourName, isTourRunning } = useManualTour();
+
+  if (!hasTour) {
+    return null; // No tour available for current page
+  }
+
+  return (
+    <button onClick={startTour} disabled={isTourRunning}>
+      Start {tourName}
+    </button>
+  );
+}
+```
+
+## Customization
+
+### Styling
+
+The tour is styled to match the platform's design tokens. To customize:
+
+1. **Global Styles**: Edit `TourGuide.tsx` styles object
+2. **Per-Step Styles**: Add `styles` property to individual steps
+3. **CSS Variables**: Uses platform CSS variables (e.g., `--base-violet-solid-9`)
+
+### Mobile Optimization
+
+The tour automatically adjusts for mobile:
+- Smaller tooltip width (300px vs 400px)
+- Adjusted font sizes
+- Optimized padding
+- Touch-friendly buttons
+
+### Disabling Auto-Tours
+
+To disable auto-tours globally, don't call `useTourTrigger()` in your pages.
+
+To disable for specific users, you can add logic:
+
+```tsx
+const { user } = useSession();
+const shouldShowTour = user?.preferences?.showTours ?? true;
+
+useTourTrigger(shouldShowTour);
+```
+
+## Best Practices
+
+### 1. Keep Tours Short
+- Aim for 3-7 steps per tour
+- Focus on key features only
+- Create multiple tours for different sections
+
+### 2. Use Clear Content
+```tsx
+{
+  target: '[data-tour="download"]',
+  content: 'Click here to download the dataset in various formats like CSV, JSON, or Excel.',
+  placement: 'left',
+}
+```
+
+### 3. Proper Target Selection
+- Use unique `data-tour` attributes
+- Avoid dynamic selectors that might change
+- Ensure targets are visible when tour runs
+
+### 4. Handle Missing Targets
+The tour automatically skips steps if targets aren't found, but you should:
+- Test tours thoroughly
+- Use conditional rendering carefully
+- Consider adding fallback content
+
+### 5. Accessibility
+- Provide clear, descriptive content
+- Use proper ARIA labels
+- Ensure keyboard navigation works
+- Test with screen readers
+
+## Troubleshooting
+
+### Tour Not Showing
+
+1. Check if tour is registered in `toursByRoute`
+2. Verify `data-tour` attributes exist on page
+3. Check if user has already seen the tour (check localStorage)
+4. Ensure `TourProvider` is in component tree
+
+### Target Not Found
+
+1. Verify element exists in DOM when tour runs
+2. Check selector syntax
+3. Add delay to `useTourTrigger()` if needed
+4. Use browser DevTools to inspect elements
+
+### Styling Issues
+
+1. Check CSS variable values in browser
+2. Verify Tailwind classes are available
+3. Check z-index conflicts
+4. Test in different browsers
+
+### Mobile Issues
+
+1. Test on actual devices, not just browser DevTools
+2. Check touch event handling
+3. Verify responsive breakpoints
+4. Test with different screen sizes
+
+## API Reference
+
+### TourConfig
+
+```typescript
+interface TourConfig {
+  id: string;                    // Unique tour identifier
+  name: string;                  // Display name
+  steps: Step[];                 // Array of tour steps
+  continuous?: boolean;          // Show next button (default: true)
+  showProgress?: boolean;        // Show step progress (default: true)
+  showSkipButton?: boolean;      // Show skip button (default: true)
+  disableScrolling?: boolean;    // Disable page scrolling (default: false)
+}
+```
+
+### useTour() Return Values
+
+```typescript
+{
+  activeTour: TourConfig | null;           // Current active tour
+  isTourRunning: boolean;                  // Is tour currently running
+  stepIndex: number;                       // Current step index
+  startTour: (tour: TourConfig) => void;   // Start a tour
+  stopTour: () => void;                    // Stop current tour
+  nextStep: () => void;                    // Go to next step
+  prevStep: () => void;                    // Go to previous step
+  goToStep: (index: number) => void;       // Go to specific step
+  hasSeenTour: (tourId: string) => boolean;// Check if tour was seen
+  markTourAsSeen: (tourId: string) => void;// Mark tour as seen
+  resetAllTours: () => void;               // Reset all tour history
+  isMobile: boolean;                       // Is mobile device
+}
+```
+
+## Examples
+
+### Example 1: Conditional Tour Based on User Role
+
+```tsx
+'use client';
+
+import { useSession } from 'next-auth/react';
+import { useTourTrigger } from '@/hooks/use-tour-trigger';
+
+export default function DashboardPage() {
+  const { data: session } = useSession();
+  const isAdmin = session?.user?.role === 'admin';
+
+  // Only show tour to admins
+  useTourTrigger(isAdmin);
+
+  return <div>{/* Dashboard content */}</div>;
+}
+```
+
+### Example 2: Multi-Step Onboarding
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import { useTour } from '@/contexts/TourContext';
+import { step1Tour, step2Tour, step3Tour } from '@/config/tours';
+
+export default function OnboardingFlow() {
+  const [currentStep, setCurrentStep] = useState(1);
+  const { startTour, isTourRunning } = useTour();
+
+  const handleNextOnboarding = () => {
+    if (currentStep === 1) {
+      startTour(step1Tour);
+      setCurrentStep(2);
+    } else if (currentStep === 2) {
+      startTour(step2Tour);
+      setCurrentStep(3);
+    } else if (currentStep === 3) {
+      startTour(step3Tour);
+      setCurrentStep(4);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleNextOnboarding} disabled={isTourRunning}>
+        Continue Onboarding (Step {currentStep}/3)
+      </button>
+    </div>
+  );
+}
+```
+
+### Example 3: Tour with Custom Trigger
+
+```tsx
+'use client';
+
+import { useTour } from '@/contexts/TourContext';
+import { datasetDetailTour } from '@/config/tours';
+
+export default function DatasetPage() {
+  const { startTour, hasSeenTour } = useTour();
+
+  const handleHelpClick = () => {
+    startTour(datasetDetailTour);
+  };
+
+  return (
+    <div>
+      <button onClick={handleHelpClick}>
+        {hasSeenTour(datasetDetailTour.id) ? 'Replay Tour' : 'Need Help?'}
+      </button>
+      {/* Page content */}
+    </div>
+  );
+}
+```
+
+## Support
+
+For issues or questions:
+1. Check this documentation
+2. Review example implementations
+3. Check browser console for errors
+4. Contact the development team
+
+## Future Enhancements
+
+Potential improvements:
+- [ ] Analytics tracking for tour completion rates
+- [ ] A/B testing different tour flows
+- [ ] Video tutorials in tour steps
+- [ ] Interactive elements within tours
+- [ ] Multi-language support
+- [ ] Tour templates for common patterns
diff --git a/hooks/use-tour-trigger.ts b/hooks/use-tour-trigger.ts
new file mode 100644
index 00000000..b00e278c
--- /dev/null
+++ b/hooks/use-tour-trigger.ts
@@ -0,0 +1,58 @@
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { useTour } from '@/contexts/TourContext';
+import { getTourByRoute } from '@/config/tours';
+
+/**
+ * Hook to automatically trigger tour for first-time users on specific routes
+ * 
+ * @param enabled - Whether to enable auto-trigger (default: true)
+ * @param delay - Delay in ms before showing tour (default: 1000)
+ */
+export function useTourTrigger(enabled: boolean = true, delay: number = 1000) {
+  const pathname = usePathname();
+  const { startTour, hasSeenTour, isTourRunning } = useTour();
+
+  useEffect(() => {
+    if (!enabled || isTourRunning) return;
+
+    // Get tour for current route
+    const tour = getTourByRoute(pathname);
+    
+    if (tour && !hasSeenTour(tour.id)) {
+      // Delay showing tour to allow page to fully load
+      const timer = setTimeout(() => {
+        startTour(tour);
+      }, delay);
+
+      return () => clearTimeout(timer);
+    }
+  }, [pathname, enabled, delay, startTour, hasSeenTour, isTourRunning]);
+}
+
+/**
+ * Hook to manually control tour for a specific route
+ */
+export function useManualTour() {
+  const pathname = usePathname();
+  const { startTour, stopTour, isTourRunning } = useTour();
+
+  const startCurrentTour = () => {
+    const tour = getTourByRoute(pathname);
+    if (tour) {
+      startTour(tour);
+    }
+  };
+
+  const tour = getTourByRoute(pathname);
+
+  return {
+    startTour: startCurrentTour,
+    stopTour,
+    isTourRunning,
+    hasTour: !!tour,
+    tourName: tour?.name,
+  };
+}
diff --git a/lib/tour-utils.ts b/lib/tour-utils.ts
new file mode 100644
index 00000000..82241010
--- /dev/null
+++ b/lib/tour-utils.ts
@@ -0,0 +1,271 @@
+/**
+ * Tour utility functions
+ */
+
+import { TourConfig, TourStorageData } from '@/types/tour';
+
+const STORAGE_KEY = 'civicdata-tours-seen';
+
+/**
+ * Get seen tours from localStorage
+ */
+export function getSeenTours(): Set<string> {
+  if (typeof window === 'undefined') return new Set();
+  
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      const data: string[] = JSON.parse(stored);
+      return new Set(data);
+    }
+  } catch (error) {
+    console.error('Failed to load tour history:', error);
+  }
+  
+  return new Set();
+}
+
+/**
+ * Save seen tours to localStorage
+ */
+export function saveSeenTours(tours: Set<string>): void {
+  if (typeof window === 'undefined') return;
+  
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(Array.from(tours)));
+  } catch (error) {
+    console.error('Failed to save tour history:', error);
+  }
+}
+
+/**
+ * Check if a tour has been seen
+ */
+export function hasSeenTour(tourId: string): boolean {
+  const seenTours = getSeenTours();
+  return seenTours.has(tourId);
+}
+
+/**
+ * Mark a tour as seen
+ */
+export function markTourAsSeen(tourId: string): void {
+  const seenTours = getSeenTours();
+  seenTours.add(tourId);
+  saveSeenTours(seenTours);
+}
+
+/**
+ * Reset all tour history
+ */
+export function resetAllTours(): void {
+  if (typeof window === 'undefined') return;
+  
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch (error) {
+    console.error('Failed to reset tour history:', error);
+  }
+}
+
+/**
+ * Reset specific tour
+ */
+export function resetTour(tourId: string): void {
+  const seenTours = getSeenTours();
+  seenTours.delete(tourId);
+  saveSeenTours(seenTours);
+}
+
+/**
+ * Get tour statistics
+ */
+export function getTourStats(): {
+  totalSeen: number;
+  seenTours: string[];
+} {
+  const seenTours = getSeenTours();
+  return {
+    totalSeen: seenTours.size,
+    seenTours: Array.from(seenTours),
+  };
+}
+
+/**
+ * Check if element exists in DOM
+ */
+export function elementExists(selector: string): boolean {
+  if (typeof window === 'undefined') return false;
+  
+  try {
+    return document.querySelector(selector) !== null;
+  } catch (error) {
+    console.error('Invalid selector:', selector, error);
+    return false;
+  }
+}
+
+/**
+ * Validate tour configuration
+ */
+export function validateTour(tour: TourConfig): {
+  valid: boolean;
+  errors: string[];
+} {
+  const errors: string[] = [];
+
+  if (!tour.id) {
+    errors.push('Tour must have an id');
+  }
+
+  if (!tour.name) {
+    errors.push('Tour must have a name');
+  }
+
+  if (!tour.steps || tour.steps.length === 0) {
+    errors.push('Tour must have at least one step');
+  }
+
+  if (tour.steps) {
+    tour.steps.forEach((step, index) => {
+      if (!step.target) {
+        errors.push(`Step ${index + 1} must have a target`);
+      }
+      if (!step.content) {
+        errors.push(`Step ${index + 1} must have content`);
+      }
+    });
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Check if device is mobile
+ */
+export function isMobileDevice(): boolean {
+  if (typeof window === 'undefined') return false;
+  
+  return window.innerWidth < 768;
+}
+
+/**
+ * Wait for element to appear in DOM
+ */
+export function waitForElement(
+  selector: string,
+  timeout: number = 5000
+): Promise<Element | null> {
+  return new Promise((resolve) => {
+    if (elementExists(selector)) {
+      resolve(document.querySelector(selector));
+      return;
+    }
+
+    const observer = new MutationObserver(() => {
+      if (elementExists(selector)) {
+        observer.disconnect();
+        resolve(document.querySelector(selector));
+      }
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
+
+    setTimeout(() => {
+      observer.disconnect();
+      resolve(null);
+    }, timeout);
+  });
+}
+
+/**
+ * Scroll element into view smoothly
+ */
+export function scrollToElement(selector: string): void {
+  if (typeof window === 'undefined') return;
+  
+  const element = document.querySelector(selector);
+  if (element) {
+    element.scrollIntoView({
+      behavior: 'smooth',
+      block: 'center',
+      inline: 'nearest',
+    });
+  }
+}
+
+/**
+ * Get tour progress percentage
+ */
+export function getTourProgress(currentStep: number, totalSteps: number): number {
+  if (totalSteps === 0) return 0;
+  return Math.round(((currentStep + 1) / totalSteps) * 100);
+}
+
+/**
+ * Format tour step for analytics
+ */
+export function formatTourStepForAnalytics(
+  tourId: string,
+  stepIndex: number,
+  stepTarget: string
+): {
+  tourId: string;
+  stepIndex: number;
+  stepTarget: string;
+  timestamp: number;
+} {
+  return {
+    tourId,
+    stepIndex,
+    stepTarget,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Debounce function for resize handlers
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeout: NodeJS.Timeout | null = null;
+
+  return function executedFunction(...args: Parameters<T>) {
+    const later = () => {
+      timeout = null;
+      func(...args);
+    };
+
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    timeout = setTimeout(later, wait);
+  };
+}
+
+/**
+ * Check if tours are enabled (can be used for feature flags)
+ */
+export function areToursEnabled(): boolean {
+  // Add your feature flag logic here
+  // For now, always return true
+  return true;
+}
+
+/**
+ * Get recommended delay based on page complexity
+ */
+export function getRecommendedDelay(elementCount: number): number {
+  if (elementCount < 10) return 500;
+  if (elementCount < 50) return 1000;
+  if (elementCount < 100) return 1500;
+  return 2000;
+}
diff --git a/package-lock.json b/package-lock.json
index f3541d2c..d8bb3278 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -36,6 +36,7 @@
         "react": "^18.2.0",
         "react-aria": "3.22.0",
         "react-dom": "^18.2.0",
+        "react-joyride": "^2.9.3",
         "react-quill": "^2.0.0",
         "sharp": "^0.33.2",
         "usehooks-ts": "^2.13.0",
@@ -2152,6 +2153,12 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@gilbarbara/deep-equal": {
+      "version": "0.3.1",
+      "resolved": "https://registry.npmjs.org/@gilbarbara/deep-equal/-/deep-equal-0.3.1.tgz",
+      "integrity": "sha512-I7xWjLs2YSVMc5gGx1Z3ZG1lgFpITPndpi8Ku55GeEIKpACCPQNS/OTqQbxgTCfq0Ncvcc+CrFov96itVh6Qvw==",
+      "license": "MIT"
+    },
     "node_modules/@graphql-codegen/add": {
       "version": "4.0.1",
       "resolved": "https://registry.npmjs.org/@graphql-codegen/add/-/add-4.0.1.tgz",
@@ -12851,6 +12858,12 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/deep-diff": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/deep-diff/-/deep-diff-1.0.2.tgz",
+      "integrity": "sha512-aWS3UIVH+NPGCD1kki+DCU9Dua032iSsO43LqQpcs4R3+dVv7tX0qBGjiVHJHjplsoUM2XRO/KB92glqc68awg==",
+      "license": "MIT"
+    },
     "node_modules/deep-eql": {
       "version": "4.1.3",
       "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-4.1.3.tgz",
@@ -12908,6 +12921,15 @@
       "integrity": "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==",
       "dev": true
     },
+    "node_modules/deepmerge": {
+      "version": "4.3.1",
+      "resolved": "https://registry.npmjs.org/deepmerge/-/deepmerge-4.3.1.tgz",
+      "integrity": "sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/default-browser": {
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/default-browser/-/default-browser-5.2.1.tgz",
@@ -15839,6 +15861,12 @@
         "node": ">=8"
       }
     },
+    "node_modules/is-lite": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/is-lite/-/is-lite-1.2.1.tgz",
+      "integrity": "sha512-pgF+L5bxC+10hLBgf6R2P4ZZUBOQIIacbdo8YvuCP8/JvsWxG7aZ9p10DYuLtifFci4l3VITphhMlMV4Y+urPw==",
+      "license": "MIT"
+    },
     "node_modules/is-lower-case": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/is-lower-case/-/is-lower-case-2.0.2.tgz",
@@ -18205,6 +18233,17 @@
         "node": ">= 6"
       }
     },
+    "node_modules/popper.js": {
+      "version": "1.16.1",
+      "resolved": "https://registry.npmjs.org/popper.js/-/popper.js-1.16.1.tgz",
+      "integrity": "sha512-Wb4p1J4zyFTbM+u6WuO4XstYx4Ky9Cewe4DWrel7B0w6VVICvPwdOpotjzcf6eD8TsckVnIMNONQyPIUFOUbCQ==",
+      "deprecated": "You can find the new Popper v2 at @popperjs/core, this package is dedicated to the legacy v1",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/popperjs"
+      }
+    },
     "node_modules/possible-typed-array-names": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/possible-typed-array-names/-/possible-typed-array-names-1.0.0.tgz",
@@ -18818,6 +18857,45 @@
         "react": "^18.2.0"
       }
     },
+    "node_modules/react-floater": {
+      "version": "0.7.9",
+      "resolved": "https://registry.npmjs.org/react-floater/-/react-floater-0.7.9.tgz",
+      "integrity": "sha512-NXqyp9o8FAXOATOEo0ZpyaQ2KPb4cmPMXGWkx377QtJkIXHlHRAGer7ai0r0C1kG5gf+KJ6Gy+gdNIiosvSicg==",
+      "license": "MIT",
+      "dependencies": {
+        "deepmerge": "^4.3.1",
+        "is-lite": "^0.8.2",
+        "popper.js": "^1.16.0",
+        "prop-types": "^15.8.1",
+        "tree-changes": "^0.9.1"
+      },
+      "peerDependencies": {
+        "react": "15 - 18",
+        "react-dom": "15 - 18"
+      }
+    },
+    "node_modules/react-floater/node_modules/@gilbarbara/deep-equal": {
+      "version": "0.1.2",
+      "resolved": "https://registry.npmjs.org/@gilbarbara/deep-equal/-/deep-equal-0.1.2.tgz",
+      "integrity": "sha512-jk+qzItoEb0D0xSSmrKDDzf9sheQj/BAPxlgNxgmOaA3mxpUa6ndJLYGZKsJnIVEQSD8zcTbyILz7I0HcnBCRA==",
+      "license": "MIT"
+    },
+    "node_modules/react-floater/node_modules/is-lite": {
+      "version": "0.8.2",
+      "resolved": "https://registry.npmjs.org/is-lite/-/is-lite-0.8.2.tgz",
+      "integrity": "sha512-JZfH47qTsslwaAsqbMI3Q6HNNjUuq6Cmzzww50TdP5Esb6e1y2sK2UAaZZuzfAzpoI2AkxoPQapZdlDuP6Vlsw==",
+      "license": "MIT"
+    },
+    "node_modules/react-floater/node_modules/tree-changes": {
+      "version": "0.9.3",
+      "resolved": "https://registry.npmjs.org/tree-changes/-/tree-changes-0.9.3.tgz",
+      "integrity": "sha512-vvvS+O6kEeGRzMglTKbc19ltLWNtmNt1cpBoSYLj/iEcPVvpJasemKOlxBrmZaCtDJoF+4bwv3m01UKYi8mukQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@gilbarbara/deep-equal": "^0.1.1",
+        "is-lite": "^0.8.2"
+      }
+    },
     "node_modules/react-hook-form": {
       "version": "7.51.1",
       "resolved": "https://registry.npmjs.org/react-hook-form/-/react-hook-form-7.51.1.tgz",
@@ -18833,11 +18911,56 @@
         "react": "^16.8.0 || ^17 || ^18"
       }
     },
+    "node_modules/react-innertext": {
+      "version": "1.1.5",
+      "resolved": "https://registry.npmjs.org/react-innertext/-/react-innertext-1.1.5.tgz",
+      "integrity": "sha512-PWAqdqhxhHIv80dT9znP2KvS+hfkbRovFp4zFYHFFlOoQLRiawIic81gKb3U1wEyJZgMwgs3JoLtwryASRWP3Q==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/react": ">=0.0.0 <=99",
+        "react": ">=0.0.0 <=99"
+      }
+    },
     "node_modules/react-is": {
       "version": "16.13.1",
       "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz",
       "integrity": "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ=="
     },
+    "node_modules/react-joyride": {
+      "version": "2.9.3",
+      "resolved": "https://registry.npmjs.org/react-joyride/-/react-joyride-2.9.3.tgz",
+      "integrity": "sha512-1+Mg34XK5zaqJ63eeBhqdbk7dlGCFp36FXwsEvgpjqrtyywX2C6h9vr3jgxP0bGHCw8Ilsp/nRDzNVq6HJ3rNw==",
+      "license": "MIT",
+      "dependencies": {
+        "@gilbarbara/deep-equal": "^0.3.1",
+        "deep-diff": "^1.0.2",
+        "deepmerge": "^4.3.1",
+        "is-lite": "^1.2.1",
+        "react-floater": "^0.7.9",
+        "react-innertext": "^1.1.5",
+        "react-is": "^16.13.1",
+        "scroll": "^3.0.1",
+        "scrollparent": "^2.1.0",
+        "tree-changes": "^0.11.2",
+        "type-fest": "^4.27.0"
+      },
+      "peerDependencies": {
+        "react": "15 - 18",
+        "react-dom": "15 - 18"
+      }
+    },
+    "node_modules/react-joyride/node_modules/type-fest": {
+      "version": "4.41.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.41.0.tgz",
+      "integrity": "sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==",
+      "license": "(MIT OR CC0-1.0)",
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/react-leaflet": {
       "version": "4.2.1",
       "resolved": "https://registry.npmjs.org/react-leaflet/-/react-leaflet-4.2.1.tgz",
@@ -20156,6 +20279,18 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/scroll": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/scroll/-/scroll-3.0.1.tgz",
+      "integrity": "sha512-pz7y517OVls1maEzlirKO5nPYle9AXsFzTMNJrRGmT951mzpIBy7sNHOg5o/0MQd/NqliCiWnAi0kZneMPFLcg==",
+      "license": "MIT"
+    },
+    "node_modules/scrollparent": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/scrollparent/-/scrollparent-2.1.0.tgz",
+      "integrity": "sha512-bnnvJL28/Rtz/kz2+4wpBjHzWoEzXhVg/TE8BeVGJHUqE8THNIRnDxDWMktwM+qahvlRdvlLdsQfYe+cuqfZeA==",
+      "license": "ISC"
+    },
     "node_modules/scuid": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/scuid/-/scuid-1.1.0.tgz",
@@ -21245,6 +21380,16 @@
       "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
       "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="
     },
+    "node_modules/tree-changes": {
+      "version": "0.11.3",
+      "resolved": "https://registry.npmjs.org/tree-changes/-/tree-changes-0.11.3.tgz",
+      "integrity": "sha512-r14mvDZ6tqz8PRQmlFKjhUVngu4VZ9d92ON3tp0EGpFBE6PAHOq8Bx8m8ahbNoGE3uI/npjYcJiqVydyOiYXag==",
+      "license": "MIT",
+      "dependencies": {
+        "@gilbarbara/deep-equal": "^0.3.1",
+        "is-lite": "^1.2.1"
+      }
+    },
     "node_modules/ts-api-utils": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-1.3.0.tgz",
diff --git a/package.json b/package.json
index 56331472..654489dd 100644
--- a/package.json
+++ b/package.json
@@ -45,6 +45,7 @@
     "react": "^18.2.0",
     "react-aria": "3.22.0",
     "react-dom": "^18.2.0",
+    "react-joyride": "^2.9.3",
     "react-quill": "^2.0.0",
     "sharp": "^0.33.2",
     "usehooks-ts": "^2.13.0",
diff --git a/types/tour.ts b/types/tour.ts
new file mode 100644
index 00000000..9b15a17d
--- /dev/null
+++ b/types/tour.ts
@@ -0,0 +1,180 @@
+/**
+ * Tour-related TypeScript types and interfaces
+ */
+
+import { Step, Placement, Styles } from 'react-joyride';
+
+/**
+ * Tour configuration interface
+ */
+export interface TourConfig {
+  /** Unique identifier for the tour */
+  id: string;
+  
+  /** Display name of the tour */
+  name: string;
+  
+  /** Array of tour steps */
+  steps: Step[];
+  
+  /** Whether to show next/prev buttons (default: true) */
+  continuous?: boolean;
+  
+  /** Whether to show step progress (default: true) */
+  showProgress?: boolean;
+  
+  /** Whether to show skip button (default: true) */
+  showSkipButton?: boolean;
+  
+  /** Whether to disable page scrolling during tour (default: false) */
+  disableScrolling?: boolean;
+}
+
+/**
+ * Tour step interface (extends Joyride Step)
+ */
+export interface TourStep extends Step {
+  /** CSS selector or HTMLElement to target */
+  target: string | HTMLElement;
+  
+  /** Content to display in the tooltip */
+  content: React.ReactNode;
+  
+  /** Placement of the tooltip relative to target */
+  placement?: Placement;
+  
+  /** Optional title for the step */
+  title?: React.ReactNode;
+  
+  /** Skip the beacon animation for this step */
+  disableBeacon?: boolean;
+  
+  /** Disable the spotlight overlay for this step */
+  disableOverlay?: boolean;
+  
+  /** Disable scrolling to this step */
+  disableScrolling?: boolean;
+  
+  /** Offset from the target element */
+  offset?: number;
+  
+  /** Custom styles for this step */
+  styles?: Styles;
+}
+
+/**
+ * Tour context state
+ */
+export interface TourContextState {
+  /** Currently active tour */
+  activeTour: TourConfig | null;
+  
+  /** Whether a tour is currently running */
+  isTourRunning: boolean;
+  
+  /** Current step index */
+  stepIndex: number;
+  
+  /** Whether the device is mobile */
+  isMobile: boolean;
+}
+
+/**
+ * Tour context actions
+ */
+export interface TourContextActions {
+  /** Start a tour */
+  startTour: (tour: TourConfig) => void;
+  
+  /** Stop the current tour */
+  stopTour: () => void;
+  
+  /** Go to next step */
+  nextStep: () => void;
+  
+  /** Go to previous step */
+  prevStep: () => void;
+  
+  /** Go to specific step by index */
+  goToStep: (index: number) => void;
+  
+  /** Check if a tour has been seen */
+  hasSeenTour: (tourId: string) => boolean;
+  
+  /** Mark a tour as seen */
+  markTourAsSeen: (tourId: string) => void;
+  
+  /** Reset all tour history */
+  resetAllTours: () => void;
+}
+
+/**
+ * Complete tour context type
+ */
+export type TourContextType = TourContextState & TourContextActions;
+
+/**
+ * Tour button variant types
+ */
+export type TourButtonVariant = 'icon' | 'text' | 'both';
+
+/**
+ * Tour button props
+ */
+export interface TourButtonProps {
+  /** Button variant style */
+  variant?: TourButtonVariant;
+  
+  /** Additional CSS classes */
+  className?: string;
+  
+  /** Button label text */
+  label?: string;
+}
+
+/**
+ * Manual tour hook return type
+ */
+export interface UseManualTourReturn {
+  /** Start the tour for current page */
+  startTour: () => void;
+  
+  /** Stop the current tour */
+  stopTour: () => void;
+  
+  /** Whether a tour is currently running */
+  isTourRunning: boolean;
+  
+  /** Whether current page has a tour */
+  hasTour: boolean;
+  
+  /** Name of the tour for current page */
+  tourName?: string;
+}
+
+/**
+ * Tour trigger hook options
+ */
+export interface UseTourTriggerOptions {
+  /** Whether to enable auto-trigger */
+  enabled?: boolean;
+  
+  /** Delay in milliseconds before showing tour */
+  delay?: number;
+}
+
+/**
+ * Tour route mapping type
+ */
+export type TourRouteMap = Record<string, TourConfig>;
+
+/**
+ * LocalStorage tour data structure
+ */
+export interface TourStorageData {
+  /** Array of seen tour IDs */
+  seenTours: string[];
+  
+  /** Last updated timestamp */
+  lastUpdated?: number;
+}