kmshdev SF Symbols & Iconography API Reference
Lifecycle Position
Phase 3 API Reference — load during implementation when using SF Symbols or custom icons. Dispatched from autonomous-ui-workflow Phase 2 research table.
Quick Reference
| API | Purpose |
|---|---|
Image(systemName:) |
System SF Symbol |
Image(systemName:variableValue:) |
Symbol with 0.0-1.0 value |
.symbolRenderingMode(_:) |
Set rendering mode |
.symbolVariant(_:) |
Add variant (.fill, .circle) |
.symbolEffect(_:) |
Animate symbol |
.foregroundStyle(_:_:) |
Palette colors (implies palette mode) |
Rendering Modes
| Mode | Usage |
|---|---|
.monochrome |
Single color: .symbolRenderingMode(.monochrome).foregroundStyle(.purple) |
.hierarchical |
Layered opacity: .symbolRenderingMode(.hierarchical).foregroundStyle(.purple) |
.multicolor |
Inherent colors: .symbolRenderingMode(.multicolor) |
.palette |
Custom per-layer: .foregroundStyle(.yellow, .cyan) |
Symbol Effects
// Indefinite (repeating)
Image(systemName: "bolt.slash.fill").symbolEffect(.pulse)
// Active/inactive
Image(systemName: "wifi").symbolEffect(.pulse, isActive: isConnecting)
// Value-driven
Image(systemName: "bell").symbolEffect(.bounce, value: count)
// As transition
.transition(.symbolEffect(.appear))
Variable Values
Image(systemName: "chart.bar.fill", variableValue: 0.3) // partial
Image(systemName: "chart.bar.fill", variableValue: 1.0) // full
When to Use Which
| Need | Use |
|---|---|
| Standard system icon | Image(systemName: "star.fill") |
| Icon with accessible label | Label("Favorites", systemImage: "star.fill") (preferred in buttons/toolbars) |
| Icon matching adjacent text weight | .fontWeight(.semibold) on Image to match Text |
| Animated symbol feedback | .symbolEffect(.bounce, value: trigger) |
| Progress/level indicator | Image(systemName: "wifi", variableValue: 0.5) |
| Multi-color system icon | .symbolRenderingMode(.multicolor) |
| Icon tinted to match theme | .symbolRenderingMode(.palette) with foregroundStyle(.red, .blue) |
| Custom app icon | Asset catalog → Symbol Image Set → export from SF Symbols app |
Common Mistakes
Image(systemName:)withoutLabelin buttons — no accessibility text for VoiceOver- Mismatched symbol weight with adjacent text — icons look too thin/thick next to text. Match with
.fontWeight()or.imageScale() - Using
.resizable().frame()for sizing instead of.font()— breaks alignment with text. Use.font(.title)to match text size - Missing
.symbolRenderingMode()— defaults to monochrome which may not match design intent - Hardcoded symbol names without checking SF Symbols availability — some symbols require iOS 16+ or 17+
Before (incorrect):
Button(action: addFavorite) {
Image(systemName: "star.fill") // no label — VoiceOver reads nothing useful
}
After (correct):
Button(action: addFavorite) {
Label("Add to Favorites", systemImage: "star.fill")
}
Before (incorrect):
Image(systemName: "heart.fill")
.resizable()
.frame(width: 24, height: 24) // disrupts text baseline alignment
After (correct):
Image(systemName: "heart.fill")
.font(.title2) // scales with Dynamic Type and aligns with text
Checklist
- Buttons and toolbar items use
Label("text", systemImage:)not bareImage - Icon weight matches adjacent text weight
- Icon sizing uses
.font()or.imageScale()not.resizable().frame() - Rendering mode explicitly set when multicolor or palette needed
- Symbol availability checked for newer symbols (
@available)
Cross-References
swiftui-colors-api—foregroundStyle()for symbol tintingswiftui-ui-patterns— review checklist includes accessibility label checksmacos-app-design— macOS toolbar icon conventions