跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

swift-focusengine-pro

Reviews, writes, and fixes focus management code for all Apple platforms (tvOS, iOS/iPadOS, watchOS, visionOS, macOS), covering SwiftUI, UIKit, AppKit, and RealityKit. Use when reading, writing, or reviewing apps that handle focus, hover, key view loops, or Digital Crown navigation.

Michael Haviv · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add mhaviv/Swift-FocusEngine-Agent-Skill --skill swift-focusengine-pro

技能说明


name: swift-focusengine-pro description: Reviews, writes, and fixes focus management code for all Apple platforms (tvOS, iOS/iPadOS, watchOS, visionOS, macOS), covering SwiftUI, UIKit, AppKit, and RealityKit. Use when reading, writing, or reviewing apps that handle focus, hover, key view loops, or Digital Crown navigation. version: 1.8.1 author: Michael Haviv tags:

  • swift
  • swiftui
  • uikit
  • tvos
  • ios
  • ipados
  • visionos
  • watchos
  • macos
  • focus-engine
  • focus-management
  • realitykit
  • accessibility
  • apple
  • agent-skill

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:

  1. Check for critical anti-patterns using references/anti-patterns.md.
  2. Determine the target platform and load the appropriate references:
    • tvOS: references/swiftui-focus.md and references/uikit-focus.md.
    • iOS/iPadOS: references/ios-focus.md (focus groups, halo, keyboard nav).
    • watchOS: references/watchos-focus.md (Digital Crown, sequential focus).
    • visionOS: references/visionos-focus.md (gaze, hover effects) and references/realitykit-focus.md (RealityKit entities, gestures, volumes).
    • macOS: references/macos-focus.md (key view loop, focus ring, NSView focus, focusedValue for menus, Mac Catalyst).
    • For cross-platform: load all relevant references.
  3. Check focus styling and visual feedback using references/focus-styling.md.
  4. Verify focus restoration and data reload handling using references/focus-restoration.md.
  5. Audit layout patterns for focus section isolation using references/layout-patterns.md.
  6. Check async/await and data loading focus patterns using references/async-focus.md.
  7. Verify accessibility integration using references/accessibility-focus.md.
  8. Check debugging and testing practices using references/debugging.md.

If doing a partial review, load only the relevant reference files.

Core Instructions

tvOS

  • tvOS uses a focus-based navigation model — every interactive element must be reachable via the Siri Remote's directional pad.
  • Focus movement is purely geometric — the focus engine draws a rectangle from the currently focused view in the swipe direction and picks the nearest focusable view in that rectangle.
  • If nothing is in the geometric path, focus does not move. Period. Use .focusSection() (SwiftUI) or UIFocusGuide (UIKit) to bridge gaps.
  • Never use .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.
  • Prefer ScrollPosition over ScrollViewReader.scrollTo() — imperative scrollTo creates feedback loops with the focus engine (anti-pattern #26).
  • Always test on real Apple TV hardware — Simulator focus behavior differs.

iOS/iPadOS

  • Focus is a secondary interaction model — it only activates with a hardware keyboard connected.
  • Tab moves between focus groups; arrow keys move within a group. This two-level model does NOT exist on tvOS.
  • Use focusGroupIdentifier (iOS 14+, UIKit) to define custom focus groups — this API is NOT available on tvOS.
  • Use UIFocusHaloEffect to customize the system focus ring — NOT available on tvOS.
  • Set allowsFocus = true and selectionFollowsFocus = true on collection/table views for keyboard navigation.
  • Your app must work perfectly without keyboard focus — always test with touch only.

watchOS

  • Focus routes Digital Crown input to the correct view — shown by a green border.
  • Focus is sequential (layout order), NOT spatial/directional.
  • .focusSection() is NOT available on watchOS.
  • .focusable() MUST come BEFORE .digitalCrownRotation() — reversing silently breaks crown input.
  • Do NOT add .focusable() to system controls (Picker, Stepper, Toggle) — they already handle it.

visionOS

  • Eye gaze = hover targeting, NOT focus. onHover(perform:) does NOT fire from gaze — only from pointer devices.
  • Use .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.
  • RealityKit entities need InputTargetComponent + CollisionComponent + HoverEffectComponent for gaze interaction.
  • .focusEffectDisabled() hides keyboard focus ring; .hoverEffectDisabled() disables gaze hover — they are different.

macOS

  • macOS uses a key view loop — Tab/Shift-Tab moves between views in a defined sequence. This is NOT spatial like tvOS.
  • Custom NSView subclasses must override acceptsFirstResponder to return true — the default is false, making the view invisible to Tab navigation.
  • autorecalculatesKeyViewLoop = true on NSWindow overwrites all manual nextKeyView connections. Pick one approach.
  • Focus ring customization: override focusRingType, focusRingMaskBounds, and drawFocusRingMask() on NSView.
  • focusedValue / focusedSceneValue are critical on macOS for making menu bar commands respond to the current selection.
  • Mac Catalyst: inherits iPad UIFocusSystem. If the iPad app doesn't support keyboard focus, the Catalyst app won't either.
  • Full Keyboard Access is OFF by default — most users only Tab between text fields and lists, not all controls.

All Platforms

  • Never add .focusable() to Buttons or NavigationLinks — they are already focusable. Adding it creates a double-focus wra
阅读完整来源 ↗