/tvos-app-experience-workflow

name: tvos-app-experience-workflow
description: "Guide remote-first tvOS SwiftUI and UIKit decisions: focus navigation, Large Text, Apple TV capability gates, and TVMLKit migration. Use for Apple TV interaction, focus geometry, accessibility, or platform-boundary questions."

tvOS App Experience Workflow

Purpose

Guide the Apple TV-specific decisions that ordinary SwiftUI app architecture does not own: indirect remote/controller input, visible focus movement, large-screen layout, Large Text, hardware and SDK availability, and migration away from TVMLKit. Keep SwiftUI as the primary UI path and use UIKit focus APIs only for a demonstrated geometry or lifecycle constraint.

When To Use

• Use this skill for a tvOS catalog, utility, education, fitness, game-adjacent,

or media-browsing app whose main question is remote-first interaction or focus behavior.

• Use this skill for SwiftUI content shelves, lockups, hover effects,

`focusSection()`, focused-item clipping, focus restoration, or large-screen layout decisions.

• Use this skill for `UIFocusGuide`, `UIFocusEnvironment`, preferred focus

environments, focus-update diagnostics, or a UIKit/SwiftUI focus boundary.

• Use this skill for tvOS 27 Large Text/Dynamic Type adaptation, remote versus

controller input, text-entry burden, Apple TV hardware/GPU capability gates, and beta-SDK availability questions.

• Use this skill to inventory a TVMLKit app and plan a migration to SwiftUI or

UIKit; TVMLKit has been deprecated since tvOS 18.

• Recommend `tvos-media-playback-workflow` when playback UI, remote transport

commands, Now Playing state, AVKit customization, HLS, or a custom player is the primary concern.

• Recommend `swiftui-app-architecture-workflow` when the tvOS constraints are

understood and the remaining question is ordinary SwiftUI scene, state, or component ownership.

• Recommend `apple-ui-accessibility-workflow` when the main question is the

accessibility tree or semantics beyond tvOS focus and Large Text.

Single-Path Workflow

1. Classify the request:

• SwiftUI-first content layout
• focus routing or restoration
• UIKit focus escape hatch
• Large Text or accessibility adaptation
• capability or beta-SDK gate
• TVMLKit migration inventory

2. Apply the Apple docs gate:

• use `explore-apple-swift-docs` to read current Apple documentation first
• state the documented focus, input, availability, or deprecation behavior

relied on before proposing a change

• mark tvOS 27 claims as beta-specific with the checked SDK/build date until

Apple ships the GM 3. Choose the smallest native UI surface:

• SwiftUI `Button`, `focusSection()`, lockup, hover-effect, and scroll

behavior for normal catalog layouts

• normal focus geometry with enough room for scale and elevation
• UIKit `UIFocusGuide` or preferred focus environments only when native

geometry cannot produce the intended movement 4. Check the platform boundary:

• Siri Remote, controller, voice, or companion-device input
• focus, select, Menu/Back, and restoration behavior
• text-entry alternative and remote friction
• Apple TV generation, GPU family, simulator/device-only requirement, and

unavailable framework

• Large Text, RTL, VoiceOver order, and visual focus states

5. Return one recommendation with:

• resolved request class
• documented Apple behavior relied on
• selected SwiftUI or UIKit surface
• platform/beta availability result
• validation matrix and one honest handoff

Inputs

• `request`: optional free-text tvOS task.
• `scope`: optional explicit scope: `layout`, `focus`, `uikit-focus`,

`large-text`, `capability`, `tvmlkit-migration`, or `review`.

• `framework_context`: optional `swiftui`, `uikit`, `mixed`, or `unknown`.
• `target_context`: optional Apple TV generation, tvOS deployment target,

remote/controller requirement, and whether the request is beta-targeted.

• Defaults:
• docs-first guidance always applies
• SwiftUI is the primary implementation path
• directional focus remains under user control
• tvOS 27 behavior stays beta-qualified until reverified at GM

Outputs

• `status`
• `success`: an app-experience recommendation is ready
• `handoff`: another skill owns the next step
• `blocked`: capability, runtime, or current documentation evidence is too

incomplete to make the requested claim

• `path_type`
• `primary`: native SwiftUI focus/layout guidance is sufficient
• `fallback`: a UIKit focus API, device evidence, or migration inventory is

required

• `output`
• request class
• documented Apple behavior relied on
• focus/layout or migration recommendation
• platform and beta boundary
• validation expectation and handoff

Guards and Stop Conditions

• Do not treat Siri Remote movement as touchscreen coordinates or direct a

focus move in a chosen direction; the focus system owns directional movement.

• Do not add a pointer-driven navigation model for ordinary tvOS menus.
• Do not let focused lockups clip, overlap controls, or lose their readable

title when focus scaling and elevation occur.

• Do not make typing-heavy interaction the only path through a TV experience.
• Do not claim a framework, Apple Intelligence surface, GPU feature, controller

behavior, or tvOS 27 beta behavior is available without current documentation and, when needed, device evidence.

• Do not extend TVMLKit for new features; inventory it and route a migration to

SwiftUI or UIKit instead.

• Do not claim direct Core AI, `SystemLanguageModel`, or Foundation Models

inference support on tvOS. Hand runtime selection to `model-lab-skills:choose-apple-model-runtime` with the current tvOS availability limitation explicit.

Fallbacks and Handoffs

• Recommend `tvos-media-playback-workflow` for AVKit/player choice, remote

transport commands, Now Playing, HLS/interstitials, or custom playback UI.

• Recommend `swiftu