widgets_skill

Overview

This skill documents visionOS widget patterns for spatial UI: mounting styles, surface textures, proximity-aware layouts, spatial widget families, and rendering modes. It helps you design, adapt, and preview widgets that live in physical space and behave correctly as users move through the environment. Use it to avoid common porting mistakes and ensure widgets render well in both full-color and accented modes.

How this skill works

The skill describes how to declare mounting styles (.elevated, .recessed, or both) and choose a widget texture (.glass or .paper). It explains proximity-aware rendering via @Environment(.levelOfDetail) to switch between detailed and simplified layouts, and how to mark removable container backgrounds with .containerBackground(for:). It also covers supported families including visionOS-only .systemExtraLargePortrait and API availability and guards for multiplatform targets.

When to use it

• Creating a new visionOS widget from scratch
• Porting an iOS/iPadOS widget to visionOS
• Adding proximity-aware detail levels for distance-based readability
• Choosing mounting style or surface texture for spatial placement
• Ensuring correct rendering in accented (system-tinted) mode
• Supporting visionOS-only family sizes like extra large portrait

Best practices

• Set supportedMountingStyles explicitly if your widget must embed in walls or support both placements
• Use .widgetTexture(.glass) for environmental blending, .paper for opaque poster-like content
• Provide simplified layouts in @Environment(.levelOfDetail) == .simplified with larger type and fewer elements
• Wrap removable artwork in .containerBackground(for: .widget) { } so accented mode can safely remove backgrounds
• Guard .systemExtraLargePortrait with #if os(visionOS) in multiplatform projects
• Use system semantic foregroundStyle and colors instead of hardcoded tints for glass compatibility

Example use cases

• A dashboard widget that appears large on a room shelf (.elevated) and shows full charts when close, simplified summary when far
• A framed photo widget embedded in a wall using .recessed and .paper texture for opaque imagery
• Porting a weather widget: add levelOfDetail switch to show an icon and temp at a distance and full forecast when close
• A compact glanceable widget for quick info using .systemSmall and containerBackground to support accented rendering
• A multiplatform widget that includes .systemExtraLargePortrait only on visionOS via conditional compilation