liquid-glass

Liquid Glass Design Build native macOS/iOS applications with Apple's Liquid Glass design and HIG. Core Rules Three-Layer Model ┌─────────────────────────────────────────┐ │ GLASS LAYER (Navigation/Controls) │ ← Glass here ONLY ├─────────────────────────────────────────┤ │ CONTENT LAYER (Your App) │ ← Never glass here └─────────────────────────────────────────┘ Glass is ONLY for navigation floating above content. Never on content itself. Five Principles Content First - Glass floats above, content shines through Depth Through Light - Lensing creates hierarchy, not opacity Adaptive Tinting - Colors respond to background dynamically Semantic Emphasis - Tint primary actions only Accessibility Built-In - System handles adaptations automatically Materials (macOS 14+ / Pre-iOS 26) // Card with material . padding ( 24 ) . background ( . regularMaterial , in : RoundedRectangle ( cornerRadius : 16 , style : . continuous ) ) // Material options (lightest → heaviest): // .ultraThinMaterial, .thinMaterial, .regularMaterial (default), .thickMaterial, .ultraThickMaterial Liquid Glass API (iOS 26+ / macOS Tahoe) // Basic Button ( "Action" ) { } . glassEffect ( ) // Variants . glassEffect ( . regular ) // Standard UI . glassEffect ( . clear ) // Media backgrounds only . glassEffect ( . identity ) // Disabled // Interactive (adds bounce/shimmer) Button ( "Tap" ) { } . glassEffect ( . regular . interactive ( ) ) // Multiple glass elements - MUST wrap in container GlassEffectContainer ( spacing : 30 ) { HStack { Button ( "A" ) { } . glassEffect ( ) Button ( "B" ) { } . glassEffect ( ) } } // Button styles Button ( "Cancel" ) { } . buttonStyle ( . glass ) // Secondary Button ( "Save" ) { } . buttonStyle ( . glassProminent ) . tint ( . blue ) // Primary Essential Patterns Card VStack ( alignment : . leading , spacing : 12 ) { HStack { ZStack { Circle ( ) . fill ( color . opacity ( 0.15 ) ) . frame ( width : 36 , height : 36 ) Image ( systemName : icon ) . foregroundStyle ( color ) } Spacer ( ) } Text ( value ) . font ( . system ( size : 28 , weight : . bold , design : . rounded ) ) Text ( label ) . font ( . caption ) . foregroundStyle ( . secondary ) } . padding ( 20 ) . background ( . regularMaterial , in : RoundedRectangle ( cornerRadius : 16 , style : . continuous ) ) Row with Hover HStack { content } . padding ( 16 ) . background ( isHovering ? Color . primary . opacity ( 0.04 ) : . clear ) . background ( . quaternary . opacity ( 0.5 ) , in : RoundedRectangle ( cornerRadius : 12 , style : . continuous ) ) . onHover { withAnimation ( . easeInOut ( duration : 0.15 ) ) { isHovering = $0 } } Badge HStack ( spacing : 8 ) { Circle ( ) . fill ( isActive ? . green : . orange ) . frame ( width : 8 , height : 8 ) Text ( status ) . font ( . caption ) . fontWeight ( . medium ) } . padding ( . horizontal , 12 ) . padding ( . vertical , 8 ) . background ( . regularMaterial , in : Capsule ( ) ) Icon with Tinted Background ZStack { Circle ( ) . fill ( color . opacity ( 0.15 ) ) . frame ( width : 32 , height : 32 ) Image ( systemName : icon ) . font ( . system ( size : 14 , weight : . semibold ) ) . foregroundStyle ( color ) } Shapes // Always use .continuous RoundedRectangle ( cornerRadius : 16 , style : . continuous ) // Cards RoundedRectangle ( cornerRadius : 12 , style : . continuous ) // Rows RoundedRectangle ( cornerRadius : 8 , style : . continuous ) // Small elements Capsule ( ) // Pills, badges Circle ( ) // Icons Colors // Semantic foreground . foregroundStyle ( . primary ) // Main content . foregroundStyle ( . secondary ) // Subtitles . foregroundStyle ( . tertiary ) // Timestamps // Backgrounds . background ( . quaternary ) . background ( . quaternary . opacity ( 0.5 ) ) // Accent meanings Color . blue // Primary actions, selection Color . green // Success, active Color . orange // Warning, loading Color . red // Destructive, error Color . purple // Premium, AI Color . cyan // Security // Tinted backgrounds: always 15% opacity . fill ( color . opacity ( 0.15 ) ) Typography . font ( . largeTitle ) . fontWeight ( . bold ) // Page titles . font ( . headline ) . fontWeight ( . semibold ) // Section headers . font ( . subheadline ) . fontWeight ( . medium ) // Row titles . font ( . body ) // Content (17pt default) . font ( . caption ) // Metadata . font ( . caption2 ) // Timestamps . font ( . system ( size : 28 , weight : . bold , design : . rounded ) ) // Stats Rules: Min 11pt. Avoid Ultralight/Thin/Light. Use system fonts for Dynamic Type. Spacing (8pt Grid) // Standard values: 4, 8, 12, 16, 20, 24, 32, 40, 48 . padding ( 24 ) // Cards . padding ( 16 ) // Rows . padding ( . horizontal , 12 ) . padding ( . vertical , 8 ) // Badges // Rule: external spacing ≥ internal spacing VStack ( spacing : 24 ) { CardView ( ) . padding ( 20 ) } // Correct SF Symbols // Preferred: hierarchical for depth Image ( systemName : icon ) . symbolRenderingMode ( . hierarchical ) . foregroundStyle ( color ) // Match weight to nearby text Image ( systemName : "gear" ) . font ( . system ( size : 14 , weight : . semibold ) ) Hit Targets // MINIMUM: 44pt × 44pt Button { } label : { Image ( systemName : "gear" ) } . frame ( minWidth : 44 , minHeight : 44 ) Animations // Hover . onHover { withAnimation ( . easeInOut ( duration : 0.15 ) ) { isHovering = $0 } } // Spring withAnimation ( . spring ( response : 0.3 ) ) { } withAnimation ( . bouncy ) { } // Entry . opacity ( appeared ? 1 : 0 ) . offset ( y : appeared ? 0 : 10 ) . onAppear { withAnimation ( . spring ( response : 0.5 , dampingFraction : 0.8 ) ) { appeared = true } } Do's and Don'ts DO: Use .regularMaterial for cards/toolbars Use .continuous on ALL rounded rectangles Use 15% opacity for icon backgrounds Wrap multiple glass in GlassEffectContainer Use 44pt minimum hit targets Use 8pt grid spacing Use SF Symbols with .hierarchical DON'T: Apply glass to content (lists, tables) Stack glass on glass without container Use sharp corners Go below 11pt text Create touch targets < 44pt Use full-color images on glass Accessibility System handles automatically: Reduce Transparency → opaquer glass Increase Contrast → visible borders Reduce Motion → no bouncy effects Dynamic Type → text scales Manual override if needed: @Environment ( \ . accessibilityReduceTransparency ) var reduceTransparency . glassEffect ( reduceTransparency ? . identity : . regular ) References For detailed patterns and examples, see: references/components.md - Full component implementations references/apple-hig.md - Complete Apple HIG guidelines