Use an NSVisualEffectView for this Visual Effect Material background (SwiftUI: Material). Choose NSVisualEffectView.Material by semantic purpose and set the appropriate BlendingMode; let standard controls supply vibrancy automatically instead of recreating the effect with a fixed blur and opacity.
Debug prompt — when it misbehaves调试 Prompt —— 当它不听话时
Debug my macOS vibrancy (NSVisualEffectView). Rule out: the wrong material for the surface (sidebar, menu, popover, hudWindow are distinct); blendingMode withinWindow when behindWindow was intended so nothing shows through; vibrant text/controls dead because they are not descendants of the effect view; everything going grey when the window deactivates via state followsWindowActiveState. The symptom:
# Visual Effect Material (Vibrancy) · 视觉效果材质（Vibrancy）
UI reference — https://K3tty5555.github.io/LearnUI_PM/macos/vibrancy/
**The adaptive translucent background used behind macOS sidebars, menus, and panels**
macOS 边栏、菜单和面板背后那种自适应的半透明背景
**Also called / 也叫:** visual effect material, frosted glass, translucent material, blur material / 视觉效果材质、毛玻璃、半透明材质、模糊材质
## Anatomy — every part, named / 解剖
1. **Material layer · 材质层** (`NSVisualEffectView.Material`)
“The frosted glass background behind the panel” is the material layer.
“面板背后的毛玻璃背景”就是材质层。
Prompt fragment: an NSVisualEffectView.Material layer providing the adaptive translucent background for the surface
2. **Vibrant foreground · Vibrancy 前景** (`NSVisualEffectView.allowsVibrancy`)
“The text and icons that adapt against the glass” are the vibrant foreground.
“在玻璃背景上自适应的文字和图标”就是 vibrancy 前景。
Prompt fragment: the NSVisualEffectView.allowsVibrancy foreground treatment that keeps controls legible over the material
## Prompt / 提示词
Use an NSVisualEffectView for this Visual Effect Material background (SwiftUI: Material). Choose NSVisualEffectView.Material by semantic purpose and set the appropriate BlendingMode; let standard controls supply vibrancy automatically instead of recreating the effect with a fixed blur and opacity.
用 NSVisualEffectView 实现这个视觉效果材质背景（SwiftUI：Material）。按语义用途选择 NSVisualEffectView.Material，并设置合适的 BlendingMode；让标准控件自动提供 vibrancy，不要用固定的模糊和不透明度去重造这个效果。
## Debug prompt / 调试提示词
Debug my macOS vibrancy (NSVisualEffectView). Rule out: the wrong material for the surface (sidebar, menu, popover, hudWindow are distinct); blendingMode withinWindow when behindWindow was intended so nothing shows through; vibrant text/controls dead because they are not descendants of the effect view; everything going grey when the window deactivates via state followsWindowActiveState. The symptom:
调试我的 macOS vibrancy（NSVisualEffectView）。逐一排除：材质选错了界面类型（sidebar、menu、popover、hudWindow 各不相同）；想要 behindWindow 却设成了 withinWindow，导致什么也透不出来；带 vibrancy 的文字和控件失效，因为它们不是效果视图的子视图；state 设为 followsWindowActiveState 导致窗口失活时一切变灰。症状是：
## In code / 代码里叫什么
- **AppKit** `NSVisualEffectView`
- **AppKit** `NSVisualEffectView.Material`
- **AppKit** `NSVisualEffectView.BlendingMode`
- **SwiftUI** `Material`
