widgetkit

What this skill does

# WidgetKit Development Skill

Build glanceable, timely experiences across Apple platforms using WidgetKit.

## Quick Start

### Create Widget Extension
1. File → New → Target → Widget Extension
2. Deselect "Include Live Activity" and "Include Configuration App Intent" for static widgets
3. Widget requires: `Widget` protocol, `TimelineProvider`, and SwiftUI views

### Minimal Widget Structure

```swift
@main
struct MyWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: "com.app.mywidget",
            provider: Provider()
        ) { entry in
            MyWidgetView(entry: entry)
        }
        .configurationDisplayName("My Widget")
        .description("Shows key information")
        .supportedFamilies([.systemSmall, .systemMedium])
    }
}

struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> SimpleEntry {
        SimpleEntry(date: .now)
    }
    
    func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> Void) {
        completion(SimpleEntry(date: .now))
    }
    
    func getTimeline(in context: Context, completion: @escaping (Timeline<SimpleEntry>) -> Void) {
        let entry = SimpleEntry(date: .now)
        let nextUpdate = Calendar.current.date(byAdding: .minute, value: 15, to: .now)!
        completion(Timeline(entries: [entry], policy: .after(nextUpdate)))
    }
}

struct SimpleEntry: TimelineEntry {
    let date: Date
}
```

## Widget Families & Sizes

| Family | Platforms | Use Case |
|--------|-----------|----------|
| `systemSmall` | iOS, iPadOS, macOS, visionOS | Single tap target, glanceable info |
| `systemMedium` | iOS, iPadOS, macOS, visionOS | Multiple data points, interactive elements |
| `systemLarge` | iOS, iPadOS, macOS, visionOS | Rich content, multiple interactions |
| `systemExtraLarge` | iPadOS, macOS, visionOS | Dashboard-style layouts |
| `accessoryCircular` | iOS Lock Screen, watchOS | Minimal info, gauge-style |
| `accessoryRectangular` | iOS Lock Screen, watchOS | 2-3 lines of text |
| `accessoryInline` | iOS Lock Screen, watchOS | Single line text + optional image |
| `accessoryCorner` | watchOS only | Corner complications |

### Adapt to Widget Family

```swift
struct MyWidgetView: View {
    @Environment(\.widgetFamily) var family
    
    var body: some View {
        switch family {
        case .systemSmall: CompactView()
        case .systemMedium: MediumView()
        case .systemLarge: DetailedView()
        case .accessoryCircular: GaugeView()
        case .accessoryRectangular: RectangularView()
        default: CompactView()
        }
    }
}
```

## Rendering Modes

Widgets render differently based on context:

| Mode | When Used | Behavior |
|------|-----------|----------|
| `fullColor` | Home Screen (iOS 17-), macOS desktop | Full color preserved |
| `accented` | Home Screen tinted/clear, visionOS, watchOS | Divides into accent + primary groups |
| `vibrant` | Lock Screen, StandBy | Desaturated, blurred effect |

```swift
@Environment(\.widgetRenderingMode) var renderingMode

var body: some View {
    switch renderingMode {
    case .fullColor: FullColorView()
    case .accented: AccentedView()
    case .vibrant: VibrantView()
    @unknown default: FullColorView()
    }
}
```

## Interactivity

### Buttons & Toggles (iOS 17+)
```swift
Button(intent: RefreshIntent()) {
    Label("Refresh", systemImage: "arrow.clockwise")
}

Toggle(isOn: $isEnabled, intent: ToggleIntent()) {
    Text("Enable")
}
```

### Deep Links
```swift
MyWidgetView()
    .widgetURL(URL(string: "myapp://detail/123")!)

// Or for multiple links in larger widgets:
Link(destination: URL(string: "myapp://item/1")!) {
    ItemView()
}
```

## Configuration Types

| Type | Use Case |
|------|----------|
| `StaticConfiguration` | No user configuration needed |
| `AppIntentConfiguration` | User-configurable (iOS 17+) |
| `ActivityConfiguration` | Live Activities |

## Reference Documentation

- **[Timeline & Updates](references/timelines.md)**: Timeline providers, reload policies, push updates
- **[Interactivity](references/interactivity.md)**: Buttons, toggles, App Intents, deep links
- **[Live Activities](references/live-activities.md)**: ActivityKit, Dynamic Island, Lock Screen
- **[Design Guidelines](references/design-guidelines.md)**: HIG best practices, layout, typography
- **[Platform Specifics](references/platforms.md)**: iOS, watchOS, macOS, visionOS differences
- **[Dimensions](references/dimensions.md)**: Exact sizes for all widget families per device

## Key Constraints

- **No real-time updates**: Use timelines; system batches updates
- **Limited budget**: ~40-70 refreshes/day depending on usage
- **No continuous animations**: Only transition animations up to 2 seconds
- **SwiftUI only**: UIKit views not supported
- **Stateless**: No persistent state between renders
- **No network in views**: Fetch data in timeline provider only

## Common Patterns

### Share Data with Main App
```swift
// Use App Groups
let sharedDefaults = UserDefaults(suiteName: "group.com.app.shared")

// Or shared container
let containerURL = FileManager.default.containerURL(
    forSecurityApplicationGroupIdentifier: "group.com.app.shared"
)
```

### Force Widget Refresh
```swift
import WidgetKit
WidgetCenter.shared.reloadTimelines(ofKind: "com.app.mywidget")
WidgetCenter.shared.reloadAllTimelines()
```

### Placeholder for Sensitive Content
```swift
.privacySensitive() // Redacts when device locked
```