Onboarding Generator

Onboarding Generator

Generate a complete, customizable onboarding flow with persistence, animations, and accessibility support.

When This Skill Activates

Use this skill when the user:

• Asks to "add onboarding" or "create onboarding"
• Mentions "welcome screens" or "first launch"
• Wants to "show intro on first launch"
• Asks about "onboarding flow" or "tutorial screens"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check for existing onboarding implementations
• [ ] Identify if SwiftUI or UIKit project
• [ ] Find App entry point location
• [ ] Check deployment target (TabView paging requires iOS 14+)

2. Conflict Detection

Search for existing onboarding:

Glob: **/*Onboarding*.swift, **/*Welcome*.swift
Grep: "hasCompletedOnboarding" or "isFirstLaunch"

If found, ask user:

• Replace existing onboarding?
• Keep existing, add new flow?

Configuration Questions

Ask user via AskUserQuestion:

1. Navigation style?

• Paged (horizontal swipe with dots)
• Stepped (Next/Back buttons)

2. Number of screens?

• 2-5 screens (recommend 3-4)

3. Skip option?

• Allow skip button
• Mandatory completion

4. Presentation style?

• Full screen cover (modal)
• Inline (embedded in view hierarchy)

5. Include animations?

• Animated transitions
• Static transitions

Generation Process

Step 1: Create Core Files

Generate these files: 1. OnboardingView.swift - Main container 2. OnboardingPageView.swift - Individual page template 3. OnboardingPage.swift - Page data model 4. OnboardingStorage.swift - Persistence 5. OnboardingModifier.swift - View modifier for easy integration

Step 2: Customize Based on Configuration

Paged Navigation:

TabView(selection: $currentPage) {
    ForEach(pages) { page in
        OnboardingPageView(page: page)
            .tag(page.id)
    }
}
.tabViewStyle(.page(indexDisplayMode: .always))

Stepped Navigation:

VStack {
    OnboardingPageView(page: pages[currentPage])

    HStack {
        if currentPage > 0 {
            Button("Back") { currentPage -= 1 }
        }
        Spacer()
        Button(isLastPage ? "Get Started" : "Next") {
            if isLastPage {
                completeOnboarding()
            } else {
                currentPage += 1
            }
        }
    }
}

Step 3: Determine File Location

Check project structure:

• If Sources/ exists → Sources/Onboarding/
• If App/ exists → App/Onboarding/
• Otherwise → Onboarding/

Output Format

After generation, provide:

Files Created

Sources/Onboarding/
├── OnboardingView.swift           # Main container
├── OnboardingPageView.swift       # Page template
├── OnboardingPage.swift           # Data model
├── OnboardingStorage.swift        # @AppStorage persistence
└── OnboardingModifier.swift       # .onboarding() modifier

Integration Steps

Option 1: View Modifier (Recommended)

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onboarding()  // Automatically shows on first launch
        }
    }
}

Option 2: Manual Control

@main
struct MyApp: App {
    @AppStorage("hasCompletedOnboarding") private var hasCompletedOnboarding = false

    var body: some Scene {
        WindowGroup {
            ContentView()
                .fullScreenCover(isPresented: .constant(!hasCompletedOnboarding)) {
                    OnboardingView()
                }
        }
    }
}

Customization

Add Your Content:

// In OnboardingStorage.swift or OnboardingView.swift
static let pages: [OnboardingPage] = [
    OnboardingPage(
        title: "Welcome",
        description: "Your app description here",
        imageName: "hand.wave",  // SF Symbol or asset name
        accentColor: .blue
    ),
    // Add more pages...
]

Testing Instructions

1. Delete app from simulator (to reset UserDefaults) 2. Run app - onboarding should appear 3. Complete onboarding 4. Relaunch app - onboarding should NOT appear 5. Reset via Settings or delete app to test again

Debug/Testing Reset

// Add to Settings or debug menu
Button("Reset Onboarding") {
    UserDefaults.standard.removeObject(forKey: "hasCompletedOnboarding")
}

References

• onboarding-patterns.md - Best practices and design patterns
• templates/ - All template files

Onboarding Patterns and Best Practices

Design Principles

Keep It Short

• 3-4 screens optimal
• Users want to use the app, not read tutorials
• Save detailed tutorials for in-app help

Focus on Value

• Explain benefits, not features
• "Save time" not "Has a calendar sync feature"
• Show outcomes, not mechanics

Make It Skippable

• Power users don't need handholding
• Always provide a way out
• Remember: they already downloaded your app

Navigation Patterns

Paged (Swipe)

Best for: Visual, image-heavy onboarding

TabView(selection: $currentPage) {
    ForEach(Array(pages.enumerated()), id: \.element.id) { index, page in
        OnboardingPageView(page: page)
            .tag(index)
    }
}
.tabViewStyle(.page(indexDisplayMode: .always))
.indexViewStyle(.page(backgroundDisplayMode: .always))

Pros:

• Intuitive gesture
• Progress visible via dots
• Works well on all screen sizes

Cons:

• Easy to accidentally swipe past content
• Less control over pacing

Stepped (Buttons)

Best for: Permission requests, sequential setup

VStack {
    OnboardingPageView(page: pages[currentPage])
        .transition(.asymmetric(
            insertion: .move(edge: .trailing),
            removal: .move(edge: .leading)
        ))

    HStack {
        if currentPage > 0 {
            Button("Back") {
                withAnimation { currentPage -= 1 }
            }
        }
        Spacer()
        Button(currentPage == pages.count - 1 ? "Get Started" : "Next") {
            withAnimation {
                if currentPage == pages.count - 1 {
                    completeOnboarding()
                } else {
                    currentPage += 1
                }
            }
        }
        .buttonStyle(.borderedProminent)
    }
    .padding()
}

Pros:

• Clear calls to action
• Better for requesting permissions at specific steps
• Users must acknowledge each screen

Cons:

• More taps required
• Can feel slower

Persistence Patterns

@AppStorage (Simple)

@AppStorage("hasCompletedOnboarding") private var hasCompletedOnboarding = false

When to use:

• Simple boolean "has seen onboarding"
• No need to track individual pages
• OK if reset on app reinstall

UserDefaults with Version

struct OnboardingStorage {
    private static let key = "onboardingCompletedVersion"
    private static let currentVersion = 2  // Increment to show again

    static var hasCompletedOnboarding: Bool {
        get { UserDefaults.standard.integer(forKey: key) >= currentVersion }
        set { UserDefaults.standard.set(newValue ? currentVersion : 0, forKey: key) }
    }
}

When to use:

• Want to show onboarding again after major updates
• Need to track which version user saw

Keychain (Persists Reinstall)

// Use KeychainAccess or similar library
let keychain = Keychain(service: "com.yourapp.onboarding")
let hasCompleted = keychain["completed"] != nil

When to use:

• Must persist across reinstalls
• Subscription apps where reinstall shouldn't reset

Presentation Patterns

Full Screen Cover

.fullScreenCover(isPresented: $showOnboarding) {
    OnboardingView(onComplete: { showOnboarding = false })
}

Best for:

• Immersive onboarding
• When main UI shouldn't be visible

Sheet

.sheet(isPresented: $showOnboarding) {
    OnboardingView()
        .interactiveDismissDisabled()  // Prevent swipe to dismiss
}

Best for:

• Less intrusive feel
• macOS apps (sheets are more common)

Inline

if !hasCompletedOnboarding {
    OnboardingView(onComplete: { hasCompletedOnboarding = true })
} else {
    MainContentView()
}

Best for:

• Simple apps
• When you want immediate transition

Animation Patterns

Page Transitions

OnboardingPageView(page: pages[currentPage])
    .id(currentPage)  // Force view recreation
    .transition(.asymmetric(
        insertion: .move(edge: .trailing).combined(with: .opacity),
        removal: .move(edge: .leading).combined(with: .opacity)
    ))
    .animation(.easeInOut(duration: 0.3), value: currentPage)

Image Animations

Image(systemName: page.imageName)
    .font(.system(size: 100))
    .symbolEffect(.bounce, value: isAnimating)
    .onAppear { isAnimating = true }

Progress Indicator

// Custom progress bar
GeometryReader { geometry in
    Rectangle()
        .fill(Color.accentColor)
        .frame(width: geometry.size.width * CGFloat(currentPage + 1) / CGFloat(pages.count))
        .animation(.easeInOut, value: currentPage)
}
.frame(height: 4)

Accessibility Patterns

VoiceOver Support

OnboardingPageView(page: page)
    .accessibilityElement(children: .combine)
    .accessibilityLabel("\(page.title). \(page.description)")
    .accessibilityHint("Page \(index + 1) of \(pages.count)")

Dynamic Type

Text(page.title)
    .font(.title)  // Use semantic fonts
    .minimumScaleFactor(0.7)  // Allow shrinking if needed
    .lineLimit(2)

Text(page.description)
    .font(.body)

Reduced Motion

@Environment(\.accessibilityReduceMotion) var reduceMotion

.animation(reduceMotion ? nil : .easeInOut, value: currentPage)

Permission Request Integration

Request permissions at relevant onboarding steps:

struct OnboardingPage: Identifiable {
    let id = UUID()
    let title: String
    let description: String
    let imageName: String
    let permissionRequest: PermissionType?

    enum PermissionType {
        case notifications
        case location
        case camera
        case photos
    }
}

// In OnboardingPageView
if let permission = page.permissionRequest {
    Button("Enable") {
        requestPermission(permission)
    }
    .buttonStyle(.borderedProminent)
}

Content Guidelines

Screen 1: Welcome

• App name/logo
• One-line value proposition
• Warm, inviting imagery

Screen 2-3: Key Features

• One feature per screen
• Benefit-focused copy
• Relevant illustration/screenshot

Screen 4: Get Started

• Clear call to action
• Optional: Sign up / Sign in
• Optional: Permission request

Anti-Patterns to Avoid

Don't

• Show more than 5 screens
• Use walls of text
• Require all permissions upfront
• Make it unskippable with no good reason
• Show onboarding on every app update

Do

• Keep text under 2 sentences per screen
• Use illustrations/icons
• Request permissions contextually
• Provide skip option
• Use versioned persistence for updates