macOS apps can implement translucency in their interfaces by adopting vibrancy, a subtle blurring effect that dynamically blends the foreground and background using a careful balance of lightening and darkening techniques. This effect evokes a feeling of depth by enabling views and controls to hint at content residing in the background.

Be prepared for vibrancy. Vibrancy affects all apps—even ones that don’t display any vibrant views—because some elements, such as menus, are vibrant by default.

Enable and disable vibrancy in your app as appropriate. If your app implements custom views and controls, you can configure those elements to use vibrancy. Conversely, you can disable vibrancy in a standard view or control that typically adopts it.

Prefer system-provided elements and colors. Some elements dynamically use vibrancy based on their color. Labels, for example, use vibrancy when their color is set to Label Color or Secondary Label Color. For related guidance, see Labels and System Colors.

Use template images. Template images can be vibrant, but full-color images can’t. Think carefully before you decide to use full-color images in an area such as a toolbar or sidebar. For related guidance, see Custom Icons.

For developer guidance, see NSVisualEffectView.

Vibrancy Modes

The system offers two vibrancy blending modes, which result in varying translucency effects.

Behind-window blending. Allows the content behind a window to show through. Some interface elements, such as menus, sheets, and sidebar tables, adopt this mode automatically, although it can be disabled if necessary.

In-window blending. Adopted by elements that reside on windows and allows window content residing behind the element to show through. Toolbars often implement this mode, and hint at window content that scrolls beneath the toolbar.

For developer guidance, see NSVisuaEffectBlendingMode.

Appearances and Materials

Vibrant views can be either dark or light in appearance to match the style of your app.

Light appearance

Dark appearance

The system also offers predefined materials, which you can use to achieve standard vibrancy effects on custom views. Materials exist for matching the default vibrant look of menus, popovers, sidebars, and title bars. Generic light, dark, medium light, and ultra dark materials are also available.

Don’t combine a light appearance with a dark material, or vice versa. You can mix appearances and materials—such as light appearance and medium light material, or dark appearance and ultra dark material—to achieve varying levels of light and dark vibrancy. Just be sure the mixture doesn’t conflict and the resulting effect looks good.

Use system colors with system materials. System colors are designed to look great on system-defined materials. System colors in a menu, for example, automatically adapt to the menu’s vibrant light appearance, blending with colors from the content behind the menu. When you use system-provided colors instead of custom colors, you don’t need to worry about how the colors will look in different contexts. For related guidance, see Colors.

For developer guidance, see Standard Appearances of NSAppearance, as well as NSVisualEffectMaterial.