use-cases/ios-liquid-glass.md +129 −0 added
1---
2name: Adopt liquid glass
3tagline: Use Codex to migrate an existing SwiftUI app to Liquid Glass with iOS
4 26 APIs and Xcode 26.
5summary: Use Codex and the Build iOS Apps plugin to audit existing iPhone and
6 iPad UI, replace custom blur or material stacks with native Liquid Glass, and
7 keep the migration safe with iOS 26 availability checks and simulator-driven
8 validation.
9skills:
10 - token: build-ios-apps
11 url: https://github.com/openai/plugins/tree/main/plugins/build-ios-apps
12 description: Use the SwiftUI Liquid Glass, SwiftUI UI patterns, and simulator
13 debugging skills to modernize iOS screens, adopt native glass effects, and
14 verify the result on iOS 26 simulators.
15bestFor:
16 - Existing SwiftUI apps that need a practical iOS 26 Liquid Glass migration
17 plan, not a vague redesign brief
18 - Teams that want Codex to audit custom cards, sheets, tab bars, toolbars, and
19 action buttons and then implement the migration slice by slice
20 - Apps that still support older iOS versions and need `#available(iOS 26, *)`
21 fallbacks instead of a one-way visual rewrite
22starterPrompt:
23 title: Migrate One Flow to Liquid Glass
24 body: >-
25 Use the Build iOS Apps plugin and its SwiftUI Liquid Glass skill to migrate
26 one high-traffic flow in this app to Liquid Glass.
27
28
29 Constraints:
30
31 - Treat this as an iOS 26 + Xcode 26 migration, but preserve a non-glass
32 fallback for earlier deployment targets with `#available(iOS 26, *)`.
33
34 - Audit the flow first. Call out custom backgrounds, blur stacks, chips,
35 buttons, sheets, and toolbars that should become native Liquid Glass and
36 call out surfaces that should stay plain content.
37
38 - Prefer system controls and native APIs like `glassEffect`,
39 `GlassEffectContainer`, `glassEffectID`, `.buttonStyle(.glass)`, and
40 `.buttonStyle(.glassProminent)` over custom blurs. Use `glassEffectID` with
41 `@Namespace` only when a real morphing transition improves the flow.
42
43 - Apply `glassEffect` after layout and visual modifiers, keep shapes
44 consistent, and use `.interactive()` only on controls that actually respond
45 to touch.
46
47 - Use XcodeBuildMCP to build and run on an iOS 26 simulator, capture
48 screenshots for the migrated flow, and mention exactly which scheme,
49 simulator, and checks you used.
50
51
52 Deliver:
53
54 - a concise migration plan for the flow
55
56 - the implemented Liquid Glass slice
57
58 - the fallback behavior for pre-iOS 26 devices
59
60 - the simulator validation steps and screenshots you used
61relatedLinks:
62 - label: Codex plugins
63 url: /codex/plugins
64 - label: Agent skills
65 url: /codex/skills
66techStack:
67 - need: Liquid Glass UI APIs
68 goodDefault: "[SwiftUI](https://developer.apple.com/documentation/swiftui/) with
69 `glassEffect`, `GlassEffectContainer`, and glass button styles"
70 why: These are the native APIs the skill should reach for first, so Codex
71 removes custom blur layers instead of reinventing the material system.
72 - need: Platform baseline
73 goodDefault: iOS 26 and Xcode 26
74 why: Liquid Glass lands with the iOS 26 SDK. Codex should compile with Xcode 26
75 and add explicit fallbacks for earlier OS support.
76 - need: Simulator validation
77 goodDefault: "[XcodeBuildMCP](https://www.xcodebuildmcp.com/)"
78 why: Build, launch, screenshot, and log inspection matter during a visual
79 migration, especially when reviewing multiple states and device sizes.
80---
81
82## Start from the iOS 26 baseline
83
84Treat Liquid Glass as an iOS 26 and Xcode 26 migration project first. Rebuild the app with the iOS 26 SDK, inspect what you get automatically from standard SwiftUI controls, and only then ask Codex to redesign the custom parts that still look too flat, too heavy, or too detached from system chrome.
85
86If the app still supports earlier iOS versions, make that constraint explicit up front. The SwiftUI Liquid Glass skill in the [Build iOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) should gate new glass-only APIs with `#available(iOS 26, *)` and keep a fallback path that still reads well on older devices.
87
88## Leverage the iOS plugin
89
90Use the [Build iOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) when you want Codex to combine SwiftUI UI changes with simulator-backed verification. For Liquid Glass work, the useful move is to ask Codex to audit one flow, migrate a small set of surfaces, launch the result on an iOS 26 simulator, and capture screenshots before expanding the scope.
91
92That plugin includes a SwiftUI Liquid Glass skill with a simple set of defaults worth carrying into your prompt:
93
94- Prefer native `glassEffect`, `GlassEffectContainer`, glass button styles, and `glassEffectID` transitions over custom blur views.
95- Apply `.glassEffect(...)` after layout and visual modifiers so the material wraps the final shape you actually want.
96- Wrap related glass elements in `GlassEffectContainer` when multiple surfaces appear together.
97- Use `.interactive()` only on buttons, chips, and controls that actually respond to touch.
98- Keep corner shapes, tinting, and spacing consistent across the feature instead of mixing one-off glass treatments.
99- Preserve a non-glass fallback for pre-iOS 26 targets.
100
101To learn more about installing plugins and skills, see our [plugins](https://developers.openai.com/codex/plugins) and [skills](https://developers.openai.com/codex/skills) docs.
102
103## Watch the WWDC sessions
104
105These WWDC25 sessions are a good reference set before you ask Codex to refactor a real production flow:
106
107- [Meet Liquid Glass](https://developer.apple.com/videos/play/wwdc2025/219/)
108- [Get to know the new design system](https://developer.apple.com/videos/play/wwdc2025/356/)
109- [Build a SwiftUI app with the new design](https://developer.apple.com/videos/play/wwdc2025/323/)
110- [Build a UIKit app with the new design](https://developer.apple.com/videos/play/wwdc2025/284/)
111- [What's new in SwiftUI](https://developer.apple.com/videos/play/wwdc2025/256/)
112
113## Prompt a migration plan, then a slice
114
115Liquid Glass migrations go better when Codex separates "where should glass appear?" from "write all the code now." Ask for a quick audit first, then let the agent implement one self-contained slice with simulator verification.
116
117## Practical tips
118
119### Do not glass everything
120
121Liquid Glass should create a clear control layer above content, not turn every card into a glowing panel. Ask Codex to remove decorative backgrounds that fight system materials, preserve plain content where readability matters most, and reserve tinting for semantic emphasis or primary actions.
122
123### Start with one high-traffic flow
124
125A tab root, detail screen, sheet, search surface, or onboarding flow is usually a better first migration target than a full app-wide sweep. That keeps review easier and makes it clear which Liquid Glass decisions should become reusable component patterns.
126
127### Review fallback behavior deliberately
128
129If your deployment target is below iOS 26, ask Codex to show the fallback implementation alongside the Liquid Glass version. That review step catches accidental API availability regressions and avoids shipping a migration that only works on the latest simulator.