InstructUI

🧭 A Swift package for building guided, touch-friendly instructional overlays in SwiftUI. Ideal for apps with voice assistance, learning flows, or gesture-based tutorials.

• ✅ InstructionOverlay — draws a cutout and message above any UI element
• ✅ InstructionGuide — attachable ViewModifier for multi-step instruction flows
• ✅ Built-in speech synthesis with SpeechKit
• ✅ Child-friendly and gesture-driven by design
• ✅ Works with `PreferenceKey-based layout tracking
• ✅ Fully documented with DocC-style comments

Use Swift Package Manager:

.package(url: "https://github.com/michaelborgmann/InstructUI.git", from: "0.1.0")

Then import it where needed:

import InstructUI

If using voice support, also include:

import SpeechKit

Create an array of InstructionStep using frames from instructionAnchor preferences:

@State var steps: [InstructionStep] = []
@State var currentStepIndex: Int? = 0
let speaker = SpeechSynthesizer()

Attach instructionAnchor(id:) to any view you want to highlight:

Button("Tap me") {
    currentStepIndex = 0
}
.instructionAnchor(id: "start-button")

Apply the InstructionGuide view modifier to your main container:

.frame(maxWidth: .infinity, maxHeight: .infinity) // Optional: ensure layout fills the screen
.modifier(InstructionGuide(steps: $steps, currentStepIndex: $currentStepIndex, speaker: speaker))
.edgesIgnoringSafeArea(.all) // Optional: extend behind safe areas

Use .onPreferenceChange(ViewFrameKey.self) to populate your steps once layout is complete:

.onPreferenceChange(ViewFrameKey.self) { frames in
    if !frames.isEmpty {
        instructionSteps = [
            InstructionStep(message: "This is an instruction overlay on top of a button", highlightFrame: frames["instruction-button"]!, isMessageBelow: true)
        ]
    }
}

You can advance to the next step manually or by listening to a custom event:

.onReceive(NotificationCenter.default.publisher(for: .instructionNext)) { _ in
    if let i = currentStepIndex {
        let next = i + 1
        currentStepIndex = next < steps.count ? next : nil
    }
}

To see it in action, check out the #Preview examples inside InstructionGuide.swift. These show single-step and scrollable usage patterns, helpful for getting started or customizing your implementation.

iOS 17+ Swift 5.9 or 6 Swift Concurrency Swift Package Manager (SPM)

MIT License — see LICENSE

Please credit this project if you use it in commercial or open-source apps.

Created by Michael Borgmann for the Wonder Tales storytelling engine. Part of the Vicentina Studios toolchain for creative, language-rich experiences.