dpearson2699/swift-ios-skills / skills/focus-engine
focus-engine
VerifiedImplements 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.5 KB |
| evals/evals.json | config | 3.9 KB |
| references/focus-debugging.md | markdown | 3.2 KB |
| references/focus-patterns.md | markdown | 5.9 KB |
| references/multi-platform-focus.md | markdown | 5.6 KB |
references/multi-platform-focus.md
View on GitHub# Multi-Platform Focus Patterns
Platform-specific focus behaviors beyond the common SwiftUI and UIKit patterns
covered in the main SKILL.md.
## Contents
- [tvOS Focus](#tvos-focus)
- [watchOS Focus](#watchos-focus)
- [visionOS Focus](#visionos-focus)
- [macOS Focus](#macos-focus)
## tvOS Focus
tvOS uses a **geometric focus model**: the focus engine evaluates the spatial
positions of focusable items and moves focus in the direction the user swipes
on the Siri Remote.
### Key Differences from iOS
- All actions must be reachable through focus movement and select/activate;
there is no touch path to fall back on.
- The focus engine moves focus automatically based on geometry; you cannot
programmatically set focus to an arbitrary item without the engine's consent.
- `UIFocusEnvironment.preferredFocusEnvironments` determines the preferred
destination when focus enters a container.
- `UIFocusUpdateContext` provides `previouslyFocusedItem`, `nextFocusedItem`,
`focusHeading`, and `animationCoordinator`.
### UICollectionView Focus on tvOS
```swift
override func collectionView(
_ collectionView: UICollectionView,
canFocusItemAt indexPath: IndexPath
) -> Bool {
// Prevent focus on disabled cells
let item = dataSource.itemIdentifier(for: indexPath)
return item?.isEnabled ?? false
}
override func collectionView(
_ collectionView: UICollectionView,
didUpdateFocusIn context: UIFocusUpdateContext,
with coordinator: UIFocusAnimationCoordinator
) {
coordinator.addCoordinatedFocusingAnimations { _ in
context.nextFocusedView?.transform = CGAffineTransform(scaleX: 1.1, y: 1.1)
} completion: {}
coordinator.addCoordinatedUnfocusingAnimations { _ in
context.previouslyFocusedView?.transform = .identity
} completion: {}
}
```
### focusSection() on tvOS
`focusSection()` (tvOS 15+) groups focusable children in SwiftUI so the focus
engine treats them as a navigable region:
```swift
HStack {
VStack {
ForEach(sidebarItems) { item in
Button(item.title) { select(item) }
}
}
.focusSection()
LazyVGrid(columns: columns) {
ForEach(gridItems) { item in
CardView(item: item)
}
}
.focusSection()
}
```
Without `focusSection()`, swiping right from the sidebar might land on a grid
item at the wrong vertical position.
## watchOS Focus
watchOS uses the **Digital Crown** as its primary navigation input alongside
touch. SwiftUI provides `digitalCrownRotation(_:)` to track crown input.
Docs: [digitalCrownRotation](https://sosumi.ai/documentation/swiftui/view/digitalcrownrotation(_:from:through:sensitivity:iscontinuous:ishapticfeedbackenabled:))
```swift
struct CrownScrollView: View {
@State private var offset: Double = 0
var body: some View {
ScrollView {
VStack {
ForEach(items) { item in
ItemRow(item: item)
}
}
}
.digitalCrownRotation($offset, from: 0, through: 100)
}
}
```
Focus on watchOS is simpler than tvOS — most views are linearly scrollable
and focus is implicit via the crown/scroll position.
## visionOS Focus and Hover
visionOS supports the focus system for connected input devices such as
keyboards and game controllers. When a person looks at, directly touches, or
points at a virtual object, the system uses hover feedback, not focus, to show
the interaction target. Keep these paths separate: focus is for
keyboard/game-controller navigation, while gaze, direct touch, hand input, and
pointer input use hover effects and gestures.
### Hover Effects
All interactive elements get automatic hover effects in visionOS. Customize
with `.hoverEffect(_:)`:
```swift
Button("Action") { }
.hoverEffect(.highlight) // Default for buttons
.hoverEffect(.lift) // Raises the element
```
### RealityKit Hover and Input Targets
In RealityKit scenes, use `InputTargetComponent`, `HoverEffectComponent`, and
a `CollisionComponent` to make entities receive system input and show hover
feedback:
```swift
let entity = ModelEntity(mesh: .generateBox(size: 0.1))
entity.components.set(InputTargetComponent())
entity.components.set(HoverEffectComponent())
entity.components.set(CollisionComponent(shapes: [.generateBox(size: [0.1, 0.1, 0.1])]))
```
`HoverEffectComponent` is visual feedback for gaze, direct touch, or pointer
hover. It is not a callback mechanism, does not move SwiftUI `@FocusState`, and
does not make an entity part of the focus system.
### Accessibility in visionOS
Do not expand this skill into VoiceOver, Switch Control, Voice Control, or
accessibility focus ordering. Mention that those details belong in the
`ios-accessibility` skill, then keep this reference focused on keyboard,
game-controller, hover, and RealityKit input-target behavior.
## macOS Focus
### Key View Loop
UIKit-based macOS Catalyst apps and AppKit apps use the key view loop to
determine Tab order. `NSView.nextKeyView` chains views together.
SwiftUI on macOS uses `@FocusState` identically to iOS, with Tab moving
focus between fields by default.
### NSView Focus
```swift
// AppKit: make a custom view focusable
class CustomControl: NSView {
override var acceptsFirstResponder: Bool { true }
override var canBecomeKeyView: Bool { true }
override func becomeFirstResponder() -> Bool {
needsDisplay = true
return true
}
override func resignFirstResponder() -> Bool {
needsDisplay = true
return true
}
}
```
### Full Keyboard Access
macOS Full Keyboard Access (System Settings → Keyboard → Keyboard Navigation)
enables Tab focus on all controls, not just text fields. Test your app with
this setting enabled.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |