CtrlK
BlogDocsLog inGet started
Tessl Logo

dpearson2699/swift-ios-skills

Agent skills for iOS, iPadOS, Swift, SwiftUI, and modern Apple framework development.

71

Quality

89%

Does it follow best practices?

Impact

—

No eval scenarios have been run

SecuritybySnyk

Advisory

Suggest reviewing before use

Overview
Quality
Evals
Security
Files

focus-debugging.mdskills/focus-engine/references/

Focus Debugging

Runtime tools for diagnosing focus issues in UIKit and SwiftUI apps.

Docs: UIFocusDebugger

UIFocusDebugger (LLDB)

UIFocusDebugger is a runtime-only class for use in the LLDB console during a debugging session. Do not call these methods from app code.

Commands

// Show current focus state
po UIFocusDebugger.status()

// Check why a specific view can't receive focus
po UIFocusDebugger.checkFocusability(for: myButton)

// Show focus group hierarchy
po UIFocusDebugger.focusGroups(for: myViewController)

// Show preferred focus chain
po UIFocusDebugger.preferredFocusEnvironments(for: myViewController)

// Simulate a focus update from a given environment
po UIFocusDebugger.simulateFocusUpdateRequest(from: myViewController)

Common Diagnostic Patterns

"Why won't this view focus?"

po UIFocusDebugger.checkFocusability(for: myView)

Common causes returned:

  • View is hidden or has zero alpha
  • View is not in the view hierarchy
  • canBecomeFocused returns false
  • A parent's shouldUpdateFocus(in:) returned false
  • The view is covered by another view

"Where does focus go next?"

po UIFocusDebugger.simulateFocusUpdateRequest(from: currentView)

Shows the focus engine's evaluation of the next destination based on geometry.

SwiftUI Focus Debugging

SwiftUI does not expose UIFocusDebugger directly. Strategies:

  1. Add .onChange(of: focusedField) to log focus transitions:
.onChange(of: focusedField) { old, new in
    print("Focus moved: \(String(describing: old)) → \(String(describing: new))")
}

  1. Use Accessibility Inspector (Xcode → Open Developer Tool) to inspect focus order and accessibility element hierarchy.

  2. Set breakpoints in didUpdateFocus(in:with:) for UIKit-hosted views within SwiftUI.

Focus Anti-Patterns

Anti-PatternProblemFix
Programmatically setting focus in viewDidLoadFocus engine hasn't completed initial updateUse viewDidAppear or DispatchQueue.main.async
Calling setNeedsFocusUpdate() without updateFocusIfNeeded()Focus update is deferred indefinitelyPair both calls: setNeedsFocusUpdate(); updateFocusIfNeeded()
Overriding preferredFocusEnvironments with stale referencesFocus targets a deallocated or off-screen viewReturn currently valid, on-screen environments
Using isHidden = true to disable focus on a viewRemoves the view from layout entirelyUse canBecomeFocused override or focusable(false)
Animating focus changes without UIFocusAnimationCoordinatorAnimation doesn't sync with system focus animationUse coordinator.addCoordinatedFocusingAnimations
Forgetting collisionComponent on RealityKit entitiesEntity can't receive gaze focus in visionOSAdd CollisionComponent alongside InputTargetComponent
Not testing with Full Keyboard Access on macOSTab focus skips custom controlsEnable Keyboard Navigation in System Settings and test
Relying on touch-based interactions on tvOSNo touch input availableMake all actions accessible via focus + select

skills

focus-engine

references

focus-debugging.md

focus-patterns.md

multi-platform-focus.md

SKILL.md

CHANGELOG.md

README.md

tile.json