Liquid Glass Design System

Apple's new material design combining glass optics with fluid interaction. Available across all platforms.

Quick Reference — SwiftUI

// Basic glass effect (capsule shape by default)
view.glassEffect()

// Custom shape
view.glassEffect(in: .rect(cornerRadius: 16))
view.glassEffect(in: .circle)

// Tinted glass (suggests prominence)
view.glassEffect(.regular.tint(.blue))

// Interactive (responds to touch/pointer)
view.glassEffect(.regular.interactive())

// Button styles
Button("Primary") { }.buttonStyle(.glassProminent)
Button("Secondary") { }.buttonStyle(.glass)

// Container for multiple glass views (required for merging/performance)
GlassEffectContainer(spacing: 40) {
    HStack(spacing: 40) {
        ItemView().glassEffect()
        ItemView().glassEffect()
    }
}

// Morphing transitions between glass views
@Namespace var ns
view.glassEffect().glassEffectID("myID", in: ns)

// Unite multiple views into single glass shape
view.glassEffect().glassEffectUnion(id: "group1", namespace: ns)

Critical Constraints

❌ DO NOT apply multiple glass effects without GlassEffectContainer → ✅ Wrap in GlassEffectContainer for performance and merging
❌ DO NOT forget .interactive() on buttons/controls → ✅ Add .interactive() for touch/pointer response
❌ DO NOT use heavy tint alpha values → ✅ Use subtle tints (0.2–0.3 alpha) for glass aesthetic
❌ DO NOT apply .glassEffect() before layout modifiers → ✅ Apply after .frame(), .padding(), etc.
❌ DO NOT use old NSVisualEffectView with .material for new designs → ✅ Use NSGlassEffectView (AppKit) or .glassEffect() (SwiftUI)

Reference Index

File	When to Use
`references/swiftui-glass.md`	SwiftUI glass effects, containers, morphing, button styles
`references/appkit-glass.md`	AppKit NSGlassEffectView, NSGlassEffectContainerView, hover effects
`references/uikit-glass.md`	UIKit UIGlassEffect, scroll edge effects, container effects
`references/widgetkit-glass.md`	Widget accented rendering mode, widgetAccentable modifier

Decision Tree

Building SwiftUI interface?
├── Single glass element → .glassEffect() on the view
├── Multiple glass elements → Wrap in GlassEffectContainer
├── Need morphing transitions → Use @Namespace + .glassEffectID()
├── Grouping elements into one shape → Use .glassEffectUnion()
└── Buttons → .buttonStyle(.glass) or .buttonStyle(.glassProminent)

Building AppKit interface?
├── Single glass element → NSGlassEffectView with contentView
├── Multiple glass elements → NSGlassEffectContainerView
└── Hover/interaction → NSTrackingArea + animator().tintColor

Building Widgets?
├── Support tinted/clear appearance → Check widgetRenderingMode
├── Mark accent content → .widgetAccentable()
└── Custom glass in widget → .glassEffect() (same as SwiftUI)

Common Mistakes & Fixes

Mistake	Fix
Glass views don't merge when close	Wrap in `GlassEffectContainer` with appropriate `spacing`
No animation when glass appears/disappears	Use `withAnimation { }` + `glassEffectID`
Glass button doesn't respond to hover	Add `.interactive()` to the glass effect
Too many glass effects = performance drop	Limit glass effects; use `GlassEffectContainer`
Widget looks wrong in tinted mode	Check `widgetRenderingMode` environment, use `widgetAccentable()`

liquid-glass

Liquid Glass Design System

Quick Reference — SwiftUI

Critical Constraints

Reference Index

Decision Tree

Common Mistakes & Fixes

References