# HIG: Materials

Source: [Apple HIG — Materials](https://developer.apple.com/design/human-interface-guidelines/materials)

## Overview

Two types of materials:
1. **Liquid Glass** — Dynamic material for controls/navigation (tab bars, sidebars, toolbars)
2. **Standard materials** — For visual differentiation within the content layer

## Liquid Glass

Forms a distinct functional layer floating above content. Content scrolls and peeks through.

### Rules

- **Don't** use Liquid Glass in the content layer — controls/navigation only
- Exception: transient interactive elements (sliders, toggles) take Liquid Glass when activated
- Use sparingly — system components get it automatically
- Only apply to custom controls for the most important functional elements

### Variants

| Variant | Appearance | Use When |
|---------|-----------|----------|
| **Regular** | Blurs + adjusts luminosity | Background might affect legibility; significant text (alerts, sidebars, popovers) |
| **Clear** | Highly translucent | Floating over media (photos, videos) for immersive experience |

### Clear Variant Dimming

- Bright underlying content: add dark dimming layer at 35% opacity
- Dark underlying content or AVKit controls: no dimming needed

### Color on Liquid Glass

- No inherent color — takes on colors from content behind it
- Apply color sparingly — reserve for primary actions (Done button accent)
- Color the background, not symbols/text
- Don't color multiple control backgrounds

## Standard Materials

### iOS/iPadOS

Four levels (content layer only): ultra-thin, thin, regular (default), thick

**Vibrancy for labels:** `label`, `secondaryLabel`, `tertiaryLabel`, `quaternaryLabel`
**Vibrancy for fills:** `fill`, `secondaryFill`, `tertiaryFill`

Avoid `quaternaryLabel` on thin/ultraThin (too low contrast).

### macOS

- Several standard materials with designated purposes
- Two blending modes: **behind window** and **within window**

### tvOS

| Material | Recommended For |
|----------|----------------|
| ultraThin | Full-screen views, light scheme |
| thin | Overlays, light scheme |
| regular | General overlays |
| thick | Overlays, dark scheme |

### visionOS

- Windows use system **glass** material (unmodifiable, adaptive)
- No distinct Dark Mode — glass adapts to luminance behind it
- Prefer translucency over opaque colors
- Custom component materials: thin (interactive), regular (separations), thick (dark distinct)
- Vibrancy: `label`, `secondaryLabel`, `tertiaryLabel`

### watchOS

- Use materials for context in full-screen modal views
- Don't remove default material backgrounds from modal sheets

## SwiftUI API

- `.ultraThinMaterial`, `.thinMaterial`, `.regularMaterial`, `.thickMaterial`, `.ultraThickMaterial`
- Liquid Glass: `glassEffect(_:in:)`