When I moved to Xcode 26, I added UIDesignRequiresCompatibility to Info.plist and pushed the visual change down the road. My wallpaper apps are built around a full-screen image viewer and a custom bottom bar, and I honestly could not picture what Liquid Glass would do to them all at once.
I flipped that flag back to false myself, before iOS 27 shipped. Choosing the day it comes off hurt less than waiting for the day it would be taken away. Three things broke, and none of them were the kind you can leave for "later."
Since then iOS 27 and Xcode 27 have both shipped, so the situation has moved one step forward. This piece is for anyone still building and shipping with Xcode 26 who wants to know what to check, and in what order, before moving to Xcode 27. I've kept the steps in the order I actually walked them.
Where things stand (as of November 2026)
The first thing worth saying: the grace period for this flag now lives only inside Xcode 26. At WWDC25, Apple described the compatibility option as temporary and said it would be removed in the next major release.
| When | What | How sure |
|---|---|---|
| April 28, 2026 | App Store uploads must be built with the iOS 26 SDK (Xcode 26) | Official Apple notice |
| September 14, 2026 | iOS 27 released; submissions built with Xcode 27 opened just before | Apple announcement and press coverage |
| Building with Xcode 27 | UIDesignRequiresCompatibility has no effect; standard controls render with Liquid Glass | As announced at WWDC25, confirmed in developer reports |
| Building with Xcode 27 | Apps that have not adopted the UIScene life cycle do not launch | TN3187 (Apple technical note) |
| April 2027 | App Store uploads must be built with the iOS 27 SDK | Reported as an Apple notice; check the exact date on Apple's Upcoming Requirements page |
Put plainly, you can keep shipping from Xcode 26 until next spring at the latest. The moment you move to Xcode 27, the appearance change and the launch requirement arrive on the same day. Clearing them one at a time is, I think, the safest way to spend the months in between.
Flip the flag on Xcode 26 and rehearse
Turning it off is one line: delete the key or set it to false. If your project has no Info.plist file on disk, look in the target's Info tab under Custom iOS Target Properties for the same key.
<!-- Before: keeping the pre-Liquid Glass look -->
<key>UIDesignRequiresCompatibility</key>
<true/>
<!-- After: still on Xcode 26, but rendering the look Xcode 27 will force -->
<key>UIDesignRequiresCompatibility</key>
<false/>Build on Xcode 26 with this and the standard bars and buttons draw in the new design. You borrow next spring's appearance without touching the SDK — that is the most useful thing this flag can still do for you. I set it to false rather than deleting it, so the diff shows I turned it off on purpose.
Before fixing anything, take screenshots of your main screens. A record of the broken state becomes your yardstick for "how much have I actually fixed."
The first thing to break: the bottom edge of the viewer
My viewer shows an image edge to edge, with save, share and favorite buttons along the bottom. For a long time I positioned that row with a constant equal to the tab bar height.
// Before: lift the row by a hard-coded bar height
struct ViewerScreen: View {
let item: Wallpaper
var body: some View {
VStack(spacing: 0) {
WallpaperCanvas(item: item)
ActionBar(item: item)
.padding(.bottom, 49) // tab bar height
}
.ignoresSafeArea()
}
}The Liquid Glass tab bar floats over the content and shrinks as you scroll. The safe area itself now changes with context, so a fixed 49 stops being true. On device, half the button row slid under the tab bar.
// After: let the system tell us how much room there is
struct ViewerScreen: View {
let item: Wallpaper
var body: some View {
WallpaperCanvas(item: item)
.ignoresSafeArea() // only the image bleeds to the edges
.safeAreaInset(edge: .bottom) {
ActionBar(item: item) // no more hard-coded height
}
}
}The key is putting ignoresSafeArea() on the image alone and handing the button row to safeAreaInset. Before, I had applied it to the whole VStack, which left the system no room to place anything. It is a tiny diff, but any bar height stored as a constant will break again the next time something floats or shrinks.
Custom bar colors don't vanish — they turn muddy
The second break was the navigation bar background. I had an opaque brand color set on it, and it fought with the glass material, leaving a dull, murky look.
// Before: an opaque background I configured myself
let appearance = UINavigationBarAppearance()
appearance.configureWithOpaqueBackground()
appearance.backgroundColor = .brandBackground
UINavigationBar.appearance().standardAppearance = appearance
UINavigationBar.appearance().scrollEdgeAppearance = appearanceWhat makes this one awkward is that nothing complains. It builds, no warnings, it just looks worse. I didn't catch it until I put screenshots side by side.
// After: let the system own the bar; move the brand color into the content
// (delete the five appearance lines above)
struct LibraryScreen: View {
var body: some View {
NavigationStack {
WallpaperGrid()
.navigationTitle("Library")
}
.tint(.brandAccent) // brand color lives on buttons and selection
}
}I didn't give up the brand color; I moved it from the bar background to buttons and selection states. There are also reports of system-inserted views throwing off layout math, so if anything positions itself by counting subviews[0], check it in the same pass.
From symptom to cause
These are the symptoms I hit, plus the ones that came up most in other people's write-ups of the same migration. Working top to bottom usually finds it fastest.
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| Buttons or text fields slide under the tab bar | Hard-coded bar heights (44, 49, 83…) | Item 1 of the audit script below | Replace with safeAreaInset(edge:) |
| Bar looks muddy, or the color looks doubled | configureWithOpaqueBackground() plus a background override | Comment out the appearance code from item 2 and compare | Drop the override; put color on tint or the content |
| Only some screens have misplaced elements | subviews indexing broken by system-inserted views | Item 3; count the hierarchy in the View Hierarchy debugger | Look views up by type, identifier or tag |
| Sizes are wrong on iPad or external displays | Layout math based on UIScreen.main | Item 4 | Use view.window?.windowScene?.screen or GeometryReader |
| On Xcode 27, nothing appears after launch | UIScene life cycle not adopted | Is UIApplicationSceneManifest in Info.plist? (item 6) | The SceneDelegate migration below |
What I gave the agent was an inventory, not a fix
What I asked Antigravity to do here was not to fix anything, but to list every suspicious spot. My first attempt was a single "make this Liquid Glass ready" request. It rewrote places where I had put a constant deliberately, and I spent an evening reverting the diff line by line. After that I split the work.
Now a script lists whatever can be found mechanically, and I hand that list to the agent to add a one-line reason for each hit. It runs with the bash and grep that ship with macOS.
#!/usr/bin/env bash
# liquid_glass_audit.sh — list lines that look risky for Liquid Glass / UIScene. Changes nothing.
# Usage: bash liquid_glass_audit.sh <project root>
set -u
ROOT="${1:-.}"
HITS=0
scan() {
local label="$1" pattern="$2" include="$3" out
out=$(grep -rnE --include="$include" "$pattern" "$ROOT" 2>/dev/null)
echo "## $label"
if [ -n "$out" ]; then echo "$out"; HITS=$((HITS + $(echo "$out" | wc -l))); else echo "(none)"; fi
echo
}
scan "1. Hard-coded bar heights (44/49/83/96)" '\.(padding|offset|frame)\(.*[^0-9](44|49|83|96)[^0-9]' '*.swift'
scan "2. Hand-built bar appearances" 'UI(Navigation|Tab|Tool)BarAppearance\(' '*.swift'
scan "3. Indexed subviews access" 'subviews\[[0-9]+\]' '*.swift'
scan "4. UIScreen.main references" 'UIScreen\.main([^A-Za-z]|$)' '*.swift'
scan "5. AppDelegate life-cycle methods" 'func application(DidBecomeActive|WillResignActive|DidEnterBackground|WillEnterForeground)|open url: URL' '*.swift'
scan "6. Compatibility flag and scene manifest" 'UIDesignRequiresCompatibility|UIApplicationSceneManifest' '*.plist'
echo "Candidates: ${HITS} lines (nothing was changed)"
# Exit code: 1 if anything was found, 0 if not (handy in CI to see whether the count grows)
[ "$HITS" -eq 0 ]Run against a small test folder, it prints something like this (items 2, 3 and 5 trimmed):
## 1. Hard-coded bar heights (44/49/83/96)
./App/Viewer.swift:1: .padding(.bottom, 49)
## 4. UIScreen.main references
./App/Viewer.swift:4:let scale = UIScreen.main.scale
## 6. Compatibility flag and scene manifest
./App/Info.plist:1:<key>UIDesignRequiresCompatibility</key>
Candidates: 6 lines (nothing was changed)The pattern for item 4 is bounded so that a home-made property like UIScreen.mainScreenSize doesn't match. Item 1 will also catch an unrelated padding(.horizontal, 44), so read it expecting false positives.
The prompt only needs to fix the output shape and say "don't change anything":
Read the attached output of liquid_glass_audit.sh. For each line, rate whether it is
likely to cause a problem with Liquid Glass or the UIScene migration as high / medium / low,
with a one-line reason. Do not modify any code. For anything rated low, say why.I ended up touching about half of what came back. The rest I kept as a record of "read it, it's fine." In a migration like this, I've come to think the slow part isn't fixing things — it's becoming sure that something doesn't need fixing. The agent finds, I decide. Since I started working that way, I haven't had to revert a diff.
Before Liquid Glass, look at the UIScene life cycle
I wrote about appearance first, but this one comes first in priority. TN3187 says that when you build with the SDK of the major release after iOS 26, apps that haven't adopted the UIScene life cycle won't launch. A muddy bar and an app that doesn't open are not in the same league.
Apps that start with a SwiftUI @main struct ...: App are already scene-based. The ones at risk are UIKit apps whose AppDelegate owns the window. My older app was exactly that: it created UIWindow(frame: UIScreen.main.bounds) inside application(_:didFinishLaunchingWithOptions:).
First, add the scene configuration to Info.plist. If you're staying single-window, UIApplicationSupportsMultipleScenes can be false.
<key>UIApplicationSceneManifest</key>
<dict>
<key>UIApplicationSupportsMultipleScenes</key>
<false/>
<key>UISceneConfigurations</key>
<dict>
<key>UIWindowSceneSessionRoleApplication</key>
<array>
<dict>
<key>UISceneConfigurationName</key>
<string>Default Configuration</string>
<key>UISceneDelegateClassName</key>
<string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
</dict>
</array>
</dict>
</dict>Then create a SceneDelegate and move window setup, URL handling and life-cycle work over from the AppDelegate.
import UIKit
final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
var window: UIWindow?
func scene(_ scene: UIScene,
willConnectTo session: UISceneSession,
options connectionOptions: UIScene.ConnectionOptions) {
guard let windowScene = scene as? UIWindowScene else { return }
let window = UIWindow(windowScene: windowScene) // no UIScreen.main
window.rootViewController = RootViewController()
window.makeKeyAndVisible()
self.window = window
// A URL that cold-launches the app only arrives here
if let url = connectionOptions.urlContexts.first?.url {
DeepLinkRouter.shared.open(url)
}
}
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
if let url = URLContexts.first?.url {
DeepLinkRouter.shared.open(url) // URL opened while running
}
}
func sceneDidBecomeActive(_ scene: UIScene) {
AdSession.shared.resume()
}
func sceneDidEnterBackground(_ scene: UIScene) {
LibraryStore.shared.save()
}
}Leave only app-wide, run-once work in the AppDelegate, such as push registration and SDK setup.
| Was in AppDelegate | Moves to |
|---|---|
Creating window and setting rootViewController | scene(_:willConnectTo:options:) |
applicationDidBecomeActive(_:) | sceneDidBecomeActive(_:) |
applicationDidEnterBackground(_:) | sceneDidEnterBackground(_:) |
application(_:open:options:) | scene(_:openURLContexts:), plus connectionOptions.urlContexts at launch |
| Push registration, SDK initialization | Stays in AppDelegate |
The row that stalled me longest was the fourth one. I implemented only openURLContexts and, for a while, didn't notice that opening the app from a URL while it wasn't running did nothing at all. Cold-launch URLs come in through connectionOptions, so handle both, as in the code above.
Comparing ways to sequence the work
Same destination, but where you start changes how much you redo. These are the three approaches I weighed.
| Approach | Fits when | Weak spot |
|---|---|---|
| A. Stay on Xcode 26, flip the flag, fix appearance first | You ship often and can't pick the SDK upgrade day yet | UIScene problems stay hidden |
| B. Stay on Xcode 26, migrate to UIScene first, then do A | An older UIKit app whose AppDelegate owns the window | Visual checks come later |
| C. Jump straight to Xcode 27 and fix both at once | A newer SwiftUI-lifecycle app with few custom bars | Harder to tell whether a break is visual or launch-related |
My rule of thumb: if your AppDelegate creates the window, choose B; if it doesn't, choose A; if it's a small app that fits neither worry, C is fine. My older app went B, the newer one went A.
Common misconceptions
"If I leave the flag set to YES, Xcode 27 builds will keep the old look." They won't. The flag stops working the moment you build with Xcode 27. The grace period only lasts as long as Xcode 26 builds are accepted.
"Removing the flag means I'm ready for Xcode 27." It only means the appearance work is done. Adopting UIScene is a separate requirement, and that one decides whether the app launches.
"SwiftUI apps don't need to do anything." The life cycle is unlikely to bite, but UIKit screens wrapped in UIViewRepresentable and AppDelegate code kept alive through UIApplicationDelegateAdaptor still belong in the inventory. Visual breakage happens in SwiftUI too.
The order I'd follow before April 2027
Here is the sequence I actually used:
- On Xcode 26, set
UIDesignRequiresCompatibilityto false and build (this is where reality shows up) - Save screenshots of the broken screens before fixing anything
- Run the audit script and have the agent annotate it
- Replace hard-coded bar heights with
safeAreaInset - Drop bar background overrides; move the brand color to
tintor the content - Route
UIScreen.mainthroughwindowScene.screen - Migrate to the UIScene life cycle (single window is fine)
- Move to Xcode 27, build, and check launch paths one by one: notifications, URLs, widgets
Steps 1 through 5 took me about half a day per app. Leave them for the week before the deadline and that half day becomes half a day your release is blocked.
Where you'll get stuck next
The first thing that tends to trip people up after moving to Xcode 27 is launch paths. Opening from a notification, from a URL and from a widget each go through a different part of the SceneDelegate. I wrote up how I check them in The Five Days Between the iOS 27 RC and Release — I Check Init Order and Entitlement Restore Before Layout.
Outside the code, rule files for agents and READMEs that still say "iOS 26" will cause their own mismatches after the upgrade. I covered that sweep in When the iOS 27 Date Landed, the First File I Grepped Was AGENTS.md. If you've automated submissions, it's worth bringing the build settings from the iOS release pipeline article in line with Xcode 27 as well.
The one thing you can do today is set that single Info.plist line to false and build. That alone shows you, today, where next spring's trouble is waiting. It's the one step I try never to postpone, however busy the week gets.
References: Meet Liquid Glass (WWDC25 Session 219) / UIDesignRequiresCompatibility (Apple Developer Documentation) / TN3187: Migrating to the UIKit scene-based life cycle