/watchos

name: watchOS
description: watchOS development guidance including SwiftUI for Watch, Watch Connectivity, complications, and watch-specific UI patterns. Use for watchOS code review, best practices, or Watch app development.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-11-08
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

watchOS Development

Comprehensive guidance for watchOS app development with SwiftUI, Watch Connectivity, and complications.

When This Skill Activates

Use this skill when the user:

• Is building a watchOS app or Watch extension
• Asks about Watch Connectivity (iPhone ↔ Watch sync)
• Needs help with complications or ClockKit
• Wants to implement watch-specific UI patterns
• Asks about **WidgetKit complications** or migrating from ClockKit to WidgetKit
• Wants to build **watch face complications** (accessoryCircular, accessoryRectangular, accessoryCorner, accessoryInline)
• Asks about **HealthKit on watchOS**, workout sessions, heart rate, or fitness tracking
• Needs **Extended Runtime sessions** for background workout tracking
• Wants to build **watchOS widgets** or Smart Stack widgets
• Asks about **widget relevance**, Smart Stack ordering, or widget suggestions
• Needs to share widgets **cross-platform** between iOS and watchOS
• Asks about **watchOS accessibility** — VoiceOver, AssistiveTouch, or Dynamic Type on the Watch

Key Principles

1. Watch-First Design

• Glanceable content - users look for seconds, not minutes
• Quick interactions - 2 seconds or less
• Essential information only - no scrolling walls of text
• Large touch targets - minimum 38pt height

2. Independent vs Companion

• Prefer independent Watch apps when possible
• Use Watch Connectivity for data sync, not as dependency
• Cache data locally for offline access
• Handle connectivity failures gracefully

3. Performance

• Minimize background work (battery)
• Use complication updates sparingly
• Prefer timeline-based content over live updates
• Keep views lightweight

watchOS Design Rules (WWDC20/23)

The Ten-Second Test

Design for roughly ten seconds of attention: "if you had ten seconds of someone's attention, which information would you surface?" Launch directly into that detail view — chosen by location, recency, or frequency — and make it so unmistakable it needs no title.

Three Foundational Layouts

| Layout | Use For | Notes | |--------|---------|-------| | **Dial** | Dense at-a-glance status | Up to 4 corner controls; `.scenePadding(.horizontal)` to align with the bezel | | **Infographic** | Charts + metrics | One chart with supporting numbers | | **List** | Scrollable finding | When the user must locate an item |

Navigation Model

• Prefer **vertical pagination** via the Digital Crown between purposeful, single-screen-height pages — horizontal paging is "more difficult to navigate".
• Prefer the two-level **Source List** pattern with `NavigationSplitView`: always initialize the selection so the app launches straight to detail, and leave the source list untitled.
• Reach for `NavigationStack` only when neither fits — and hierarchical navigation should remember the last destination across launches.
• The Digital Crown anchors navigation, scrolling, and precision input, but ALWAYS back it up with touch.

// Source List: launch to detail, not the list
NavigationSplitView {
    List(rooms, selection: $selectedRoom) { room in  // source list stays untitled
        Text(room.name)
    }
} detail: {
    RoomView(room: selectedRoom)
}
// Initialize selectedRoom (last used / most relevant) so launch lands on detail

Backgrounds and Materials

• Backgrounds must carry utility — recognition or information (a solar gradient tracking the sun, a state change from black to orange) — never mere flourish.
• Four vibrant full-screen materials (Ultra Thin → Thick) pair with Primary–Quaternary vibrant foreground styles and vibrant semantic colors to keep content legible over any background.

Toolbars and Action Buttons

• Toolbar placements: `.topBarLeading`, `.topBarTrailing` (moves the time to the center), and `.bottomBar`.
• Bottom-of-detail action buttons are the most discoverable pattern. A red label signals destructive — add a confirmation if the data isn't recoverable.
• The More button (ellipsis in a circular container: white at 85% opacity with a 1pt black outer glow at 50%) holds ONLY secondary actions — never a primary action.
• Toolbar-revealed buttons belong only in scrolling views — scrolling is what makes them discoverable.

Accessibility on watchOS (WWDC21 10223)

Dynamic Type on the Watch

• watchOS has 11 text styles; a fixed `.font(.system(size: 24))` never scales — use `.font(.title3)` and friends.
• Let text wrap: `lineLimit(1)` truncates at accessibility sizes — set the real maximum you support (`.lineLimit(3)`) or remove the limit.
• Watch setup defaults text size to the closest match to the paired iPhone's setting — expect real users at accessibility sizes (WWDC21 10223).
• Swap layout when wrapping gets crowded:

@Environment(\.sizeCategory) var sizeCategory

var body: some View {
    if sizeCategory < .extraExtraLarge {
        PlantViewHorizontal(plant: $plant)   // default layout
    } else {
        PlantViewVertical(plant: $plant)     // stacked layout for large sizes
    }
}

VoiceOver

• `NavigationLink` combines its children's accessibility automatically — don't add extra grouping inside one; the whole row becomes a single element (WWDC21 10223).
• Label icon+text rows so they read as meaning, not parts: `.accessibilityLabel("Watering in five days")` instead of "Drop, image. Five days." Label icon-only buttons too: `.accessibilityLabel("Log \(task.name)")` → "Log watering, button".
• Steppers/counters: collapse [minus, value, plus] into one adjustable element. Put the changing number in the **value** — it is re-spoken on every change; the label is spok