widgets

name	widgets
description	Writes and reviews SwiftUI WidgetKit code for Home Screen, Lock Screen, StandBy, and watch widgets - timeline providers and reload policies, StaticConfiguration / AppIntentConfiguration, user-configurable widgets, widget families and sizing, accented/tinted rendering modes, interactive widgets and Controls (Control Center), Live Activities and the Dynamic Island, Smart Stack relevance, push-updated widgets, and visionOS / CarPlay / macOS surfaces. Use when building a widget extension, a timeline provider, a Lock Screen or accessory widget, a watch complication, an interactive button/toggle widget, a Control Center control, a Live Activity, or fixing a widget that won't update or render correctly in tinted mode.
license	MIT
metadata	{"author":"Anton Novoselov","version":"1.2"}

Write and review SwiftUI WidgetKit code, choosing the right configuration, timeline policy, and surface so the widget renders correctly in every mode, updates within its budget, and behaves correctly across the extension/app process boundary.

Review process:

1. Establish the widget execution model (the extension process, app groups, the timeline lifecycle, the reload budget) using references/fundamentals.md.
2. Validate the timeline provider (placeholder/snapshot/timeline, reload policy, WidgetCenter reloads, entry relevance) using references/timeline-provider.md.
3. Validate the configuration and any user-configurable parameters (StaticConfiguration, AppIntentConfiguration, WidgetConfigurationIntent) using references/configuration-and-intents.md.
4. Check whether any legacy API is in use and route it to the modern equivalent (SiriKit .intentdefinition → App Intents, ClockKit → WidgetKit, PreviewProvider → #Preview) using references/migration-and-deprecations.md.
5. Validate data loading - networking, persistence, images, location - in the provider and intents using references/data-and-networking.md.
6. Validate family support and per-family layout (WidgetFamily, sizing, content margins, ViewThatFits) using references/families-and-layout.md.
7. Validate Lock Screen / accessory widgets and watch complications (widgetLabel, AccessoryWidgetBackground, the transparent-container trick, ClockKit migration) using references/lock-screen-and-watch.md.
8. Validate rendering across full-color, accented, tinted, and vibrant modes (widgetRenderingMode, widgetAccentable, widgetAccentedRenderingMode, the luminance-to-alpha trick) using references/rendering-modes-and-tinting.md.
9. Validate interactivity (Button(intent:), Toggle(intent:), the app-process boundary, reloadTimelines, invalidatableContent) using references/interactive-widgets.md.
10. Validate deep links and navigation into the app (widgetURL, Link, onOpenURL, OpenIntent) using references/deep-linking-and-navigation.md.
11. Validate animations and entry transitions (contentTransition, .transition + identity, invalidatableContent, what doesn't animate) using references/animations-and-transitions.md.
12. Validate Control Center controls (ControlWidget, toggle vs button, SetValueIntent, value providers, ControlCenter reloads) using references/controls.md.
13. Validate Live Activities and the Dynamic Island (ActivityAttributes, ActivityConfiguration, DynamicIsland, request/update/end, push, supplementalActivityFamilies) using references/live-activities.md.
14. Validate Smart Stack relevance (TimelineEntryRelevance, relevance() / WidgetRelevance, RelevanceConfiguration, push-based relevance) using references/relevance-and-smart-stacks.md.
15. Check the design and gallery presentation (glanceability, sizes, the don'ts, configurationDisplayName/description, the placeholder) using references/design-and-gallery.md.
16. Validate previews and the testing/debugging workflow (#Preview(as:), WidgetKit developer mode, the reload budget) using references/previews-and-testing.md.
17. Validate platform-specific surfaces (visionOS spatial widgets, CarPlay, macOS menu bar, the availability map) using references/platforms.md.
18. Catch common mistakes using references/anti-patterns.md.

If doing partial work, load only the relevant reference files.

Task-based routing

Match the user's goal to the read order. Load only what you need.

"Create my first widget" / "show me a complete widget"

1. references/fundamentals.md - the extension, the widget bundle, the timeline lifecycle
2. references/worked-example.md - one widget built end to end (entry → provider → layout → links → tinting → animation → preview)
3. references/timeline-provider.md - TimelineProvider, entries, reload policy
4. references/families-and-layout.md - pick families, per-family layout
5. references/previews-and-testing.md - #Preview(as:) to iterate

"Let the user configure my widget"

1. references/configuration-and-intents.md - AppIntentConfiguration + WidgetConfigurationIntent, dynamic options, defaults
2. references/timeline-provider.md - AppIntentTimelineProvider (the intent is the first argument)

"Add a Lock Screen widget / watch complication"

1. references/lock-screen-and-watch.md - accessory families, widgetLabel, AccessoryWidgetBackground, gauges, ClockKit migration
2. references/rendering-modes-and-tinting.md - accessory widgets are always rendered in a tint mode

"My widget looks wrong in tinted / dark / accented mode"

1. references/rendering-modes-and-tinting.md - widgetRenderingMode, widgetAccentable, widgetAccentedRenderingMode, the luminance-to-alpha trick, designing for the accent group
2. references/lock-screen-and-watch.md - the transparent containerBackground for accessory widgets

"Add a button / toggle inside my widget"

1. references/interactive-widgets.md - Button(intent:) / Toggle(intent:), the app-process boundary, App Group store, reloadTimelines, invalidatableContent
2. references/configuration-and-intents.md - isDiscoverable = false on helper intents

"Add a Control Center control / Action button / Lock Screen control"

1. references/controls.md - ControlWidget, ControlWidgetToggle (SetValueIntent) vs ControlWidgetButton (AppIntent), value providers, ControlCenter.shared.reloadControls
2. references/interactive-widgets.md - the same app-process / shared-store rules apply

"Build a Live Activity / Dynamic Island"

1. references/live-activities.md - ActivityAttributes / ContentState, ActivityConfiguration, DynamicIsland regions, request/update/end, staleness, push, supplementalActivityFamilies, the iOS-27 landscape Dynamic Island
2. references/interactive-widgets.md - LiveActivityIntent buttons

"Keep my widget fresh from the server"

1. references/timeline-provider.md - reload policy, the reload budget, reload on app background
2. references/relevance-and-smart-stacks.md - push-updated widgets (WidgetPushHandler, iOS 26), and when a Live Activity is the right tool instead

"Make my widget show up in the Smart Stack at the right time"

1. references/relevance-and-smart-stacks.md - TimelineEntryRelevance, relevance() + WidgetRelevance, RelevanceConfiguration (watchOS 26), RelevantContext

"Fetch data / load images / use a database or location in my widget"

1. references/data-and-networking.md - App Group snapshot, async fetch in the provider, image downsampling, SwiftData/Core Data, NSWidgetUsesLocation
2. references/timeline-provider.md - where fetching fits in the lifecycle and the budget

"Deep link / open my app from the widget"

1. references/deep-linking-and-navigation.md - widgetURL vs Link, per-family rules, onOpenURL, OpenIntent

"Animate my widget / make values roll or transition"

1. references/animations-and-transitions.md - entry diffing, contentTransition(.numericText), .transition + .id, invalidatableContent, what doesn't animate

"Modernize an old widget / I'm seeing IntentConfiguration / ClockKit / PreviewProvider"

1. references/migration-and-deprecations.md - the old → new map, CustomIntentMigratedAppIntent, the ClockKit migrator, dual-path #available

"Design my widget well / make it gallery-ready"

1. references/design-and-gallery.md - glanceable/personal/relevant, sizes & tap styles, the don'ts, the snapshot, the placeholder

"Support visionOS / CarPlay / macOS / Apple Watch"

1. references/platforms.md - spatial widgets (supportedMountingStyles, widgetTexture, levelOfDetail), CarPlay, macOS menu bar, the availability map

"My widget won't update / shows stale data / never appears"

1. references/previews-and-testing.md - the reload budget, WidgetKit developer mode, debugging
2. references/anti-patterns.md - the usual causes

"I'm hitting build errors or rendering bugs"

1. references/anti-patterns.md - catches with before/after fixes

Decision trees

Quick orientation when you know the task but not the right API.

Which configuration should the widget use?

No user configuration, fixed behavior?
  -> StaticConfiguration(kind:provider:)

User picks parameters (account, city, repo)?
  -> AppIntentConfiguration(kind:intent:provider:) + WidgetConfigurationIntent   (iOS 17+)

Migrating an existing iOS 14-16 configurable widget?
  -> WidgetConfigurationIntent + CustomIntentMigratedAppIntent (keep intentClassName)
  -> or keep IntentConfiguration(kind:intent:provider:) with the legacy INIntent

Appears in the Smart Stack only when relevant (watchOS)?
  -> RelevanceConfiguration(kind:provider:)   (watchOS 26+)

Which timeline provider?

StaticConfiguration?
  -> TimelineProvider           (placeholder / getSnapshot / getTimeline, completion-based)

AppIntentConfiguration?
  -> AppIntentTimelineProvider  (placeholder / snapshot(for:in:) / timeline(for:in:), async, intent FIRST)

RelevanceConfiguration (watchOS)?
  -> RelevanceEntriesProvider   (placeholder / relevance() / entry(configuration:context:), one entry per config)

Which reload policy?

Next update time is known (countdown ends, event starts)?
  -> .after(date)

Entries cover a window and the next batch can be computed at the end?
  -> .atEnd

Content only changes from interaction / push, never on a schedule?
  -> .never   (then reload via WidgetCenter from an intent, app, or push)

Which interactive element?

Inside a widget or Live Activity, runs an action?
  -> Button(intent:) with an AppIntent          (iOS 17+)

Inside a widget, binary on/off?
  -> Toggle(isOn:intent:) with an AppIntent      (iOS 17+)

Inside a Control Center control, binary on/off?
  -> ControlWidgetToggle(action:) with a SetValueIntent

Inside a Control Center control, runs an action / opens the app?
  -> ControlWidgetButton(action:) with an AppIntent (or OpenIntent to launch)

Widget vs Live Activity vs Control?

Glanceable data on a schedule, lives on Home/Lock Screen?
  -> Widget (timeline)

Ongoing, time-bound event the user wants to watch live (delivery, game, workout)?
  -> Live Activity (ActivityKit) - NOT a fast-reloading widget

A quick action or state toggle from Control Center / Lock Screen / Action button?
  -> Control (ControlWidget)

Core Instructions

• A widget runs in a separate extension process, not your app. It is always SwiftUI, even in a UIKit app. The system archives your view and renders it later - your code is not running while the widget is on screen. Share data with the app only through an App Group container (shared UserDefaults(suiteName:), a shared file, or a shared ModelContainer/Core Data store) - never UserDefaults.standard, never in-memory singletons.
• Never make a widget interactive with a closure or onTapGesture. The only interactivity is Button(intent:) / Toggle(intent:) backed by an AppIntent (iOS 17+), plus Link / widgetURL for deep links. Anything else silently does nothing.
• Always mark the widget's background with .containerBackground(for: .widget) { ... } (iOS 17+). Without it the widget is blank in the gallery, can't be removed/relocated cleanly, and the system can't substitute the material background in Lock Screen / StandBy / tinted contexts. The container type is ContainerBackgroundPlacement (value .widget) - there is no WidgetBackgroundPlacement.
• Never do blocking or asynchronous work in placeholder(in:) - it must return synchronously with stand-in data. Do real fetching in getSnapshot/getTimeline (or the async snapshot/timeline). Use .redacted(reason: .placeholder) for the first-render stand-in.
• getSnapshot (and snapshot(for:in:)) is what the widget gallery shows - return realistic, populated sample data even when the user has none yet, never an empty/loading state.
• Treat timeline reloads as a budgeted, opportunistic resource, not a timer. The system gives roughly 40-70 reloads/day per widget and learns from viewing habits. Never assume .after(date) fires exactly on time. Provide multiple entries to cover a window, pick the policy that matches your data (.atEnd / .after / .never), and trigger a final WidgetCenter.shared.reloadAllTimelines() when the app enters the background if data changed.

Output Format

If the user asks for a review, organize findings by file. For each issue:

1. State the file and relevant line(s).
2. Name the anti-pattern being replaced.
3. Show a brief before/after code fix.

Skip files with no issues. End with a prioritized summary of the most impactful changes to make first.

If the user asks you to write or fix widget code, make the changes directly instead of returning a findings report.

Example output:

CaffeineWidget.swift

Line 14: placeholder(in:) does a synchronous disk fetch - placeholders must return instantly.

// Before
func placeholder(in context: Context) -> Entry {
    Entry(date: .now, drinks: Store.shared.loadAllDrinks())   // blocks the render
}

// After
func placeholder(in context: Context) -> Entry {
    Entry(date: .now, drinks: .sample)   // synchronous stand-in; real data in getTimeline
}

Line 41: interactive onTapGesture in a widget does nothing - use an App Intent.

// Before
Image(systemName: "plus.circle").onTapGesture { addDrink() }

// After
Button(intent: AddDrinkIntent()) { Image(systemName: "plus.circle") }
// AddDrinkIntent.perform() writes to the App Group store, then:
// WidgetCenter.shared.reloadTimelines(ofKind: "CaffeineWidget")

Summary

1. Placeholder (high): must be synchronous; move fetching to the timeline.
2. Interactivity (high): gestures don't work in widgets; back the tap with an AppIntent.

End of example.

References

• references/fundamentals.md - the widget execution model: the extension process, app groups, WidgetBundle, the Widget protocol, the timeline lifecycle, containerBackground, content margins, deep linking, kind, and the "which surface" map.
• references/timeline-provider.md - TimelineProvider vs AppIntentTimelineProvider, TimelineEntry, Timeline, reload policies, the reload budget, WidgetCenter reloads, reload-on-background, TimelineEntryRelevance.
• references/configuration-and-intents.md - StaticConfiguration, AppIntentConfiguration, WidgetConfigurationIntent, dynamic options / entity parameters, recommendations(), defaults.
• references/migration-and-deprecations.md - the old → new map: SiriKit .intentdefinition / IntentConfiguration → App Intents, IntentTimelineProvider → AppIntentTimelineProvider, ClockKit → WidgetKit, PreviewProvider → #Preview, what's deprecated vs legacy-but-supported, CustomIntentMigratedAppIntent.
• references/data-and-networking.md - loading data for timelines: App Group snapshots, async/background URLSession fetches, image downsampling, SwiftData/Core Data in widgets, location, Lock Screen privacy.
• references/families-and-layout.md - WidgetFamily cases, sizing, supportedFamilies, content margins, the per-family switch, ViewThatFits, ContainerRelativeShape.
• references/lock-screen-and-watch.md - accessory families, watch complications, widgetLabel, AccessoryWidgetBackground, gauges, the transparent containerBackground trick, ClockKit → WidgetKit migration.
• references/rendering-modes-and-tinting.md - widgetRenderingMode (.fullColor/.accented/.vibrant), widgetAccentable, , the luminance-to-alpha trick, designing for the tinted/clear Home Screen and accent groups.