liquid-glass_KM
Use for Apple Liquid Glass work on iOS 26+, iPadOS 26+, and related SwiftUI/UIKit interfaces. Covers native glassEffect APIs, GlassEffectContainer, glassEffectID, glass button styles, tab/search acces
SKILL.mdskills/apple/liquid-glass_KM/SKILL.md
GitHubLiquid Glass
Use this skill to implement, review, or refactor Apple-native Liquid Glass UI. Prefer real SwiftUI/UIKit code and current SDK behavior over visual imitation.
Activation
Use when the request mentions Liquid Glass, iOS 26 UI, glassEffect, frosted Apple controls, agent composers, floating toolbars, native tab/search accessories, canvas/media overlays, or migration from older SwiftUI Materials.
Stay out of scope for web CSS glassmorphism, Android, generic mockups, or legacy-only backports. If older OS support is required, keep the iOS 26 native path primary and add a minimal fallback.
Workflow
- Identify the surface: system navigation, custom control group, composer, sheet/popover, canvas overlay, or migration.
- Choose the smallest native API that fits before custom drawing.
- Keep content readable; put glass around controls and transient chrome, not dense text bodies.
- Add motion only when it clarifies state, navigation, or direct manipulation.
- Respect Reduce Transparency, Reduce Motion, Dynamic Type, VoiceOver labels, hit targets, and contrast.
- Verify against the active SDK when a symbol is new, beta-sensitive, or absent from the project.
Native API Priority
Use standard SwiftUI/UIKit components first:
- Native
NavigationStack,TabView, sheets, popovers, menus, toolbar items, and.searchable. Tab(role: .search),tabViewBottomAccessory, andtabBarMinimizeBehaviorfor tab/search flows.safeAreaBarfor iOS 26 custom bars when the active SDK exposes the needed behavior; otherwise usesafeAreaInset.backgroundExtensionEffect()for media/header imagery continuing under sidebars or inspectors..buttonStyle(.glass)and.buttonStyle(.glassProminent)before custom button backgrounds.glassEffect(_:in:)for custom glass controls, compact overlays, pills, bars, and floating surfaces.GlassEffectContainer(spacing:)when multiple glass elements need coherent blending, performance, or morphing.glassEffectID(_:in:)for state or hierarchy changes that should morph instead of fade.NavigationTransition.zoomwithmatchedTransitionSourcefor list/grid/card to detail continuity..contentTransition(.symbolEffect(.replace))for send/stop, play/pause, expand/collapse, and mic/waveform swaps.- UIKit public APIs such as
UIGlassEffect,UIGlassContainerEffect,UIButton.Configuration.glass(), and standard tab/navigation/sheet behavior.
Use glassEffectUnion only after verifying the active Xcode 26 SDK exposes the needed overload and the design truly needs separated elements to read as one connected glass group. Prefer GlassEffectContainer plus stable IDs as the generated default.
Never use private APIs such as _UILiquidLensView, KVC on private backdrop layers, or hidden UIKit hierarchy assumptions in production code.
Design Rules
Liquid Glass is a functional material for controls, navigation, overlays, and transient surfaces. It should preserve context while protecting legibility.
Use one main glass slab or morph domain per local control group. Avoid glass-on-glass, busy nested blur, full-screen decorative glare, and blanket tint. Tint should mean something: selected, primary, destructive, recording, streaming, or status.
For AI chat and agent apps, favor:
- A glass bottom composer with plain readable messages above it.
- Floating tool controls, attachment chips, status chips, and canvas/media controls.
- Collapsible agent metadata and reasoning controls, with plain text bodies.
- Native tab/search accessories for global active-agent or queue state.
For visual polish, read references/animation-visual-patterns.md. Keep motion short, interruptible, and useful. Prefer morphing, symbol replacement, small scale/opacity changes, and direct manipulation over ornamental shimmer.
Accessibility And Performance
In reusable components, read:
@Environment(\.accessibilityReduceTransparency) private var reduceTransparency
@Environment(\.accessibilityReduceMotion) private var reduceMotion
@Environment(\.colorSchemeContrast) private var contrast
When transparency is reduced, replace glass with an opaque system background plus a subtle border. When motion is reduced, replace morphing and springy transitions with opacity or short ease animations.
Keep hit targets around 44 points or larger. Give icon-only controls useful accessibility labels. Avoid glass behind dense text, tiny labels, or busy media unless you add a dimming or contrast layer.
Control GPU cost by avoiding stacked blur, many independent full-width glass rows, display-link-driven effects, and shader overlays for ordinary controls. Use GlassEffectContainer around related elements to help rendering and morphing.
Code Generation Rules
- Generate real Swift code before design commentary.
- Use
@available(iOS 26.0, *)on reusable components that call iOS 26-only APIs. - Match the existing project architecture and naming when editing a project.
- Keep snippets self-contained with sample state and
#Previewwhen practical. - Put related controls inside one
GlassEffectContainer. - Use stable IDs with
glassEffectIDfor morphing between compact and expanded states. - Use native tab/search/sheet APIs before recreating system chrome.
- For drag interactions, use gesture translation and predicted end translation to choose the final state.
- For visual examples, use real app surfaces: composers, toolbars, panels, canvases, media headers, command palettes, and tab accessories.
Quick Patterns
Composer group
GlassEffectContainer(spacing: 10) {
HStack(spacing: 10) {
Button("Tools", systemImage: toolsExpanded ? "xmark" : "plus") {
withAnimation(animation) { toolsExpanded.toggle() }
}
.buttonStyle(.glass)
.contentTransition(.symbolEffect(.replace))
TextField("Ask, search, or delegate", text: $prompt, axis: .vertical)
.textFieldStyle(.plain)
.padding(.horizontal, 14)
.padding(.vertical, 12)
.glassEffect(.regular.interactive(), in: Capsule())
Button(isStreaming ? "Stop" : "Send", systemImage: isStreaming ? "stop.fill" : "arrow.up") {
submitOrStop()
}
.buttonStyle(.glassProminent)
.contentTransition(.symbolEffect(.replace))
}
}
Reduced transparency fallback
@ViewBuilder
func adaptiveGlassBackground<S: InsettableShape>(_ shape: S) -> some View {
if reduceTransparency {
shape
.fill(.background)
.overlay(shape.stroke(.separator.opacity(0.6), lineWidth: 0.5))
} else {
shape.glassEffect(.regular, in: shape)
}
}
Morphing cluster
@Namespace private var glassNamespace
GlassEffectContainer(spacing: 8) {
if isExpanded {
expandedPanel
.glassEffect(.regular, in: .rect(cornerRadius: 24))
.glassEffectID("agent-tools", in: glassNamespace)
} else {
compactButton
.glassEffect(.regular.interactive(), in: Capsule())
.glassEffectID("agent-tools", in: glassNamespace)
}
}
Verified gotchas (selection morph)
These rules are SDK-verified against iPhoneSimulator26.4.sdk/.../SwiftUICore.framework/.../SwiftUICore.swiftmodule/arm64-apple-ios-simulator.swiftinterface:
public struct Glass : Swift.Equatable, Swift.Sendable {
public static var regular: Glass { get }
public static var clear: Glass { get }
public static var identity: Glass { get } // ← REAL — frequently misdocumented
public func tint(_ color: Color?) -> Glass
public func interactive(_ isEnabled: Bool = true) -> Glass
}
Glass.identityIS a real Glass variant. It renders no visible effect but keeps the view in the morph graph. Use it for the inactive state when you wantGlassEffectContainerto morph the selection between cells. Many third-party docs and AI agents claim.identitydoesn't exist — they are wrong; the SDK header above proves it.Conditional rendering breaks the morph.
.background { if isSelected { GlassView() } }makes the container see view-destroyed + view-created, not a morph. Render the glass view for every cell at all times:.identitywhen inactive,.regular.tint(...)when active. SameglassEffectID+ namespace across cells.Don't nest
.glassEffect()inside another.glassEffect()within the sameGlassEffectContainer. Two glass surfaces in one container mute each other — the inner tinted glass collapses to a flat color overlay, and foreground text on the inner pill can render invisibly even with.whiteor.tint. Use.ultraThinMaterialor a regular.backgroundfor the OUTER rail, and.glassEffect()ONLY on the moving inner element.State-bound animation goes OUTSIDE the
GlassEffectContainer..animation(_:value:)on or outside the container is correct (matches the Apple Music tab bar pattern). DON'T wrap state changes inwithAnimationin the tap handler — it captures stale state on rapid taps and can desync the morph.
Bonus subtleties
GlassEffectContainer(spacing:)controls how far glass blobs can flow between siblings. 20–24 is typical for a cross-cell selection morph; set to 0 if you specifically want to PREVENT merging.- The text-invisibility symptom in #3 is a vibrancy interaction between outer-rail glass and inner-pill glass. Switching the outer rail to Material removes it.
Canonical morphing-selection pattern
Use this for filter pills, tab bars, segmented controls, any "selection slides between cells" UX:
// 1. Render the selection glass for every cell, ALL the time.
// 2. Use Glass.identity for inactive cells, .regular.tint(...).interactive() for active.
// 3. Shared @Namespace + same glassEffectID across all cells.
// 4. Wrap the cell row in GlassEffectContainer with spacing >= the visual gap between cells.
// 5. Outer container = .ultraThinMaterial (NOT .glassEffect) so cell glass doesn't nest into rail glass.
// 6. Animation is state-bound on or outside the container, NOT withAnimation in the tap handler.
@Namespace private var ns
@State private var selection: Item.ID = ...
GlassEffectContainer(spacing: 24) {
HStack(spacing: 6) {
ForEach(items) { item in
Button { selection = item.id } label: { ItemLabel(item) }
.frame(maxWidth: .infinity)
.background {
Capsule()
.fill(.clear)
.glassEffect(
selection == item.id
? .regular.tint(.accentColor).interactive()
: .identity,
in: Capsule()
)
.glassEffectID("selection", in: ns)
}
}
}
}
.background(.ultraThinMaterial, in: Capsule()) // NOT another glassEffect!
.animation(.spring(response: 0.34, dampingFraction: 0.82), value: selection)
Read As Needed
references/api-map.mdfor exact API selection.references/design-principles.mdfor Apple-aligned visual rules.references/animation-visual-patterns.mdfor motion, morphing, and visual polish.references/performance-accessibility.mdfor guardrails.references/component-taxonomy.mdfor choosing surfaces.references/library-evaluation.mdbefore recommending dependencies.references/source-evaluation.mdwhen integrating community research.recipes/ChatComposerRecipe.swiftfor AI composer patterns.recipes/NativeSearchAccessoryRecipe.swiftfor native tab/search/accessory patterns.snippets/29-background-extension-safe-area-bars.swiftfor media extension and safe-area bars.