---
title: "適配 Apple Liquid Glass 視覺體系"
description: "說明如何把 SwiftUI app 遷移到 Liquid Glass，並用小步審計和驗證降低重設計風險。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

把現有 SwiftUI app 遷移到 Liquid Glass，不應該從“整體重設計”開始。更穩的方式是把它當成 iOS 26 + Xcode 26 migration：先審計一個高流量 flow，再用 native Liquid Glass APIs 替換 custom blur/material stacks，併為早於 iOS 26 的裝置保留 fallback。

> [!IMPORTANT]
> 平臺視覺遷移必須以當前 Apple SDK、deployment target 和官方 API 文件為準。不要在舊 Xcode、舊 simulator 或未驗證裝置上直接把 visual migration 寫進生產路徑。

官方頁面：[https://developers.openai.com/codex/use-cases/ios-liquid-glass](https://developers.openai.com/codex/use-cases/ios-liquid-glass)

## 適合什麼任務

| 場景 | Codex 應該做什麼 |
|---|---|
| 現有 SwiftUI app 需要實際 iOS 26 Liquid Glass 遷移計劃 | 審計現有 UI，先遷移一個 flow |
| app 裡有 custom cards、sheets、tab bars、toolbars、action buttons | 判斷哪些應變成 native Liquid Glass，哪些應保持 plain content |
| app 仍支援舊 iOS 版本 | 使用 `#available(iOS 26, *)` gate 新 API，並保留非 glass fallback |

## 使用的能力

| 能力 | 用法 | 連結 |
|---|---|---|
| `build-ios-apps` | 使用 SwiftUI Liquid Glass、SwiftUI UI patterns 和 simulator debugging skills，現代化 iOS screens，並在 iOS 26 simulators 上驗證 | [https://github.com/openai/plugins/tree/main/plugins/build-ios-apps](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) |

相關官方說明：

- Codex plugins：[https://developers.openai.com/codex/plugins](https://developers.openai.com/codex/plugins)
- Agent skills：[https://developers.openai.com/codex/skills](https://developers.openai.com/codex/skills)

## 起始提示詞

```text
请使用 Build iOS Apps plugin 和其中的 SwiftUI Liquid Glass skill，把这个 app 中一个高流量 flow 迁移到 Liquid Glass。

约束：
- 把它当作 iOS 26 + Xcode 26 migration 处理，但要用 `#available(iOS 26, *)` 为更早 deployment targets 保留 non-glass fallback。
- 先 audit 这个 flow。指出哪些 custom backgrounds、blur stacks、chips、buttons、sheets 和 toolbars 应该变成 native Liquid Glass，也指出哪些 surfaces 应该保持 plain content。
- 优先使用 system controls 和 native APIs，例如 `glassEffect`、`GlassEffectContainer`、`glassEffectID`、`.buttonStyle(.glass)` 和 `.buttonStyle(.glassProminent)`，不要用 custom blurs 重造。只有当真实 morphing transition 能改善 flow 时，才结合 `@Namespace` 使用 `glassEffectID`。
- 在 layout 和 visual modifiers 之后应用 `glassEffect`，保持 shapes 一致，只在真正响应 touch 的 controls 上使用 `.interactive()`。
- 使用 XcodeBuildMCP 在 iOS 26 simulator 上 build 和 run，为迁移后的 flow 捕获 screenshots，并明确说明使用了哪个 scheme、simulator 和 checks。

交付：
- 这个 flow 的简洁 migration plan
- 已实现的 Liquid Glass slice
- pre-iOS 26 devices 上的 fallback behavior
- 使用过的 simulator validation steps 和 screenshots
```

這個 prompt 先要求 audit，再要求實現一個 self-contained slice，並強制寫清楚 simulator validation。

## 推薦技術面

| 需要 | 推薦預設值 | 原因 |
|---|---|---|
| Liquid Glass UI APIs | [SwiftUI](https://developer.apple.com/documentation/swiftui/) + `glassEffect`、`GlassEffectContainer`、glass button styles | 優先使用 native APIs，移除 custom blur layers |
| Platform baseline | iOS 26 and Xcode 26 | Liquid Glass 隨 iOS 26 SDK 提供，Codex 應使用 Xcode 26 編譯並顯式新增舊系統 fallback |
| Simulator validation | [XcodeBuildMCP](https://www.xcodebuildmcp.com/) | visual migration 需要 build、launch、screenshot 和 log inspection |

## 從 iOS 26 Baseline 開始

先用 iOS 26 SDK 重新 build app，看看 standard SwiftUI controls 自動獲得了什麼效果。只有 custom parts 仍然過平、過重或脫離 system chrome 時，再讓 Codex 遷移。

如果 app deployment target 低於 iOS 26，prompt 裡必須提前寫明。SwiftUI Liquid Glass skill 應該用 `#available(iOS 26, *)` 保護 glass-only APIs，並保留在舊裝置上仍可讀的 fallback path。

## 使用 iOS Plugin

Liquid Glass 任務裡，Build iOS Apps plugin 的實用模式是：

1. 審計一個 flow。
2. 遷移一小組 surfaces。
3. 在 iOS 26 simulator 上 launch。
4. 截圖後再擴大 scope。

預設規則可以直接寫進 prompt：

- 優先使用 native `glassEffect`、`GlassEffectContainer`、glass button styles 和 `glassEffectID` transitions，不用 custom blur views 重造材質系統。
- `.glassEffect(...)` 放在 layout 和 visual modifiers 後面，讓 material 包住最終 shape。
- 多個相關 glass surfaces 一起出現時，用 `GlassEffectContainer` 包起來。
- `.interactive()` 只用於真的響應 touch 的 buttons、chips、controls。
- corner shapes、tinting、spacing 在 feature 內保持一致。
- pre-iOS 26 targets 保留 non-glass fallback。

## WWDC 參考

開始遷移真實 production flow 前，先看這些 WWDC25 session：

- [Meet Liquid Glass](https://developer.apple.com/videos/play/wwdc2025/219/)
- [Get to know the new design system](https://developer.apple.com/videos/play/wwdc2025/356/)
- [Build a SwiftUI app with the new design](https://developer.apple.com/videos/play/wwdc2025/323/)
- [Build a UIKit app with the new design](https://developer.apple.com/videos/play/wwdc2025/284/)
- [What's new in SwiftUI](https://developer.apple.com/videos/play/wwdc2025/256/)

## 實用建議

### 不要把所有東西都玻璃化

Liquid Glass 應該在內容上方形成清楚的 control layer，而不是把每張 card 都變成發光面板。閱讀優先的 content 應保持 plain；tinting 留給 semantic emphasis 或 primary actions。

### 先做一個高流量 Flow

tab root、detail screen、sheet、search surface 或 onboarding flow 通常比全 app sweep 更適合第一輪遷移。這樣 review 更容易，也更容易沉澱 reusable component patterns。

### 有意 review fallback

如果 deployment target 低於 iOS 26，讓 Codex 同時展示 Liquid Glass version 和 fallback implementation。這樣能提前發現 API availability regression。

## 接下來去哪

<Cards>
  <Card title="構建 iOS 應用" description="先建立可重複 build、launch 和 simulator validation loop。" href="/zh-Hant/docs/codex/official/08-scenarios/109-ios-app" />
  <Card title="SwiftUI 重構" description="視覺遷移前先把過大的 screen 拆成可 review 的邊界。" href="/zh-Hant/docs/codex/official/08-scenarios/102-swiftui-refactor" />
  <Card title="iOS 模擬器修 Bug" description="遷移後用同一條 simulator flow 驗證視覺和行為。" href="/zh-Hant/docs/codex/official/08-scenarios/101-ios-simulator-bug" />
  <Card title="官方 Liquid Glass use case" description="API、SDK 和外掛說明以官方頁面與 Apple 文件為準。" href="https://developers.openai.com/codex/use-cases/ios-liquid-glass" />
</Cards>
