apple-liquid-glass-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apple Liquid Glass Design

Apple Liquid Glass 设计指南

Lifecycle Position

生命周期定位

Phases 2-3 (Design → Implement). Related:

swiftui-components

(glass templates),

swiftui-material-api

(material backgrounds).

Reference for Apple's Liquid Glass design system introduced in iOS 26, iPadOS 26, and macOS 26. Liquid Glass is a dynamic material that combines optical properties of glass with fluidity, forming a functional layer for controls and navigation elements.

第2-3阶段（设计→实现）。相关内容：

swiftui-components

（玻璃效果模板）、

swiftui-material-api

（材质背景）。

本文档是针对iOS 26、iPadOS 26和macOS 26中引入的Apple Liquid Glass设计系统的参考资料。Liquid Glass是一种动态材质，融合了玻璃的光学特性与流体特性，可为控件和导航元素构建功能性图层。

When to Use This Skill

何时使用该技能

Trigger conditions:

Applying Liquid Glass effects to custom SwiftUI views (
```
glassEffect
```
,
```
GlassEffectContainer
```
)
Using background extension effects to stretch content under sidebars/inspectors
Styling buttons with
```
.glass
```
or
```
.glassProminent
```
button styles
Implementing morph animations between Liquid Glass elements
Organizing toolbar items with
```
ToolbarSpacer(.fixed)
```
grouping
Creating app icons with Icon Composer for Liquid Glass
Extending horizontal scroll views under sidebars/inspectors
Adding scroll edge effects for content legibility
Implementing tab bar minimize behavior
Using
```
ConcentricRectangle
```
for concentric corner radii
Working with
```
UIGlassEffect
```
(UIKit) or
```
NSGlassEffectView
```
(AppKit)
Adopting Liquid Glass in existing apps (migration from older SDK)
Opting out via
```
UIDesignRequiresCompatibility
```
Info.plist key

Do NOT use when:

Working with pre-iOS 26 glass effects (visionOS
```
glassBackgroundEffect
```
is a separate API)
General SwiftUI layout questions unrelated to Liquid Glass

触发条件：

为自定义SwiftUI视图应用Liquid Glass效果（
```
glassEffect
```
、
```
GlassEffectContainer
```
）
使用背景扩展效果将内容延伸至侧边栏/检查器下方
为按钮应用
```
.glass
```
或
```
.glassProminent
```
按钮样式
实现Liquid Glass元素之间的形态动画
使用
```
ToolbarSpacer(.fixed)
```
组织工具栏项目
使用Icon Composer创建适配Liquid Glass的应用图标
将水平滚动视图延伸至侧边栏/检查器下方
添加滚动边缘效果以提升内容可读性
实现标签栏最小化行为
使用
```
ConcentricRectangle
```
创建同心圆角
处理
```
UIGlassEffect
```
（UIKit）或
```
NSGlassEffectView
```
（AppKit）
在现有应用中适配Liquid Glass（从旧版SDK迁移）
通过
```
UIDesignRequiresCompatibility
```
Info.plist键选择退出适配

请勿使用场景：

处理iOS 26之前的玻璃效果（visionOS的
```
glassBackgroundEffect
```
是独立API）
与Liquid Glass无关的通用SwiftUI布局问题

Workflow Decision Tree

工作流决策树

Choose the path that matches the request:

选择与请求匹配的路径：

1) Review an existing feature

1) 审核现有功能

Inspect where Liquid Glass should be used and where it should not.
Verify correct modifier order, shape usage, and container placement.
Check for iOS 26+ availability handling and sensible fallbacks.

检查应使用和不应使用Liquid Glass的场景
验证修饰符顺序、形状使用和容器放置是否正确
检查iOS 26+兼容性处理及合理的降级方案

2) Improve a feature using Liquid Glass

2) 使用Liquid Glass优化功能

Identify target components for glass treatment (surfaces, chips, buttons, cards).
Refactor to use
```
GlassEffectContainer
```
where multiple glass elements appear.
Introduce interactive glass only for tappable or focusable elements.

确定需要应用玻璃效果的目标组件（表面、芯片、按钮、卡片）
重构代码，在存在多个玻璃元素的场景中使用
```
GlassEffectContainer
```
仅为可点击或可聚焦元素添加交互式玻璃效果

3) Implement a new feature using Liquid Glass

3) 使用Liquid Glass实现新功能

Design the glass surfaces and interactions first (shape, prominence, grouping).
Add glass modifiers after layout/appearance modifiers.
Add morphing transitions only when the view hierarchy changes with animation.

先设计玻璃表面和交互逻辑（形状、突出度、分组）
在布局/外观修饰符之后添加玻璃效果修饰符
仅当视图层级随动画变化时，才添加形态过渡动画

Review Checklist

审核检查清单

Availability:
```
#available(iOS 26, *)
```
present with fallback UI.
Composition: Multiple glass views wrapped in
```
GlassEffectContainer
```
.
Modifier order:
```
glassEffect
```
applied after layout/appearance modifiers.
Interactivity:
```
interactive()
```
only where user interaction exists.
Transitions:
```
glassEffectID
```
used with
```
@Namespace
```
for morphing.
Consistency: Shapes, tinting, and spacing align across the feature.

兼容性：存在
```
#available(iOS 26, *)
```
声明及对应的降级UI
组合方式：多个玻璃视图被包裹在
```
GlassEffectContainer
```
中
修饰符顺序：
```
glassEffect
```
在布局/外观修饰符之后应用
交互性：仅在存在用户交互的场景中使用
```
interactive()
```
过渡效果：配合
```
@Namespace
```
使用
```
glassEffectID
```
实现形态动画
一致性：功能中的形状、着色和间距保持统一

Implementation Checklist

实现检查清单

Define target elements and desired glass prominence.
Wrap grouped glass elements in
```
GlassEffectContainer
```
and tune spacing.

Use

.glassEffect(.regular.tint(...).interactive(), in: .rect(cornerRadius: ...))

as needed.

Use

.buttonStyle(.glass)

.buttonStyle(.glassProminent)

for actions.

Add morphing transitions with
```
glassEffectID
```
when hierarchy changes.
Provide fallback materials and visuals for earlier iOS versions.

定义目标元素及所需的玻璃效果突出度
将分组的玻璃元素包裹在
```
GlassEffectContainer
```
中并调整间距

根据需要使用

.glassEffect(.regular.tint(...).interactive(), in: .rect(cornerRadius: ...))

为操作按钮应用

.buttonStyle(.glass)

.buttonStyle(.glassProminent)

当视图层级变化时，使用
```
glassEffectID
```
添加形态过渡动画
为iOS旧版本提供降级材质和视觉效果

Availability & Fallbacks

兼容性与降级方案

All Liquid Glass APIs require iOS 26 or later. Always provide fallbacks:

swift

if #available(iOS 26, *) {
    content
        .padding()
        .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16))
} else {
    content
        .padding()
        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
}

所有Liquid Glass API均要求iOS 26或更高版本。请始终提供降级方案：

swift

if #available(iOS 26, *) {
    content
        .padding()
        .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16))
} else {
    content
        .padding()
        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
}

Fallback Materials

降级材质选项

```
.ultraThinMaterial
```
— Closest to glass appearance
```
.thinMaterial
```
— Slightly more opaque
```
.regularMaterial
```
— Standard blur
```
.thickMaterial
```
— More opaque
```
.ultraThickMaterial
```
— Most opaque

```
.ultraThinMaterial
```
— 最接近玻璃外观
```
.thinMaterial
```
— 略不透明
```
.regularMaterial
```
— 标准模糊效果
```
.thickMaterial
```
— 更高不透明度
```
.ultraThickMaterial
```
— 最高不透明度

Conditional Modifier Extension

条件修饰符扩展

swift

extension View {
    @ViewBuilder
    func glassEffectWithFallback(
        _ style: Glass = .regular,
        in shape: some Shape = .rect,
        fallbackMaterial: Material = .ultraThinMaterial
    ) -> some View {
        if #available(iOS 26, *) {
            self.glassEffect(style, in: shape)
        } else {
            self.background(fallbackMaterial, in: shape)
        }
    }
}

swift

extension View {
    @ViewBuilder
    func glassEffectWithFallback(
        _ style: Glass = .regular,
        in shape: some Shape = .rect,
        fallbackMaterial: Material = .ultraThinMaterial
    ) -> some View {
        if #available(iOS 26, *) {
            self.glassEffect(style, in: shape)
        } else {
            self.background(fallbackMaterial, in: shape)
        }
    }
}

Key Concepts

核心概念

Concept	Description
Liquid Glass	Dynamic material that blurs content behind it, reflects color/light, and reacts to touch and pointer in real time
Glass variants	`.regular` (default), `.clear` (transparent), `.identity` (no effect)
GlassEffectContainer	Groups multiple glass effects for performance and morph animations
Morph animation	Shapes blend/separate fluidly when views appear/disappear within a container
Background extension	Mirrors and blurs edge content under sidebars/inspectors for edge-to-edge feel
Icon Composer	Xcode tool for creating multilayer Liquid Glass app icons
ConcentricRectangle	Shape that maintains concentric corner radii relative to its container

概念	描述
Liquid Glass	动态材质，可模糊后方内容、反射颜色/光线，并实时响应触摸和指针操作
玻璃效果变体	`.regular` （默认）、 `.clear` （透明）、 `.identity` （无效果）
GlassEffectContainer	组合多个玻璃效果以提升性能并支持形态动画
形态动画	当视图在容器内显示/消失时，形状会流畅地融合/分离
背景扩展	镜像并模糊边缘内容至侧边栏/检查器下方，实现边缘到边缘的视觉效果
Icon Composer	Xcode工具，用于创建多层Liquid Glass应用图标
ConcentricRectangle	相对于容器保持同心圆角的形状

Quick Reference

快速参考

Apply Liquid Glass to a view (SwiftUI)

为SwiftUI视图应用Liquid Glass

swift

// Default: regular glass, capsule shape
Text("Hello")
    .padding()
    .glassEffect()

// Custom shape with rounded rectangle
Text("Hello")
    .padding()
    .glassEffect(in: .rect(cornerRadius: 16.0))

// Tinted + interactive (reacts to touch)
Text("Hello")
    .padding()
    .glassEffect(.regular.tint(.orange).interactive())

swift

// 默认：常规玻璃效果，胶囊形状
Text("Hello")
    .padding()
    .glassEffect()

// 自定义圆角矩形形状
Text("Hello")
    .padding()
    .glassEffect(in: .rect(cornerRadius: 16.0))

// 着色+交互式（响应触摸）
Text("Hello")
    .padding()
    .glassEffect(.regular.tint(.orange).interactive())

Glass button styles

玻璃按钮样式

swift

// Standard glass button
Button("Action") { }
    .buttonStyle(.glass)

// Prominent glass button (stronger visual weight)
Button("Primary") { }
    .buttonStyle(.glassProminent)

// Clear variant glass button
Button("Subtle") { }
    .buttonStyle(.glass(.clear))

swift

// 标准玻璃按钮
Button("Action") { }
    .buttonStyle(.glass)

// 突出显示的玻璃按钮（更强视觉权重）
Button("Primary") { }
    .buttonStyle(.glassProminent)

// 透明变体玻璃按钮
Button("Subtle") { }
    .buttonStyle(.glass(.clear))

GlassEffectContainer with morph animation

带形态动画的GlassEffectContainer

swift

@State private var isExpanded = false
@Namespace private var namespace

GlassEffectContainer(spacing: 40.0) {
    HStack(spacing: 40.0) {
        Image(systemName: "scribble.variable")
            .frame(width: 80, height: 80)
            .glassEffect()
            .glassEffectID("pencil", in: namespace)

        if isExpanded {
            Image(systemName: "eraser.fill")
                .frame(width: 80, height: 80)
                .glassEffect()
                .glassEffectID("eraser", in: namespace)
        }
    }
}

Button("Toggle") {
    withAnimation { isExpanded.toggle() }
}
.buttonStyle(.glass)

swift

@State private var isExpanded = false
@Namespace private var namespace

GlassEffectContainer(spacing: 40.0) {
    HStack(spacing: 40.0) {
        Image(systemName: "scribble.variable")
            .frame(width: 80, height: 80)
            .glassEffect()
            .glassEffectID("pencil", in: namespace)

        if isExpanded {
            Image(systemName: "eraser.fill")
                .frame(width: 80, height: 80)
                .glassEffect()
                .glassEffectID("eraser", in: namespace)
        }
    }
}

Button("Toggle") {
    withAnimation { isExpanded.toggle() }
}
.buttonStyle(.glass)

Background extension effect

背景扩展效果

swift

NavigationSplitView {
    // sidebar
} detail: {
    ZStack {
        Image(decorative: "hero")
            .backgroundExtensionEffect()
            .overlay(alignment: .bottom) {
                // Overlay goes AFTER the modifier so it
                // doesn't extend under the sidebar
                Text("Title").font(.largeTitle)
            }
    }
}

swift

NavigationSplitView {
    // 侧边栏
} detail: {
    ZStack {
        Image(decorative: "hero")
            .backgroundExtensionEffect()
            .overlay(alignment: .bottom) {
                // 叠加层需在修饰符之后添加，
                // 避免延伸至侧边栏下方
                Text("Title").font(.largeTitle)
            }
    }
}

Toolbar grouping with spacers

使用间隔符进行工具栏分组

swift

.toolbar {
    ToolbarSpacer(.flexible)
    ToolbarItem { ShareLink(item: item, preview: preview) }
    ToolbarSpacer(.fixed)
    ToolbarItemGroup {
        FavoriteButton(item: item)
        CollectionsMenu(item: item)
    }
    ToolbarSpacer(.fixed)
    ToolbarItem {
        Button("Info", systemImage: "info") { showInspector.toggle() }
    }
}

swift

.toolbar {
    ToolbarSpacer(.flexible)
    ToolbarItem { ShareLink(item: item, preview: preview) }
    ToolbarSpacer(.fixed)
    ToolbarItemGroup {
        FavoriteButton(item: item)
        CollectionsMenu(item: item)
    }
    ToolbarSpacer(.fixed)
    ToolbarItem {
        Button("Info", systemImage: "info") { showInspector.toggle() }
    }
}

Horizontal scroll under sidebar

侧边栏下方的水平滚动

swift

ScrollView(.horizontal, showsIndicators: false) {
    LazyHStack(spacing: Constants.standardPadding) {
        Spacer().frame(width: Constants.standardPadding)
        ForEach(items) { item in
            ItemView(item: item)
        }
    }
}
// Ensure no padding on containing view so scroll touches sidebar edge

swift

ScrollView(.horizontal, showsIndicators: false) {
    LazyHStack(spacing: Constants.standardPadding) {
        Spacer().frame(width: Constants.standardPadding)
        ForEach(items) { item in
            ItemView(item: item)
        }
    }
}
// 确保容器视图无内边距，使滚动区域触达侧边栏边缘

Custom badge with glass effect

带玻璃效果的自定义徽章

swift

BadgeLabel(badge: badge)
    .glassEffect(.regular, in: .rect(cornerRadius: 12))

swift

BadgeLabel(badge: badge)
    .glassEffect(.regular, in: .rect(cornerRadius: 12))

Glass effect union (merge multiple shapes)

玻璃效果合并（融合多个形状）

swift

GlassEffectContainer(spacing: 20.0) {
    HStack(spacing: 20.0) {
        ForEach(items.indices, id: \.self) { i in
            Image(systemName: items[i])
                .frame(width: 80, height: 80)
                .glassEffect()
                .glassEffectUnion(id: i < 2 ? "group1" : "group2",
                                  namespace: namespace)
        }
    }
}

swift

GlassEffectContainer(spacing: 20.0) {
    HStack(spacing: 20.0) {
        ForEach(items.indices, id: \.self) { i in
            Image(systemName: items[i])
                .frame(width: 80, height: 80)
                .glassEffect()
                .glassEffectUnion(id: i < 2 ? "group1" : "group2",
                                  namespace: namespace)
        }
    }
}

Tab bar minimize on scroll

滚动时标签栏最小化

swift

TabView {
    Tab("Numbers", systemImage: "number") {
        ScrollView { /* content */ }
    }
}
.tabBarMinimizeBehavior(.onScrollDown)

swift

TabView {
    Tab("Numbers", systemImage: "number") {
        ScrollView { /* 内容 */ }
    }
}
.tabBarMinimizeBehavior(.onScrollDown)

Scroll edge effect

滚动边缘效果

swift

ScrollView {
    LazyVStack {
        ForEach(data) { item in RowView(item) }
    }
}
.scrollEdgeEffectStyle(.hard, for: .all)

swift

ScrollView {
    LazyVStack {
        ForEach(data) { item in RowView(item) }
    }
}
.scrollEdgeEffectStyle(.hard, for: .all)

Concentric corner radii

同心圆角

swift

ZStack {
    Color.cyan
        .fill(.rect(corners: .concentric(minimum: 12), isUniform: false))
        .padding(.all, padding)
}
.containerShape(.rect(cornerRadius: 24))

swift

ZStack {
    Color.cyan
        .fill(.rect(corners: .concentric(minimum: 12), isUniform: false))
        .padding(.all, padding)
}
.containerShape(.rect(cornerRadius: 24))

API Quick Reference

API快速参考

API	Framework	Purpose
`.glassEffect(_:in:)`	SwiftUI	Apply Liquid Glass to any view
`.glassEffect()`	SwiftUI	Apply default (regular, capsule) glass
`GlassEffectContainer`	SwiftUI	Combine glass effects for performance + morphing
`.glassEffectID(_:in:)`	SwiftUI	Identity for morph transitions
`.glassEffectTransition(_:)`	SwiftUI	Control transition type ( `.matchedGeometry` , `.materialize` )
`.glassEffectUnion(id:namespace:)`	SwiftUI	Merge multiple shapes into one glass effect
`Glass`	SwiftUI	Config struct: `.regular` , `.clear` , `.identity`
`.interactive(_:)`	SwiftUI	Make glass react to touch/pointer
`.tint(_:)`	SwiftUI	Tint a glass effect
`.buttonStyle(.glass)`	SwiftUI	Standard glass button
`.buttonStyle(.glassProminent)`	SwiftUI	Prominent glass button
`.buttonStyle(.glass(.clear))`	SwiftUI	Clear variant glass button
`.backgroundExtensionEffect()`	SwiftUI	Extend view under sidebar/inspector
`UIBackgroundExtensionView`	UIKit	Background extension in UIKit
`NSBackgroundExtensionView`	AppKit	Background extension in AppKit
`UIGlassEffect`	UIKit	Glass visual effect in UIKit
`NSGlassEffectView`	AppKit	Glass effect view in AppKit
`ToolbarSpacer(.fixed)`	SwiftUI	Separate toolbar groups
`GlassEffectTransition`	SwiftUI	`.matchedGeometry` , `.materialize` , `.identity`
`DefaultGlassEffectShape`	SwiftUI	Default capsule shape for glass
`ConcentricRectangle`	SwiftUI	Concentric corner radius shape
`.tabBarMinimizeBehavior(_:)`	SwiftUI	Auto-minimize tab bar on scroll
`.scrollEdgeEffectStyle(_:for:)`	SwiftUI	Legibility effect at scroll edges
`UIDesignRequiresCompatibility`	Info.plist	Opt out of Liquid Glass (compatibility mode)

API	框架	用途
`.glassEffect(_:in:)`	SwiftUI	为任意视图应用Liquid Glass效果
`.glassEffect()`	SwiftUI	应用默认（常规、胶囊形）玻璃效果
`GlassEffectContainer`	SwiftUI	组合玻璃效果以提升性能并支持形态动画
`.glassEffectID(_:in:)`	SwiftUI	形态过渡动画的标识
`.glassEffectTransition(_:)`	SwiftUI	控制过渡类型（ `.matchedGeometry` 、 `.materialize` ）
`.glassEffectUnion(id:namespace:)`	SwiftUI	将多个形状合并为一个玻璃效果
`Glass`	SwiftUI	配置结构体： `.regular` 、 `.clear` 、 `.identity`
`.interactive(_:)`	SwiftUI	使玻璃效果响应触摸/指针操作
`.tint(_:)`	SwiftUI	为玻璃效果添加着色
`.buttonStyle(.glass)`	SwiftUI	标准玻璃按钮样式
`.buttonStyle(.glassProminent)`	SwiftUI	突出显示的玻璃按钮样式
`.buttonStyle(.glass(.clear))`	SwiftUI	透明变体玻璃按钮样式
`.backgroundExtensionEffect()`	SwiftUI	将视图延伸至侧边栏/检查器下方
`UIBackgroundExtensionView`	UIKit	UIKit中的背景扩展视图
`NSBackgroundExtensionView`	AppKit	AppKit中的背景扩展视图
`UIGlassEffect`	UIKit	UIKit中的玻璃视觉效果
`NSGlassEffectView`	AppKit	AppKit中的玻璃效果视图
`ToolbarSpacer(.fixed)`	SwiftUI	分隔工具栏组
`GlassEffectTransition`	SwiftUI	过渡类型： `.matchedGeometry` 、 `.materialize` 、 `.identity`
`DefaultGlassEffectShape`	SwiftUI	玻璃效果的默认胶囊形状
`ConcentricRectangle`	SwiftUI	同心圆角形状
`.tabBarMinimizeBehavior(_:)`	SwiftUI	滚动时自动最小化标签栏
`.scrollEdgeEffectStyle(_:for:)`	SwiftUI	滚动边缘的可读性效果
`UIDesignRequiresCompatibility`	Info.plist	选择退出Liquid Glass适配（兼容模式）

Common Mistakes

常见错误

Overusing Liquid Glass on custom controls. Apple explicitly warns: "Avoid overusing Liquid Glass effects. Limit these effects to the most important functional elements." Too many glass elements distract from content.

Not using GlassEffectContainer. Applying

glassEffect

to multiple views without a container degrades performance. Always wrap related glass views in a

GlassEffectContainer

Applying backgroundExtensionEffect with padding. The view must touch the leading/trailing edges of the containing view. Remove padding from the view and its containers so the effect can extend under the sidebar.

Putting overlays before backgroundExtensionEffect. Apply

.backgroundExtensionEffect()

to the image first, then add

.overlay()

after, so that overlaid text/buttons don't extend under the sidebar.

Hard-coding layout metrics for controls. Controls have new shapes and sizes in iOS 26. If you hard-code dimensions, your controls won't adopt the new rounded forms automatically.

Ignoring accessibility settings. Liquid Glass adapts when users enable Reduce Transparency or Reduce Motion. Test with these settings on. Standard components handle this automatically; custom implementations need fallbacks.

Custom backgrounds interfering with glass. Remove custom backgrounds from bars, tab bars, toolbars, and split views. They overlay or interfere with the system Liquid Glass appearance.

Not testing with
UIDesignRequiresCompatibility
. To ship with the latest SDK while opting out temporarily, add this key to your Info.plist. Remove it when you're ready for the full Liquid Glass experience.

在自定义控件中过度使用Liquid Glass。Apple明确警告：“避免过度使用Liquid Glass效果。仅将这些效果应用于最重要的功能元素。”过多的玻璃元素会分散用户对内容的注意力。

未使用GlassEffectContainer。不为多个视图包裹容器就直接应用

glassEffect

会降低性能。请始终将相关的玻璃视图包裹在

GlassEffectContainer

中。

为应用了backgroundExtensionEffect的视图添加内边距。视图必须触达容器视图的左右边缘。请移除视图及其容器的内边距，使效果能够延伸至侧边栏下方。

在backgroundExtensionEffect之前添加叠加层。先为图片应用

.backgroundExtensionEffect()

，再添加

.overlay()

，避免叠加的文本/按钮延伸至侧边栏下方。

为控件硬编码布局指标。iOS 26中控件有新的形状和尺寸。如果硬编码尺寸，控件将无法自动适配新的圆角样式。

忽略无障碍设置。当用户启用“降低透明度”或“减少动态效果”时，Liquid Glass会自动适配。请在这些设置开启的情况下进行测试。标准组件会自动处理这些场景；自定义实现则需要提供降级方案。

自定义背景干扰玻璃效果。移除导航栏、标签栏、工具栏和分栏视图的自定义背景。这些背景会覆盖或干扰系统Liquid Glass的外观。

未使用
UIDesignRequiresCompatibility
进行测试。如需使用最新SDK但暂时退出适配，请在Info.plist中添加该键。准备好全面适配Liquid Glass后再移除它。

Reference Files

参考文件

Detailed documentation organized by topic in

references/

File	Content	Pages
`getting_started.md`	Adopting Liquid Glass overview, Landmarks sample walkthrough, migration guide for existing apps	2
`background_extension.md`	`backgroundExtensionEffect()` API, UIKit ( `UIBackgroundExtensionView` ), AppKit ( `NSBackgroundExtensionView` ), alignment requirements	4
`custom_glass_views.md`	`glassEffect` , `Glass` struct, `GlassEffectContainer` , transitions, morph animations, button styles, union effects, UIKit/AppKit equivalents	23
`toolbar_glass.md`	`ToolbarSpacer` , toolbar grouping patterns	2
`horizontal_scrolling.md`	Extending horizontal ScrollView under sidebar/inspector	1
`activity_badges.md`	Custom badges with glass effects, morph animations, ViewModifier patterns	1
`navigation_and_layout.md`	`tabBarMinimizeBehavior` , `scrollEdgeEffectStyle`	2
`controls.md`	`ConcentricRectangle` shape, per-corner concentric radius control	1
`app_icons.md`	Icon Composer workflow: layers, groups, Liquid Glass material, platform variants	1
`platform_considerations.md`	`UIDesignRequiresCompatibility` Info.plist key for opting out	1
`other.md`	View styles overview, all Liquid Glass related SwiftUI style APIs	1

references/

目录下按主题组织的详细文档：

文件	内容	页数
`getting_started.md`	Liquid Glass适配概述、Landmarks示例演练、现有应用迁移指南	2
`background_extension.md`	`backgroundExtensionEffect()` API、UIKit（ `UIBackgroundExtensionView` ）、AppKit（ `NSBackgroundExtensionView` ）、对齐要求	4
`custom_glass_views.md`	`glassEffect` 、 `Glass` 结构体、 `GlassEffectContainer` 、过渡效果、形态动画、按钮样式、合并效果、UIKit/AppKit等效实现	23
`toolbar_glass.md`	`ToolbarSpacer` 、工具栏分组模式	2
`horizontal_scrolling.md`	将水平ScrollView延伸至侧边栏/检查器下方	1
`activity_badges.md`	带玻璃效果的自定义徽章、形态动画、ViewModifier模式	1
`navigation_and_layout.md`	`tabBarMinimizeBehavior` 、 `scrollEdgeEffectStyle`	2
`controls.md`	`ConcentricRectangle` 形状、圆角半径控制	1
`app_icons.md`	Icon Composer工作流：图层、分组、Liquid Glass材质、平台变体	1
`platform_considerations.md`	用于退出适配的 `UIDesignRequiresCompatibility` Info.plist键	1
`other.md`	视图样式概述、所有与Liquid Glass相关的SwiftUI样式API	1

Working with This Skill

技能使用指南

Getting Started

入门

Read

references/getting_started.md

for the adoption overview and Landmarks sample walkthrough. It covers the full scope: background extension, horizontal scrolling, toolbar glass, custom badges, and Icon Composer.

阅读

references/getting_started.md

获取适配概述和Landmarks示例演练。内容涵盖完整范围：背景扩展、水平滚动、工具栏玻璃效果、自定义徽章和Icon Composer。

For Specific Features

特定功能参考

Each topic has a dedicated reference file. For custom glass views and animations,

custom_glass_views.md

is the most comprehensive (23 pages covering all SwiftUI glass APIs).

每个主题都有对应的参考文件。对于自定义玻璃视图和动画，

custom_glass_views.md

是最全面的文档（23页，涵盖所有SwiftUI玻璃API）。

Cross-Framework Implementation

跨框架实现

SwiftUI: Primary framework. Use
```
glassEffect
```
,
```
GlassEffectContainer
```
, etc.

UIKit: Use

UIGlassEffect

and

UIBackgroundExtensionView

. See

custom_glass_views.md

and

background_extension.md

AppKit: Use

NSGlassEffectView

and

NSBackgroundExtensionView

. See same reference files.

SwiftUI：主要框架。使用
```
glassEffect
```
、
```
GlassEffectContainer
```
等API。

UIKit：使用

UIGlassEffect

和

UIBackgroundExtensionView

。请查看

custom_glass_views.md

和

background_extension.md

。

AppKit：使用
```
NSGlassEffectView
```
和
```
NSBackgroundExtensionView
```
。请查看相同的参考文件。

Adoption Checklist

适配检查清单

Build with latest Xcode SDK to see automatic Liquid Glass adoption
Remove custom backgrounds from bars, toolbars, split views
Test with accessibility settings (Reduce Transparency, Reduce Motion)
Group toolbar items with
```
ToolbarSpacer(.fixed)
```
Add
```
backgroundExtensionEffect()
```
to hero images in split views
Wrap custom glass views in
```
GlassEffectContainer
```
Create new app icon with Icon Composer
Test across all supported platforms

使用最新Xcode SDK构建，以查看自动适配的Liquid Glass效果
移除导航栏、工具栏、分栏视图的自定义背景
在无障碍设置（降低透明度、减少动态效果）下进行测试
使用
```
ToolbarSpacer(.fixed)
```
对工具栏项目进行分组
为分栏视图中的主图添加
```
backgroundExtensionEffect()
```
将自定义玻璃视图包裹在
```
GlassEffectContainer
```
中
使用Icon Composer创建新的应用图标
在所有支持的平台上进行测试

Notes

说明

Documentation sourced from Apple Developer Documentation via sosumi.ai extraction
All APIs require iOS 26.0+ / iPadOS 26.0+ / macOS 26.0+ unless otherwise noted
visionOS glass background APIs (
```
glassBackgroundEffect
```
,
```
FeatheredGlassBackgroundEffect
```
) are separate from the Liquid Glass system described here
watchOS and tvOS have limited Liquid Glass support; standard components adopt it automatically

文档内容通过sosumi.ai从Apple开发者文档提取
除非另有说明，所有API均要求iOS 26.0+ / iPadOS 26.0+ / macOS 26.0+
visionOS的玻璃背景API（
```
glassBackgroundEffect
```
、
```
FeatheredGlassBackgroundEffect
```
）与本文档描述的Liquid Glass系统无关
watchOS和tvOS对Liquid Glass的支持有限；标准组件会自动适配

Cross-References

交叉引用

```
swiftui-26-api
```
— Non-glass iOS 26 APIs (WebView, TextEditor rich text, @Animatable macro, UIHostingSceneDelegate, dragContainer, windowResizeAnchor)

```
swiftui-26-api
```
— 非玻璃效果的iOS 26 API（WebView、TextEditor富文本、@Animatable宏、UIHostingSceneDelegate、dragContainer、windowResizeAnchor）