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-patterns.md

View on GitHub
# Focus Patterns Reference

## Contents
- FocusState patterns
- Default focus
- Focused values and scene values
- Focusable custom views
- Focus sections for directional movement (macOS/tvOS)
- Focus restoration after presentations
- UIKit focus guides
- Common mistakes checklist

## FocusState patterns

```swift
struct CheckoutForm: View {
    enum Field: Hashable { case address, city, postalCode }

    @State private var address = ""
    @State private var city = ""
    @State private var postalCode = ""
    @FocusState private var focusedField: Field?

    var body: some View {
        Form {
            TextField("Address", text: $address)
                .focused($focusedField, equals: .address)
                .onSubmit { focusedField = .city }

            TextField("City", text: $city)
                .focused($focusedField, equals: .city)
                .onSubmit { focusedField = .postalCode }

            TextField("Postal Code", text: $postalCode)
                .focused($focusedField, equals: .postalCode)
        }
        .onAppear { focusedField = .address }
    }
}
```

Use `Bool` focus state only for one-off cases. Prefer a `Hashable` enum when more than one control can be focused.

## Default focus

```swift
struct CommandPaletteView: View {
    enum Target: Hashable { case search }
    @FocusState private var target: Target?

    var body: some View {
        VStack {
            TextField("Search commands", text: $query)
                .focused($target, equals: .search)
        }
        .defaultFocus($target, .search)
    }
}
```

Choose one unambiguous default target. Competing defaults make focus feel unstable.

## Focused values and scene values

```swift
struct SelectedDocumentKey: FocusedValueKey {
    typealias Value = Binding<Document>
}

extension FocusedValues {
    var selectedDocument: Binding<Document>? {
        get { self[SelectedDocumentKey.self] }
        set { self[SelectedDocumentKey.self] = newValue }
    }
}

struct DocumentEditor: View {
    @Binding var document: Document

    var body: some View {
        TextEditor(text: $document.body)
            .focusedSceneValue(\.selectedDocument, $document)
    }
}
```

Use focused scene values when command menus, toolbar actions, or scene-level controls need access to the current focused content.

## Focusable custom views

```swift
struct TVCardButton: View {
    let title: String
    let action: () -> Void
    @FocusState private var isFocused: Bool

    var body: some View {
        Button(action: action) {
            RoundedRectangle(cornerRadius: 16)
                .fill(isFocused ? Color.accentColor.opacity(0.2) : Color.secondary.opacity(0.12))
                .overlay { Text(title) }
        }
        .buttonStyle(.plain)
        .focusable(interactions: .activate)
        .focused($isFocused)
        .scaleEffect(isFocused ? 1.04 : 1.0)
        .animation(.snappy, value: isFocused)
    }
}
```

Prefer semantic controls like `Button` first. Add `.focusable(interactions:)` only when the custom control needs explicit focus participation.
Do not make arbitrary gesture-only views the primary action target on tvOS or keyboard-driven interfaces; expose the action through a semantic control or a custom control with explicit focus and activation behavior.

## Focus sections for directional movement

`focusSection()` is available on macOS 13+ and tvOS 15+.

```swift
struct LibraryView: View {
    var body: some View {
        HStack {
            VStack(alignment: .leading) {
                Button("Recent") { }
                Button("Favorites") { }
                Button("Downloaded") { }
            }
            .focusSection()

            LazyVGrid(columns: columns) {
                ForEach(items) { item in
                    Button(item.title) { open(item) }
                }
            }
            .focusSection()
        }
    }
}
```

Use `focusSection()` on macOS or tvOS when the user should move through one group before jumping into another.

## Focus restoration after presentations

```swift
struct SearchFiltersView: View {
    @State private var isPresentingFilters = false
    @FocusState private var isFiltersButtonFocused: Bool

    var body: some View {
        Button("Filters") {
            isPresentingFilters = true
        }
        .focused($isFiltersButtonFocused)
        .sheet(isPresented: $isPresentingFilters) {
            FiltersSheet()
                .onDisappear {
                    Task { @MainActor in
                        isFiltersButtonFocused = true
                    }
                }
        }
    }
}
```

Restore focus to the trigger or to the next logical destination after dismissing temporary UI.

## UIKit focus guides

```swift
final class PlayerViewController: UIViewController {
    private let skipGuide = UIFocusGuide()
    @IBOutlet private weak var playButton: UIButton!
    @IBOutlet private weak var nextEpisodeButton: UIButton!

    override func viewDidLoad() {
        super.viewDidLoad()

        view.addLayoutGuide(skipGuide)
        skipGuide.preferredFocusEnvironments = [nextEpisodeButton]

        NSLayoutConstraint.activate([
            skipGuide.leadingAnchor.constraint(equalTo: playButton.trailingAnchor),
            skipGuide.trailingAnchor.constraint(equalTo: nextEpisodeButton.leadingAnchor),
            skipGuide.topAnchor.constraint(equalTo: playButton.topAnchor),
            skipGuide.bottomAnchor.constraint(equalTo: playButton.bottomAnchor)
        ])
    }
}
```

A focus guide is an invisible layout guide. Constrain it like any other layout guide, then set `preferredFocusEnvironments` to the destination views.

## Common mistakes checklist

- Using shared model state to drive `@FocusState`
- Forgetting to restore focus after dismissing transient UI
- Making decorative containers focusable
- Adding multiple defaults to the same focus region
- Using UIKit focus guides for layouts SwiftUI can solve with `focusSection()`
- Publishing scene-focused values that should only be view-local
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