RelevanceKit

Use RelevanceKit to tell the Apple Watch Smart Stack when a widget matters by time, location, fitness state, sleep schedule, or connected hardware. Targets Swift 6.4 and watchOS 26+ relevant-widget workflows.

Beta-sensitive. Re-check current Apple documentation before changing availability, signatures, or Smart Stack behavior.

Choose a provider
Scope boundaries
Signals and permissions
Provider invariants
Testing
Common mistakes
Review checklist
References

Choose a provider

Use one of two models:

Add relevance() to an existing AppIntentTimelineProvider when the widget always has timeline content and relevance is supplementary.
Use RelevanceConfiguration with a RelevanceEntriesProvider when the widget should appear only under matching conditions or create multiple relevant cards. This path is watchOS 26+.

Read RelevanceKit patterns for complete providers, every RelevantContext factory, permissions, grouping, associatedKind, previews, and RelevantIntentManager updates.

RelevantContext is declared across Apple platforms, but its relevance effect is watchOS-only. Shared provider code may compile elsewhere without changing widget visibility there.

Scope boundaries

Keep this skill focused on RelevantContext, WidgetRelevanceAttribute, provider relevance(), RelevanceConfiguration, grouping, RelevantIntentManager, and permissions required by relevance clues.

Route these sibling concerns elsewhere:

Widget timelines, families, reload budgets, rendering, push reloads, Live Activities, and controls → widgetkit.
Workout sessions, activity/sleep queries, routes, and HealthKit authorization UX → healthkit.
Geocoding, place search, directions, regions, geofencing, and location authorization architecture → mapkit.

Signals and permissions

Context	Use	Required setup
`.date(...)`	Moment, scheduled event, or date interval	None
`.location(inferred:)`	Home, work, school, commute	App location permission plus `NSWidgetWantsLocation`
`.location(_:)`	Specific `CLRegion`	Same location setup
`.location(category:)`	Nearby point-of-interest category	Same setup; returns optional
`.fitness(.workoutActive)`	Active workout	HealthKit read access to `HKWorkoutType`
`.fitness(.activityRingsIncomplete)`	Ring progress	Exact exercise/move/stand read types
`.sleep(...)`	Bedtime or wakeup	Sleep-analysis read access
`.hardware(headphones:)`	Headphone connection	None

Location purpose strings belong in the containing app. The widget extension declares NSWidgetWantsLocation and checks CLLocationManager.isAuthorizedForWidgetUpdates. Enable HealthKit and request the exact read types in every target that supplies fitness or sleep relevance.

Provider invariants

Return WidgetRelevanceAttribute values in priority order; the system may use only a subset.
location(category:) is optional—omit unsupported categories rather than force-unwrapping.
A relevance entries provider supplies relevance, entry, placeholder, and a deterministic preview path.
When timeline and relevant widgets represent the same data, set .associatedKind(_:) to avoid duplicate Smart Stack cards.
Use .automatic, .ungrouped, or .named grouping intentionally.
For timeline-provider relevance, call RelevantIntentManager.shared.updateRelevantIntents whenever source data changes, not only during timeline refresh.
Degrade gracefully when authorization is absent; do not manufacture false location, fitness, or sleep clues.

Testing

Enable WidgetKit Developer Mode on the Apple Watch.
Preview entry and configuration states at relevant display sizes.
Exercise permission granted, denied, restricted, and unavailable data paths.
Verify ordering, grouping, and duplicate suppression with realistic entries.
Finish on a physical watch; do not treat compilation or iOS preview behavior as proof of Smart Stack ranking.

Common Mistakes

Expecting RelevanceKit calls to affect iOS widget ranking.
Creating a relevant widget when a normal timeline plus relevance is sufficient.
Returning location clues without widget-update authorization.
Failing to refresh relevant intents after source data changes.
Omitting associatedKind and creating duplicate cards.
Assuming every point-of-interest category creates a context.

Review Checklist

Provider model matches always-available versus condition-only content.
Relevance scope is separated from WidgetKit, HealthKit, and MapKit ownership.
Every clue has its exact permission and availability setup.
Attributes are priority-ordered and unsupported optionals are omitted.
Entry, placeholder, relevance, and preview paths are deterministic.
Grouping and associatedKind prevent unwanted duplicates.
Relevant intents update whenever underlying data changes.
Physical-watch testing covers permission and ranking behavior.

relevancekit