@umituz/react-native-onboarding 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Ümit UZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,175 @@
+# @umituz/react-native-onboarding
+
+Generic onboarding flow for React Native apps with gradient backgrounds, animations, and customizable slides. Follows SOLID, DRY, KISS principles - fully reusable across hundreds of apps.
+
+## Features
+
+- ✅ **Generic & Reusable**: Works with any app, fully customizable via props
+- ✅ **Gradient Backgrounds**: Beautiful gradient backgrounds for each slide
+- ✅ **Animations**: Smooth transitions and animations
+- ✅ **SOLID Principles**: Clean architecture, easy to extend
+- ✅ **DRY**: No code duplication, generic components
+- ✅ **KISS**: Simple API, easy to understand and use
+- ✅ **Type-Safe**: Full TypeScript support
+- ✅ **Customizable**: Icons, messages, gradients, buttons - all configurable
+- ✅ **Storage Integration**: Uses @umituz/react-native-storage for persistence
+
+## Installation
+
+```bash
+npm install @umituz/react-native-onboarding
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { OnboardingScreen } from '@umituz/react-native-onboarding';
+
+const slides = [
+  {
+    id: '1',
+    title: 'Welcome',
+    description: 'Welcome to the app',
+    icon: '🎉',
+    gradient: ['#3B82F6', '#8B5CF6'],
+  },
+  {
+    id: '2',
+    title: 'Features',
+    description: 'Discover amazing features',
+    icon: '✨',
+    gradient: ['#60A5FA', '#A78BFA'],
+  },
+];
+
+<OnboardingScreen
+  slides={slides}
+  onComplete={() => {
+    // Navigate to main app
+  }}
+/>
+```
+
+### Advanced Example with Customization
+
+```typescript
+import { OnboardingScreen } from '@umituz/react-native-onboarding';
+
+<OnboardingScreen
+  slides={slides}
+  onComplete={handleComplete}
+  onSkip={handleSkip}
+  skipButtonText="Skip"
+  nextButtonText="Next"
+  getStartedButtonText="Get Started"
+  showSkipButton={true}
+  showBackButton={true}
+  showProgressBar={true}
+  showDots={true}
+  showProgressText={true}
+  storageKey="@myapp_onboarding_completed"
+  autoComplete={false}
+/>
+```
+
+### With Features List
+
+```typescript
+const slides = [
+  {
+    id: '1',
+    title: 'Powerful Features',
+    description: 'Everything you need in one place',
+    icon: '🚀',
+    gradient: ['#3B82F6', '#8B5CF6'],
+    features: [
+      'Feature 1: Amazing capability',
+      'Feature 2: Another great feature',
+      'Feature 3: One more awesome thing',
+    ],
+  },
+];
+```
+
+### Custom Components
+
+```typescript
+<OnboardingScreen
+  slides={slides}
+  renderHeader={({ isFirstSlide, onBack, onSkip }) => (
+    <CustomHeader onBack={onBack} onSkip={onSkip} />
+  )}
+  renderFooter={({ currentIndex, totalSlides, isLastSlide, onNext }) => (
+    <CustomFooter onNext={onNext} />
+  )}
+  renderSlide={(slide) => <CustomSlide slide={slide} />}
+/>
+```
+
+## API Reference
+
+### `OnboardingSlide`
+
+```typescript
+interface OnboardingSlide {
+  id: string;
+  title: string;
+  description: string;
+  icon: string; // Emoji or icon name
+  gradient: string[]; // [startColor, endColor] or [color1, color2, color3]
+  image?: string; // Optional image URL
+  features?: string[]; // Optional features list
+}
+```
+
+### `OnboardingOptions`
+
+```typescript
+interface OnboardingOptions {
+  slides: OnboardingSlide[];
+  onComplete?: () => void | Promise<void>;
+  onSkip?: () => void | Promise<void>;
+  skipButtonText?: string;
+  nextButtonText?: string;
+  getStartedButtonText?: string;
+  showSkipButton?: boolean;
+  showBackButton?: boolean;
+  showProgressBar?: boolean;
+  showDots?: boolean;
+  showProgressText?: boolean;
+  storageKey?: string;
+  autoComplete?: boolean;
+}
+```
+
+### `useOnboardingStore`
+
+Hook for managing onboarding completion state.
+
+```typescript
+const { isOnboardingComplete, complete, skip, reset } = useOnboardingStore();
+```
+
+### `useOnboardingNavigation`
+
+Hook for managing navigation state.
+
+```typescript
+const { currentIndex, goToNext, goToPrevious, isLastSlide, isFirstSlide } =
+  useOnboardingNavigation(totalSlides, onComplete, onSkip);
+```
+
+## Architecture
+
+- **Domain Layer**: Entities and interfaces (business logic)
+- **Infrastructure Layer**: Storage and hooks (state management)
+- **Presentation Layer**: Components and screens (UI)
+
+No app-specific code, fully generic and reusable.
+
+## License
+
+MIT
+

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@umituz/react-native-onboarding",
+  "version": "1.0.0",
+  "description": "Generic onboarding flow for React Native apps with gradient backgrounds, animations, and customizable slides. SOLID, DRY, KISS principles applied.",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "version:patch": "npm version patch -m 'chore: release v%s'",
+    "version:minor": "npm version minor -m 'chore: release v%s'",
+    "version:major": "npm version major -m 'chore: release v%s'"
+  },
+  "keywords": [
+    "react-native",
+    "onboarding",
+    "welcome",
+    "tutorial",
+    "gradient",
+    "animation",
+    "ddd",
+    "domain-driven-design",
+    "solid",
+    "dry",
+    "kiss"
+  ],
+  "author": "Ümit UZ <umit@umituz.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/umituz/react-native-onboarding"
+  },
+  "peerDependencies": {
+    "@umituz/react-native-storage": "latest",
+    "@umituz/react-native-localization": "latest",
+    "@umituz/react-native-theme": "latest",
+    "expo-linear-gradient": "^15.0.0",
+    "react": ">=18.2.0",
+    "react-native": ">=0.74.0",
+    "react-native-safe-area-context": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.45",
+    "@types/react-native": "^0.73.0",
+    "@umituz/react-native-storage": "^1.1.0",
+    "@umituz/react-native-localization": "latest",
+    "@umituz/react-native-theme": "latest",
+    "expo-linear-gradient": "^15.0.7",
+    "react": "^18.2.0",
+    "react-native": "^0.74.0",
+    "react-native-safe-area-context": "^5.6.0",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}
+

package/src/domain/entities/OnboardingOptions.ts

@@ -0,0 +1,79 @@
+/**
+ * Onboarding Options
+ *
+ * Configuration options for onboarding flow
+ */
+
+import type { OnboardingSlide } from "./OnboardingSlide";
+
+/**
+ * Onboarding Options
+ * Customize the onboarding experience
+ */
+export interface OnboardingOptions {
+  /**
+   * Array of slides to display
+   */
+  slides: OnboardingSlide[];
+
+  /**
+   * Callback when onboarding is completed
+   */
+  onComplete?: () => void | Promise<void>;
+
+  /**
+   * Callback when onboarding is skipped
+   */
+  onSkip?: () => void | Promise<void>;
+
+  /**
+   * Custom skip button text (default: "Skip")
+   */
+  skipButtonText?: string;
+
+  /**
+   * Custom next button text (default: "Next")
+   */
+  nextButtonText?: string;
+
+  /**
+   * Custom get started button text (default: "Get Started")
+   */
+  getStartedButtonText?: string;
+
+  /**
+   * Show skip button (default: true)
+   */
+  showSkipButton?: boolean;
+
+  /**
+   * Show back button (default: true)
+   */
+  showBackButton?: boolean;
+
+  /**
+   * Show progress bar (default: true)
+   */
+  showProgressBar?: boolean;
+
+  /**
+   * Show dots indicator (default: true)
+   */
+  showDots?: boolean;
+
+  /**
+   * Show progress text (default: true)
+   */
+  showProgressText?: boolean;
+
+  /**
+   * Storage key for completion state (default: "@onboarding_completed")
+   */
+  storageKey?: string;
+
+  /**
+   * Auto-complete onboarding on last slide (default: false)
+   */
+  autoComplete?: boolean;
+}
+

package/src/domain/entities/OnboardingSlide.ts

@@ -0,0 +1,48 @@
+/**
+ * Onboarding Slide Entity
+ *
+ * Domain entity representing a single onboarding slide
+ */
+
+/**
+ * Onboarding Slide
+ * Each slide represents one step in the onboarding flow
+ */
+export interface OnboardingSlide {
+  /**
+   * Unique identifier for the slide
+   */
+  id: string;
+
+  /**
+   * Slide title
+   */
+  title: string;
+
+  /**
+   * Slide description/body text
+   */
+  description: string;
+
+  /**
+   * Icon to display (emoji or icon name)
+   */
+  icon: string;
+
+  /**
+   * Gradient colors for the slide background
+   * [startColor, endColor] or [color1, color2, color3] for multi-stop gradients
+   */
+  gradient: string[];
+
+  /**
+   * Optional image URL (alternative to icon)
+   */
+  image?: string;
+
+  /**
+   * Optional features list to display
+   */
+  features?: string[];
+}
+

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * React Native Onboarding - Public API
+ *
+ * Generic onboarding flow for React Native apps with gradient backgrounds,
+ * animations, and customizable slides. Follows SOLID, DRY, KISS principles.
+ *
+ * Architecture:
+ * - Domain: Entities and interfaces (business logic)
+ * - Infrastructure: Storage and hooks (state management)
+ * - Presentation: Components and screens (UI)
+ *
+ * Usage:
+ *   import { OnboardingScreen, OnboardingSlide } from '@umituz/react-native-onboarding';
+ *
+ *   <OnboardingScreen
+ *     slides={[
+ *       {
+ *         id: '1',
+ *         title: 'Welcome',
+ *         description: 'Welcome to the app',
+ *         icon: '🎉',
+ *         gradient: ['#3B82F6', '#8B5CF6'],
+ *       },
+ *     ]}
+ *     onComplete={() => console.log('Completed')}
+ *   />
+ */
+
+// =============================================================================
+// DOMAIN LAYER - Entities and Interfaces
+// =============================================================================
+
+export type { OnboardingSlide } from "./domain/entities/OnboardingSlide";
+export type { OnboardingOptions } from "./domain/entities/OnboardingOptions";
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Storage and Hooks
+// =============================================================================
+
+export {
+  useOnboardingStore,
+  useOnboarding,
+} from "./infrastructure/storage/OnboardingStore";
+export {
+  useOnboardingNavigation,
+  type UseOnboardingNavigationReturn,
+} from "./infrastructure/hooks/useOnboardingNavigation";
+
+// =============================================================================
+// PRESENTATION LAYER - Components and Screens
+// =============================================================================
+
+export { OnboardingScreen, type OnboardingScreenProps } from "./presentation/screens/OnboardingScreen";
+export { OnboardingSlide, type OnboardingSlideProps } from "./presentation/components/OnboardingSlide";
+export { OnboardingHeader, type OnboardingHeaderProps } from "./presentation/components/OnboardingHeader";
+export { OnboardingFooter, type OnboardingFooterProps } from "./presentation/components/OnboardingFooter";
+

package/src/infrastructure/hooks/useOnboardingNavigation.ts

@@ -0,0 +1,71 @@
+/**
+ * useOnboardingNavigation Hook
+ *
+ * Manages navigation state and callbacks for onboarding flow
+ */
+
+import { useState, useCallback } from "react";
+import { DeviceEventEmitter } from "react-native";
+
+export interface UseOnboardingNavigationReturn {
+  currentIndex: number;
+  goToNext: () => void;
+  goToPrevious: () => void;
+  isLastSlide: boolean;
+  isFirstSlide: boolean;
+}
+
+/**
+ * Hook for managing onboarding navigation
+ *
+ * @param totalSlides - Total number of slides
+ * @param onComplete - Callback when onboarding completes
+ * @param onSkip - Callback when onboarding is skipped
+ * @returns Navigation state and handlers
+ */
+export const useOnboardingNavigation = (
+  totalSlides: number,
+  onComplete?: () => void | Promise<void>,
+  onSkip?: () => void | Promise<void>,
+): UseOnboardingNavigationReturn => {
+  const [currentIndex, setCurrentIndex] = useState(0);
+
+  const goToNext = useCallback(() => {
+    if (currentIndex < totalSlides - 1) {
+      setCurrentIndex(currentIndex + 1);
+    }
+  }, [currentIndex, totalSlides]);
+
+  const goToPrevious = useCallback(() => {
+    if (currentIndex > 0) {
+      setCurrentIndex(currentIndex - 1);
+    }
+  }, [currentIndex]);
+
+  const complete = useCallback(async () => {
+    if (onComplete) {
+      await onComplete();
+    }
+    // Emit event for app-level handling
+    DeviceEventEmitter.emit("onboarding-complete");
+  }, [onComplete]);
+
+  const skip = useCallback(async () => {
+    if (onSkip) {
+      await onSkip();
+    }
+    // Emit event for app-level handling
+    DeviceEventEmitter.emit("onboarding-complete");
+  }, [onSkip]);
+
+  return {
+    currentIndex,
+    goToNext,
+    goToPrevious,
+    complete,
+    skip,
+    isLastSlide: currentIndex === totalSlides - 1,
+    isFirstSlide: currentIndex === 0,
+  };
+};
+

package/src/infrastructure/storage/OnboardingStore.ts

@@ -0,0 +1,128 @@
+/**
+ * Onboarding Store
+ *
+ * Zustand store for managing onboarding completion state
+ * Uses @umituz/react-native-storage for persistence
+ */
+
+import { create } from "zustand";
+import {
+  storageRepository,
+  StorageKey,
+  unwrap,
+} from "@umituz/react-native-storage";
+
+interface OnboardingStore {
+  // State
+  isOnboardingComplete: boolean;
+  currentStep: number;
+  loading: boolean;
+  error: string | null;
+
+  // Actions
+  initialize: (storageKey?: string) => Promise<void>;
+  complete: (storageKey?: string) => Promise<void>;
+  skip: (storageKey?: string) => Promise<void>;
+  setCurrentStep: (step: number) => void;
+  reset: (storageKey?: string) => Promise<void>;
+  setLoading: (loading: boolean) => void;
+  setError: (error: string | null) => void;
+}
+
+const DEFAULT_STORAGE_KEY = StorageKey.ONBOARDING_COMPLETED;
+
+export const useOnboardingStore = create<OnboardingStore>((set, get) => ({
+  isOnboardingComplete: false,
+  currentStep: 0,
+  loading: true,
+  error: null,
+
+  initialize: async (storageKey = DEFAULT_STORAGE_KEY) => {
+    set({ loading: true, error: null });
+
+    const result = await storageRepository.getString(storageKey, "false");
+    const data = unwrap(result, "false");
+
+    set({
+      isOnboardingComplete: data === "true",
+      loading: false,
+      error: result.success ? null : result.error?.message || null,
+    });
+  },
+
+  complete: async (storageKey = DEFAULT_STORAGE_KEY) => {
+    set({ loading: true, error: null });
+
+    const result = await storageRepository.setString(storageKey, "true");
+
+    set({
+      isOnboardingComplete: result.success,
+      loading: false,
+      error: result.success ? null : result.error?.message || null,
+    });
+  },
+
+  skip: async (storageKey = DEFAULT_STORAGE_KEY) => {
+    set({ loading: true, error: null });
+
+    const result = await storageRepository.setString(storageKey, "true");
+
+    set({
+      isOnboardingComplete: result.success,
+      loading: false,
+      error: result.success ? null : result.error?.message || null,
+    });
+  },
+
+  setCurrentStep: (step) => set({ currentStep: step }),
+
+  reset: async (storageKey = DEFAULT_STORAGE_KEY) => {
+    set({ loading: true, error: null });
+
+    const result = await storageRepository.removeItem(storageKey);
+
+    set({
+      isOnboardingComplete: false,
+      currentStep: 0,
+      loading: false,
+      error: result.success ? null : result.error?.message || null,
+    });
+  },
+
+  setLoading: (loading) => set({ loading }),
+  setError: (error) => set({ error }),
+}));
+
+/**
+ * Hook for accessing onboarding state
+ */
+export const useOnboarding = () => {
+  const {
+    isOnboardingComplete,
+    currentStep,
+    loading,
+    error,
+    initialize,
+    complete,
+    skip,
+    setCurrentStep,
+    reset,
+    setLoading,
+    setError,
+  } = useOnboardingStore();
+
+  return {
+    isOnboardingComplete,
+    currentStep,
+    loading,
+    error,
+    initialize,
+    complete,
+    skip,
+    setCurrentStep,
+    reset,
+    setLoading,
+    setError,
+  };
+};
+

package/src/presentation/components/OnboardingFooter.tsx

@@ -0,0 +1,142 @@
+/**
+ * Onboarding Footer Component
+ *
+ * Displays progress bar, dots, and next/get started button
+ */
+
+import React, { useMemo } from "react";
+import { View, TouchableOpacity, Text, StyleSheet } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useLocalization } from "@umituz/react-native-localization";
+import { useAppDesignTokens } from "@umituz/react-native-theme";
+
+export interface OnboardingFooterProps {
+  currentIndex: number;
+  totalSlides: number;
+  isLastSlide: boolean;
+  onNext: () => void;
+  showProgressBar?: boolean;
+  showDots?: boolean;
+  showProgressText?: boolean;
+  nextButtonText?: string;
+  getStartedButtonText?: string;
+}
+
+export const OnboardingFooter: React.FC<OnboardingFooterProps> = ({
+  currentIndex,
+  totalSlides,
+  isLastSlide,
+  onNext,
+  showProgressBar = true,
+  showDots = true,
+  showProgressText = true,
+  nextButtonText,
+  getStartedButtonText,
+}) => {
+  const insets = useSafeAreaInsets();
+  const { t } = useLocalization();
+  const tokens = useAppDesignTokens();
+  const styles = useMemo(() => getStyles(insets, tokens), [insets, tokens]);
+
+  const buttonText = isLastSlide
+    ? getStartedButtonText || t("onboarding.getStarted", "Get Started")
+    : nextButtonText || t("general.continue", "Continue");
+
+  return (
+    <View style={styles.footer}>
+      {showProgressBar && (
+        <View style={styles.progressContainer}>
+          <View style={styles.progressBar}>
+            <View
+              style={[
+                styles.progressFill,
+                { width: `${((currentIndex + 1) / totalSlides) * 100}%` },
+              ]}
+            />
+          </View>
+        </View>
+      )}
+
+      {showDots && (
+        <View style={styles.dots}>
+          {Array.from({ length: totalSlides }).map((_, index) => (
+            <View
+              key={index}
+              style={[styles.dot, index === currentIndex && styles.dotActive]}
+            />
+          ))}
+        </View>
+      )}
+
+      <TouchableOpacity style={styles.button} onPress={onNext}>
+        <Text style={styles.buttonText}>{buttonText}</Text>
+      </TouchableOpacity>
+
+      {showProgressText && (
+        <Text style={styles.progressText}>
+          {currentIndex + 1} {t("general.of", "of")} {totalSlides}
+        </Text>
+      )}
+    </View>
+  );
+};
+
+const getStyles = (
+  insets: { bottom: number },
+  tokens: ReturnType<typeof useAppDesignTokens>,
+) =>
+  StyleSheet.create({
+    footer: {
+      paddingHorizontal: 30,
+      paddingTop: 30,
+      paddingBottom: insets.bottom + 20,
+    },
+    progressContainer: {
+      marginBottom: 20,
+    },
+    progressBar: {
+      height: 4,
+      backgroundColor: "rgba(255, 255, 255, 0.2)",
+      borderRadius: 2,
+      overflow: "hidden",
+    },
+    progressFill: {
+      height: "100%",
+      backgroundColor: "#FFFFFF",
+      borderRadius: 2,
+    },
+    dots: {
+      flexDirection: "row",
+      justifyContent: "center",
+      marginBottom: 30,
+      gap: 8,
+    },
+    dot: {
+      width: 6,
+      height: 6,
+      borderRadius: 3,
+      backgroundColor: "rgba(255, 255, 255, 0.4)",
+    },
+    dotActive: {
+      width: 8,
+      backgroundColor: "#FFFFFF",
+    },
+    button: {
+      backgroundColor: "#FFFFFF",
+      paddingVertical: 16,
+      borderRadius: 28,
+      alignItems: "center",
+      marginBottom: 12,
+    },
+    buttonText: {
+      color: tokens.colors.primary,
+      fontSize: 16,
+      fontWeight: "bold",
+    },
+    progressText: {
+      color: "rgba(255, 255, 255, 0.75)",
+      fontSize: 12,
+      textAlign: "center",
+    },
+  });
+

package/src/presentation/components/OnboardingHeader.tsx

@@ -0,0 +1,92 @@
+/**
+ * Onboarding Header Component
+ *
+ * Displays back and skip buttons
+ */
+
+import React, { useMemo } from "react";
+import { View, TouchableOpacity, Text, StyleSheet } from "react-native";
+import { useLocalization } from "@umituz/react-native-localization";
+
+export interface OnboardingHeaderProps {
+  isFirstSlide: boolean;
+  onBack: () => void;
+  onSkip: () => void;
+  showBackButton?: boolean;
+  showSkipButton?: boolean;
+  skipButtonText?: string;
+}
+
+export const OnboardingHeader: React.FC<OnboardingHeaderProps> = ({
+  isFirstSlide,
+  onBack,
+  onSkip,
+  showBackButton = true,
+  showSkipButton = true,
+  skipButtonText,
+}) => {
+  const { t } = useLocalization();
+  const styles = useMemo(() => getStyles(), []);
+
+  const skipText = skipButtonText || t("onboarding.skip", "Skip");
+
+  return (
+    <View style={styles.header}>
+      {showBackButton ? (
+        <TouchableOpacity
+          onPress={onBack}
+          disabled={isFirstSlide}
+          style={[
+            styles.headerButton,
+            isFirstSlide && styles.headerButtonDisabled,
+          ]}
+        >
+          <Text style={styles.headerButtonText}>←</Text>
+        </TouchableOpacity>
+      ) : (
+        <View style={styles.headerButton} />
+      )}
+      {showSkipButton && (
+        <TouchableOpacity onPress={onSkip}>
+          <Text style={styles.skipText}>{skipText}</Text>
+        </TouchableOpacity>
+      )}
+    </View>
+  );
+};
+
+const getStyles = () =>
+  StyleSheet.create({
+    header: {
+      flexDirection: "row",
+      justifyContent: "space-between",
+      alignItems: "center",
+      paddingHorizontal: 20,
+      paddingTop: 10,
+      paddingBottom: 20,
+    },
+    headerButton: {
+      width: 40,
+      height: 40,
+      borderRadius: 20,
+      backgroundColor: "rgba(255, 255, 255, 0.2)",
+      alignItems: "center",
+      justifyContent: "center",
+      borderWidth: 1,
+      borderColor: "rgba(255, 255, 255, 0.3)",
+    },
+    headerButtonDisabled: {
+      opacity: 0.3,
+    },
+    headerButtonText: {
+      color: "#FFFFFF",
+      fontSize: 20,
+      fontWeight: "bold",
+    },
+    skipText: {
+      color: "#FFFFFF",
+      fontSize: 16,
+      fontWeight: "600",
+    },
+  });
+

package/src/presentation/components/OnboardingSlide.tsx

@@ -0,0 +1,107 @@
+/**
+ * Onboarding Slide Component
+ *
+ * Displays a single onboarding slide with icon, title, and description
+ */
+
+import React, { useMemo } from "react";
+import { View, Text, StyleSheet, ScrollView } from "react-native";
+import type { OnboardingSlide as OnboardingSlideType } from "../../domain/entities/OnboardingSlide";
+
+export interface OnboardingSlideProps {
+  slide: OnboardingSlideType;
+}
+
+export const OnboardingSlide: React.FC<OnboardingSlideProps> = ({ slide }) => {
+  const styles = useMemo(() => getStyles(), []);
+
+  return (
+    <ScrollView
+      contentContainerStyle={styles.content}
+      showsVerticalScrollIndicator={false}
+      scrollEnabled={false}
+    >
+      <View style={styles.slideContent}>
+        <View style={styles.iconContainer}>
+          <Text style={styles.icon}>{slide.icon}</Text>
+        </View>
+        <Text style={styles.title}>{slide.title}</Text>
+        <Text style={styles.description}>{slide.description}</Text>
+        {slide.features && slide.features.length > 0 && (
+          <View style={styles.featuresContainer}>
+            {slide.features.map((feature, index) => (
+              <View key={index} style={styles.featureItem}>
+                <Text style={styles.featureBullet}>•</Text>
+                <Text style={styles.featureText}>{feature}</Text>
+              </View>
+            ))}
+          </View>
+        )}
+      </View>
+    </ScrollView>
+  );
+};
+
+const getStyles = () =>
+  StyleSheet.create({
+    content: {
+      flex: 1,
+      justifyContent: "center",
+      alignItems: "center",
+      paddingHorizontal: 30,
+    },
+    slideContent: {
+      alignItems: "center",
+      maxWidth: 400,
+    },
+    iconContainer: {
+      width: 120,
+      height: 120,
+      borderRadius: 60,
+      backgroundColor: "rgba(255, 255, 255, 0.2)",
+      alignItems: "center",
+      justifyContent: "center",
+      marginBottom: 40,
+      borderWidth: 2,
+      borderColor: "rgba(255, 255, 255, 0.3)",
+    },
+    icon: {
+      fontSize: 60,
+    },
+    title: {
+      fontSize: 28,
+      fontWeight: "bold",
+      color: "#FFFFFF",
+      textAlign: "center",
+      marginBottom: 16,
+    },
+    description: {
+      fontSize: 16,
+      color: "rgba(255, 255, 255, 0.95)",
+      textAlign: "center",
+      lineHeight: 24,
+      marginBottom: 20,
+    },
+    featuresContainer: {
+      width: "100%",
+      marginTop: 10,
+    },
+    featureItem: {
+      flexDirection: "row",
+      alignItems: "flex-start",
+      marginBottom: 12,
+    },
+    featureBullet: {
+      color: "#FFFFFF",
+      fontSize: 20,
+      marginRight: 12,
+      marginTop: 2,
+    },
+    featureText: {
+      flex: 1,
+      fontSize: 15,
+      color: "rgba(255, 255, 255, 0.9)",
+      lineHeight: 22,
+    },
+  });
+

package/src/presentation/screens/OnboardingScreen.tsx

@@ -0,0 +1,169 @@
+/**
+ * Onboarding Screen
+ *
+ * Main onboarding screen component with gradient backgrounds
+ * Generic and reusable across hundreds of apps
+ */
+
+import React, { useMemo } from "react";
+import { View, StyleSheet, StatusBar } from "react-native";
+import { LinearGradient } from "expo-linear-gradient";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import type { OnboardingOptions } from "../../domain/entities/OnboardingOptions";
+import { useOnboardingNavigation } from "../../infrastructure/hooks/useOnboardingNavigation";
+import { useOnboardingStore } from "../../infrastructure/storage/OnboardingStore";
+import { OnboardingHeader } from "../components/OnboardingHeader";
+import { OnboardingSlide } from "../components/OnboardingSlide";
+import { OnboardingFooter } from "../components/OnboardingFooter";
+
+export interface OnboardingScreenProps extends OnboardingOptions {
+  /**
+   * Optional custom header component
+   */
+  renderHeader?: (props: {
+    isFirstSlide: boolean;
+    onBack: () => void;
+    onSkip: () => void;
+  }) => React.ReactNode;
+
+  /**
+   * Optional custom footer component
+   */
+  renderFooter?: (props: {
+    currentIndex: number;
+    totalSlides: number;
+    isLastSlide: boolean;
+    onNext: () => void;
+  }) => React.ReactNode;
+
+  /**
+   * Optional custom slide component
+   */
+  renderSlide?: (slide: OnboardingOptions["slides"][0]) => React.ReactNode;
+}
+
+/**
+ * Onboarding Screen Component
+ *
+ * Displays onboarding flow with gradient backgrounds, animations, and navigation
+ */
+export const OnboardingScreen: React.FC<OnboardingScreenProps> = ({
+  slides,
+  onComplete,
+  onSkip,
+  skipButtonText,
+  nextButtonText,
+  getStartedButtonText,
+  showSkipButton = true,
+  showBackButton = true,
+  showProgressBar = true,
+  showDots = true,
+  showProgressText = true,
+  storageKey,
+  autoComplete = false,
+  renderHeader,
+  renderFooter,
+  renderSlide,
+}) => {
+  const insets = useSafeAreaInsets();
+  const onboardingStore = useOnboardingStore();
+
+  const handleComplete = async () => {
+    await onboardingStore.complete(storageKey);
+    if (onComplete) {
+      await onComplete();
+    }
+  };
+
+  const handleSkip = async () => {
+    await onboardingStore.skip(storageKey);
+    if (onSkip) {
+      await onSkip();
+    }
+  };
+
+  const {
+    currentIndex,
+    goToNext,
+    goToPrevious,
+    isLastSlide,
+    isFirstSlide,
+  } = useOnboardingNavigation(slides.length, handleComplete, handleSkip);
+
+  const handleNext = () => {
+    if (isLastSlide) {
+      if (autoComplete) {
+        handleComplete();
+      } else {
+        handleComplete();
+      }
+    } else {
+      goToNext();
+    }
+  };
+
+  const currentSlide = slides[currentIndex];
+  const styles = useMemo(() => getStyles(insets), [insets]);
+
+  return (
+    <View style={styles.container}>
+      <StatusBar barStyle="light-content" />
+      <LinearGradient
+        colors={currentSlide.gradient}
+        start={{ x: 0, y: 0 }}
+        end={{ x: 1, y: 1 }}
+        style={StyleSheet.absoluteFill}
+      />
+      {renderHeader ? (
+        renderHeader({
+          isFirstSlide,
+          onBack: goToPrevious,
+          onSkip: handleSkip,
+        })
+      ) : (
+        <OnboardingHeader
+          isFirstSlide={isFirstSlide}
+          onBack={goToPrevious}
+          onSkip={handleSkip}
+          showBackButton={showBackButton}
+          showSkipButton={showSkipButton}
+          skipButtonText={skipButtonText}
+        />
+      )}
+      {renderSlide ? (
+        renderSlide(currentSlide)
+      ) : (
+        <OnboardingSlide slide={currentSlide} />
+      )}
+      {renderFooter ? (
+        renderFooter({
+          currentIndex,
+          totalSlides: slides.length,
+          isLastSlide,
+          onNext: handleNext,
+        })
+      ) : (
+        <OnboardingFooter
+          currentIndex={currentIndex}
+          totalSlides={slides.length}
+          isLastSlide={isLastSlide}
+          onNext={handleNext}
+          showProgressBar={showProgressBar}
+          showDots={showDots}
+          showProgressText={showProgressText}
+          nextButtonText={nextButtonText}
+          getStartedButtonText={getStartedButtonText}
+        />
+      )}
+    </View>
+  );
+};
+
+const getStyles = (insets: { top: number }) =>
+  StyleSheet.create({
+    container: {
+      flex: 1,
+      paddingTop: insets.top,
+    },
+  });
+