Reviews, writes, and fixes focus management code for Apple platforms (tvOS, iOS/iPadOS, watchOS, visionOS, macOS) using SwiftUI, UIKit, AppKit, RealityKit. Use for focus, hover, key loops, Digital Crown navigation.
npx claudepluginhub mhaviv/swift-focusengine-agent-skill --plugin swift-focusengine-proThis skill uses the workspace's default tool permissions.
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.
agents/openai.yamlreferences/accessibility-focus.mdreferences/anti-patterns.mdreferences/async-focus.mdreferences/debugging.mdreferences/focus-restoration.mdreferences/focus-styling.mdreferences/ios-focus.mdreferences/layout-patterns.mdreferences/macos-focus.mdreferences/realitykit-focus.mdreferences/swiftui-focus.mdreferences/uikit-focus.mdreferences/visionos-focus.mdreferences/watchos-focus.mdImplements keyboard, directional, and scene-level focus in SwiftUI and UIKit for iOS, macOS, tvOS, watchOS, visionOS. Use for @FocusState, defaultFocus, focus sections, restoration, guides, debugging.
Routes iOS UI issues to specialized skills for SwiftUI, UIKit, layout, navigation, animations, design guidelines, accessibility, and tvOS.
Reviews SwiftUI code for best practices, modern APIs, maintainability, performance, accessibility, and Swift conventions. Use when reading, writing, or reviewing SwiftUI projects.
Share bugs, ideas, or general feedback.
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:
references/anti-patterns.md.references/swiftui-focus.md and references/uikit-focus.md.references/ios-focus.md (focus groups, halo, keyboard nav).references/watchos-focus.md (Digital Crown, sequential focus).references/visionos-focus.md (gaze, hover effects) and references/realitykit-focus.md (RealityKit entities, gestures, volumes).references/macos-focus.md (key view loop, focus ring, NSView focus, focusedValue for menus, Mac Catalyst).references/focus-styling.md.references/focus-restoration.md.references/layout-patterns.md.references/async-focus.md.references/accessibility-focus.md.references/debugging.md.If doing a partial review, load only the relevant reference files.
.focusSection() (SwiftUI) or UIFocusGuide (UIKit) to bridge gaps..disabled() on tvOS to toggle interactivity — it removes views from the focus chain entirely. .allowsHitTesting(false) is unreliable on tvOS (may map to isUserInteractionEnabled = 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 inside ScrollView on tvOS — use defaultFocus(_:_:priority:) instead. Note: defaultFocus with .userInitiated only fires on initial appearance, NOT on every re-entry.ScrollPosition over ScrollViewReader.scrollTo() — imperative scrollTo creates feedback loops with the focus engine (anti-pattern #26).focusGroupIdentifier (iOS 15+, UIKit) to define custom focus groups — this API is NOT available on tvOS.UIFocusHaloEffect to customize the system focus ring — NOT available on tvOS.allowsFocus = true and selectionFollowsFocus = true on collection/table views for keyboard navigation..focusSection() is NOT available on watchOS..focusable() MUST come BEFORE .digitalCrownRotation() — reversing silently breaks crown input..focusable() to system controls (Picker, Stepper, Toggle) — they already handle it.onHover(perform:) does NOT fire from gaze — only from pointer devices..hoverEffect() for gaze visual feedback. System controls get it automatically; custom views need it explicitly.@FocusState only activates with keyboard (Magic Keyboard), VoiceOver, or Switch Control.InputTargetComponent + CollisionComponent + HoverEffectComponent for gaze interaction..focusEffectDisabled() hides keyboard focus ring; .hoverEffectDisabled() disables gaze hover — they are different.acceptsFirstResponder to return true — the default is false, making the view invisible to Tab navigation.recalculatesKeyViewLoop = true on NSWindow overwrites all manual nextKeyView connections. Pick one approach.focusRingType, focusRingMaskBounds, and drawFocusRingMask() on NSView.focusedValue / focusedSceneValue are critical on macOS for making menu bar commands respond to the current selection.UIFocusSystem. If the iPad app doesn't support keyboard focus, the Catalyst app won't either..focusable() to Buttons or NavigationLinks — they are already focusable. Adding it creates a double-focus wrapper.@FocusState (SwiftUI) and UIKit focus APIs (setNeedsFocusUpdate) on the same view hierarchy branch.@AccessibilityFocusState) is completely separate from UI focus (@FocusState).Organize findings by file. For each issue:
.allowsHitTesting(false) instead of .disabled()").Skip files with no issues. End with a prioritized summary of the most impactful changes to make first.
Example output:
Line 49: .disabled() removes view from tvOS focus chain (anti-pattern #1).
// Before
TopicClipsGridView(...)
.disabled(!wrapper.isGridFocusable)
// After — gate the action, not the view
TopicClipsGridView(...)
.opacity(wrapper.isGridFocusable ? 1.0 : 0.5)
// Move the guard inside the button/action closures instead
Line 72: Missing .focusSection() on horizontal ScrollView in vertical layout.
// Before
ScrollView(.horizontal) {
HStack { /* row items */ }
}
// After
ScrollView(.horizontal) {
HStack { /* row items */ }
}
.focusSection()
.disabled() on line 49 removes grid from focus chain entirely..focusSection() causes cross-row focus jumps.End of example.
references/anti-patterns.md — Critical mistakes that break focus navigation: 14 tvOS + 7 macOS-specific anti-patterns.references/swiftui-focus.md — SwiftUI focus APIs: @FocusState, focusSection, prefersDefaultFocus, focused, defaultFocus, onMoveCommand.references/uikit-focus.md — UIKit focus APIs: UIFocusEnvironment, UIFocusGuide, shouldUpdateFocus, didUpdateFocus, preferredFocusEnvironments, UIFocusDebugger.references/focus-styling.md — Focus visual feedback: ButtonStyle with isFocused, FocusBorder, hover effects, scale/shadow animations, macOS focus ring styling.references/focus-restoration.md — Handling focus after data reloads, navigation, and async updates.references/layout-patterns.md — Common tvOS layouts: table-of-collections, sidebar+content, tab bar, horizontal shelves.references/ios-focus.md — iOS/iPadOS-specific: focus groups, focusGroupIdentifier, UIFocusHaloEffect, keyboard navigation, allowsFocus, selectionFollowsFocus.references/watchos-focus.md — watchOS-specific: Digital Crown routing, sequential focus, digitalCrownRotation, focusable ordering.references/visionos-focus.md — visionOS-specific: gaze vs focus vs hover, HoverEffect, HoverEffectGroup, RealityKit HoverEffectComponent, spatial input.references/macos-focus.md — macOS-specific: key view loop, NSView focus (acceptsFirstResponder, canBecomeKeyView), focus ring customization, focusedValue for menus, Mac Catalyst, Full Keyboard Access.references/realitykit-focus.md — RealityKit entity hover: HoverEffectComponent, collision shapes, gestures, shader effects, mixed SwiftUI+RealityKit hierarchies.references/async-focus.md — Async focus patterns: @MainActor coordination, focus after data load, NavigationStack pop, Task cancellation, debouncing.references/accessibility-focus.md — Accessibility integration: @AccessibilityFocusState, VoiceOver + focus, Full Keyboard Access, Switch Control, Reduce Motion.references/debugging.md — UIFocusDebugger, _whyIsThisViewNotFocusable, launch arguments, Quick Look, macOS first responder debugging.