visionos-design-guidelines by ehmo/platform-design-skills
npx skills add https://github.com/ehmo/platform-design-skills --skill visionos-design-guidelines基于 Apple 人机界面指南的 Apple Vision Pro 综合设计规则。这些规则确保空间计算应用舒适、直观且符合平台惯例。
空间布局决定了用户的舒适度和可用性。放置不当会导致颈部疲劳、方向迷失或内容无法访问。
SL-01:将内容置于视野中心。 将主要窗口和内容直接放置在用户正前方、与眼睛齐平的位置。舒适的垂直视野范围大约在眼睛水平线上方和下方各 30 度。超出此范围的内容需要头部移动,并会导致疲劳。
SL-02:保持舒适距离。 将内容放置在距离用户自然的位置,窗口通常为 1-2 米。内容太近会感觉有侵入感;内容太远则难以阅读。系统默认放置距离约为 1.5 米。除非有充分理由,否则请遵守此距离。
SL-03:切勿将内容放置在用户身后。 用户不转身就无法看到身后的内容。所有 UI 元素必须出现在面向前的半球内。如果内容必须环绕用户,请提供清晰的导航来旋转或重新定位。
SL-04:尊重个人空间。 不要将 3D 对象或窗口放置在距离用户头部小于一臂距离(约 0.5 米)的范围内。进入个人空间的对象会引起不适和侵入感。直接触摸交互是例外,此时对象被有意放置在触手可及的范围内。
SL-05:使用 Z 轴深度建立层次结构。 距离用户更近的元素显得更突出且更具交互性。将次要或背景内容推得更远。在分层元素之间使用细微的深度偏移(几厘米),而不是使用破坏界面整体感的剧烈分离。
SL-06:周到地管理多个窗口。 显示多个窗口时,将它们围绕用户排列成平缓的弧线,而不是堆叠或重叠。每个窗口应可单独重新定位。避免同时生成过多窗口,以免空间杂乱不堪。
SL-07:将内容锚定到环境,而非头部。 当用户移动头部时,窗口和对象应保持在世界空间中的固定位置。头部锁定内容(跟随头部移动的内容)会引起不适和晕动症。仅对短暂、瞬态的元素(如工具提示)使用相对于头部的定位。
visionOS 使用间接交互作为其主要输入模型:用户注视目标并捏合手指进行选择。这与触摸或鼠标输入有根本区别。
EH-01:围绕“注视-捏合”作为主要交互进行设计。 标准交互是:用户注视一个元素(眼睛提供目标定位),然后捏合拇指和食指(手提供确认)。围绕此模型设计所有主要交互。用户无需抬手或指向对象。
EH-02:最小交互目标尺寸为 60pt。 眼动追踪存在固有的不精确性。所有可点击元素的直径必须至少为 60 点,才能被视线可靠地定位。这比 iOS 触摸目标(44pt)要大。更小的目标会导致挫败感和误选。
正确示例:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
// visionOS — 按钮满足 60pt 最小值
Button(action: confirmAction) {
Label("Confirm", systemImage: "checkmark")
.frame(minWidth: 60, minHeight: 60)
.padding(.horizontal, 16)
}
.buttonStyle(.borderedProminent)
错误示例:
// visionOS — 32pt 按钮太小,无法可靠地进行视线定位
Button(action: confirmAction) {
Image(systemName: "checkmark")
.frame(width: 32, height: 32) // 低于 60pt 最小值;眼动追踪不可靠
}
EH-03:在注视时提供悬停反馈。 当用户视线停留在交互元素上时,显示可见的高亮或轻微扩展,以确认该元素已被定位。此反馈至关重要,因为没有光标。没有悬停状态,用户无法判断他们将要选择什么。
EH-04:支持近距离对象的直接触摸。 当 3D 对象或 UI 元素在一臂距离内时,允许直接触摸交互(伸手并点击)。直接触摸应感觉自然:在接触时提供视觉和音频反馈。在能增强临场感的沉浸式体验中使用直接触摸。
EH-05:切勿为内容目的追踪视线。 眼睛位置仅用于系统交互定位。不要使用视线方向来推断用户兴趣、根据用户注视的内容更改内容或记录用户注视的位置。这是平台的核心隐私原则。系统不会向应用暴露原始眼动追踪数据。
EH-06:保持自定义手势简单直观。 如果定义了超出系统捏合的自定义手势,请确保它们易于发现、执行起来身体舒适,并且不与系统手势冲突。避免需要持续抬手、复杂手指模式或双手协调才能完成基本操作的手势。
EH-07:不要要求精确的手部定位。 用户在与手部自然放在腿上或身体两侧时进行交互。不要要求用户将手保持在特定位置、伸到特定位置或维持持续的手势。间接交互模型的存在正是为了减少体力消耗。
EH-08:在交互开始时确认意图。 一旦系统识别出视线目标、捏合、拖拽拾取或直接触摸接触,立即显示可见的状态变化。延迟确认会破坏眼手协调循环,使选择感觉不确定。
| 交互 | 方法 | 使用场景 |
|---|---|---|
| 点击 / 选择 | 注视 + 捏合 | 按钮、链接、列表项 |
| 滚动 | 注视 + 捏合拖拽 | 列表、长内容 |
| 缩放 | 双手捏合 | 地图、图像、3D 模型 |
| 旋转 | 双手扭转 | 3D 对象操作 |
| 拖拽 | 注视 + 捏合保持并移动 | 重新定位窗口 |
| 直接触摸 | 伸手并点击 | 近距离 3D 对象 |
| 长按 | 注视 + 捏合并保持 | 上下文菜单 |
| 元素 | 最小尺寸 | 推荐尺寸 |
|---|---|---|
| 按钮 | 60pt | 60-80pt |
| 列表行 | 高度 60pt | 高度 80pt |
| 标签栏项目 | 60pt | 72pt |
| 关闭/取消 | 60pt | 60pt |
| 工具栏项目 | 60pt | 60pt |
| 3D 交互对象 | 等效 60pt | 根据上下文缩放 |
visionOS 中的窗口悬浮在用户的物理空间中。它们使用玻璃材质,与现实环境融为一体。
WN-01:使用玻璃材质作为默认窗口背景。 系统玻璃材质会根据用户的现实环境动态调整,提供一致且可读的背景。除非有特定的设计原因(例如媒体播放),否则不要用不透明的纯色替换玻璃材质。玻璃材质将界面固定在共享空间中。
WN-02:保持标准窗口控件。 窗口底部包含一个系统提供的窗口栏,用于重新定位,以及一个关闭按钮。不要隐藏、覆盖或替换这些控件。用户依赖所有应用间一致的窗口管理。
WN-03:在适当时使窗口可调整大小。 如果你的内容受益于不同尺寸(文档、浏览器、媒体),请支持窗口调整大小。使用系统调整大小手柄。定义合理的最小和最大尺寸。随着窗口大小的调整,响应式地调整布局。
WN-04:将标签栏作为前导装饰放置(左侧)。 在 visionOS 上,标签栏(应用导航)作为垂直装饰定位在窗口的前导(左)边缘,而不是像 iOS 那样在底部。这使得导航易于访问,同时不占用窗口内容区域。使用 SF Symbols 作为标签图标。
WN-05:将工具栏作为底部装饰放置。 主要操作控件出现在锚定在窗口底边的工具栏装饰中。此位置将控件放置在靠近用户手部自然放置的位置,并保持内容区域不被遮挡。
WN-06:窗口悬浮在空间中,没有固定屏幕。 没有固定的显示器。窗口存在于用户的物理环境中。设计的内容在从轻微角度和不同距离观看时看起来应正确。避免假定固定视口大小或像素完美定位的设计。
体积在边界框内显示 3D 内容。它们非常适合 3D 模型、可视化以及用户可以从多个角度检查的对象。
VL-01:将 3D 内容限制在体积边界内。 所有内容必须适合定义的体积尺寸。超出边界的内容将被裁剪。根据所容纳的内容适当调整体积大小,并遵守系统强制执行的限制。
VL-02:为从所有角度观看而设计。 用户可以实际围绕体积行走或重新定位它。确保 3D 内容从所有观看角度看起来都正确,而不仅仅是正面。避免从侧面看像纸板剪贴画的扁平外观。
VL-03:不要要求特定的观看位置。 用户可以从上方、下方或任何一侧观看体积。无论观看角度如何,内容都必须保持可理解性。如果方向很重要,请使用视觉提示(底座、标签),而不是强制特定的位置。
VL-04:根据空间适当缩放内容。 体积的大小应相对于其内容和用户的环境。分子模型可能很小,可以放在一臂距离处。建筑可视化可能占据整个桌面。考虑用户将与体积交互的上下文。
VL-05:将体积用于自包含的 3D 体验。 体积不是内部有 3D 对象的窗口。当 3D 内容是主要体验时(检查产品模型、查看 3D 图表),使用体积。对于可能包含一些 3D 元素的主要是 2D 的界面,使用窗口。
visionOS 支持从共享空间(应用与现实并存)到完全沉浸(完全虚拟环境)的一系列沉浸程度。
IS-01:从共享空间开始。 应用默认启动到共享空间,多个应用窗口与现实世界并存。仅当用户明确请求时才过渡到更沉浸的体验。不要在启动时强制沉浸。
IS-02:使用渐进式沉浸。 逐步通过沉浸级别:共享空间(窗口与现实并存)到完整空间(你的应用接管,但透视保持)再到完全沉浸(完全虚拟环境)。每一步都应该是用户有意发起且感觉自然的。
IS-03:始终提供退出路径。 用户必须始终能够返回到沉浸程度较低的状态或完全退出体验。数字表冠是系统级的退出方式。在你的应用内,提供清晰的控制来降低沉浸度。切勿将用户困在沉浸式体验中。
IS-04:为安全起见使用透视。 在用户可能实际移动的体验中,保持真实环境的透视或提供防护边界。用户需要意识到物理障碍物、其他人和房间边界。完全沉浸仅适用于用户静止不动时。
IS-05:逐渐调暗透视。 当过渡到更高沉浸度时,逐渐调暗透视环境,而不是直接切黑。突然的视觉变化会让人迷失方向。在沉浸级别之间使用平滑、动画化的过渡。
IS-06:不要假定房间布局或大小。 用户处于不同的物理空间中。不要设计需要最小房间尺寸、假定有清晰地板区域或期望特定家具摆放的体验。优雅地适应任何可用的物理空间。
IS-07:提供空间音频提示。 在沉浸式空间中,使用空间音频帮助用户定位。声音应来自虚拟环境中其源头的方向。音频提示可以引导注意力并提供反馈,而无需视觉聚焦。
visionOS 使用基于物理的材质系统,可响应现实世界的光照。正确使用材质可以创建深度层次结构并确保可读性。
MD-01:对 UI 表面使用系统玻璃材质。 玻璃材质是 visionOS UI 的基础。它提供深度、半透明性和环境融合。使用系统提供的玻璃变体(常规、薄、超薄),而不是自定义的半透明材质。
MD-02:镜面高光响应环境。 visionOS 中的材质会对现实世界的光照条件做出反应。设计利用这一点的元素:交互元素上微妙的镜面高光增强了它们的立体感。不要用纯哑光表面使材质扁平化。
MD-03:分层材质以创建深度层次结构。 对前景元素使用更浅/更厚的玻璃,对背景使用更深/更薄的玻璃。侧边栏使用与内容区域略有不同的玻璃色调。这种分层创建了自然的视觉层次结构,没有尖锐的边框。
MD-04:应用活力效果以提高文本可读性。 玻璃材质上的文本使用活力效果,以确保无论背景环境如何都能保持清晰易读。使用包含适当活力效果的系统文本样式。玻璃上的自定义文本渲染必须考虑变化的背景亮度和颜色。
MD-05:使用阴影和高光表示高度。 悬浮在窗口表面上方的元素(弹出窗口、菜单、悬停状态)应投射微妙的阴影,并在其上部边缘显示轻微的镜面高光。这些深度提示有助于用户理解界面层之间的空间关系。
MD-06:在共享空间中避免完全不透明的背景。 共享空间中的不透明表面会在环境中造成视觉空洞。使用让环境透过的半透明玻璃材质。例外情况包括媒体播放(视频、照片),其中不透明背景可以改善观看体验。
装饰是附着在窗口边缘、部分悬浮在窗口边界之外的 UI 控件。它们提供工具栏、导航和上下文操作。
OR-01:将控件作为装饰附着,而不是内联。 工具栏、标签栏和持久性操作按钮应作为装饰,而不是嵌入窗口内容区域。装饰保持内容区域整洁,并在控件和内容之间建立清晰的空间层次结构。
OR-02:将主要操作放在底部装饰中。 底边装饰是放置操作控件(播放/暂停、格式化工具、共享)的主要位置。此位置符合人体工程学,易于访问,且视觉突出,同时不会遮挡内容。
OR-03:将导航放在前导(左侧)装饰中。 应用级导航(相当于标签栏)附着在窗口的前导边缘。这使得导航持久且易于访问,同时将内容区域和底部装饰留给上下文控件。
OR-04:不要用装饰遮挡窗口内容。 装饰从窗口边缘向外延伸,而不是向内。它们不应覆盖或重叠窗口的内容区域。适当调整装饰的大小,使其在功能上保持有效,而不会在视觉上压倒内容。
OR-05:在适当时根据上下文显示装饰。 并非所有装饰都需要始终可见。工具栏可以在悬停时(当用户注视窗口时)出现,并在用户视线移开时淡出。这保持了界面的整洁,同时保持了可发现性。
OR-06:使用标准装饰样式。 装饰使用与窗口相同的玻璃材质系统,但深度略有不同。使用系统提供的装饰容器,而不是自定义的浮动 UI。这确保了与其他 visionOS 应用的视觉一致性。
OR-07:保持基本控件的可发现性。 使用装饰来放置用户必须反复使用的命令,例如导航、播放或主要操作。不要将基本控件隐藏在需要记忆的手势或仅悬停才显示的提示后面。
visionOS 支持 VoiceOver、切换控制和指针控制替代方案。空间 UI 必须可以在不依赖眼动和手势输入的情况下进行导航。
ACC-01:每个交互元素都必须有有意义的无障碍标签。 用户可以交互的按钮、控件和 3D 对象必须有 VoiceOver 可以播报的标签。不要仅依赖视觉外观或位置。
ACC-02:VoiceOver 必须能够到达所有交互元素。 确保无障碍树覆盖所有可聚焦的控件。可交互的自定义 RealityKit 实体必须在无障碍层次结构中注册。
ACC-03:支持指针控制和切换控制替代方案。 并非所有用户都能使用眼动追踪和手部捏合。确保应用可以通过替代输入方法(如头部指针、切换控制或键盘导航)完全导航。
ACC-04:尊重减少动态效果。 当启用减少动态效果时,必须禁用或减少空间动画、沉浸式过渡和视差效果。空间环境中的突然运动会导致迷失方向。
@Environment(\.accessibilityReduceMotion) var reduceMotion
var body: some View {
Model3D(named: "SceneObject")
.rotation3DEffect(reduceMotion ? .zero : rotation, axis: (0, 1, 0))
}
ACC-05:响应粗体文本。 当用户启用粗体文本时,visionOS 中的自定义渲染文本必须适应。SwiftUI 动态类型样式会自动处理此问题;自定义渲染必须检查 UIAccessibility.isBoldTextEnabled 或使用 @Environment(\.legibilityWeight) 来检测并应用更粗的字重。
ACC-06:响应增加对比度。 当用户启用增加对比度时,自定义颜色必须提供更高对比度的变体。在 SwiftUI 中使用 @Environment(\.colorSchemeContrast) 来检测 .increased,并为在玻璃或环境背景上渲染的文本和 UI 元素替换更高对比度的颜色值。
使用此清单评估 visionOS 设计或实现。
legibilityWeight 或 UIAccessibility.isBoldTextEnabled)colorSchemeContrast 提供更高对比度的变体)这些是 visionOS 设计中的常见错误。请避免它们。
| 反面模式 | 问题 | 正确方法 |
|---|---|---|
| 头部锁定 UI | 导致晕动症,感觉幽闭 | 将 UI 锚定到世界空间 |
| 过小的点击目标 | 眼动追踪无法可靠定位 < 60pt 的目标 | 最小 60pt 交互目标 |
| 无悬停状态 | 用户无法分辨什么是可交互的 | 始终在注视时显示高亮 |
| 共享空间中的不透明窗口 | 在环境中造成视觉空洞 | 使用系统玻璃材质 |
| 强制完全沉浸 | 令人迷失方向,困住用户 | 从共享空间开始,渐进式沉浸 |
| 用户身后的内容 | 不可见,需要全身旋转 | 将内容保持在向前半球内 |
| 视线驱动的内容 | 侵犯隐私,感觉被监视 | 仅将视线用于系统定位 |
| 扁平的 3D 体积 | 从侧面看像纸板剪贴画 | 为所有观看角度设计 |
| 内联工具栏 | 浪费内容空间,打破惯例 | 使用装饰放置控件 |
| 小房间假设 | 在狭小空间中失败 | 适应可用的物理空间 |
| 突然的沉浸度变化 | 令人迷失方向,破坏临场感 | 使用动画进行渐进式过渡 |
| 持续抬手 | 几分钟内导致身体疲劳 | 为手部放在身体两侧而设计 |
| 自定义窗口装饰 | 破坏平台一致性 | 使用系统窗口控件 |
| Z 轴冲突层 | 视觉闪烁,层次结构不清晰 | 使用有意的深度偏移 |
每周安装量
188
代码仓库
GitHub 星标数
283
首次出现
2026年2月1日
安全审计
安装于
claude-code157
codex156
opencode152
gemini-cli146
github-copilot132
cursor131
Comprehensive design rules for Apple Vision Pro based on Apple Human Interface Guidelines. These rules ensure spatial computing apps are comfortable, intuitive, and consistent with platform conventions.
Spatial layout determines user comfort and usability. Poor placement causes neck strain, disorientation, or inaccessible content.
SL-01: Center content in the field of view. Place primary windows and content directly ahead of the user at eye level. The comfortable vertical viewing range is approximately 30 degrees above and below eye level. Content outside this range requires head movement and causes fatigue.
SL-02: Maintain comfortable distance. Position content at a natural distance from the user, typically 1-2 meters for windows. Content too close feels invasive; content too far is hard to read. The system default placement is approximately 1.5 meters. Respect this unless there is a strong reason to override.
SL-03: Never place content behind the user. Users cannot see content behind them without physically turning around. All UI elements must appear within the forward-facing hemisphere. If content must surround the user, provide clear navigation to rotate or reposition.
SL-04: Respect personal space. Do not place 3D objects or windows closer than arm's length (~0.5 meters) from the user's head. Objects inside personal space cause discomfort and a feeling of intrusion. Direct-touch interactions are the exception, where objects are intentionally within reach.
SL-05: Use Z-depth to establish hierarchy. Elements closer to the user appear more prominent and interactive. Push secondary or background content further back. Use subtle depth offsets (a few centimeters) between layered elements rather than dramatic separation that fragments the interface.
SL-06: Manage multiple windows thoughtfully. When displaying multiple windows, arrange them in a gentle arc around the user rather than stacking or overlapping. Each window should be individually repositionable. Avoid spawning too many simultaneous windows that overwhelm the space.
SL-07: Anchor content to the environment, not the head. Windows and objects should stay fixed in world space as the user moves their head. Head-locked content (content that follows head movement) causes discomfort and motion sickness. Only use head-relative positioning for brief, transient elements like tooltips.
visionOS uses indirect interaction as its primary input model: users look at a target and pinch to select. This is fundamentally different from touch or mouse input.
EH-01: Design for look-and-pinch as the primary interaction. The standard interaction is: user looks at an element (eyes provide targeting), then pinches thumb and index finger together (hand provides confirmation). Design all primary interactions around this model. Users do not need to raise their hands or point at objects.
EH-02: Minimum interactive target size is 60pt. Eye tracking has inherent imprecision. All tappable elements must be at least 60 points in diameter to be reliably targeted by gaze. This is larger than iOS touch targets (44pt). Smaller targets cause frustration and mis-selections.
Correct:
// visionOS — button meeting 60pt minimum
Button(action: confirmAction) {
Label("Confirm", systemImage: "checkmark")
.frame(minWidth: 60, minHeight: 60)
.padding(.horizontal, 16)
}
.buttonStyle(.borderedProminent)
Incorrect:
// visionOS — 32pt button too small for reliable gaze targeting
Button(action: confirmAction) {
Image(systemName: "checkmark")
.frame(width: 32, height: 32) // Below 60pt minimum; unreliable with eye tracking
}
EH-03: Provide hover feedback on gaze. When the user's eyes rest on an interactive element, show a visible highlight or subtle expansion to confirm the element is targeted. This feedback is essential because there is no cursor. Without hover states, users cannot tell what they are about to select.
EH-04: Support direct touch for close-range objects. When 3D objects or UI elements are within arm's reach, allow direct touch interaction (physically reaching out and tapping). Direct touch should feel natural: provide visual and audio feedback on contact. Use direct touch for immersive experiences where it enhances presence.
EH-05: Never track gaze for content purposes. Eye position is used exclusively for system interaction targeting. Do not use gaze direction to infer user interest, change content based on what the user looks at, or record where the user looks. This is a core privacy principle of the platform. The system does not expose raw eye-tracking data to apps.
EH-06: Keep custom gestures simple and intuitive. If you define custom hand gestures beyond the system pinch, ensure they are easy to discover, physically comfortable to perform, and do not conflict with system gestures. Avoid gestures that require sustained hand raising, complex finger patterns, or two-handed coordination for basic actions.
EH-07: Do not require precise hand positioning. Users interact with hands resting naturally in their lap or at their sides. Do not require users to hold their hands in specific positions, reach to specific locations, or maintain sustained gestures. The indirect interaction model exists specifically to reduce physical effort.
EH-08: Confirm intent at the start of the interaction. As soon as the system recognizes gaze target, pinch, drag pickup, or direct touch contact, show a visible state change. Delayed confirmation breaks the eye-hand loop and makes selection feel uncertain.
| Interaction | Method | Use Case |
|---|---|---|
| Tap / Select | Look + pinch | Buttons, links, list items |
| Scroll | Look + pinch-and-drag | Lists, long content |
| Zoom | Two-hand pinch | Maps, images, 3D models |
| Rotate | Two-hand twist | 3D object manipulation |
| Drag | Look + pinch-hold-and-move | Repositioning windows |
| Direct touch | Reach and tap | Close-range 3D objects |
| Long press | Look + pinch-and-hold | Context menus |
| Element | Minimum Size | Recommended Size |
|---|---|---|
| Buttons | 60pt | 60-80pt |
| List rows | 60pt height | 80pt height |
| Tab bar items | 60pt | 72pt |
| Close/dismiss | 60pt | 60pt |
| Toolbar items | 60pt | 60pt |
| 3D interactive objects | 60pt equivalent | Scale to context |
Windows in visionOS float in the user's physical space. They use a glass material that blends with the real-world environment.
WN-01: Use glass material as the default window background. The system glass material dynamically adapts to the user's real-world surroundings, providing a consistent and readable backdrop. Do not replace glass with opaque solid colors unless you have a specific design reason (such as media playback). Glass grounds the interface in the shared space.
WN-02: Maintain standard window controls. Windows include a system-provided window bar at the bottom for repositioning and a close button. Do not hide, override, or replace these controls. Users rely on consistent window management across all apps.
WN-03: Make windows resizable when appropriate. If your content benefits from different sizes (documents, browsers, media), support window resizing. Use the system resize handle. Define reasonable minimum and maximum sizes. Adapt layout responsively as the window resizes.
WN-04: Place the tab bar as a leading ornament (left side). On visionOS, the tab bar (app navigation) is positioned as a vertical ornament on the leading (left) edge of the window, not at the bottom as on iOS. This keeps navigation accessible without consuming window content area. Use SF Symbols for tab icons.
WN-05: Place the toolbar as a bottom ornament. Primary action controls appear in a toolbar ornament anchored to the bottom edge of the window. This positions controls near the user's natural hand resting position and keeps the content area unobstructed.
WN-06: Windows float in space with no fixed screen. There is no fixed display. Windows exist in the user's physical environment. Design content that looks correct when viewed from slight angles and at varying distances. Avoid designs that assume a fixed viewport size or pixel-perfect positioning.
Volumes display 3D content within a bounded box. They are ideal for 3D models, visualizations, and objects users can examine from multiple angles.
VL-01: Contain 3D content within the volume bounds. All content must fit within the defined volume dimensions. Content that escapes the bounds will be clipped. Size the volume appropriately for the content it holds and respect the system-enforced limits.
VL-02: Design for viewing from all angles. Users can physically walk around a volume or reposition it. Ensure 3D content looks correct from all viewing angles, not just the front. Avoid flat facades that look like cardboard cutouts from the side.
VL-03: Do not require a specific viewing position. The user may view the volume from above, below, or any side. Content must remain comprehensible regardless of viewing angle. If orientation matters, use visual cues (a base, a label) rather than forcing a specific position.
VL-04: Scale content appropriately for the space. Volumes should be sized relative to their content and the user's environment. A molecular model might be small and held at arm's length. An architectural visualization might fill a table. Consider the context in which users will interact with the volume.
VL-05: Use volumes for self-contained 3D experiences. Volumes are not windows with 3D objects inside them. Use volumes when the 3D content is the primary experience (examining a product model, viewing a 3D chart). Use windows for primarily 2D interfaces that may include some 3D elements.
visionOS supports a spectrum of immersion from shared space (apps alongside reality) to full immersion (complete virtual environment).
IS-01: Start in the Shared Space. Apps launch into the Shared Space by default, where multiple app windows coexist alongside the real world. Only transition to more immersive experiences when the user explicitly requests it. Do not force immersion on launch.
IS-02: Use progressive immersion. Move through immersion levels gradually: Shared Space (windows alongside reality) to Full Space (your app takes over but passthrough remains) to Full Immersion (completely virtual environment). Each step should feel intentional and user-initiated.
IS-03: Always provide an exit path. Users must always be able to return to a less immersive state or exit the experience entirely. The Digital Crown is the system-level escape. Within your app, provide clear controls to reduce immersion. Never trap users in an immersive experience.
IS-04: Use passthrough for safety. In experiences where users might move physically, maintain passthrough of the real environment or provide a guardian boundary. Users need awareness of physical obstacles, other people, and room boundaries. Full immersion is only appropriate when the user is stationary.
IS-05: Dim passthrough gradually. When transitioning to increased immersion, dim the passthrough environment gradually rather than cutting to black. Abrupt visual changes are disorienting. Use smooth, animated transitions between immersion levels.
IS-06: Do not assume room layout or size. Users are in diverse physical spaces. Do not design experiences that require a minimum room size, assume a clear floor area, or expect specific furniture placement. Gracefully adapt to whatever physical space is available.
IS-07: Provide spatial audio cues. In immersive spaces, use spatial audio to help users orient. Sounds should come from the direction of their source in the virtual environment. Audio cues can guide attention and provide feedback without requiring visual focus.
visionOS uses a physically-based material system that responds to real-world lighting. Proper use of materials creates depth hierarchy and ensures readability.
MD-01: Use the system glass material for UI surfaces. The glass material is the foundation of visionOS UI. It provides depth, translucency, and environmental integration. Use the system-provided glass variants (regular, thin, ultra-thin) rather than custom translucent materials.
MD-02: Specular highlights respond to the environment. Materials in visionOS react to real-world lighting conditions. Design elements that leverage this: subtle specular highlights on interactive elements reinforce their dimensionality. Do not flatten materials with purely matte surfaces.
MD-03: Layer materials to create depth hierarchy. Use lighter/thicker glass for foreground elements and darker/thinner glass for background. Sidebars use a slightly different glass tint than content areas. This layering creates natural visual hierarchy without sharp borders.
MD-04: Apply vibrancy for text readability. Text over glass materials uses vibrancy effects to remain legible regardless of the background environment. Use the system text styles which include appropriate vibrancy. Custom text rendering over glass must account for varying background lightness and color.
MD-05: Use shadows and highlights for elevation. Elements that float above the window surface (popovers, menus, hover states) should cast subtle shadows and show slight specular highlights on their upper edges. These depth cues help users understand the spatial relationship between interface layers.
MD-06: Avoid fully opaque backgrounds in shared space. Opaque surfaces in the shared space create visual holes in the environment. Use translucent glass materials that let the environment show through. Exceptions include media playback (video, photos) where an opaque background improves the viewing experience.
Ornaments are UI controls that attach to the edges of windows, floating partially outside the window bounds. They provide toolbars, navigation, and contextual actions.
OR-01: Attach controls as ornaments rather than inline. Toolbars, tab bars, and persistent action buttons belong as ornaments, not embedded within the window content area. Ornaments keep the content area clean and establish a clear spatial hierarchy between controls and content.
OR-02: Place primary actions in the bottom ornament. The bottom edge ornament is the primary location for action controls (play/pause, formatting tools, share). This position is ergonomically accessible and visually prominent without obscuring content.
OR-03: Place navigation in the leading (left) ornament. App-level navigation (tab bar equivalent) attaches to the leading edge of the window. This keeps navigation persistent and accessible while leaving the content area and bottom ornament for contextual controls.
OR-04: Do not occlude window content with ornaments. Ornaments extend outward from the window edge, not inward. They should not cover or overlap the window's content area. Size ornaments appropriately so they remain functional without becoming visually dominant over the content.
OR-05: Show ornaments contextually when appropriate. Not all ornaments need to be visible at all times. Toolbars can appear on hover (when the user looks at the window) and fade when the user looks away. This keeps the interface clean while maintaining discoverability.
OR-06: Use standard ornament styling. Ornaments use the same glass material system as windows but at a slightly different depth. Use system-provided ornament containers rather than custom floating UI. This ensures visual consistency with other visionOS apps.
OR-07: Keep essential controls discoverable. Use ornaments for commands users must revisit repeatedly, such as navigation, playback, or primary actions. Do not hide essential controls behind memorized gestures or hover-only affordances.
visionOS supports VoiceOver, Switch Control, and pointer control alternatives. Spatial UI must be navigable without relying solely on eye and hand input.
ACC-01: Every interactive element must have a meaningful accessibility label. Buttons, controls, and 3D objects that users can interact with must have labels VoiceOver can announce. Do not rely on visual appearance or position alone.
ACC-02: VoiceOver must be able to reach all interactive elements. Ensure the accessibility tree covers all focusable controls. Custom RealityKit entities that are interactive must be registered in the accessibility hierarchy.
ACC-03: Support pointer control and Switch Control alternatives. Not all users can use eye tracking and hand pinch. Ensure the app is fully navigable via alternative input methods such as head pointer, Switch Control, or keyboard navigation.
ACC-04: Respect Reduce Motion. Spatial animations, immersive transitions, and parallax effects must be disabled or reduced when Reduce Motion is enabled. Abrupt motion in a spatial environment can cause disorientation.
@Environment(\.accessibilityReduceMotion) var reduceMotion
var body: some View {
Model3D(named: "SceneObject")
.rotation3DEffect(reduceMotion ? .zero : rotation, axis: (0, 1, 0))
}
ACC-05: Respond to Bold Text. When the user enables Bold Text, custom-rendered text in visionOS must adapt. SwiftUI dynamic type styles handle this automatically; custom rendering must check UIAccessibility.isBoldTextEnabled or use @Environment(\.legibilityWeight) to detect and apply heavier weights.
ACC-06: Respond to Increase Contrast. When the user enables Increase Contrast, custom colors must provide higher-contrast variants. Use @Environment(\.colorSchemeContrast) in SwiftUI to detect .increased and substitute higher-contrast color values for text and UI elements rendered against glass or environment backgrounds.
Use this checklist to evaluate a visionOS design or implementation.
legibilityWeight or UIAccessibility.isBoldTextEnabled)colorSchemeContrast)These are common mistakes in visionOS design. Avoid them.
| Anti-Pattern | Problem | Correct Approach |
|---|---|---|
| Head-locked UI | Causes motion sickness, feels claustrophobic | Anchor UI to world space |
| Tiny tap targets | Eye tracking cannot reliably target < 60pt | Minimum 60pt interactive targets |
| No hover states | Users cannot tell what is interactive | Always show highlight on gaze |
| Opaque windows in shared space | Creates visual holes in environment | Use system glass material |
| Forced full immersion | Disorienting, traps users | Start in shared space, progressive immersion |
| Content behind user | Invisible, requires full body rotation | Keep content in forward hemisphere |
| Gaze-driven content | Privacy violation, feels surveilled | Use gaze only for system targeting |
| Flat 3D volumes | Looks like cardboard cutout from side | Design for all viewing angles |
Weekly Installs
188
Repository
GitHub Stars
283
First Seen
Feb 1, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
claude-code157
codex156
opencode152
gemini-cli146
github-copilot132
cursor131
前端设计技能指南:避免AI垃圾美学,打造独特生产级界面
49,900 周安装
| Inline toolbars | Wastes content space, breaks conventions | Use ornaments for controls |
| Small room assumptions | Fails in tight spaces | Adapt to available physical space |
| Abrupt immersion changes | Disorienting, breaks presence | Gradual transitions with animation |
| Sustained arm raising | Physical fatigue in minutes | Design for hands resting at sides |
| Custom window chrome | Breaks platform consistency | Use system window controls |
| Z-fighting layers | Visual flicker, unclear hierarchy | Use intentional depth offsets |