/widget-generator

name: widget-generator
description: Generate WidgetKit widgets for iOS/macOS home screen and lock screen with timeline providers, interactive elements, and App Intent configuration. Use when adding widgets to an app.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Widget Generator

Generate a complete WidgetKit widget implementation with timeline providers, size-specific views, lock screen accessory widgets, interactive elements (iOS 17+), and App Intent configuration.

When This Skill Activates

Use this skill when the user:

• Asks to "add widgets" or "add a widget" to their app
• Mentions "WidgetKit" or "home screen widgets"
• Wants "lock screen widgets" or "accessory widgets"
• Asks about "widget timelines" or "timeline providers"
• Wants "interactive widgets" with buttons or toggles
• Mentions "widget configuration" or "configurable widgets"
• Asks about "App Intent widgets" or "AppIntentConfiguration"
• Wants to show data on the home screen or lock screen

Pre-Generation Checks

1. Project Context Detection

• [ ] Check for existing widget extension target
• [ ] Check for an existing `WidgetBundle`
• [ ] Verify deployment target (iOS 17+ recommended for interactive widgets)
• [ ] Identify source file locations and project structure

2. Conflict Detection

Search for existing widget code:

Glob: **/*Widget*.swift, **/*TimelineProvider*.swift
Grep: "WidgetKit" or "TimelineProvider" or "WidgetBundle" or "WidgetConfiguration"

If an existing widget extension is found:

• Ask if the new widget should be added to the existing widget extension
• Check for an existing `WidgetBundle` to extend

If a `WidgetBundle` already exists:

• Add the new widget to the existing bundle instead of creating a new one
• Do NOT create a second `@main` entry point

If widget code with the same name exists:

• Ask user whether to replace or rename

3. Required Capabilities

**Widgets require:**

• A widget extension target (File > New > Target > Widget Extension)
• App Groups capability if sharing data between the main app and widget
• iOS 14+ for basic widgets, iOS 16+ for lock screen, iOS 17+ for interactive widgets

Configuration Questions

Ask user via AskUserQuestion:

1. **What is this widget for?** (freeform)

• Examples: weather forecast, task list, fitness stats, quick actions, countdown timer
• This determines the data model and timeline update strategy

2. **Which widget sizes should be supported?**

• Home screen: systemSmall, systemMedium, systemLarge, systemExtraLarge (iPad only)
• Lock screen: accessoryCircular, accessoryRectangular, accessoryInline
• All home screen sizes
• All home screen + lock screen sizes (recommended)

3. **What type of widget?**

• **Static** (`StaticConfiguration`) -- content updated on a schedule, no user configuration
• **Configurable** (`AppIntentConfiguration`, iOS 17+) -- user can choose what the widget displays via long-press edit
• **Interactive** (`AppIntentConfiguration` + `Button`/`Toggle`, iOS 17+) -- user can tap buttons or toggles directly on the widget

4. **What is the data source?**

• Local data (UserDefaults, SwiftData, Core Data)
• Shared data via App Groups (main app writes, widget reads)
• Network API (fetched during timeline refresh)
• Combination of local and network

5. **How often should the widget update?**

• Every 15 minutes (minimum practical interval)
• Every 30 minutes
• Every hour (recommended default)
• A few times per day
• Based on specific times (e.g., calendar events)
• On-demand from the main app via `WidgetCenter.shared.reloadTimelines(ofKind:)`

Generation Process

Step 1: Determine File Locations

Check project structure:

• If a widget extension target directory exists, add view and provider files there
• Otherwise, instruct user to create a Widget Extension target first

For widget extension files:

• Place inside the existing widget extension directory (e.g., `MyAppWidgets/`)

For shared data models (if using App Groups):

• If `Sources/` or `Shared/` exists --> place there
• Otherwise --> create alongside existing models

Step 2: Create Core Files

Generate these files based on configuration answers:

1. **`{Name}Widget.swift`** -- Widget definition with configuration

• `Widget` struct with `StaticConfiguration` or `AppIntentConfiguration`
• Supported families declaration
• Display name and description

2. **`{Name}TimelineProvider.swift`** -- Timeline logic

• `TimelineProvider` (static) or `AppIntentTimelineProvider` (configurable)
• Placeholder, snapshot, and timeline methods

3. **`{Name}Entry.swift`** -- Timeline entry model

• `TimelineEntry` struct with date and display data

4. **`{Name}WidgetViews.swift`** -- Size-specific views

• Separate view struct for each supported family
• Uses `containerBackground` for iOS 17+ removable backgrounds

5. **`{Name}AppIntent.swift`** (if interactive or configurable)

• `WidgetConfigurationIntent` for configurable widgets
• `AppIntent` for interactive widget buttons/toggles

6. **WidgetBundle update** -- Register the new widget

• Add to existing bundle or create new one

Step 3: Generate Code from Templates

Use the templates in **templates.md** and customize based on user answers:

• Replace placeholder names with the actual widget name
• Configure supported families based on size selection
• Include or exclude interactive elements
• Include or exclude lock screen accessory views
• Set up App Group shared data access if needed
• Configure timeline refresh policy based on update frequency

Widget Design Rules (WWDC20)

Apply these when generating the size-specific views. A good widget idea is at least one of **personal** (the user's own data), **informational** (the most-wanted status at a glance), or **contextual** (the right thing for this moment). **Glanceab