@devo-bmad-custom/agent-orchestration 1.0.2 → 1.0.4

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

@@ -1,494 +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.
-
+---
+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.
+