@devo-bmad-custom/agent-orchestration 1.0.0

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/tipkit/SKILL.md

@@ -0,0 +1,494 @@
+---
+name: tipkit
+description: "Implement, review, or improve in-app tips and onboarding using Apple's TipKit framework. Use when adding feature discovery tooltips, onboarding flows, contextual tips, first-run experiences, coach marks, or working with Tip protocol, TipView, popoverTip, tip rules, tip events, or feature education UI."
+---
+
+# TipKit
+
+Add feature discovery tips, contextual hints, and onboarding coach marks to
+iOS 17+ apps using Apple's TipKit framework. TipKit manages display frequency,
+eligibility rules, and persistence so tips appear at the right time and
+disappear once the user has learned the feature.
+
+## Contents
+
+- [Setup](#setup)
+- [Defining Tips](#defining-tips)
+- [Displaying Tips](#displaying-tips)
+- [Tip Rules](#tip-rules)
+- [Tip Actions](#tip-actions)
+- [Tip Groups](#tip-groups)
+- [Programmatic Control](#programmatic-control)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+- [References](#references)
+
+## Setup
+
+Call `Tips.configure()` once in `App.init`, before any views render. This
+initializes the tips datastore and begins rule evaluation. Calling it later
+risks a race where tip views attempt to display before the datastore is ready.
+
+```swift
+import SwiftUI
+import TipKit
+
+@main
+struct MyApp: App {
+    init() {
+        try? Tips.configure([
+            .datastoreLocation(.applicationDefault)
+        ])
+    }
+
+    var body: some Scene {
+        WindowGroup { ContentView() }
+    }
+}
+```
+
+### DatastoreLocation Options
+
+| Option | Use Case |
+|---|---|
+| `.applicationDefault` | Default location, app sandbox (most apps) |
+| `.groupContainer(identifier:)` | Share tips state across app and extensions |
+| `.url(_:)` | Custom file URL for full control over storage location |
+
+### CloudKit Sync
+
+Sync tip state across a user's devices so they do not see the same tip on
+every device. Add the CloudKit container option alongside the datastore
+location.
+
+```swift
+try? Tips.configure([
+    .datastoreLocation(.applicationDefault),
+    .cloudKitContainer(.named("iCloud.com.example.app"))
+])
+```
+
+## Defining Tips
+
+Conform a struct to the `Tip` protocol. Provide a `title` at minimum.
+Add `message` for supporting detail and `image` for a leading icon. Keep
+titles short and action-oriented because the tip appears as a compact callout.
+
+```swift
+import TipKit
+
+struct FavoriteTip: Tip {
+    var title: Text { Text("Pin Your Favorites") }
+    var message: Text? { Text("Tap the heart icon to save items for quick access.") }
+    var image: Image? { Image(systemName: "heart") }
+}
+```
+
+**Properties**: `title` (required), `message` (optional detail), `image` (optional leading icon), `actions` (optional buttons), `rules` (optional eligibility conditions), `options` (display frequency, max count).
+
+**Lifecycle**: Pending (rules unsatisfied) -> Eligible (all rules pass) -> Invalidated (dismissed, actioned, or programmatically removed). Once invalidated, a tip does not reappear unless the datastore is reset.
+
+## Displaying Tips
+
+### Inline Tips with TipView
+
+Embed a `TipView` directly in your layout. It renders as a rounded card that
+appears and disappears with animation. Use for tips within scrollable content.
+
+```swift
+let favoriteTip = FavoriteTip()
+var body: some View {
+    VStack {
+        TipView(favoriteTip)
+        ItemListView()
+    }
+}
+```
+
+### Popover Tips with .popoverTip()
+
+Attach a tip as a popover anchored to any view. The framework draws an arrow
+from the popover to the anchor. Use for tips pointing to a specific control.
+
+```swift
+Button { toggleFavorite() } label: { Image(systemName: "heart") }
+    .popoverTip(favoriteTip)
+
+// Control arrow direction (omit to let system choose)
+.popoverTip(favoriteTip, arrowEdge: .bottom)
+```
+
+### Custom TipViewStyle
+
+Create a custom style to control tip appearance across the app. Conform
+to `TipViewStyle` and implement `makeBody(configuration:)`.
+
+```swift
+struct CustomTipStyle: TipViewStyle {
+    func makeBody(configuration: Configuration) -> some View {
+        HStack(spacing: 12) {
+            configuration.image?
+                .font(.title2)
+                .foregroundStyle(.tint)
+
+            VStack(alignment: .leading, spacing: 4) {
+                configuration.title
+                    .font(.headline)
+                configuration.message?
+                    .font(.subheadline)
+                    .foregroundStyle(.secondary)
+            }
+        }
+        .padding()
+    }
+}
+
+// Apply globally or per view
+TipView(favoriteTip)
+    .tipViewStyle(CustomTipStyle())
+```
+
+## Tip Rules
+
+Rules control when a tip becomes eligible. All rules in the `rules` array
+must pass before the tip displays. TipKit supports two rule types:
+parameter-based and event-based.
+
+### Parameter-Based Rules
+
+Use `@Parameter` to track app state. The tip becomes eligible when the
+parameter value satisfies the rule condition.
+
+```swift
+struct FavoriteTip: Tip {
+    @Parameter
+    static var hasSeenList: Bool = false
+
+    var title: Text { Text("Pin Your Favorites") }
+
+    var rules: [Rule] {
+        #Rule(Self.$hasSeenList) { $0 == true }
+    }
+}
+
+// Set the parameter when the user reaches the list
+FavoriteTip.hasSeenList = true
+```
+
+### Event-Based Rules
+
+Use `Tips.Event` to track user actions. Donate to the event each time the
+action occurs. The rule fires when the donation count or timing condition
+is met. This is ideal for tips that should appear after the user has
+performed an action several times without discovering a related feature.
+
+```swift
+struct ShortcutTip: Tip {
+    static let appOpenedEvent = Tips.Event(id: "appOpened")
+
+    var title: Text { Text("Try the Quick Action") }
+
+    var rules: [Rule] {
+        #Rule(Self.appOpenedEvent) { $0.donations.count >= 3 }
+    }
+}
+
+// Donate each time the app opens
+ShortcutTip.appOpenedEvent.donate()
+```
+
+### Combining Multiple Rules
+
+Place multiple rules in the array. All must pass (logical AND).
+
+```swift
+struct AdvancedTip: Tip {
+    @Parameter
+    static var isLoggedIn: Bool = false
+
+    static let featureUsedEvent = Tips.Event(id: "featureUsed")
+
+    var title: Text { Text("Unlock Advanced Mode") }
+
+    var rules: [Rule] {
+        #Rule(Self.$isLoggedIn) { $0 == true }
+        #Rule(Self.featureUsedEvent) { $0.donations.count >= 5 }
+    }
+}
+```
+
+### Display Frequency Options
+
+Control how often tips appear using the `options` property.
+
+```swift
+struct DailyTip: Tip {
+    var title: Text { Text("Daily Reminder") }
+
+    var options: [TipOption] {
+        MaxDisplayCount(3)                   // Show at most 3 times total
+        IgnoresDisplayFrequency(true)        // Bypass global frequency limit
+    }
+}
+```
+
+Global display frequency is set at configuration time:
+
+```swift
+try? Tips.configure([
+    .displayFrequency(.daily)  // .immediate, .hourly, .daily, .weekly, .monthly
+])
+```
+
+With `.daily`, the system shows at most one tip per day across the entire
+app, unless a specific tip sets `IgnoresDisplayFrequency(true)`.
+
+## Tip Actions
+
+Add action buttons to a tip for direct interaction. Each action has an `id`
+and a label. Handle the action in the tip view's action handler.
+
+```swift
+struct FeatureTip: Tip {
+    var title: Text { Text("Try the New Editor") }
+    var message: Text? { Text("We added a powerful new editing mode.") }
+
+    var actions: [Action] {
+        Action(id: "open-editor", title: "Open Editor")
+        Action(id: "learn-more", title: "Learn More")
+    }
+}
+```
+
+Handle actions in the view:
+
+```swift
+TipView(featureTip) { action in
+    switch action.id {
+    case "open-editor":
+        navigateToEditor()
+        featureTip.invalidate(reason: .actionPerformed)
+    case "learn-more":
+        showHelpSheet = true
+    default:
+        break
+    }
+}
+```
+
+## Tip Groups
+
+Use `TipGroup` to coordinate multiple tips within a single view.
+`TipGroup` ensures only one tip from the group displays at a time,
+preventing tip overload. Tips display in priority order.
+
+```swift
+struct OnboardingView: View {
+    let tipGroup = TipGroup(.ordered) {
+        WelcomeTip()
+        NavigationTip()
+        ProfileTip()
+    }
+
+    var body: some View {
+        VStack {
+            if let currentTip = tipGroup.currentTip {
+                TipView(currentTip)
+            }
+
+            Button("Next") {
+                tipGroup.currentTip?.invalidate(reason: .actionPerformed)
+            }
+        }
+    }
+}
+```
+
+### Priority Options
+
+| Initializer | Behavior |
+|---|---|
+| `.ordered` | Tips display in the order they are listed |
+
+When the current tip is invalidated, the next eligible tip in the group
+becomes `currentTip`.
+
+## Programmatic Control
+
+### Invalidating Tips
+
+Call `invalidate(reason:)` when the user performs the discovered action or
+when the tip is no longer relevant.
+
+```swift
+let tip = FavoriteTip()
+tip.invalidate(reason: .actionPerformed)
+```
+
+| Reason | When to Use |
+|---|---|
+| `.actionPerformed` | User performed the action the tip describes |
+| `.displayCountExceeded` | Tip hit its maximum display count |
+| `.tipClosed` | User explicitly dismissed the tip |
+
+### Testing Utilities
+
+TipKit provides static methods to control tip visibility during development
+and testing. Gate these behind `#if DEBUG` or `ProcessInfo` checks so they
+never run in production builds.
+
+```swift
+#if DEBUG
+// Show all tips regardless of rules (useful during development)
+Tips.showAllTipsForTesting()
+
+// Show only specific tips
+Tips.showTipsForTesting([FavoriteTip.self, ShortcutTip.self])
+
+// Hide all tips (useful for UI tests that do not involve tips)
+Tips.hideAllTipsForTesting()
+
+// Reset the datastore (clears all tip state, invalidations, and events)
+try? Tips.resetDatastore()
+#endif
+```
+
+### Using ProcessInfo for Test Schemes
+
+```swift
+if ProcessInfo.processInfo.arguments.contains("--show-all-tips") {
+    Tips.showAllTipsForTesting()
+}
+```
+
+Pass `--show-all-tips` as a launch argument in the Xcode scheme for
+development builds.
+
+## Common Mistakes
+
+### DON'T: Call Tips.configure() anywhere except App.init
+
+Calling `Tips.configure()` in a view's `onAppear` or `task` modifier
+creates a race condition where tip views try to render before the
+datastore is ready, causing missing or flickering tips.
+
+```swift
+// WRONG
+struct ContentView: View {
+    var body: some View {
+        Text("Hello")
+            .task { try? Tips.configure() }  // Too late, views already rendered
+    }
+}
+
+// CORRECT
+@main struct MyApp: App {
+    init() { try? Tips.configure() }
+    var body: some Scene { WindowGroup { ContentView() } }
+}
+```
+
+### DON'T: Show too many tips at once
+
+Displaying multiple tips simultaneously overwhelms users and dilutes the
+impact of each tip. Users learn to ignore them.
+
+```swift
+// WRONG: Three tips visible at the same time
+VStack {
+    TipView(tipA)
+    TipView(tipB)
+    TipView(tipC)
+}
+
+// CORRECT: Use TipGroup to sequence them
+let group = TipGroup(.ordered) { TipA(); TipB(); TipC() }
+if let currentTip = group.currentTip {
+    TipView(currentTip)
+}
+```
+
+### DON'T: Forget to invalidate tips after the user performs the action
+
+If a tip says "Tap the star to favorite" and the user taps the star but
+the tip remains, it erodes trust in the UI.
+
+```swift
+// WRONG: Tip stays visible after user acts
+Button("Favorite") { toggleFavorite() }
+    .popoverTip(favoriteTip)
+
+// CORRECT: Invalidate on action
+Button("Favorite") {
+    toggleFavorite()
+    favoriteTip.invalidate(reason: .actionPerformed)
+}
+.popoverTip(favoriteTip)
+```
+
+### DON'T: Leave testing tips enabled in production
+
+`Tips.showAllTipsForTesting()` bypasses all rules and frequency limits.
+Shipping this in production means every user sees every tip immediately.
+
+```swift
+// WRONG: Always active
+Tips.showAllTipsForTesting()
+
+// CORRECT: Gated behind DEBUG
+#if DEBUG
+Tips.showAllTipsForTesting()
+#endif
+```
+
+### DON'T: Make tip titles too long
+
+Long titles get truncated or wrap awkwardly in the compact tip callout.
+Put the key action in the title and supporting context in the message.
+
+```swift
+// WRONG
+var title: Text { Text("You can tap the heart button to save this item to your favorites list") }
+
+// CORRECT
+var title: Text { Text("Save to Favorites") }
+var message: Text? { Text("Tap the heart icon to keep items for quick access.") }
+```
+
+### DON'T: Use tips for critical information
+
+Users can dismiss tips at any time and they do not reappear. Never put
+essential instructions or safety information in a tip.
+
+```swift
+// WRONG: Critical info in a dismissible tip
+struct DataLossTip: Tip {
+    var title: Text { Text("Unsaved changes will be lost") }
+}
+
+// CORRECT: Use an alert or inline warning for critical information
+// Reserve tips for feature discovery and progressive disclosure
+```
+
+## Review Checklist
+
+- [ ] `Tips.configure()` called in `App.init`, before any views render
+- [ ] Each tip has a clear, concise title (action-oriented, under ~40 characters)
+- [ ] Tips invalidated when the user performs the discovered action
+- [ ] Rules set so tips appear at the right time (not immediately on first launch for all tips)
+- [ ] `TipGroup` used when multiple tips exist in one view
+- [ ] Testing utilities (`showAllTipsForTesting`, `resetDatastore`) gated behind `#if DEBUG`
+- [ ] CloudKit sync configured if the app supports multiple devices
+- [ ] Display frequency set appropriately (`.daily` or `.weekly` for most apps)
+- [ ] Tips used for feature discovery only, not for critical information
+- [ ] Custom `TipViewStyle` applied consistently if the default style does not match the app design
+- [ ] Tip actions handled and tip invalidated in the action handler
+- [ ] Event donations placed at the correct user action points
+- [ ] Ensure custom Tip types are Sendable; configure Tips on @MainActor
+
+## References
+
+- See `references/tipkit-patterns.md` for complete implementation patterns
+  including custom styles, event-based rules, tip groups, testing strategies,
+  onboarding flows, and SwiftUI preview configuration.
+