◉ANTIGRAVITY LABJP
Articles/App Development
▣ App Development/2026-08-19Intermediate

Turn Off the Liquid Glass Compatibility Flag Yourself, Before Xcode 27 Does It for You

Build with Xcode 27 and UIDesignRequiresCompatibility no longer does anything. Here is how I flipped it off on Xcode 26 to surface the breakage early, a symptom-to-cause table, a complete UIScene migration, and the order to finish before the April 2027 SDK deadline.

iOS 274Liquid GlassXcode 27SwiftUI10indie development31

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.

WhenWhatHow sure
April 28, 2026App Store uploads must be built with the iOS 26 SDK (Xcode 26)Official Apple notice
September 14, 2026iOS 27 released; submissions built with Xcode 27 opened just beforeApple announcement and press coverage
Building with Xcode 27UIDesignRequiresCompatibility has no effect; standard controls render with Liquid GlassAs announced at WWDC25, confirmed in developer reports
Building with Xcode 27Apps that have not adopted the UIScene life cycle do not launchTN3187 (Apple technical note)
April 2027App Store uploads must be built with the iOS 27 SDKReported 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 = appearance

What 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.

SymptomLikely causeHow to checkFix
Buttons or text fields slide under the tab barHard-coded bar heights (44, 49, 83…)Item 1 of the audit script belowReplace with safeAreaInset(edge:)
Bar looks muddy, or the color looks doubledconfigureWithOpaqueBackground() plus a background overrideComment out the appearance code from item 2 and compareDrop the override; put color on tint or the content
Only some screens have misplaced elementssubviews indexing broken by system-inserted viewsItem 3; count the hierarchy in the View Hierarchy debuggerLook views up by type, identifier or tag
Sizes are wrong on iPad or external displaysLayout math based on UIScreen.mainItem 4Use view.window?.windowScene?.screen or GeometryReader
On Xcode 27, nothing appears after launchUIScene life cycle not adoptedIs 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 AppDelegateMoves to
Creating window and setting rootViewControllerscene(_:willConnectTo:options:)
applicationDidBecomeActive(_:)sceneDidBecomeActive(_:)
applicationDidEnterBackground(_:)sceneDidEnterBackground(_:)
application(_:open:options:)scene(_:openURLContexts:), plus connectionOptions.urlContexts at launch
Push registration, SDK initializationStays 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.

ApproachFits whenWeak spot
A. Stay on Xcode 26, flip the flag, fix appearance firstYou ship often and can't pick the SDK upgrade day yetUIScene problems stay hidden
B. Stay on Xcode 26, migrate to UIScene first, then do AAn older UIKit app whose AppDelegate owns the windowVisual checks come later
C. Jump straight to Xcode 27 and fix both at onceA newer SwiftUI-lifecycle app with few custom barsHarder 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:

  1. On Xcode 26, set UIDesignRequiresCompatibility to false and build (this is where reality shows up)
  2. Save screenshots of the broken screens before fixing anything
  3. Run the audit script and have the agent annotate it
  4. Replace hard-coded bar heights with safeAreaInset
  5. Drop bar background overrides; move the brand color to tint or the content
  6. Route UIScreen.main through windowScene.screen
  7. Migrate to the UIScene life cycle (single window is fine)
  8. 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

Share

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

If you found this article helpful, a small tip ($1.50) would mean a lot to us. Your support helps keep this site ad-free and covers server and hosting costs.

Related Articles

▣ App Dev2026-11-12
Check Web Font Delivery with an Origin Header, Too: How a Fallback Font Went Unnoticed on My Site for 13 Days
For 13 days, the Latin web font on my own site kept returning 404 and every page was drawn in a fallback face. A plain curl returned 200; only the browser's request, which carries an Origin header, received the stale 404. Here is a script that compares three kinds of request, a setting that keeps long cache lifetimes off error responses, and how to pick a purge that reaches every variant.
▣ App Dev2026-10-30
After I Closed the Image Viewer with Esc, the Page Behind It Stopped Scrolling: What I Counted When Moving to the dialog Element
While fixing the full-screen image viewer on my own site, I worked through three problems in order: Esc did nothing, the page behind kept scrolling, and the close button sat on top of the artwork. Even after moving to dialog, one bug remained, with a check script and numbers.
▣ App Dev2026-10-28
I Fetched All 155 Sitemap URLs. Every One Returned 200, but 93% of the lastmod Dates Were the Same Day
A record of fetching every sitemap URL and cross-checking status, canonical, hreflang and lastmod. Full standard-library Python scripts and the mismatch I found.