visionos-widgetkit-developer_skill

Overview

This skill helps you design, implement, and troubleshoot WidgetKit widgets for Apple Vision Pro (visionOS). It focuses on visionOS specifics: mounting styles (elevated vs recessed), textures (glass vs paper), proximity-aware layouts using LevelOfDetail, and timeline/update debugging. You get a practical checklist and concrete implementation patterns to ensure legibility and correct behavior when widgets are pinned in 3D space. The guidance also clarifies when to target a visionOS-native widget versus a compatibility widget from iPhone/iPad builds.

How this skill works

When asked to build or debug a Vision Pro widget, the skill first clarifies scope (native visionOS widget vs compatibility mode) and required families. It then maps a two-tier layout strategy: a default (close) layout and a simplified (far) layout driven by @Environment(.levelOfDetail). It recommends mounting styles and textures, validates legibility/density trade-offs, and provides a timeline and refresh checklist to diagnose stale or missing updates. Finally, it lists concrete checks for common failure modes and offers implementation code patterns to follow.

When to use it

• Designing a widget specifically for Apple Vision Pro with spatial considerations
• Converting existing iOS/iPadOS widgets to work well when pinned in visionOS
• Implementing proximity-aware layouts using LevelOfDetail for near/far readability
• Choosing mounting styles and textures to match your app’s visual language
• Troubleshooting stale timelines, missing families, or rendering differences in recessed mode

Best practices

• Define two layouts: a detailed default and a simplified far view using @Environment(.levelOfDetail)
• Explicitly declare supportedMountingStyles and test both elevated and recessed modes
• Pick widgetTexture (glass or paper) to match contrast needs and test in multiple lighting conditions
• Favor larger typography and reduced content density for .simplified to maintain glanceability from distance
• Use a deliberate timeline policy and implement reloads/refresh logic; add diagnostics for stale entries

Example use cases

• Create a visionOS-native weather widget with glass texture for high-contrast glanceability across a room
• Adapt an iPhone widget to be compatibility-friendly while adding a simplified layout for distance
• Debug a widget that appears broken in recessed mounting by checking safe area, background blending, and supported families
• Resolve stale content by auditing timeline policy, background refresh settings, and provider code