Building Apple Watch Apps with Antigravity — A Complete watchOS Development Guide

Setup and context — Why Use Antigravity for watchOS Development

Developing apps for Apple Watch requires a different mindset compared to iPhone development. Small screen real estate, battery efficiency, Complications (glanceable widgets on the watch face), and HealthKit integration all demand watchOS-specific knowledge and design patterns.

Antigravity's AI agents have a deep understanding of these watchOS-specific patterns, helping you generate SwiftUI code, configure Xcode targets, and wire up frameworks like HealthKit and WatchConnectivity — dramatically reducing development time.

In this guide, you'll learn:

• How to set up a watchOS project and connect it with Antigravity agents
• Best practices for building compact SwiftUI interfaces for the Watch
• Step-by-step implementation of Complications with WidgetKit
• AI-assisted HealthKit data fetching
• Designing iPhone-to-Watch communication with WatchConnectivity

If you're new to iOS development altogether, we recommend starting with Building iOS Apps with Antigravity — A Beginner's Guide to Swift and SwiftUI first.

watchOS Development Fundamentals

The Building Blocks of a watchOS App

A typical watchOS app consists of three main components:

• Watch App: The main app that runs on Apple Watch
• Watch Extension: Handles background processing and data fetching (merged into Watch App since watchOS 7)
• iPhone App (optional): A companion app for data sharing and heavier processing

Since watchOS 7, the Watch App and Extension targets have been unified into a single target, simplifying the project structure. The core design philosophy for watchOS is "lightweight, fast interactions, minimal information per screen."

Prerequisites Before Using Antigravity for watchOS

Before diving into watchOS development with Antigravity, make sure you have:

• macOS 15 or later
• Xcode 26 (or the latest available version)
• An active Apple Developer Program membership (required for device testing and App Store distribution)
• An Apple Watch (simulator works for basic testing)

Step 1 — Create a watchOS Project in Xcode

Choosing the Right Template

Open Xcode and navigate to "File → New → Project." Under the "watchOS" tab, select "Watch App" for a standalone Watch experience, or "Watch App for iOS App" if you need an iPhone companion app.

Once the project is created, send Antigravity a prompt like this to optimize the initial project structure:

@Antigravity Please review the project structure and suggest an optimal
folder layout for a watchOS app. I'm building a simple fitness tracker
using SwiftUI.

Antigravity will generate a scaffold for ContentView.swift, App.swift, and a ComplicationController.swift for Complications — all with inline comments explaining each component.

Step 2 — Build Watch UIs with SwiftUI

Designing for a Small Screen

The Apple Watch display is considerably smaller than an iPhone, which means your UI design principles need to shift:

• Display only the most essential information per screen
• Favor simple tap interactions; consider Digital Crown support
• Use vertical-only scroll views
• Choose larger font sizes for readability at a glance

Ask Antigravity to generate watchOS-optimized components like this:

// Workout list view generated by Antigravity for watchOS
struct WorkoutListView: View {
    let workouts: [Workout]
 
    var body: some View {
        // NavigationStack is available on watchOS 9+
        NavigationStack {
            List(workouts) { workout in
                NavigationLink(destination: WorkoutDetailView(workout: workout)) {
                    HStack {
                        Image(systemName: workout.iconName)
                            .foregroundColor(.orange)
                            .frame(width: 28, height: 28)
                        VStack(alignment: .leading, spacing: 2) {
                            Text(workout.name)
                                .font(.system(size: 15, weight: .semibold))
                            Text(workout.duration)
                                .font(.system(size: 13))
                                .foregroundColor(.secondary)
                        }
                    }
                }
            }
            .navigationTitle("Workouts")
        }
    }
}

Adding Digital Crown Support

One of the unique interaction patterns on Apple Watch is the Digital Crown. Using .focusable() and digitalCrownRotation, you can let users scroll or adjust values without lifting a finger.

struct HeartRateView: View {
    @State private var crownValue: Double = 70.0
 
    var body: some View {
        VStack {
            Text("Target Heart Rate")
                .font(.footnote)
                .foregroundColor(.secondary)
            Text("\(Int(crownValue))")
                .font(.system(size: 48, weight: .bold, design: .rounded))
                .foregroundColor(.red)
            Text("bpm")
                .font(.footnote)
        }
        // Rotate the Digital Crown to adjust the target value
        .focusable()
        .digitalCrownRotation(
            $crownValue,
            from: 50,
            through: 200,
            by: 1,
            sensitivity: .medium
        )
    }
}
// Expected output: rotating the crown updates the heart rate target in real time

Step 3 — Implementing Complications with WidgetKit

Complications are small, glanceable widgets that appear on the Apple Watch face. They're one of the most powerful engagement tools for Watch apps — users can see your app's data at a glance without ever opening the app.

From ClockKit to WidgetKit

Starting with watchOS 9, Complications are built using WidgetKit — the same API used for iOS home screen widgets. This makes the implementation more familiar if you've already built iOS widgets.

Just tell Antigravity "implement a watchOS Complication using WidgetKit" and it will generate a complete scaffold like this:

import WidgetKit
import SwiftUI
 
// The data model for the Complication
struct FitnessEntry: TimelineEntry {
    let date: Date
    let stepCount: Int
    let caloriesBurned: Double
}
 
// The Complication's visual representation
struct FitnessComplicationView: View {
    var entry: FitnessEntry
 
    var body: some View {
        VStack(alignment: .leading, spacing: 2) {
            Image(systemName: "figure.walk")
                .foregroundColor(.green)
            Text("\(entry.stepCount)")
                .font(.system(size: 14, weight: .bold))
                .minimumScaleFactor(0.7)
            Text("steps")
                .font(.system(size: 10))
                .foregroundColor(.secondary)
        }
    }
}
 
// Timeline provider — controls when and how data is refreshed
struct FitnessProvider: TimelineProvider {
    func getTimeline(in context: Context, completion: @escaping (Timeline<FitnessEntry>) -> Void) {
        let entry = FitnessEntry(
            date: Date(),
            stepCount: 8432,       // In production, fetch from HealthKit
            caloriesBurned: 312.5
        )
        let timeline = Timeline(entries: [entry], policy: .atEnd)
        completion(timeline)
    }
 
    func placeholder(in context: Context) -> FitnessEntry {
        FitnessEntry(date: Date(), stepCount: 0, caloriesBurned: 0)
    }
 
    func getSnapshot(in context: Context, completion: @escaping (FitnessEntry) -> Void) {
        completion(FitnessEntry(date: Date(), stepCount: 8432, caloriesBurned: 312.5))
    }
}

For a deeper dive into iOS home screen widgets using the same WidgetKit API, check out Antigravity × SwiftUI WidgetKit Complete Guide — Build Home Screen Widgets Fast with AI Agents.

Step 4 — Fetching Health Data with HealthKit

Setting Up Permissions

To use HealthKit, you need to add usage descriptions to Info.plist and enable the HealthKit capability in your target settings.

Tell Antigravity "set up HealthKit and write code to fetch step count and heart rate" and it will handle the full setup, including authorization and data queries:

import HealthKit
 
class HealthKitManager: ObservableObject {
    private let healthStore = HKHealthStore()
 
    // The data types we want to read
    private let typesToRead: Set<HKObjectType> = [
        HKObjectType.quantityType(forIdentifier: .stepCount)!,
        HKObjectType.quantityType(forIdentifier: .heartRate)!,
        HKObjectType.quantityType(forIdentifier: .activeEnergyBurned)!
    ]
 
    // Request user authorization
    func requestAuthorization() async throws {
        guard HKHealthStore.isHealthDataAvailable() else {
            throw HealthKitError.notAvailable
        }
        try await healthStore.requestAuthorization(
            toShare: [],
            read: typesToRead
        )
    }
 
    // Fetch today's total step count
    func fetchTodayStepCount() async -> Int {
        let type = HKQuantityType(.stepCount)
        let startOfDay = Calendar.current.startOfDay(for: Date())
        let predicate = HKQuery.predicateForSamples(
            withStart: startOfDay,
            end: Date(),
            options: .strictStartDate
        )
 
        return await withCheckedContinuation { continuation in
            let query = HKStatisticsQuery(
                quantityType: type,
                quantitySamplePredicate: predicate,
                options: .cumulativeSum
            ) { _, result, _ in
                let count = result?.sumQuantity()?.doubleValue(for: .count()) ?? 0
                continuation.resume(returning: Int(count))
            }
            self.healthStore.execute(query)
        }
    }
}
// Expected output: returns today's total step count as an Int

Step 5 — Communicating Between iPhone and Watch

Designing a WatchConnectivity Architecture

The recommended pattern for watchOS apps is to keep the iPhone app as the "source of truth" for settings and large datasets, while the Watch displays only the minimal data needed for quick interactions. WCSession makes bidirectional, real-time communication between the two devices straightforward.

import WatchConnectivity
 
class WatchSessionManager: NSObject, WCSessionDelegate, ObservableObject {
    @Published var receivedData: [String: Any] = [:]
 
    override init() {
        super.init()
        if WCSession.isSupported() {
            WCSession.default.delegate = self
            WCSession.default.activate()
        }
    }
 
    // Receive a message from the iPhone
    func session(
        _ session: WCSession,
        didReceiveMessage message: [String: Any]
    ) {
        DispatchQueue.main.async {
            self.receivedData = message
        }
    }
 
    // Send a message from the Watch to iPhone
    func sendToPhone(_ message: [String: Any]) {
        guard WCSession.default.isReachable else { return }
        WCSession.default.sendMessage(message, replyHandler: nil) { error in
            print("Send error: \(error.localizedDescription)")
        }
    }
 
    // --- Required WCSessionDelegate methods ---
    func sessionDidBecomeInactive(_ session: WCSession) {}
    func sessionDidDeactivate(_ session: WCSession) {
        WCSession.default.activate()
    }
    func session(
        _ session: WCSession,
        activationDidCompleteWith activationState: WCSessionActivationState,
        error: Error?
    ) {}
}

With Antigravity, you can simply say "sync user preferences from iPhone to Watch using WatchConnectivity" and it will generate matching implementations for both sides — keeping the code consistent across targets without manual coordination.

Step 6 — Testing and Debugging

Using the Simulator

Xcode's Watch Simulator is great for testing layouts and basic navigation flows without needing physical hardware. However, actual HealthKit data and real-time Complication updates require a physical Apple Watch.

For AI-assisted debugging, try this Antigravity prompt:

@Antigravity Fix all the errors currently shown in Xcode.
Also add mock HealthKit data injection for testing on the watchOS simulator.

Common Errors and How to Fix Them

"HealthKit is not available on this device"

HealthKit isn't supported in the simulator. Use HKHealthStore.isHealthDataAvailable() to detect this case and return mock data during development.

Complications not updating on the watch face

The WidgetKit Timeline may not be refreshing. Make sure you're calling WidgetCenter.shared.reloadAllTimelines() at the right point in your app lifecycle.

WatchConnectivity messages not arriving

Ensure both the iPhone and Apple Watch are signed in with the same Apple ID, and that Bluetooth is enabled on both devices.

Practical Antigravity Prompts for watchOS Development

Here's a quick reference of Antigravity prompts that work particularly well for watchOS projects:

Architecture design

Design a fitness tracker watchOS app with the following features:
step count, heart rate display, workout start/stop, and Complication support.
Suggest an architecture using SwiftUI + HealthKit + WatchConnectivity.

UI generation

Create a SwiftUI workout-in-progress screen optimized for
Apple Watch Ultra's display. Show heart rate, elapsed time,
and calories burned in real time.

Debugging

This watchOS app has build errors in Xcode 26.
Analyze the error log and tell me the root cause and fix.
[paste error log here]

Summary

Using Antigravity for watchOS development lets you move from project setup to a fully functional Apple Watch app — covering SwiftUI UI design, Complications, HealthKit integration, and WatchConnectivity — with AI agents handling much of the boilerplate. The key to getting the most out of Antigravity is giving it specific, watchOS-aware prompts that reflect the unique constraints of the platform.

As next steps, if you want to add in-app purchases to your Watch app, check out Antigravity × StoreKit 2 In-App Purchase Guide — Build Subscription Billing Fast with AI Agents. To go deeper on SwiftUI for Apple platforms, Antigravity SwiftUI Skills: A Complete Guide to Accelerating iOS App Development in 2026 is a great next read.

For those who want to take their watchOS skills even further, our premium article on CloudKit-synced app architecture — "Antigravity × SwiftUI + CloudKit: Advanced Guide to Shipping iCloud Sync in Production" — is well worth exploring.

To deepen your understanding of Swift itself,