Material & Structure API Reference
Lifecycle Position
Phase 3 API Reference — load during implementation when working with materials, shapes, or container backgrounds. Dispatched from autonomous-ui-workflow Phase 2 research table.
Material Types
| Material |
Translucency |
Usage |
.ultraThinMaterial |
Mostly translucent |
Subtle overlays |
.thinMaterial |
More translucent |
Light overlays |
.regularMaterial |
Somewhat translucent |
Standard overlays |
.thickMaterial |
More opaque |
Heavy overlays |
.ultraThickMaterial |
Mostly opaque |
Dense overlays |
.bar |
System toolbar style |
Toolbars, nav bars |
Text("Hello").padding().background(.regularMaterial)
Rectangle().fill(.thickMaterial)
macOS Active Appearance
Text("Hello").containerBackground(
Material.regular.materialActiveAppearance(.active), for: .window)
Default: window + bar materials appear inactive when window inactive. Others always active.
Shapes
| Shape |
Notes |
Rectangle |
Fills frame |
RoundedRectangle(cornerRadius:) |
Rounded corners |
UnevenRoundedRectangle |
Different corner radii |
Capsule |
Pill shape |
Circle |
Perfect circle |
Ellipse |
Oval |
Path |
Custom 2D outline |
ContainerRelativeShape |
Matches container |
Layout Containers
Stacks: HStack, VStack, ZStack, HSplitView, VSplitView
Grids: Grid+GridRow, LazyHGrid, LazyVGrid
Lists: List, Form, ScrollView+ScrollViewReader
Navigation: NavigationSplitView, NavigationStack, TabView
When to Use Which
| Material |
When to Use |
.ultraThinMaterial |
Overlays where content behind must be clearly visible (e.g., floating controls, HUD) |
.thinMaterial |
Sidebars, toolbars where partial visibility is wanted |
.regularMaterial |
Default cards, popovers, general surfaces |
.thickMaterial |
High-contrast surfaces where readability is critical |
.ultraThickMaterial |
Opaque-like surfaces that still respond to dark/light mode |
.bar |
Navigation bars, tab bars, toolbars (system-matched) |
Background Patterns
// Shape-clipped background (preferred for cards)
.background(.regularMaterial, in: RoundedRectangle(cornerRadius: 12))
// Full-bleed background
.background(.thinMaterial)
// Widget/Live Activity container background
.containerBackground(.thickMaterial, for: .widget)
// Stroke vs strokeBorder
RoundedRectangle(cornerRadius: 12)
.stroke(.blue, lineWidth: 2) // Straddles the edge (half inside, half outside)
RoundedRectangle(cornerRadius: 12)
.strokeBorder(.blue, lineWidth: 2) // Entirely inside the shape
Common Mistakes
- Material without sufficient text contrast — always test both light and dark mode. Add
.shadow() to text if needed
background(.regularMaterial) without shape parameter — no corner radius clipping. Use background(_:in:) variant- Using
clipShape() + background() separately instead of background(_:in:) — the in: parameter handles clipping
stroke() when strokeBorder() is intended — stroke bleeds outside the frame by half the line width- Applying material to views inside
ScrollView without drawingGroup() — performance cost compounds
Checklist
Cross-References
apple-liquid-glass-design — Liquid Glass replaces materials in many cases on iOS 26+swiftui-effects-api — blur and shadow effects that complement materialsswiftui-colors-api — colors layered under/over materials
1---2name: swiftui-material-api3description: This skill should be used when the user asks to "add material background", "apply translucent overlay", "use .regularMaterial", "choose material thickness", "work with shapes", or needs SwiftUI material and structure API reference. Provides material types (ultraThin to ultraThick), shapes (Rectangle, Capsule, Circle), and layout containers.4---56# Material & Structure API Reference78## Lifecycle Position910Phase 3 API Reference — load during implementation when working with materials, shapes, or container backgrounds. Dispatched from `autonomous-ui-workflow` Phase 2 research table.1112## Material Types1314| Material | Translucency | Usage |15|----------|-------------|-------|16| `.ultraThinMaterial` | Mostly translucent | Subtle overlays |17| `.thinMaterial` | More translucent | Light overlays |18| `.regularMaterial` | Somewhat translucent | Standard overlays |19| `.thickMaterial` | More opaque | Heavy overlays |20| `.ultraThickMaterial` | Mostly opaque | Dense overlays |21| `.bar` | System toolbar style | Toolbars, nav bars |2223```swift24Text("Hello").padding().background(.regularMaterial)25Rectangle().fill(.thickMaterial)26```2728## macOS Active Appearance2930```swift31Text("Hello").containerBackground(32 Material.regular.materialActiveAppearance(.active), for: .window)33```3435Default: `window` + `bar` materials appear inactive when window inactive. Others always active.3637## Shapes3839| Shape | Notes |40|-------|-------|41| `Rectangle` | Fills frame |42| `RoundedRectangle(cornerRadius:)` | Rounded corners |43| `UnevenRoundedRectangle` | Different corner radii |44| `Capsule` | Pill shape |45| `Circle` | Perfect circle |46| `Ellipse` | Oval |47| `Path` | Custom 2D outline |48| `ContainerRelativeShape` | Matches container |4950## Layout Containers5152**Stacks:** `HStack`, `VStack`, `ZStack`, `HSplitView`, `VSplitView`53**Grids:** `Grid`+`GridRow`, `LazyHGrid`, `LazyVGrid`54**Lists:** `List`, `Form`, `ScrollView`+`ScrollViewReader`55**Navigation:** `NavigationSplitView`, `NavigationStack`, `TabView`5657## When to Use Which5859| Material | When to Use |60|----------|-------------|61| `.ultraThinMaterial` | Overlays where content behind must be clearly visible (e.g., floating controls, HUD) |62| `.thinMaterial` | Sidebars, toolbars where partial visibility is wanted |63| `.regularMaterial` | Default cards, popovers, general surfaces |64| `.thickMaterial` | High-contrast surfaces where readability is critical |65| `.ultraThickMaterial` | Opaque-like surfaces that still respond to dark/light mode |66| `.bar` | Navigation bars, tab bars, toolbars (system-matched) |6768## Background Patterns6970```swift71// Shape-clipped background (preferred for cards)72.background(.regularMaterial, in: RoundedRectangle(cornerRadius: 12))7374// Full-bleed background75.background(.thinMaterial)7677// Widget/Live Activity container background78.containerBackground(.thickMaterial, for: .widget)7980// Stroke vs strokeBorder81RoundedRectangle(cornerRadius: 12)82 .stroke(.blue, lineWidth: 2) // Straddles the edge (half inside, half outside)83RoundedRectangle(cornerRadius: 12)84 .strokeBorder(.blue, lineWidth: 2) // Entirely inside the shape85```8687## Common Mistakes88891. Material without sufficient text contrast — always test both light and dark mode. Add `.shadow()` to text if needed902. `background(.regularMaterial)` without shape parameter — no corner radius clipping. Use `background(_:in:)` variant913. Using `clipShape()` + `background()` separately instead of `background(_:in:)` — the `in:` parameter handles clipping924. `stroke()` when `strokeBorder()` is intended — stroke bleeds outside the frame by half the line width935. Applying material to views inside `ScrollView` without `drawingGroup()` — performance cost compounds9495## Checklist9697- [ ] Material thickness matches content importance (thicker = more readable)98- [ ] Using `background(_:in:)` with shape for clipped material backgrounds99- [ ] `strokeBorder` used instead of `stroke` when border must stay inside frame100- [ ] Materials tested in both light and dark mode101- [ ] Widget backgrounds use `containerBackground(_:for:)` not `background()`102103## Cross-References104105- `apple-liquid-glass-design` — Liquid Glass replaces materials in many cases on iOS 26+106- `swiftui-effects-api` — blur and shadow effects that complement materials107- `swiftui-colors-api` — colors layered under/over materials
kmshdev