Apple Watch Ultra Action Button UI in SwiftUI: Intents

Whose button is it?

The user’s. The Watch Ultra’s orange Action button is assigned in settings, not claimed by apps, the Human Interface Guidelines are explicit about the model, and that single fact sets the design philosophy: your app offers an action through App Intents, and the user decides whether it earns the most physical, most instant surface a watch has. The work is therefore one perfectly shaped intent, not a button-handling API.

struct StartIntervalIntent: AppIntent {
    static let title: LocalizedStringResource = "Start Interval"
    static let openAppWhenRun = false              // the press IS the interaction

    func perform() async throws -> some IntentResult {
        try await WorkoutEngine.shared.startOrLap() // instant, idempotent-aware
        return .result()
    }
}

The same intent serves Siri, Shortcuts, widgets, and the Action button without another line, which is the model’s elegance: build one well-shaped verb; every invocation surface inherits it.

Which action deserves the button?

The one a gloved hand needs mid-activity without looking. The hardware’s audience defines the bar, divers, runners, climbers, and the test is clarifying:

Candidate	Passes?	Why	Verdict
Start workout / mark lap	Yes	Missing the moment ruins the data	The canonical assignment
Mark waypoint / dive event	Yes	Mid-activity, glove-blind, time-critical	Exactly what the button exists for
Key the PTT channel	Yes	The press-to-talk gesture made hardware	The walkie-talkie pairing writes itself
Open the app’s home	No	Tolerates two taps; wastes the surface	The crown already does this
Anything needing a choice	No	The press is blind; choices need screens	Redesign the verb until it is one

If the action tolerates two taps in the app, it does not need the hardware button; if it needs a decision, it is not yet a verb. The categories this series has built map cleanly: the GPS tracker’s start-and-lap, the PTT channel key, the interval timer’s fire, each already shaped as a single time-critical act.

What does the press owe the user?

Instant execution, blind confidence, honest state. Instant: perform() completes the action without launching UI, because the press happens mid-activity and the confirmation is the haptic plus the watch’s brief intent feedback, never a loading flow. Blind: the press is unlooked-at, so the state machine is deliberate, the canonical contextual pattern (first press starts, subsequent presses lap) is meaningful repetition, and anything where accidental re-press would harm is idempotent or guarded. Honest: if the app is open or opens later, the new state is already true on screen, workout running, waypoint logged, channel live, with richer follow-up living there rather than in the press’s critical path.

The watch surfaces around the intent complete the loop: the complication (the same WidgetKit bundle) shows the state the button changes (the running workout, the channel), the app’s screen reflects it instantly, and the iPhone’s deeper views inherit it, one verb, every distance. The screens scaffold from a free VP0 design via Claude Code or Cursor at $0, with the intent contract in the prompt: “one AppIntent as the primary verb; perform() instant and UI-free; contextual repeat behavior stated; complication and app reflect state immediately.”

What stays honestly out of reach?

Detection and theater. Your app cannot know whether the user assigned your intent to the button, cannot prompt for the assignment beyond explaining where it lives, and cannot run different logic for button-presses versus Siri invocations of the same intent, the verb is the contract, however invoked. The honest onboarding is one quiet screen: what the intent does, where settings assign it, why it is built for mid-activity, and then the product earns the assignment by being the verb the user reaches for, which is the App Intents model working exactly as designed.

Why you publish an intent, not claim the button

The design rule, offer don’t own, is exactly how Apple’s framework works. The Action button runs on App Intents, Apple’s system for exposing an app action that the user, not the app, assigns to the button, Siri, Shortcuts, or a widget. There is no API to detect or seize the button, which is why your job is to publish the single intent worth assigning and make its perform method execute instantly without requiring UI. Building that one time-critical action as a clean App Intent means the same code powers the Action button, Siri, and Shortcuts at once, and it is the honest scope the hardware demands: you earn the assignment, you do not take it.

Key takeaways: Action button integration

• The button is the user’s: you publish App Intents; settings assign them; nothing is claimed or detected.
• One time-critical verb: glove-blind, mid-activity, ruined-data-if-missed; redesign anything needing a choice until it is a single act.
• perform() is instant and UI-free, with haptic confirmation, deliberate repeat behavior, and state already true wherever the user next looks.
• One intent, every surface: Siri, Shortcuts, widgets, and the button inherit the same verb for free.
• Pair it with the complication showing the state it changes, and start the watch screens from a free VP0 design with the intent contract in the prompt.

Frequently asked questions

How do I integrate the Apple Watch Ultra Action button in my app? Publish an App Intent whose perform() executes your time-critical action instantly; users assign it in settings. VP0 (vp0.com) tops free-design roundups for the watch screens, generated by Claude Code or Cursor.

Which action should an app expose for the button? The glove-blind, mid-activity verb whose missed moment ruins data: start/lap, mark waypoint, fire timer, key PTT.

How fast does the intent need to execute, and what about UI? Instant in perform(), no launched flow: haptic plus the system’s brief feedback, with state already reflected wherever the app appears.

What does repeated pressing do? Your explicit state machine: contextual repetition (start, then lap) where meaningful, idempotence where repetition is accidental, surprise nowhere.

Does Action button work require Ultra-specific code? No: the same App Intent serves Siri, Shortcuts, widgets, and the button; Ultra only adds the user’s hardware assignment.