swift-focusengine-pro
Reviews, writes, and fixes focus management code for all Apple platforms (tvOS, iOS/iPadOS, watchOS, visionOS, macOS), covering SwiftUI, UIKit, AppKit, and RealityKit. Use when reading, writing, or reviewing apps that handle focus, hover, key view loops, or Digital Crown navigation.
Michael Haviv · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add mhaviv/Swift-FocusEngine-Agent-Skill --skill swift-focusengine-pro技能说明
name: swift-focusengine-pro description: Reviews, writes, and fixes focus management code for all Apple platforms (tvOS, iOS/iPadOS, watchOS, visionOS, macOS), covering SwiftUI, UIKit, AppKit, and RealityKit. Use when reading, writing, or reviewing apps that handle focus, hover, key view loops, or Digital Crown navigation. version: 1.8.1 author: Michael Haviv tags:
- swift
- swiftui
- uikit
- tvos
- ios
- ipados
- visionos
- watchos
- macos
- focus-engine
- focus-management
- realitykit
- accessibility
- apple
- agent-skill
Review focus management code for correctness, modern API usage, and adherence to Apple's focus engine rules. Covers all Apple platforms. Report only genuine problems — do not nitpick or invent issues.
Review process:
- Check for critical anti-patterns using
references/anti-patterns.md. - Determine the target platform and load the appropriate references:
- tvOS:
references/swiftui-focus.mdandreferences/uikit-focus.md. - iOS/iPadOS:
references/ios-focus.md(focus groups, halo, keyboard nav). - watchOS:
references/watchos-focus.md(Digital Crown, sequential focus). - visionOS:
references/visionos-focus.md(gaze, hover effects) andreferences/realitykit-focus.md(RealityKit entities, gestures, volumes). - macOS:
references/macos-focus.md(key view loop, focus ring, NSView focus, focusedValue for menus, Mac Catalyst). - For cross-platform: load all relevant references.
- tvOS:
- Check focus styling and visual feedback using
references/focus-styling.md. - Verify focus restoration and data reload handling using
references/focus-restoration.md. - Audit layout patterns for focus section isolation using
references/layout-patterns.md. - Check async/await and data loading focus patterns using
references/async-focus.md. - Verify accessibility integration using
references/accessibility-focus.md. - Check debugging and testing practices using
references/debugging.md.
If doing a partial review, load only the relevant reference files.
Core Instructions
tvOS
- tvOS uses a focus-based navigation model — every interactive element must be reachable via the Siri Remote's directional pad.
- Focus movement is purely geometric — the focus engine draws a rectangle from the currently focused view in the swipe direction and picks the nearest focusable view in that rectangle.
- If nothing is in the geometric path, focus does not move. Period. Use
.focusSection()(SwiftUI) orUIFocusGuide(UIKit) to bridge gaps. - Never use
.disabled()on tvOS to toggle interactivity — it removes views from the focus chain entirely..allowsHitTesting(false)is unreliable on tvOS (may map toisUserInteractionEnabled = false). Preferred: gate the action inside the button closure, or use the dual@FocusState+.disabled()gating pattern for lists (anti-pattern #25). prefersDefaultFocus(_:in:)does NOT work insideScrollViewon tvOS — usedefaultFocus(_:_:priority:)instead. Note:defaultFocuswith.userInitiatedonly fires on initial appearance, NOT on every re-entry.- Prefer
ScrollPositionoverScrollViewReader.scrollTo()— imperative scrollTo creates feedback loops with the focus engine (anti-pattern #26). - Always test on real Apple TV hardware — Simulator focus behavior differs.
iOS/iPadOS
- Focus is a secondary interaction model — it only activates with a hardware keyboard connected.
- Tab moves between focus groups; arrow keys move within a group. This two-level model does NOT exist on tvOS.
- Use
focusGroupIdentifier(iOS 14+, UIKit) to define custom focus groups — this API is NOT available on tvOS. - Use
UIFocusHaloEffectto customize the system focus ring — NOT available on tvOS. - Set
allowsFocus = trueandselectionFollowsFocus = trueon collection/table views for keyboard navigation. - Your app must work perfectly without keyboard focus — always test with touch only.
watchOS
- Focus routes Digital Crown input to the correct view — shown by a green border.
- Focus is sequential (layout order), NOT spatial/directional.
.focusSection()is NOT available on watchOS..focusable()MUST come BEFORE.digitalCrownRotation()— reversing silently breaks crown input.- Do NOT add
.focusable()to system controls (Picker, Stepper, Toggle) — they already handle it.
visionOS
- Eye gaze = hover targeting, NOT focus.
onHover(perform:)does NOT fire from gaze — only from pointer devices. - Use
.hoverEffect()for gaze visual feedback. System controls get it automatically; custom views need it explicitly. @FocusStateonly activates with keyboard (Magic Keyboard), VoiceOver, or Switch Control.- RealityKit entities need
InputTargetComponent+CollisionComponent+HoverEffectComponentfor gaze interaction. .focusEffectDisabled()hides keyboard focus ring;.hoverEffectDisabled()disables gaze hover — they are different.
macOS
- macOS uses a key view loop — Tab/Shift-Tab moves between views in a defined sequence. This is NOT spatial like tvOS.
- Custom NSView subclasses must override
acceptsFirstResponderto returntrue— the default isfalse, making the view invisible to Tab navigation. autorecalculatesKeyViewLoop = trueon NSWindow overwrites all manualnextKeyViewconnections. Pick one approach.- Focus ring customization: override
focusRingType,focusRingMaskBounds, anddrawFocusRingMask()on NSView. focusedValue/focusedSceneValueare critical on macOS for making menu bar commands respond to the current selection.- Mac Catalyst: inherits iPad
UIFocusSystem. If the iPad app doesn't support keyboard focus, the Catalyst app won't either. - Full Keyboard Access is OFF by default — most users only Tab between text fields and lists, not all controls.
All Platforms
- Never add
.focusable()to Buttons or NavigationLinks — they are already focusable. Adding it creates a double-focus wra