tipkit

What this skill does

# 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 {
            configuration.image?
                .font(.title2)
                .foregroundStyle(.tint)

            VStack(alignment: .leading) {
                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)
            }
        }
    }
}
```

###