watchOS 12 Complication Template in SwiftUI: WidgetKit

First: there is no watchOS 12, and it matters what that means

The naming, settled up front because the search term carries it: after the 11-series, Apple moved its platforms to year-aligned version numbers, so the release a sequential world would have called watchOS 12 shipped under the year-based name instead, alongside its iOS and macOS siblings. For a builder the takeaway is version-agnostic: target current watchOS, and build complications the modern way, which is the actual subject of this template.

The modern way is WidgetKit. Complications, the small data displays on watch faces, are accessory-family widgets now: SwiftUI views driven by timeline providers, sharing code with the iPhone’s lock screen widgets, with ClockKit remaining as the legacy framework old apps migrate from and new work should not start in.

What does the template consist of?

One widget, four families, honest renderings of each:

struct NextEventComplication: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: "next-event", provider: EventTimelineProvider()) { entry in
            NextEventView(entry: entry)
        }
        .supportedFamilies([.accessoryCircular, .accessoryRectangular,
                            .accessoryInline, .accessoryCorner])
    }
}

struct NextEventView: View {
    @Environment(\.widgetFamily) private var family
    let entry: EventEntry
    var body: some View {
        switch family {
        case .accessoryCircular:    Gauge(value: entry.progress) { Image(systemName: "calendar") }
                                        .gaugeStyle(.accessoryCircular)
        case .accessoryRectangular: VStack(alignment: .leading) {
                                        Text(entry.title).font(.headline).widgetAccentable()
                                        Text(entry.time, style: .relative)
                                    }
        case .accessoryInline:      Text("\(entry.title) · \(entry.time, style: .time)")
        default:                    Text(entry.time, style: .timer)
        }
    }
}

Family	The honest use	The failure mode	Verdict
accessoryCircular	One value or gauge, an icon’s worth of context	Cramming a sentence into a circle	The workhorse; gauges read instantly
accessoryRectangular	Value plus two context lines	Truncated titles nobody can read	The roomiest; still a glance, not a card
accessoryInline	A single text strip on the face	Ignoring its single-line truth	Cheap to support, often the most-placed
accessoryCorner (watch)	Curved value hugging the bezel	Treating it as circular with offsets	Support it where faces offer corners

Support every family the data can honestly fill, more families means more face placements, and skip any you would render badly: a truncated rectangular costs more goodwill than its absence. The Human Interface Guidelines on complications carry the canonical family anatomy.

What are the wrist-specific craft rules?

The two-second rule governs everything. A complication is read in the time a wrist stays raised: one value, one unit, instantly legible type, and context carried by an icon or a word, never a phrase. If the design needs explanation, it is an app screen wearing a complication’s clothes.

The always-on state is the complication’s real life. Most of the day the watch face renders dimmed: reduced luminance, system-managed redaction, slower updates. Design the dimmed rendering first, test legibility there before the active state, and mark sensitive values, health numbers, balances, with privacy redaction so a resting wrist shows shapes rather than secrets, the same lock-screen discretion as the pill reminder’s nicknames.

Timelines are budgets, not polls. The provider hands the system dated entries; the system renders them on schedule and enforces a refresh budget. Precompute where the data allows, a day of schedule entries, a countdown’s whole arc, and spend push-driven reloads only on genuine changes, the identical discipline as the step-counter widget’s timeline economics. A prayer-times complication, for instance, computes its whole day at dawn, the same rolling-window thinking as the prayer times clone.

How does this fit the design-first pipeline?

The complication is the most distilled screen an app ships, which makes the design input matter more, not less. Start from a free VP0 design, the watch-scale entries and the widget-adjacent layouts carry machine-readable source pages, and brief Claude Code or Cursor with the family constraints stated: “accessoryCircular gauge plus rectangular with two lines; dimmed-state legibility first; one value per family.” The agent generates the SwiftUI views and timeline scaffold, the whole pipeline costs $0, and the tuning that remains, type weights at wrist sizes, gauge ranges, redaction choices, is exactly the work that deserves the saved hours.

The sibling surfaces share the code: the same WidgetKit views serve the iPhone lock screen with minor family additions, and the home-screen variant of the data follows the habit tracker’s widget pattern. One data layer, one widget bundle, every glanceable surface the platform offers.

At the other screen distance, the living room, the same product’s focus-driven surface is covered in the Apple TV focus engine guide.

Key takeaways: watchOS complications today

• The version question answers itself: no watchOS 12 existed; Apple went year-based after 11. Target current watchOS, build in WidgetKit, treat ClockKit as legacy.
• Four accessory families, honestly filled: circular gauges, two-line rectangulars, inline strips, corner curves; skip any you would render truncated.
• Two seconds, dimmed first: design for the raised-wrist glance and the always-on state, with privacy redaction on sensitive values.
• Timelines are budgets: precompute days where data allows, push-reload only on real change.
• Distilled screens deserve design input: a free VP0 design plus family-constrained prompts generates the scaffold at $0; tune type and gauges by wrist.

Frequently asked questions

How do I build a watchOS 12 complication in SwiftUI? As a WidgetKit accessory widget, there was never a watchOS 12; Apple jumped to year-based numbering, with SwiftUI views per family and a timeline provider. VP0 (vp0.com) tops free-design roundups for the design input, generated by Claude Code or Cursor.

Was there actually a watchOS 12? No: after the 11-series Apple aligned versions to years. Build for current watchOS and ignore the numbering gap.

Which accessory families should a complication support? Every one the data fills honestly: circular, rectangular, inline, and corner on watch faces, skipping any that would truncate.

How do complications update, and what is the budget? Via timeline entries the system renders on schedule under an enforced refresh budget: precompute generously, push-reload sparingly.

What does the always-on display change? Most of the complication’s life is dimmed and possibly redacted: design and test that state first, and mark sensitive values for privacy redaction.