Skip to content

dpearson2699/swift-ios-skills / skills/focus-engine

focus-engine

Verified

Implements keyboard, directional, and scene-level focus behavior across SwiftUI and UIKit. Use when managing @FocusState, defaultFocus, focused values, focusable interactions, focus sections, tvOS geometric focus and Siri Remote navigation, watchOS Digital Crown input, visionOS connected-device focus versus gaze hover/input targets, macOS key view loop and Full Keyboard Access, focus restoration after presentation changes, custom focus routing with UIFocusGuide, or debugging focus with UIFocusDebugger.

FileKindSize
SKILL.mdskill md9.5 KB
evals/evals.jsonconfig3.9 KB
references/focus-debugging.mdmarkdown3.2 KB
references/focus-patterns.mdmarkdown5.9 KB
references/multi-platform-focus.mdmarkdown5.6 KB

references/focus-debugging.md

View on GitHub
# Focus Debugging

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

Docs: [UIFocusDebugger](https://sosumi.ai/documentation/uikit/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

```lldb
// 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?"**

```lldb
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?"**

```lldb
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:

```swift
.onChange(of: focusedField) { old, new in
    print("Focus moved: \(String(describing: old)) → \(String(describing: new))")
}
```

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

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

## Focus Anti-Patterns

| Anti-Pattern | Problem | Fix |
|-------------|---------|-----|
| Programmatically setting focus in `viewDidLoad` | Focus engine hasn't completed initial update | Use `viewDidAppear` or `DispatchQueue.main.async` |
| Calling `setNeedsFocusUpdate()` without `updateFocusIfNeeded()` | Focus update is deferred indefinitely | Pair both calls: `setNeedsFocusUpdate(); updateFocusIfNeeded()` |
| Overriding `preferredFocusEnvironments` with stale references | Focus targets a deallocated or off-screen view | Return currently valid, on-screen environments |
| Using `isHidden = true` to disable focus on a view | Removes the view from layout entirely | Use `canBecomeFocused` override or `focusable(false)` |
| Animating focus changes without `UIFocusAnimationCoordinator` | Animation doesn't sync with system focus animation | Use `coordinator.addCoordinatedFocusingAnimations` |
| Forgetting `collisionComponent` on RealityKit entities | Entity can't receive gaze/direct-touch input or hover feedback in visionOS | Add `CollisionComponent` alongside `InputTargetComponent` |
| Not testing with Full Keyboard Access on macOS | Tab focus skips custom controls | Enable Keyboard Navigation in System Settings and test |
| Relying on touch-based interactions on tvOS | No touch input available | Make all actions accessible via focus + select |
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall