axiom-liquid-glass

Liquid Glass — Apple 的全新材质设计系统

何时使用此技能

适用于：

• 在应用中实现 Liquid Glass 效果
• 检查现有 UI，寻找采用 Liquid Glass 的机会
• 调试 Liquid Glass 材质带来的视觉瑕疵
• 优化 Liquid Glass 的性能
• 请求专家评审 Liquid Glass 的实现
• 了解何时使用 Regular 或 Clear 变体
• 排查色调、易读性或自适应行为问题

相关技能

• 使用 axiom-liquid-glass-ref，获取全面的应用级采用指南（应用图标、控件、导航、菜单、窗口和平台注意事项）

示例提示词

• “Liquid Glass 与模糊效果有什么不同？我应该采用它吗？”
• “我的透镜效果看起来像普通模糊。我遗漏了什么？”
• “Liquid Glass 在 iPad 和 iPhone 上看起来不太一样。我该如何调整？”
• “如何确保 Liquid Glass 上方文本的对比度？”
• “评审 Liquid Glass 实现时，专家会依据哪些标准？”

---

什么是 Liquid Glass？

Liquid Glass 是 Apple 在 WWDC 2025 上推出的下一代材质设计系统。它通过创造一种全新的数字超材料，实现了相较于以往材质（Aqua、iOS 7 模糊效果、灵动岛）的重大演进。这种超材料能够：

• 动态弯曲并塑造光线（透镜效果），而不是散射光线
• 像轻盈的液体一样自然流动，并响应触控和应用的动态变化
• 自动适应尺寸、环境、内容以及浅色／深色模式
• 统一设计语言，适用于所有 Apple 平台（iOS、iPadOS、macOS、axiom-visionOS）

核心理念：Liquid Glass 以圆润、悬浮的形态，配合圆角沉浸式屏幕的演进；这些形态触感自然，同时让内容清晰呈现。

---

视觉特性

1. 透镜效果（主要视觉特征）

Liquid Glass 的核心特征是透镜效果——通过扭曲和弯曲光线来传达存在感、运动感和形态。元素通过调节光线弯曲而显现或隐去，而非淡入淡出。控件极其轻盈，同时又有清晰的视觉区分度。

2. 动态与流动性

• 通过弯曲光线来响应交互
• 凝胶般的柔韧性传达出短暂、可塑的特性
• 交互时，元素会融入 Liquid Glass（适用于控件）
• 应用状态之间动态变形，如同一个悬浮平面

3. 自适应行为

Liquid Glass 持续自适应，没有固定的浅色／深色外观：

• 文本在下方滚动时，阴影会加深；色调会变化以提升易读性
• 小型元素（导航栏）会独立切换浅色／深色；大型元素（菜单、侧边栏）不会切换，但会调整纵深感
• 环境光会微妙地映射到表面上

---

实现指南

基本 API 用法

SwiftUI：glassEffect 修饰符

// Basic usage - applies glass within capsule shape
Text("Hello")
    .glassEffect()

// Custom shape
Text("Hello")
    .glassEffect(in: RoundedRectangle(cornerRadius: 12))

// Interactive elements (iOS - for controls/containers)
Button("Tap Me") {
    // action
}
.glassEffect()
.interactive() // Add for custom controls on iOS

自动采用：只需使用 Xcode 26 重新编译，标准控件便会自动启用 Liquid Glass。

变体：Regular 与 Clear

关键决策：切勿在同一界面中混用 Regular 和 Clear。

Regular 变体（默认 — 95% 的情况）

适用范围最广。具备完整的自适应效果和自动易读性，可适用于任何尺寸和内容。用于导航栏、标签栏、工具栏、按钮、菜单和侧边栏。

Clear 变体（仅限特殊情况）

始终更加透明，不具备自适应行为。需要添加调暗层以保证易读性。

仅当以下三个条件全部满足时使用：

1. 元素位于媒体内容丰富的区域上方
2. 内容层不会受到调暗层的负面影响
3. 玻璃上方的内容醒目且明亮

若未满足全部三个条件就使用 Clear，会导致易读性较差。实现示例请参见 axiom-liquid-glass-ref。

---

分层系统架构

Liquid Glass 由协同工作的四层组成：

1. 高光 — 光源会根据几何形状产生高光；部分高光会响应设备运动
2. 阴影 — 感知内容：文字上方更明显，浅色背景上方更弱
3. 内部辉光 — 交互时材质会从内部发光，并扩散到附近的玻璃元素
4. 自适应着色 — 多个图层协同调整以保持层级；所有这些功能均会自动内置

---

滚动边缘效果

滚动边缘效果会在内容滚动时将其渐隐至背景中，使玻璃层浮于移动内容上方。存在固定的附属视图（例如列标题）时，请使用 .scrollEdgeEffect(.hard)，以增强视觉区分。完整的 API 详情请参阅 axiom-liquid-glass-ref。

---

着色与颜色

Liquid Glass 引入了自适应着色——选择一种颜色后，系统会根据下方内容的亮度生成对应色调，其灵感来自现实中的彩色玻璃。与所有玻璃行为（变形、自适应、交互）兼容。

着色规则

// ✅ Tint primary actions only
Button("View Bag") { }.tint(.red).glassEffect()

// ❌ Don't tint everything — when everything is tinted, nothing stands out
VStack {
    Button("Action 1").tint(.blue).glassEffect()
    Button("Action 2").tint(.green).glassEffect()  // No hierarchy
}

// ❌ Solid fills break Liquid Glass character
Button("Action") { }.background(.red)  // Opaque, wrong

// ✅ Use .tint() instead of solid fills
Button("Action") { }.tint(.red).glassEffect()  // Grounded in environment

将着色保留给主要 UI 操作。使用内容层来体现应用的整体配色方案。

---

易读性与对比度

SwiftUI 会在玻璃效果中自动使用鲜明的文字和色调，无需手动调整。小型元素（导航栏、标签栏）会切换明暗以确保清晰可辨。大型元素（菜单、侧边栏）会进行自适应，但不会切换明暗（这会对大面积表面造成过度干扰）。符号和字形会遵循玻璃行为，并自动最大化对比度。

仅在有明确功能需要时选择性地使用自定义色调（例如，在单个工具栏按钮上使用 .tint(.orange) 来突出显示）。

---

无障碍

Liquid Glass 提供了多项无障碍功能，可调整材质，而不牺牲其魅力：

降低透明度

• 让 Liquid Glass 更具磨砂感
• 更充分地遮挡其背后的内容
• 启用系统设置后自动应用

增强对比度

• 让元素以黑色或白色为主
• 通过对比色边框突出显示
• 启用系统设置后自动应用

减少动态效果

• 降低效果强度
• 禁用弹性属性
• 启用系统设置后自动应用

开发者无需采取任何操作：使用 Liquid Glass 时，所有功能均会自动启用。

---

性能注意事项

视图层级的影响

顾虑：复杂视图层级中的 Liquid Glass 渲染开销

建议：

• Regular 变体针对性能进行了优化
• 较大的元素（菜单、侧边栏）会使用更明显的效果，但由系统管理
• 避免过度嵌套玻璃元素

优化：

// ❌ Avoid deep nesting
ZStack {
    GlassContainer1()
        .glassEffect()
    ZStack {
        GlassContainer2()
            .glassEffect()
        // More nesting...
    }
}

// ✅ Flatten hierarchy
VStack {
    GlassContainer1()
        .glassEffect()

    GlassContainer2()
        .glassEffect()
}

渲染开销

自适应行为会带来计算开销：

• 明暗切换
• 阴影调整
• 色调计算
• 镜头效果

系统会负责优化，但仍需注意：

• 不要无故为 Liquid Glass 元素添加动画
• 谨慎使用 Clear 变体（需要计算调暗图层）
• 遇到性能问题时，使用 Instruments 进行分析

---

测试 Liquid Glass

请在以下配置下进行测试：

• 浅色／深色模式
• 启用“降低透明度”
• 启用“增强对比度”
• 启用“减少动态效果”
• 动态字体（较大的字号）
• 内容滚动（验证滚动边缘效果）
• 从右向左书写的语言

有关全面的 UI 测试模式（包括视觉回归和无障碍测试），请参阅 axiom-ui-testing。

---

设计评审压力：为你的实现辩护

问题

在设计评审的压力下，你会遇到以下要求：

• “到处都用 Clear 变体——Regular 太不透明了”
• “所有控件都用玻璃效果，以保持视觉统一”
• “再增加一些透明度，让内容透出来”

这些听起来都很合理。**但它们违背了框架的设计原则。**你的职责是用证据而非观点进行辩护。

警示信号 — 违反技能指南的设计师要求

如果听到以下任何说法，请停止并参考该技能：

• ❌ “到处都用 Clear”——Clear 需要满足三个特定条件，而不是出于设计偏好
• ❌ “Glass 比填充效果更好看”——应优先考虑正确的层级（导航层还是内容层），而非美观
• ❌ “用户不会注意到区别”——在低对比度场景下，Clear 变体无法通过易读性测试
• ❌ “为了保持一致，在 glass 上叠加 glass”——明确禁止；请改用填充效果
• ❌ “给列表应用 glass，更显精致”——列表属于内容层；这样做会造成视觉混乱

如何专业地提出异议

步骤 1：展示框架

"I want to make this change, but let me show you Apple's guidance on Clear variant.
It requires THREE conditions:

1. Media-rich content background
2. Dimming layer for legibility
3. Bold, bright controls on top

Let me show which screens meet all three..."

步骤 2：展示风险

在设备上打开应用，展示：

• 低对比度场景下的 Clear 变体（无法阅读）
• 相同场景下的 Regular 变体（清晰可读）

步骤 3：提出折中方案

"Clear can work beautifully in these 6 hero sections where all three conditions apply.
Regular handles everything else with automatic legibility. Best of both worlds."

步骤 4：记录决定

如果你的意见被否决（设计师坚持到处都用 Clear）：

Slack message to PM + designer:

"Design review decided to use Clear variant across all controls.
Important: Clear variant requires legibility testing in low-contrast scenarios
(bright sunlight, dark content). If we see accessibility issues after launch,
we'll need an expedited follow-up. I'm flagging this proactively."

为什么这样做有效

• 你不是在质疑他们的品味（你也喜欢 Clear）
• 你是在指出无障碍性／易读性风险
• 你提供了一个能在主视觉区域保留其设计愿景的解决方案
• 你记录了决定（上线后能保护你）

真实案例：App Store 上线阻碍（截止时间为 36 小时后）

场景

• 还有 36 小时就要上线
• 首席设计师说：“到处都用 Clear”
• 客户正在旁听评审会议
• 你已根据该技能实现了 Regular

应对方式

// In the meeting, demo side-by-side:

// Regular variant (current implementation)
NavigationBar()
    .glassEffect() // Automatic legibility

// Clear variant (requested)
NavigationBar()
    .glassEffect(.clear) // Requires dimming layer below

// Show the three-condition checklist
// Demonstrate which screens pass/fail
// Offer: Clear in hero sections, Regular elsewhere

结果

• 用 30 分钟演示折中方案
• 用 90 分钟实现改动
• 按计划上线，并确保最佳易读性
• 上线后没有收到无障碍性投诉

何时接受设计决定（即使你不同意）

有时设计师有正当理由覆盖该技能的建议。出现以下情况时，请接受：

• 他们理解三条件框架
• 他们愿意承担易读性风险
• 你以书面形式记录了决定
• 他们承诺关注上线后的反馈

在 Slack 中记录

"Design review decided to use Clear variant [in these locations].
We understand this requires:
- All three conditions met: [list them]
- Potential legibility issues in low-contrast scenarios
- Accessibility testing across brightness levels

Monitoring plan:
- Gather user feedback first 48 hours
- Run accessibility audit
- Have fallback to Regular variant ready for push if needed"

这能保护你们双方，也能表明你并非阻挠项目，而是在降低风险。

---

专家评审清单

评审 Liquid Glass 实现（你自己的代码或他人的代码）时，请检查：

1. 材质是否恰当

• Liquid Glass 是否仅用于导航层（而非内容层）？
• 标准控件是否通过 Xcode 26 重新编译自动获得 glass 效果？
• 是否避免了 glass 叠加 glass 的情况？

2. 变体选择

• 大多数情况下是否使用 Regular 变体？
• 如果使用 Clear 变体，是否满足全部三个条件？
  • 是否位于媒体内容丰富的内容之上？
  • 是否可以接受调暗图层？
  • 上方的内容是否明亮且醒目？
• 是否确保同一界面中不会混用 Regular 和 Clear？

3. 易读性与对比度

• 是否仅对主要操作进行选择性着色（而非所有元素）？
• 是否在内容层中使用颜色来体现应用的整体配色方案？
• 是否避免在 glass 元素上使用纯色填充？
• 元素在不同背景上是否都保持清晰可读？

4. 层级与层次

• 是否避免内容在稳定状态下相交？
• glass 上方的元素是否使用填充／透明效果（而非 glass）？
• 视觉层次是否清晰（导航层与内容层）？

5. 滚动边缘效果

• Liquid Glass 与滚动内容相接处是否应用了滚动边缘效果？
• 固定的辅助视图是否使用了 hard 样式？

6. 无障碍性

• 在“降低透明度”设置下，实现是否正常？
• 在“增强对比度”设置下，实现是否正常？
• 在“减少动态效果”设置下，实现是否正常？
• 所有配置下，交互元素是否都可点击？

7. 性能

• 视图层级是否足够扁平？
• 是否仅在必要时为 glass 元素添加动画？
• 是否谨慎使用 Clear 变体？

---

常见错误与解决方案

Glass 放置错误

// ❌ Glass on content layer — competes with navigation
List(landmarks) { landmark in
    LandmarkRow(landmark).glassEffect()
}

// ✅ Glass on navigation layer only
.toolbar {
    ToolbarItem { Button("Add") { }.glassEffect() }
}

// ❌ Clear without dimming — poor legibility
ZStack {
    VideoPlayer(player: player)
    PlayButton().glassEffect(.clear)
}

// ✅ Clear with dimming layer
ZStack {
    VideoPlayer(player: player)
        .overlay(.black.opacity(0.4))
    PlayButton().glassEffect(.clear)
}

过度着色

只为主要操作着色。当所有内容都带有色彩时，就没有什么能脱颖而出。

静态材质预期

不要硬编码阴影或固定不透明度。采用自适应行为，并在浅色／深色模式和不同背景下进行测试。

---

故障排除

视觉瑕疵

问题：玻璃效果过于透明或不可见

检查：

1. 是否使用了 Clear 变体？（如果不合适，请切换为 Regular）
2. 背景内容是否极浅或极深？（玻璃效果会自适应——这可能是正常行为）
3. 是否启用了降低透明度？（检查辅助功能设置）

问题：玻璃效果看起来不透明或边缘生硬

检查：

1. 是否在玻璃效果上使用了纯色填充？（请移除，改用着色）
2. 是否启用了增强对比度？（这是预期行为）
3. 自定义形状是否过于复杂？（简化几何形状）

深色模式问题

问题：玻璃效果在深色背景上没有切换为深色样式

检查：

1. 元素是否较大（菜单、侧边栏）？（大型元素不会切换——这是设计如此）
2. 背景是否确实为深色？（使用 Color Picker 验证）
3. 是否覆盖了外观设置？（如果非预期，请移除 .preferredColorScheme()）

问题：深色模式下玻璃上的内容难以辨认

修复：

// Let SwiftUI handle contrast automatically
Text("Label")
    .foregroundStyle(.primary) // ✅ Adapts automatically

// Don't hardcode colors
Text("Label")
    .foregroundColor(.black) // ❌ Won't adapt to dark mode

性能问题

问题：使用 Liquid Glass 滚动时感觉卡顿

调试：

1. 使用 Instruments 进行性能分析（参见 axiom-swiftui-performance skill）
2. 检查视图 body 是否更新过于频繁
3. 简化玻璃效果下方的视图层级
4. 确认没有将玻璃效果应用于内容层（会严重影响性能）

问题：动画卡顿

检查：

1. 是否正在为玻璃形状变化添加动画？（开销较大）
2. 使用 SwiftUI Instrument 分析耗时较长的视图更新
3. 如果处于关键路径，请考虑减少玻璃效果的使用

---

从先前材质迁移

从 UIBlurEffect / NSVisualEffectView 迁移

之前（UIKit）：

let blurEffect = UIBlurEffect(style: .systemMaterial)
let blurView = UIVisualEffectView(effect: blurEffect)
view.addSubview(blurView)

之后（使用 Liquid Glass 的 SwiftUI）：

ZStack {
    // Content
}
.glassEffect()

优势：自动适配（无需手动切换样式）、内置交互反馈、适合平台的外观，并包含辅助功能特性。

从自定义材质迁移

1. 先尝试 Liquid Glass——它可能会自动提供所需效果
2. 评估 Regular 与 Clear——Clear 可能符合自定义透明度需求
3. 在不同配置下进行测试——Liquid Glass 会自动适配

保留自定义材质的情况：Liquid Glass 无法实现特定的艺术效果；需要兼容 iOS < 26；或使用与 Liquid Glass 原则不兼容的非标准 UI 范式。

UIKit + SwiftUI 互操作

增量迁移时，玻璃效果按框架分别应用：

• SwiftUI 视图使用 .glassEffect() / .glassBackgroundEffect()
• UIKit 视图使用 UIKit Liquid Glass API（迁移映射请参见 axiom-liquid-glass-ref）
• UIHostingController 中托管的 SwiftUI 视图会独立获得玻璃效果

完整的 UIBlurEffect 迁移映射表请参见 axiom-liquid-glass-ref。

---

向后兼容性

UIDesignRequiresCompatibility 键（iOS 26）

如需使用最新 SDK 发布，同时保留之前的外观：

<key>UIDesignRequiresCompatibility</key>
<true/>

效果：应用使用 iOS 26 SDK 构建，外观与 iOS 18 及更早版本一致，Liquid Glass 效果已禁用，并使用先前的模糊／材质样式。

适用情况：需要时间审核界面变化、采用渐进式迁移策略，或暂时保持外观完全一致。

迁移策略：

1. 启用 UIDesignRequiresCompatibility 后发布
2. 在单独的构建中审核界面变化
3. 逐步更新界面
4. 准备好使用 Liquid Glass 后移除此键

---

API 参考

完整 API 参考涵盖 glassEffect()、glassBackgroundEffect()、工具栏修饰符、滚动边缘效果、导航／搜索 API、控件／布局、GlassEffectContainer、glassEffectID、类型及向后兼容性，请参见 axiom-liquid-glass-ref。

---

资源

WWDC：2025-219、2025-256、2025-323（使用新设计构建 SwiftUI 应用）

文档：/technologyoverviews/adopting-liquid-glass、/swiftui/landmarks-building-an-app-with-liquid-glass、/swiftui/applying-liquid-glass-to-custom-views

技能：axiom-liquid-glass-ref

---

平台： iOS 26+、iPadOS 26+、macOS Tahoe、axiom-visionOS 3 Xcode： 26+ 历史记录： 查看 git log 了解变更