Visual Effect Material
Visual Effect Material is a macOS surface style that blends and blurs what is behind it. It changes with the window state and light or dark look.
A real example
A sidebar looks connected to the desktop and document below it. Its labels still have enough contrast.
Main parts
- 01Background blending region
- 02Adaptive blur and tint
- 03Optional vibrant foreground treatment
- 04Window, appearance, and accessibility response
Use it when
Use it to separate a sidebar or tool area while still showing some context behind it. Let the system adapt to light, dark, active, and inactive states.
Do not use it when
Avoid decorative blur and stacked clear layers. Foreground details must stay readable when transparency drops or the window becomes inactive.
Name used in code
AppKit NSVisualEffectView / SwiftUI Material Before you ship
Check the supported macOS versions and AppKit or SwiftUI integration. Check standard focus and keyboard behavior. Also check VoiceOver, Full Keyboard Access, window resizing, and multi-window state. When needed, check restore, localization, and reduced motion.
Outcome: Apply or review Visual Effect Material in a native macOS app without breaking platform rules. User context: A sidebar looks connected to the desktop and document below it. Its labels still have enough contrast. macOS concept or control: Visual Effect Material. Why it fits: Use it to separate a sidebar or tool area while still showing some context behind it. Let the system adapt to light, dark, active, and inactive states. Do not use it when: Avoid decorative blur and stacked clear layers. Foreground details must stay readable when transparency drops or the window becomes inactive. Platform requirements: List the supported macOS versions. Say whether AppKit or SwiftUI owns each part and how they connect. Define window, menu, focus, keyboard, saved state, restore, and multi-window behavior. Platform accessibility and resilience: Use the right accessibility APIs. Check VoiceOver and Full Keyboard Access. Support localization, contrast, and reduced motion when needed. Keep user state after a relaunch. Acceptance criteria: Check the behavior on supported macOS versions with a keyboard and VoiceOver. Window resizing, focus, state restore, and AppKit or SwiftUI integration work in the normal macOS way. Evidence and limits (evidence boundary): It is official for that source. Other platforms or teams may use the term in another way. Unknowns to confirm: Supported macOS versions, AppKit or SwiftUI structure, and window model. Also confirm sandbox and entitlement limits, save rules, and the accessibility goal.
Check this request
Review the current use of Visual Effect Material. Definition: Visual Effect Material is a macOS surface style that blends and blurs what is behind it. It changes with the window state and light or dark look. Release checks: Check the supported macOS versions and AppKit or SwiftUI integration. Check standard focus and keyboard behavior. Also check VoiceOver, Full Keyboard Access, window resizing, and multi-window state. When needed, check restore, localization, and reduced motion. Before changing code, report the evidence you found, gaps, severity, and the smallest safe fix.